Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Get Started with Tracr Search Bulk

The Tracr Search Bulk API allows to search for up to 1000 diamonds from multiple participants of Tracr and retrieve the history of the diamond up to the original rough.

You need to know

The Tracr Search Bulk API is only available for authenticated users. For more details please contact support@tracr.com.

Before you start

  • Contact Tracr Support (support@tracr.com) to obtain authentication credentials.

  • Collect the platform ID (UUID - the participant's unique identifier) and the Tracr ID of the polished diamond(s) from the owner of the diamond(s) that you want to query.

Platform ID

You will need the platform ID to be able to search other user's Tracr instances. This can be collected from the URL in either UAT or Prod: {platform_id}.uat.tracr.com or {platform_id}.tracr.com

API security

The API use OAuth 2.0 authentication. Tracr Support will provide a Client ID and Client Secret during the technical onboarding.

Generate a JWT token

Call POST https://auth.tracr.com/oauth/token

{
  "client_id":"<client_id>",        
  "client_secret":"<client_secret>",
  "audience":"https://search.tracr.network/v1",
  "grant_type":"client_credentials"
}
{
  "access_token": "<access_token>",
  "token_type": "Bearer"
}

Pass the token to the endpoint

To pass the token to the API, provide it in the Authorization header.

Get the ancestry for bulk diamonds

Call POST /v1/bulk/traceability-ancestry

Request

The request object is a collection of search items. Each search item is related to a platform ID and a list of Tracr IDs.

Example:

  • Diamonds – A list of Tracr IDs from the given platform IDs.

  • Platform ID - The unique Tracr identifier of the participant. This ID is static.

  • Modified Since - An optional filter to retrieve only diamonds updated after a specific date.

Results

An array of Result items.

Result item

  • Status - The status of the query for the platform. Status can be success or unauthorised.

  • Platform ID - The unique Tracr identifier of the participant.

  • Results - A dictionary with the search results. Key : Tracr ID Value : A collection of diamonds including ancestors.

Unauthorised access

Each participant needs to authorise the API to access the inventory. If the permission is missing, the API cannot request any diamonds for a platform id.

Example:

The participant needs to raise a ticket with Tracr Support (support@tracr.com) to get the permission set up.