API V1

Deprecated

Get Diamond

get

Look up a single diamond in Tracr and return its data if it exists.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Responses

200

Successful Response

application/json

A simplified set of data about a Tracr-registered diamond.

caratsstringRequired

The weight of the diamond in carats

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,3}0*$

claritystring · enum · nullableOptional

Clarity of the diamond

Possible values:

colourstring · enum · nullableOptional

Colour of the diamond

Possible values:

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

display_colourstring · nullableOptional

Formatted Fancy colour (Intensity + Overtone + Colour) or colour from the standard scale

fancy_colourstring · enum · nullableOptional

The fancy colour of the diamond.

Possible values:

provenancestring · nullableOptional

The provenance name of the diamond.

shapestring · enumRequired

Shape of polished diamond.

Possible values:

404

Returned when a Diamond is not found in the Tracr network.

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

get/v1/diamonds/{diamond_id}

HTTPcURLJavaScriptPython

GET /v1/diamonds/{diamond_id} HTTP/1.1
Accept: */*

{
  "assets": [
    {
      "asset_type": null,
      "content_hash": null,
      "created_at": null,
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": null,
      "extension": null,
      "filename": null,
      "gallery": null,
      "gallery_priority": null,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "image_type": null,
      "is_hero": null,
      "label": null,
      "updated_at": null
    }
  ],
  "carats": "text",
  "clarity": "FL",
  "colour": "D",
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "display_colour": "text",
  "fancy_colour": "BK",
  "provenance": "text",
  "shape": "Asscher"
}

Deprecated

Upload Diamond Grading Certificate

post

Add a grading certificate to a diamond in Tracr.

Accepts a multipart/form-data request.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Body

application/x-www-form-urlencoded

certificate_filestring · binaryRequired

The certificate file. Must be an application/pdf file, otherwise the upload will be rejected.

graded_datestring · date-time · nullableOptional

The graded date of the diamond as an ISO 8601 string

grader_certificate_nostring · nullableOptional

The grader certificate number

grader_inscription_nostring · nullableOptional

The grader inscription number

grader_report_nostring · nullableOptional

The grader report number

grading_labstring · nullableOptional

Responses

201

Successful Response

application/json

Sent when an inscription number or certificate has been added to a diamond.

hashstringRequired

The hash of the uploaded inscription number data.

404

Returned when a Diamond is not found in the Tracr network.

application/json

406

Returned when certificate_file is not an application/pdf file.

application/json

409

Returned when a given grading cert. has already been uploaded for a given diamond.

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

post/v1/diamonds/{diamond_id}/certificate

HTTPcURLJavaScriptPython

POST /v1/diamonds/{diamond_id}/certificate HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 179

"certificate_file='binary'&graded_date='2026-08-08T00:07:19.987Z'&grader_certificate_no='text'&grader_inscription_no='text'&grader_report_no='text'&grading_lab='text'"

{
  "hash": "text"
}

Deprecated

Add Diamond Inscription Number

post

Add an inscription number to a diamond in Tracr.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Body

application/json

The data required to add an inscription number to a diamond.

inscription_datestring · date-time · nullableOptional

inscription_grading_labstring · nullableOptional

inscription_numberstring · min: 1Required

The inscription number to add to the diamond. Must have a non-zero length.

Responses

201

Successful Response

application/json

Sent when an inscription number or certificate has been added to a diamond.

hashstringRequired

The hash of the uploaded inscription number data.

404

Returned when a Diamond is not found in the Tracr network.

application/json

409

Returned when a given inscription number has already been uploaded for a given diamond.

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

post/v1/diamonds/{diamond_id}/inscription-number

HTTPcURLJavaScriptPython

POST /v1/diamonds/{diamond_id}/inscription-number HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "inscription_date": "2026-08-08T00:07:19.987Z",
  "inscription_grading_lab": "text",
  "inscription_number": "text"
}

{
  "hash": "text"
}

Deprecated

Validate Diamond

post

Validate that a set of diamond data matches that stored in Tracr.

This endpoint uploads the sarine scan file to the diamond's Tracr instance, then notifies the DiamondID service that it needs to perform an identify-polished operation on the diamond.

The success or failure of this operation can be determined by GETing /diamonds/{diamond_id}/validate/status.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Body

multipart/form-data

sarine_scanstring · binaryRequired

Responses

202

Returned when a validation request is accepted for processing.

application/json

A response to a request for the validation of a diamond.

diamond_idstringRequired

The ID of the diamond for which validation has been requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

request_idstringRequired

The unique ID for this validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

status_urlstringRequired

The URL from which to fetch the status of this validation request via an HTTP GET

verification_statusstringOptional

The current status of the verification request

Default: Pending

404

Returned when a Diamond is not found in the Tracr network.

application/json

406

Returned when the sarine_scan file is not valid.

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

post/v1/diamonds/{diamond_id}/validate

HTTPcURLJavaScriptPython

POST /v1/diamonds/{diamond_id}/validate HTTP/1.1
Content-Type: multipart/form-data
Accept: */*
Content-Length: 24

{
  "sarine_scan": "binary"
}

{
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "request_id": "e1mv3nn4n10kd1lw6mde6sums",
  "status_url": "text",
  "verification_status": "Pending"
}

Deprecated

Get Answered Responses

get

