Guidelines

The API is a collection of services that will allow you to easily upload and update your certification and material data in Origin data hub.

What to do to use the public API

Step 1 - Obtain access

To be able to use the Origin data hub public API (aka Origin Connect API or CAPI), you must first contact Origin support at support@origin.build

The public API is secured and you must be provided with an access token to be able submit request.

The request header must contain authorization: Bearer {YOUR_ACCESS_TOKEN}.

Step 2 - Plan your integration

Depending on your needs, you'll first have to target which service(s) to use from the services catalog.

For example, if you need to upload one or more certifications in Origin data hub, the services you need to use is CertificationsCreate

The services names are defined according to the following convention

[(Entity|Entities)Action]

• Entity : The entity name in singular form, meaning the service deal with a single entity a the time
• Entities : The entity name in plural form, meaning the service deal with one or more entities at the time
• Action : The action that is performed on the prefix entity|entities

For example, according to this convention, CertificationsCreate will allow you to create one or more certifications in Origin.

Step 3 - Map your data to the service payload

Each service describes the message format (or the payload) that it supports. You will need to get familiar with the documentation of the services you will use to be able to map your data the right way and submit it to Origin.

Step 4 - Before submitting your data

Please use the Check Service (Check v1 or Check v2) to make sure your setup and your access token are working.

If you receive a response with 401 HTTP status (Unauthorized), it is possible that your access token is not present in the request header.

Please review your request header. It must contain authorization: Bearer {YOUR_ACCESS_TOKEN}.

Step 5 - Submit your data

Once everything is set, you can proceed and submit your data to Origin public API.

• Split payloads into batches:
  • Recommended maximum is 25 entities per request, even though no hard limit is currently enforced.
  • This reduces timeout risk (60 seconds) and avoids losing the externalId-to-originId correlation in create responses.
  • If correlation is lost, it can still be rebuilt by searching with externalId, but this is less efficient.

Step 6 - Map your ids to Origin ids

IDs in Origin

IDs let you uniquely identify entities (materials, certifications, etc.).

From the Origin Connect API (CAPI), each entity can be referenced using:

• originId: The unique ID assigned by Origin. Across all Origin, one originId maps to exactly one entity.

• externalId: Your own internal ID from your Content Management System (CMS). Mapping your CMS IDs to Origin entities helps automate synchronization between both systems.

• externalId has no enforced format restriction in CAPI, to keep flexibility across different client systems.

When you create an entity in CAPI, an originId is generated for this entity.

This originId is the unique identifier of your entity in Origin data hub and it will be used for any update or delete action on this entity.

The originId is returned in the response of the create service in the result.correlations array. You can find the mapping between your externalId and the generated originId in this array.

When creating entities through CAPI, strongly map each externalId to its originId for future operations.

When updating entities, you can use either originId or externalId, but originId is strongly recommended.

⚠️ Note : The externalId is not always present on existing entities in Origin data hub that have not been created through the API. If you want to have an externalId for all your entities, you can use the update service of the API to add an externalId to your existing entities in Origin data hub. The originId is needed to add or update an externalId to an existing entity in Origin data hub.

⚠️ Note : The uniqueness of the externalId is not guaranteed across all entities in Origin data hub. It is recommended to use the originId to avoid conflicts.

Step 7 - Get help from Origin support if needed

If you need help completing your integration process, contact Origin support at support@origin.build.

Search for an entity in Origin data hub

If you want to search for an entity in Origin data hub, you can use the Search services like MaterialsSearch or CertificationsSearch.

Search services support searching by originId (ORIGINID), which uniquely identifies an entity in Origin data hub, or by externalId (EXTERNALID), your own internal identifier from your CMS. Note that externalId is not guaranteed to be unique across entities in Origin data hub. Other search criteria are also supported — please refer to the documentation of each search service for more details.

You can use the criterion MODIFIEDSINCE to search for entities that have been created or updated since a specific date. This criterion is useful to synchronize your CMS with Origin data hub by searching for entities that have been created or updated since the last synchronization date.

⚠️ Note : After create/update operations, changes may not appear immediately due to indexing, file downloads, calculations, and background jobs. If you search for an entity immediately after creating/updating it, it may not be found. If this happens, please wait a few minutes and try again.

Working with Files in Entities

Notes

• The materials[].logoUrl field often causes confusion.
  • In Origin, this field is used for the material thumbnail and the first material image.
  • This image can also be set in Origin Website, Material edit page, Image section, by checking Featured Image.
