All Collections
How do I use Cofactr APIs?
Cofactr Platform API Documentation
Cofactr Platform API Documentation

Getting started with the Cofactr Platform API

Matthew Haber avatar
Written by Matthew Haber
Updated over a week ago

Overview

Capabilities

Read + write access to Cofactr Platform data such as BOMs, Programs, and Stock.

Structure

HTTP REST API that is structured around the Cofactr Platform App paradigm.

Optimized For

Integrating the Cofactr platform into 3rd party or custom in-house developed systems.

Not Optimized For

Data science and analytics or powering multi-tenant 3rd party products

Licensing

Cofactr Platform API access is available in the Cofactr Custom plan. Please contact [email protected] to request an API key for your account. Usage is subject to the terms of your Subscription Agreement. Sandbox accounts are available upon request for Cofactr customers and 3rd party integration partners.

Getting Started

Endpoints

Detailed documentation for all Platform API endpoints is available at http://developers.cofactr.com/

The base URL for the Cofactr Platform API is https://flagship-api.cofactr.com/

For example, the fetch all BOMs, you would make a GET request to https://flagship-api.cofactr.com/v1/boms/

ℹ️ Tip

Make sure to include the trailing / at the end of the request URL. Your request will not work without it. https://flagship-api.cofactr.com/v1/boms/ will succeed but https://flagship-api.cofactr.com/v1/boms will fail

Authentication

Each request must include an Authorization header with the API key provided by Cofactr. Authorization: Api-Key {your api key here}

ℹ️ Tip

“Api-Key” is case sensitive

This API key will give you access to data associated with your account's primary Org as well as any Sub-Orgs.

If you would like to scope a response to only include data associated with a single Org, include an org_id URL query parameter with the ID of the Org.

For example https://flagship-api.cofactr.com/v1/boms/?org_id={UUID of org here}

POST requests will default to associating the newly created record with the primary Org associated with your API key unless an org_id URL query parameter is included with the ID of a Sub-Org.

⛔ 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.

Sandbox Orgs

Cofactr offers a Sandbox Sub-Org(s) for use in testing and development. Please contact [email protected] to request the creation of a Sandbox Sub-Org.

Sandbox Sub-Orgs behave exactly the same as any other Sub-Org with the following exceptions:

  • Within the Cofactr Platform, Sandbox orgs will be denoted by a ⛱️ beach umbrella icon in the Active Org selector dropdown at the top of the page

  • Any Order created within a Sandbox org will not actually be processed and will remain in a requested status indefinitely.

  • Managed Inventory services such as Handling Tasks and Shipments created for a Sandbox org will not actually be carried out and will remain in a requested status indefinitely.

  • When viewing data within the Platform using Blended View Mode or using the Warehouse App (which always operates in Blended View Mode), data associated with Sandbox orgs will be filtered out, unless Sandbox Mode is enabled, in which case only data associated with Sandbox orgs will be displayed.

Cofactr Unified Data Layer

The Cofactr Platform and Platform API run on Cofactr’s Unified Data layer. We recommend exploring the Cofactr Platform to learn about the connections between different data types in a hands-on manner.

Metadata Fields

Many data types within Cofactr, including BOM, BOM Line, and Program, support a metadata field.

BOM Line Metadata

BOM Line records accept an arbitrary set of key-value pairs, which will be displayed as additional columns in the BOM App within the Parts tab for a given BOM.

{ "Customer Reference Number": "xyz12" }

Program Metadata

Programs accept an arbitrate set of key-value pairs, which are not displayed within the platform, but are available via API. They also accept two special-purpose objects:

The rowData object is accepts a Cofactr Part ID and a set of arbitrary key-value pairs for each Part ID which will be displayed as additional columns in the BOM App within the Parts tab for a given BOM.

The customFields object accepts a set of key-value pairs that correspond to record-level custom fields that have been configured on your account. Please contact [email protected] to configure custom fields.

{
  "rowData": {
    "cofactr part id": {"Field Name": "value"}
  },
  "customFields": {
    "fieldName": "value"
  }
}

Parsing Raw BOM Line Data

Uploading a BOM into Cofactr is a common API use case. If you already have the Cofactr ID for each part in the BOM, you can POST that BOM data to /v1/boms/

If you have not already matched each part to a Cofactr ID, you can POST the BOM data to /v1/parse_raw_bom/, and the Cofactr system will do it’s best to match each part to the correct Cofactr ID. This uses the same logic that would be used if you uploaded a CSV or Excel file via the platform user interface.

Order Submission API

To access order execution via API, please contact [email protected]. Due to the risk of incurring significant inadvertent charges, we need to discuss your use case before enabling this API.

Did this answer your question?