Return all answered or errored validation requests for a diamond.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Responses

200

Successful Response

application/json

The full feedback on a validation operation, as returned by GIS.

diamond_idstringRequired

The ID of the diamond for which validation was requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

request_idstringRequired

The unique ID of the validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

requested_atstring · date-timeRequired

The UTC datetime at which the validation request was created.

verification_descriptionstringRequired

A message from DiamondID describing the validation status.

verification_statusstring · enumRequired

The validation status returned by DiamondID.

Possible values:

404

Returned when no validation request has been made for a given diamond.

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

get/v1/diamonds/{diamond_id}/validate/answered

HTTPcURLJavaScriptPython

GET /v1/diamonds/{diamond_id}/validate/answered HTTP/1.1
Accept: */*

[
  {
    "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
    "request_id": "e1mv3nn4n10kd1lw6mde6sums",
    "requested_at": "2026-08-08T00:07:19.987Z",
    "verification_description": "text",
    "verification_error": {
      "ANY_ADDITIONAL_PROPERTY": {
        "loc": [
          "text"
        ],
        "msg": "text",
        "type": "text"
      }
    },
    "verification_status": "Error"
  }
]

Deprecated

Get Historic Validation Requests For Diamond

get

Return all answered or errored validation requests for a diamond.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Responses

200

Successful Response

application/json

A ValidationFeedback object used for reporting historic data.

diamond_idstringRequired

The ID of the diamond for which validation was requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

expiredbooleanRequired

True if DiamondID did not respond to the request in a timely fashion.

request_idstringRequired

The unique ID of the validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

requested_atstring · date-timeRequired

The UTC datetime at which the validation request was created.

verification_descriptionstring · nullableOptional

A message from DiamondID describing the validation status.

verification_statusstring · enumOptional

The validation status returned by DiamondID.

Default: PendingPossible values:

404

Returned when no validation request has been made for a given diamond.

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

get/v1/diamonds/{diamond_id}/validate/historic

HTTPcURLJavaScriptPython

GET /v1/diamonds/{diamond_id}/validate/historic HTTP/1.1
Accept: */*

[
  {
    "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
    "expired": true,
    "request_id": "e1mv3nn4n10kd1lw6mde6sums",
    "requested_at": "2026-08-08T00:07:19.987Z",
    "verification_description": "text",
    "verification_error": {
      "ANY_ADDITIONAL_PROPERTY": {
        "loc": [
          "text"
        ],
        "msg": "text",
        "type": "text"
      }
    },
    "verification_status": "Pending"
  }
]

Deprecated

Get Latest Request Status

get

Return the latest non-expired validation request for a diamond.

This endpoint is deprecated, as it does not return a full picture of the diamond's validation history.

Instead, use /v1/diamonds/{diamond_id}/validate/{request_id} to fetch the status of a specific request, or /v1/diamonds/{diamond_id}/validate/answered to fetch the status of all requests answered by DiamondID.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Responses

200

Returned when a validation request has been answered by the DiamondID service.

application/json

The full feedback on a validation operation, as returned by GIS.

diamond_idstringRequired

The ID of the diamond for which validation was requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

request_idstringRequired

The unique ID of the validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

requested_atstring · date-timeRequired

The UTC datetime at which the validation request was created.

verification_descriptionstringRequired

A message from DiamondID describing the validation status.

verification_statusstring · enumRequired

The validation status returned by DiamondID.

Possible values:

202

Returned when a validation request has been made, but has not yet been answered by DiamondID.

application/json

404Error

application/json

410Error

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

get/v1/diamonds/{diamond_id}/validate/status

HTTPcURLJavaScriptPython

GET /v1/diamonds/{diamond_id}/validate/status HTTP/1.1
Accept: */*

{
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "request_id": "e1mv3nn4n10kd1lw6mde6sums",
  "requested_at": "2026-08-08T00:07:19.987Z",
  "verification_description": "text",
  "verification_error": {
    "ANY_ADDITIONAL_PROPERTY": {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  },
  "verification_status": "Error"
}

Deprecated

Check Validation Request Status

get

Return the status of a validation Request.

Path parameters

request_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Responses

200

Returned when a validation request has been answered by the DiamondID service.

application/json

The full feedback on a validation operation, as returned by GIS.

diamond_idstringRequired

The ID of the diamond for which validation was requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

request_idstringRequired

The unique ID of the validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

requested_atstring · date-timeRequired

The UTC datetime at which the validation request was created.

verification_descriptionstringRequired

A message from DiamondID describing the validation status.

verification_statusstring · enumRequired

The validation status returned by DiamondID.

Possible values:

202

Returned when a validation request has been made, but has not yet been answered by DiamondID.

application/json

404Error

application/json

410Error

application/json

422

Validation Error

application/json

500

Returned when an internal error occurred within GIS.

application/json

get/v1/diamonds/{diamond_id}/validate/{request_id}

HTTPcURLJavaScriptPython

GET /v1/diamonds/{diamond_id}/validate/{request_id} HTTP/1.1
Accept: */*

{
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "request_id": "e1mv3nn4n10kd1lw6mde6sums",
  "requested_at": "2026-08-08T00:07:19.987Z",
  "verification_description": "text",
  "verification_error": {
    "ANY_ADDITIONAL_PROPERTY": {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  },
  "verification_status": "Error"
}