• Filename behavior:
  • The filename is derived from the URL segment after the last slash.
  • If the URL ends with a slash, that trailing slash is ignored first.
  • Example: https://mywebsite.tld/img/myImage.png/ becomes myImage.png.

General Certification, Declaration, and TestReport (CDTR)

Notes

• Certification, Declaration, and TestReport endpoints have very similar structures and behavior.
• Certification endpoints map to standards where standardType = STANDARD:
  • /connect/v2/standards?locale=en&pageNumber=1&pageSize=100&standardType=STANDARD
• Declaration endpoints map to standards where standardType = LABEL:
  • /connect/v2/standards?locale=en&pageNumber=1&pageSize=100&standardType=LABEL
• TestReport endpoints map to standards where standardType = TESTREPORT:
  • /connect/v2/standards?locale=en&pageNumber=1&pageSize=100&standardType=TESTREPORT
  • ⚠️ Note : Create, update, and delete endpoints are not currently available for TestReport.

Notes below refer to certifications, but most also apply to declarations:

• Certifications provided by reporting bodies cannot be updated.
• If you assign externalId to an existing certification for the first time, you must reference them by originId.
• You cannot link materials from certification endpoints (unlike the Origin certification edit page). Use material endpoints for linking.
• Unpublishing a certification via CAPI (removing certifications[].channels[].name = ORIGIN) has the same effect as unpublishing on the Origin website:
  • Associated materials are detached from that certification.
• Deleting a certification via CAPI has the same effect as deleting it on the Origin website:
  • If still linked to materials, it is soft-deleted (Historical) and remains accessible in Origin.
  • If not linked, it is hard-deleted.
  • Deletion requests should be kept to the bare minimum.

Material Management via CAPI

Notes

• Material brand is optional. If omitted, the main brand is applied.
  • You can identify the main brand through the BrandsGet endpoint, where it is flagged as result.data[].isMainBrand = "true".
• materials[].managementPermission is mandatory.
  • Highly recommended value: COMPANY_EDITABLE, to avoid permission issues.
  • This permission was previously editable in Origin, but is no longer changeable.

• Company package limits may trigger error CE00003:

  example limits include (numbers are indicative and may vary by company):

  • Maximum brands: 15
  • Maximum documents per material: 10
  • Maximum images per material: 10
  • Maximum documents per material SKU: 10
  • Maximum images per material SKU: 10

Certifications Linked to Materials

Notes

• Automating material-to-certification links is difficult.
• No universal IDs exist to map both entities automatically, so manual intervention is usually required at least once to create an initial mapping.
• Deleting a material removes all certification links.
  • Re-creating the material requires rebuilding all certification links.
  • Keep deletions to the absolute minimum.
• To link a material to one of your own certifications via CAPI, use materials[].connectedCertifications[].originId.
• To link a material to a reporting body certification, you can only use materials[].connectedCertifications[].originId.

Multilingual (Advanced Guidelines)

The Api supports Multilingual Entities entities such as Materials (v2 only), Certifications (v2 only), Declaration (v2 only), Brands (v2 only) and Collections (v2 only).

Supported locale : de, es_MX, en, fr, zh_CN

The following steps will be help you to add another language to your entities.

Step 1 Create your entity

If you already have created your entity, you can pass to Step 2

We highly recommand that you create your entity in English first ("locale": "en"). The majority of users use this language and it is used as fallback language.

Example Create a Material in English (See MaterialsCreate v2 for more details)

Request Payload

{
    "materials": [
        {
            "locale": "en",
            "externalId": "ABC-001",
            "managementPermission": "COMPANY_EDITABLE",
            "name": "My Material",
            "description": "A description for My Material"
        }
    ]
}

Step 2 Update your entity with another language

Then, if you want to have a different name and description in another language for your entity, you can update it in that language.

You can take the externalId or the originId for the entity update.

Example Update a Material in French (See MaterialsUpdate v2 for more details)

Request Payload

{
    "materials": [
        {
            "locale": "fr",
            "originId": "88dada05-5d38-4b60-91b9-f1bf9d6bf5dd",
            "name": "Mon Matériau",
            "description": "Une description pour Mon Matériau"
        }
    ]
}

You can repeat this step for all other supported locales you want to add.

Advanced Guidelines

• Multilingual Certification Features
• Multilingual Declaration Features
• Multilingual Material Features