Overview
Capabilities
Granular, customizable access to Cofactr's component and supply chain data.
Structure
HTTP REST API with customizable response schemas and bulk querying.
Optimized For
Powering 3rd party products that serve multiple customers or highly customized workflows developed by in-house engineers.
Not Optimized For
Interacting with your data within the Cofactr Platform or integrating with typical in-house business applications.
Licensing
The Cofactr Component Cloud API is available as an add-on for Cofactr Custom plans or as a separate license for integration partners. Please contact [email protected] to request an API key. Usage is metered per Part, and requested data based on your selected plan.
Getting Started
Endpoints
Detailed documentation for all Platform API endpoints is available at https://graph.cofactr.com/redoc
The base URL for the Cofactr Platform API is https://graph.cofactr.com/
For example, the fetch info on a product, you would make a GET request to https://graph.cofactr.com/products/{cofactr_part_id}
Authentication
Each request must include an Authorization and Client ID header with the API key and client ID provided by Cofactr.
"X-CLIENT-ID": "<your client id>"
"X-API-KEY": "<your API key>"
The data returned by the API will be customized based on the provided X-CLIENT-ID as applicable.
⛔ Warning
Never expose your API key in front-end code or public Git repos. The Cofactr Platform API is only for server-side usage and must be kept private. Public disclosure of any of your API keys will result in immediate revocation of all of your API keys without prior warning.
Core Data Types
Product
A record of a part defined by a unique combination of Manufacturer (mfr) and Manufacturer Part Number (mpn). All parts are assigned a unique Cofactr ID aka CPID (id) that can be used to reference them and are required for querying related data such as Offers. A single product may have multiple alternative MPNs if they all represent the same part. Examples include punctuation variations of a given MPN or alternative packagings such as a large reel or small reel.
ℹ️ Tip
Cofactr’s Platform API calls these a Part. A Product in the Cofactr Component Cloud is the same thing as a Part in the Cofactr Platform.
Org
A unique entity, such as a manufacturer or distributor
Seller
An Org that sells parts. Example: Digi-Key, Arrow, etc. A Seller can also be a Manufacturer if they offer direct sales, such as Texas Instruments
ℹ️ Tip
Cofactr’s Platform API calls these a Source. A Seller in the Cofactr Component Cloud is the same thing as a Source in the Cofactr Platform.
Offer
A listing of an instance of a Part that are available for sale with accompanying price and related information. Examples: Digi-Key has 47pc at $1/ea with a 3-day lead time
Key Concepts
Schema
A Schema is a pre-configured definition for the fields that should be included in a response. If no schema is specified when a request is made, the latest version of the default product-{latest} schema will be used. Schemas are versioned (product-v1, product-v2, etc) any time a new field is added or modified. You can always continue to use an older version of the schema.
Custom Schemas can be created by the Cofactr team upon request. Please contact [email protected] for assistance with custom schemas.
Aggregation Properties
A schema may include a mixture of properties that are directly related to the queried object (example: description of a Product) and aggregation properties that are derived from related records (example: shortest lead time available across all current offers for a product). Accessing required data via an aggregation property will be more performant than making a subsequent request for additional data separately.
Additional aggregation properties may be able to be added by the Cofactr team upon request. Please contact [email protected] for assistance with additional aggregation properties.
Public vs Private Data
Most data that is accessed via the Cofactr Component Cloud API is considered public data, meaning that all clients that access this data will receive the same response. The Cofactr Component Cloud can also incorporate data that is specific and private to a specific client account. Examples of private data would include a custom_id assigned to a part for an internal part number or negotiated/contract distributor pricing derived from your own distributor API credentials.
External
Most requests can be made with an external boolean query parameter. This controls whether the Cofactr KB service exclusively uses our cached database records or whether external data sources (supplier APIs, etc) are rechecked for fresh data before making the response. This generally defaults to false, but for most production applications, it should be set to true. We recommend setting it to false to avoid using up your rate limits during heavy development and then setting it to true in production in nearly all cases.
If you know that you don’t need fresh supply chain data and that the data you are requesting is already in the Cofactr knowledge base due to having subsequently requested it, you can pass external=false to ensure that external data sources are not checked and the response time is as fast as possible.
Caching Behaviors
Even if external is set to true, cached data will be used as long as it’s fresh. Generally, we define fresh as having been checked within the last 24 hours, but different types of data (technical specs vs stock levels vs pricing, etc) have different caching behaviors that we manage for you automatically.
To force Cofactr to ignore cached data and fetch all new data, include a force_refresh=true query parameter in your request. Using this option will significantly slow down response times, and requests, where this option is used, are metered and billed at a different rate than standard requests. Additionally, we may ignore this request as needed to maintain overall performance for all of our users.
ℹ️ Using Custom Pricing?
Custom contract/negotiated pricing relies on your own distributor API credentials, which may have lower rate limits. Once you have used up your rate limit for a given distributor and time period, Cofactr Component Cloud will return cached and/or standard public data for subsequent requests until additional limit becomes available. Using force_refresh=true will make it more likely for you to use up your distributor rate limits prematurely.
Buyable Offers
Offers that are buyable (offer.status = “buyable”) can be purchased via the Cofactr platform without requesting a quote from that supplier. If you are looking to filter results only to include supplier offers that are “reliable,” limiting to buyable offers is a safe method to accomplish that.
Examples
GET Data For One Product by ID
Returns product information, including supply chain aggregations for a product by Cofactr ID
Action:
GET
Path: https://graph.cofactr.com/products/{id}
Query Params:
schema=product-v0
external=true
Response:
{
"data": { data goes here }
}
Example:
Path:
https://graph.cofactr.com/products/RCZB1AM45QIE
Query Params:
schema=product-v0
external=true
Response:
{
"data":
{
"id": "RCZB1AM45QIE", // cofactr ID aka CPID
"classification": "chip smd resistors",
"description": "Res Thin Film 0603 5kOhm 0.1% 3/20W ±25ppm/°C Molded T/R",
"documents": [
{
"label": "Datasheet",
"URL": "<omitted from sample data>",
"filename": "PNM0603E5001BST1-Vishay-datasheet-128669679.pdf"
},
],
"hero_image": "<https://assets.cofactr.com/RCZB1AM45QIE/part-img.jpg>",
"mfr": "Vishay", // canonical manufacturer name according to cofactr
"mpn": "PNM0603E5001BST1", // canonical MPN according to cofactr
"custom_id": "", // customer specific part number
"alt_mpns": [], // other MPNs that are sometimes used for this part
"msl": "1",
"package": "0603",
"specs": [
{ "id": "package", "label": "Package", "value": "0603" },
{ "id": "casecode_imperial_", "label": "Case Code (Imperial)", "value": "0603" },
{ "id": "casecode_metric_", "label": "Case Code (Metric)", "value": "1608" },
{ "id": "composition", "label": "Composition", "value": "Thin Film" },
{ "id": "height", "label": "Height", "value": "508 µm" },
{ "id": "length", "label": "Length", "value": "1.6256 mm" },
{ "id": "maxoperatingtemperature", "label": "Max Operating Temperature", "value": "125 °C" },
{ "id": "minoperatingtemperature", "label": "Min Operating Temperature", "value": "-55 °C" },
{ "id": "powerrating", "label": "Power Rating", "value": "150 mW" },
{ "id": "resistance", "label": "Resistance", "value": "5 kΩ" },
{ "id": "rohs", "label": "Rohs", "value": "Compliant" },
{ "id": "temperaturecoefficient", "label": "Temperature Coefficient", "value": "25 ppm/°C" },
{ "id": "termination", "label": "Termination", "value": "SMD/SMT" },
{ "id": "tolerance", "label": "Tolerance", "value": "0.1 %" },
{ "id": "voltagerating", "label": "Voltage Rating", "value": "75 V" },
{ "id": "width", "label": "Width", "value": "812.8 µm" }
],
"terminations": 2, // number of pins on part
"termination_type": "smt",
"buyable": 576, // total stock purchasable through cofactr platform
"quotable": 0, // total stock reported by relaible suppliers but requiring an rfq for price
"maybe": 0, // total stock reported by questionable suppliers
"min_lead": 3, // shortest lead time in business days from any buyable supplier with current stock
"lifecycle_status": "obsolete",
"updated_at": "2022-07-16T15:56:40.707495", // timestamp that data was cached
"offers": [
{
"seller": {
"id": "",
"label": "Digi-Key",
"aliases": []
},
"is_authorized": true,
"status": "buyable",
"ships_from_country": "US",
"shipping_lead": 1,
"sku": "",
"inventory_level": 1000,
"packaging": "reel",
"moq": 1,
"order_multiple": 1,
"factory_lead_days": 30,
"is_foreign": false,
"prices": [
{
"quantity": 1,
"converted_price": 1.00
}
],
}
]
}
}
GET Data For Multiple Products by ID
Returns product information including supply chain aggregations for up to 500 products by Cofactr ID
Action:
GET
Path: https://graph.cofactr.com/products/
Query Params:
schema=product-v0
external=true
limit=500
filtering=[
{
"field": "id",
"operator": "IN",
"value": [ "{id1}", "{id2}", "{id...}" ]
}
]
Response:
{
"data": [
{ each object matches product data schema specified above }
]
}
Find Products
Queries the Component Cloud to find parts:
Action:
GET
Path: https://graph.cofactr.com/products/
Query Params:
q={url encoded string of mpn, keywords, etc}
schema=product-v0
external=true
limit=10
search_strategy="default"
Response:
{
"data": [
{ each object matches product data schema specified above }
]
}
Bulk Find Products
An endpoint is available that allows bulk requests for multiple finds to be made with one call that are then batched and asynchronously executed within the Component Cloud service.
Action:
POST
Path: https://graph.cofactr.com/batch/products/
Body:
{
"batch":
[
{"method": "GET", "relative_url": "?q={mpn1}&external=true"},
{"method": "GET", "relative_url": "?q={mpn2}&external=true"},
{"method": "GET", "relative_url": "?q={mpn...}&external=true"}
]
}
Response:
{
"data":
[
[ { 0-10 product responses that match the mpn1 query each object matches product data schema specified above } ],
[ { 0-10 product responses that match the mpn2 query each object matches product data schema specified above } ],
[ { 0-10 product responses that match the mpn... query each object matches product data schema specified above } ]
]
}
Search Strategies
When you are searching for a part in Cofactr Component Cloud or finding a match for an MPN while parsing a BOM, we offer multiple search algorithms to choose between. Depending on the circumstances, one of these search strategies will likely be the best fit for your application.
Applicable Endpoints
The following endpoints accept a search_strategy query parameter:
GET Products: /products/
POST Products Batch: /batch/products/
Search Strategy Options
default
Example
/products/?q=VREF%20Analog%20Devices&search_strategy=default&schema=product-v0
Behavior
Products are selected where one of the following is true:
Full query or one of the words in the query auto-completes to the product's MPN.
Full query or one of the words in the query is an exact match to one of the product's alt MPNs or distributor SKUs.
One of the words in the query is an exact match to the product's Cofactr ID, deprecated Cofactr ID, customer ID, a word in the Cofactr classification, or a word in the description.
Recommended Usage
Default is recommended for powering search bars. The Part Search in the Cofactr Platform uses this search strategy.
mpn_sku_mfr
Example
/products/?q=MAX6101EUR%2BT&search_strategy=mpn_sku_mfr&schema=product-v0
Behavior
Tailored for a query composed of an MPN, optionally followed by a manufacturer. Products are scored based on how well their MPN, alt MPNs, SKUs, and manufacturer match the query. They're divided into tiers based on their score. When high-scoring results that are likely a match are present, lower-scoring results are filtered out to eliminate noise. Results are then sorted by inventory in descending order.
Recommended Usage
This strategy is recommended for BOM upload/matching applications. The BOM upload in the Cofactr platform uses this search strategy as its starting point, although additional matching logic is applied to the results.
mpn_exact
Example
/products/?q=MX25LM25645GXDI00&external=false&search_strategy=mpn_exact&schema=product-v0
Behavior
Products are selected where the given query matches one of the product's MPNs (including infrequently used alternative MPNs).
Recommended Usage
This search strategy is not recommended for general use.
mpn_exact_mfr
Example
/products/?q=mpn%3DAD780BRZ%26mfr%3DAnalog%20Devices&search_strategy=mpn_exact_mfr&schema=product-v0
/products/?q=mpn%3DAD780BRZREEL7%26mpn%3DAD780BRZ-REEL7DKR&search_strategy=mpn_exact_mfr&schema=product-v0
Behavior
Products are selected where all of the following is true:
One of the given MPNs matches one of the product's MPNs.
If manufacturers are given, the product's manufacturer must match one of them.
Any number of MPNs and manufacturers can be provided.
Recommended Usage
This search strategy is not recommended for general use.