Deprecated

Deprecated

Get Diamonds

get

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/diamonds/

This endpoint is deprecated. Please use the /v2/diamond/ endpoint instead.

Query parameters

participant_idstring[]Optional

User supplied identifier for the diamond, specific to this Tracr instance. Synonymous with ERP ID and Stock ID.

Default: []

diamond_idstring[]Optional

Tracr Diamond ID

Default: []

is_archivedbooleanOptional

List archived diamonds

Default: false

pageinteger · min: 1OptionalDefault: 1

sizeinteger · min: 1 · max: 1000OptionalDefault: 100

Responses

200

Successful Response

application/json

nextstring · nullableOptional

The URL for the next page. Excluded from the response if there is no next page.

pageinteger · min: 1 · nullableRequired

The number of the current page.

pagesinteger · nullableOptional

The total number of pages.

previousstring · nullableOptional

The URL for the previous page. Excluded from the response if there is no previous page.

totalintegerRequired

The total number of diamonds across all pages.

401

Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource.

403

Forbidden: The application does not have sufficient permissions for this operation.

422

Unprocessable Entity, request JSON body is not as per specification

500

Internal Server Error. If this error persists please contact the Platform Admin team.

get/diamonds/

HTTPcURLJavaScriptPython

GET /diamonds/ HTTP/1.1
Host: api.<id>.tracr.network
Accept: */*

{
  "next": "text",
  "page": 1,
  "pages": 1,
  "previous": "text",
  "results": [
    {
      "archived_at": "2026-08-08T00:25:41.944Z",
      "assurance_level": "assured",
      "box_description": "text",
      "box_id": "text",
      "current_stage": "polished",
      "data_requests": [
        {
          "created_at": "2026-08-08T00:25:41.944Z",
          "data_request_type": "three_d_plan",
          "errors": [
            "text"
          ],
          "id": "text",
          "status": "pending",
          "updated_at": "2026-08-08T00:25:41.944Z"
        }
      ],
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_parent_id": "e1mv3nn4n10kd1lw6mde6sums",
      "entity_specific_tags": {
        "dit_session_id": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "grading": [
        {
          "carats": "text",
          "clarity": "FL",
          "colour": "D",
          "crown_angle": "text",
          "crown_height": "text",
          "culet_condition": "P",
          "culet_size": "EL",
          "cut_grade": "I",
          "depth": "text",
          "depth_percent": "text",
          "diameter_maximum": "text",
          "diameter_minimum": "text",
          "display_colour": "text",
          "fancy_colour": "BK",
          "fancy_colour_intensity": "F",
          "fancy_colour_overtone": "text",
          "fluorescence_colour": "B",
          "fluorescence_intensity": "VS",
          "girdle_condition": "P",
          "girdle_thickness_from": "Extremely Thick",
          "girdle_thickness_to": "Extremely Thick",
          "graded_date": "2026-08-08T00:25:41.944Z",
          "grader_certificate_number": "text",
          "grader_clarity_characteristics": "text",
          "grader_colour": "text",
          "grader_inscription_numbers": [
            "text"
          ],
          "grader_report_comments": "text",
          "grader_report_number": "text",
          "grader_report_type": "text",
          "grader_shape": "text",
          "grading_certificate_description": "text",
          "grading_certificate_filename": "text",
          "grading_certificate_hash": "text",
          "grading_lab": "AGS",
          "id": "text",
          "is_active": true,
          "is_selectable": true,
          "length": "text",
          "measurement_text": "text",
          "pavillion_angle": "text",
          "pavillion_percent": "text",
          "polish_quality": "I",
          "shape": "Asscher",
          "source": "gis",
          "supplementary_files": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "symmetry": "I",
          "table_percent": "text",
          "validation_level": "validation",
          "width": "text"
        }
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "is_current": true,
      "lifecycle_state": "destroyed",
      "parent_id": "123e4567-e89b-12d3-a456-426614174000",
      "participant_id": "text",
      "participant_parent_id": "text",
      "participant_timestamp": "2026-08-08T00:25:41.944Z",
      "polished": {
        "carats": "text",
        "clarity": "FL",
        "colour": "D",
        "crown_angle": 1,
        "crown_height": 1,
        "culet_condition": "P",
        "culet_size": "EL",
        "cut_grade": "I",
        "depth": 1,
        "depth_percent": 1,
        "diameter_maximum": 1,
        "diameter_minimum": 1,
        "display_colour": "text",
        "fancy_colour": "BK",
        "fancy_colour_intensity": "F",
        "fancy_colour_overtone": "text",
        "fluorescence_colour": "B",
        "fluorescence_intensity": "VS",
        "girdle_condition": "P",
        "girdle_thickness_from": "Extremely Thick",
        "girdle_thickness_to": "Extremely Thick",
        "grading_certificates": [
          {
            "description": "text",
            "filename": "text",
            "graded_date": "text",
            "grader_certificate_no": "text",
            "grader_inscription_no": "text",
            "grader_report_no": "text",
            "grading_lab": "text",
            "hash": "text"
          }
        ],
        "images": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text",
            "image_type": "default"
          }
        ],
        "length": 1,
        "pavillion_angle": 1,
        "pavillion_percent": 1,
        "polish_quality": "I",
        "scan": {
          "description": "text",
          "filename": "text",
          "hash": "text",
          "scan_device_manufacturer": "text",
          "scan_device_model": "text",
          "scan_software_name": "text",
          "scan_software_version": "text"
        },
        "scan_reports": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text",
            "scan_device_manufacturer": "text",
            "scan_device_model": "text",
            "scan_software_name": "text",
            "scan_software_version": "text"
          }
        ],
        "shape": "Asscher",
        "supplementary_files": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text"
          }
        ],
        "symmetry": "I",
        "table_percent": 1,
        "videos": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text"
          }
        ],
        "width": 1
      },
      "polished_objective_verification_results": [
        {
          "id": "text",
          "source": "diadna",
          "status": "in_progress"
        }
      ],
      "possession_state": "destroyed",
      "producer_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provenance": {
        "country_code": "text",
        "is_country_code_available": true,
        "is_locked": false,
        "mine_name": "text",
        "provenance_name": "text",
        "provenance_type": "text"
      },
      "rough": {
        "carats": "text",
        "colour": "D",
        "display_colour": "text",
        "fancy_colour": "BK",
        "fancy_colour_intensity": "F",
        "fancy_colour_overtone": "text",
        "fluorescence_colour": "B",
        "fluorescence_intensity": "VS",
        "images": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text",
            "image_type": "default"
          }
        ],
        "model": "text",
        "plan": {
          "description": "text",
          "filename": "text",
          "hash": "text",
          "plan_software_manufacturer": "text",
          "plan_software_name": "text",
          "plan_software_version": "text",
          "scan_device_manufacturer": "text",
          "scan_device_model": "text"
        },
        "plan_reports": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text",
            "plan_software_manufacturer": "text",
            "plan_software_name": "text",
            "plan_software_version": "text",
            "scan_device_manufacturer": "text",
            "scan_device_model": "text"
          }
        ],
        "quality": "text",
        "scan": {
          "description": "text",
          "filename": "text",
          "hash": "text",
          "scan_device_manufacturer": "text",
          "scan_device_model": "text",
          "scan_software_name": "text",
          "scan_software_version": "text"
        },
        "scan_reports": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text",
            "scan_device_manufacturer": "text",
            "scan_device_model": "text",
            "scan_software_name": "text",
            "scan_software_version": "text"
          }
        ],
        "stress": "text",
        "supplementary_files": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text"
          }
        ],
        "videos": [
          {
            "description": "text",
            "filename": "text",
            "hash": "text"
          }
        ]
      },
      "rough_check": true,
      "rough_objective_verification_results": [
        {
          "id": "text",
          "source": "diadna",
          "status": "in_progress"
        }
      ],
      "schema_version": "text",
      "sight_no": 1,
      "sight_year": 1,
      "supplementary_tags": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "system_timestamp": "2026-08-08T00:25:41.944Z",
      "three_d_plan_available": false,
      "unlock_status": "locked",
      "verification_description": "verified record",
      "verification_status": "Verified",
      "verification_status_modified_at": "2026-08-08T00:25:41.944Z",
      "version_id": "text"
    }
  ],
  "total": 1
}

Deprecated

Update Polished Diamond

patch

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/diamonds/{id}/polished

This endpoint is deprecated. Please use the /v2/diamond/{id}/polished endpoint instead.

Path parameters

idany ofRequired

The ID (UUID) of the diamond to update.

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

or

string · uuidOptional

Body

application/json

participant_idstring · nullableOptional

User supplied identifier for the diamond, specific to this Tracr instance. Synonymous with ERP ID and Stock ID. This field must be unique within the box/shipment the diamond is registered against. Can be updated as long as the the diamond's possession_state is held.

Pattern: ^\S(.*\S)?$

participant_timestampstring · date-timeRequired

Responses

200

Successful Response

application/json

A diamond as returned from V1 API endpoints.

archived_atstring · date-time · nullableOptional

Timestamp indicating when this diamond was archived.
Tracr Class: entity_specific

assurance_levelstring · enumRequired

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: entity_specific

Possible values:

box_descriptionstring · nullableOptional

Tracr Class: entity_specific

box_idstring · nullableOptional

Identifier of the box/lot/shipment the diamond is registered against.
Tracr Class: entity_specific

current_stagestring · enumRequired

Indicates whether the diamond is rough or polished.
Tracr Class: traceability

Possible values:

diamond_idstringRequired

The diamond's unique identifier assigned by Tracr. Synonymous with Tracr ID.
Tracr Class: traceability

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

diamond_parent_idstring · nullableOptional

Tracr ID of the diamond's parent.
Tracr Class: traceability

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

idstring · uuidRequired

Legacy identifier of the diamond, superseded by diamond_id. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

is_currentbooleanRequired

Indicates whether the version of the diamond returned from the API is the latest version. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: entity_specific

lifecycle_statestring · enumRequired

Tracr Class: traceability

Possible values:

parent_idstring · uuid · nullableOptional

Legacy identifier of the diamond's parent, superseded by diamond_parent_id. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

participant_idstring · nullableOptional

User supplied identifier for the diamond, specific to this Tracr instance. Synonymous with ERP ID and Stock ID.
Tracr Class: entity_specific

participant_parent_idstring · nullableOptional

ERP of the diamond's parent.
Tracr Class: entity_specific

participant_timestampstring · date-timeRequired

User supplied timestamp of when the diamond was last modified.
Tracr Class: entity_specific

possession_statestring · enumRequired

Tracr Class: supplementary

Possible values:

producer_uuidstring · uuidRequired

Tracr platform identifier of the producer that first registered this diamond.
Tracr Class: traceability

rough_checkbooleanRequired

Indicates whether this diamond has passed rough objective verification. Prior to a diamond being unlocked the Rough Check status will always be false.
Tracr Class: supplementary

schema_versionstring · nullableOptional

Indicates the internal schema version used when putting the diamond on blockchain. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

sight_nointeger · nullableOptional

Tracr Class: entity_specific

sight_yearinteger · nullableOptional

Tracr Class: entity_specific

system_timestampstring · date-timeRequired

Tracr Class: entity_specific

three_d_plan_availablebooleanOptional

Indicates whether a 3D plan is available for the diamond.
Tracr Class: supplementary

Default: false

unlock_statusstring · enumRequired

Tracr Class: supplementary

Possible values:

verification_descriptionstringOptional

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

Default: verified record

verification_statusstring · enumOptional

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

Default: VerifiedPossible values:

verification_status_modified_atstring · date-time · nullableOptional

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: entity_specific

version_idstringRequired

The identifier of the diamond's current version. This changes to a new unique identifier each time the diamond is updated.
Tracr Class: traceability

401

Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource.

403

Forbidden: The application does not have sufficient permissions for this operation.

404

Diamond ID not found. A diamond, with the provided ID, does not exist.

409

Diamond is archived

412

Precondition check failed: The operation cannot be applied to the current state of the diamond.

422

Unprocessable Entity, request JSON body is not as per specification

500

Internal Server Error. If this error persists please contact the Platform Admin team.

patch/diamonds/{id}/polished

HTTPcURLJavaScriptPython

PATCH /diamonds/{id}/polished HTTP/1.1
Host: api.<id>.tracr.network
Content-Type: application/json
Accept: */*
Content-Length: 792

{
  "entity_specific_tags": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "participant_id": "text",
  "participant_timestamp": "2026-08-08T00:25:41.944Z",
  "polished": {
    "carats": 1,
    "clarity": "text",
    "colour": "text",
    "crown_angle": 1,
    "crown_height": 1,
    "culet_condition": "text",
    "culet_size": "text",
    "cut_grade": "text",
    "depth": 1,
    "depth_percent": 1,
    "diameter_maximum": 1,
    "diameter_minimum": 1,
    "fancy_colour": "text",
    "fancy_colour_intensity": "text",
    "fancy_colour_overtone": "text",
    "fluorescence_colour": "text",
    "fluorescence_intensity": "text",
    "girdle_condition": "text",
    "girdle_thickness_from": "text",
    "girdle_thickness_to": "text",
    "length": 1,
    "pavillion_angle": 1,
    "pavillion_percent": 1,
    "polish_quality": "text",
    "shape": "text",
    "symmetry": "text",
    "table_percent": 1,
    "width": 1
  },
  "supplementary_tags": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "archived_at": "2026-08-08T00:25:41.944Z",
  "assurance_level": "assured",
  "box_description": "text",
  "box_id": "text",
  "current_stage": "polished",
  "data_requests": [
    {
      "created_at": "2026-08-08T00:25:41.944Z",
      "data_request_type": "three_d_plan",
      "errors": [
        "text"
      ],
      "id": "text",
      "status": "pending",
      "updated_at": "2026-08-08T00:25:41.944Z"
    }
  ],
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "diamond_parent_id": "e1mv3nn4n10kd1lw6mde6sums",
  "entity_specific_tags": {
    "dit_session_id": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "grading": [
    {
      "carats": "text",
      "clarity": "FL",
      "colour": "D",
      "crown_angle": "text",
      "crown_height": "text",
      "culet_condition": "P",
      "culet_size": "EL",
      "cut_grade": "I",
      "depth": "text",
      "depth_percent": "text",
      "diameter_maximum": "text",
      "diameter_minimum": "text",
      "display_colour": "text",
      "fancy_colour": "BK",
      "fancy_colour_intensity": "F",
      "fancy_colour_overtone": "text",
      "fluorescence_colour": "B",
      "fluorescence_intensity": "VS",
      "girdle_condition": "P",
      "girdle_thickness_from": "Extremely Thick",
      "girdle_thickness_to": "Extremely Thick",
      "graded_date": "2026-08-08T00:25:41.944Z",
      "grader_certificate_number": "text",
      "grader_clarity_characteristics": "text",
      "grader_colour": "text",
      "grader_inscription_numbers": [
        "text"
      ],
      "grader_report_comments": "text",
      "grader_report_number": "text",
      "grader_report_type": "text",
      "grader_shape": "text",
      "grading_certificate_description": "text",
      "grading_certificate_filename": "text",
      "grading_certificate_hash": "text",
      "grading_lab": "AGS",
      "id": "text",
      "is_active": true,
      "is_selectable": true,
      "length": "text",
      "measurement_text": "text",
      "pavillion_angle": "text",
      "pavillion_percent": "text",
      "polish_quality": "I",
      "shape": "Asscher",
      "source": "gis",
      "supplementary_files": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "symmetry": "I",
      "table_percent": "text",
      "validation_level": "validation",
      "width": "text"
    }
  ],
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "is_current": true,
  "lifecycle_state": "destroyed",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "participant_id": "text",
  "participant_parent_id": "text",
  "participant_timestamp": "2026-08-08T00:25:41.944Z",
  "polished": {
    "carats": "text",
    "clarity": "FL",
    "colour": "D",
    "crown_angle": 1,
    "crown_height": 1,
    "culet_condition": "P",
    "culet_size": "EL",
    "cut_grade": "I",
    "depth": 1,
    "depth_percent": 1,
    "diameter_maximum": 1,
    "diameter_minimum": 1,
    "display_colour": "text",
    "fancy_colour": "BK",
    "fancy_colour_intensity": "F",
    "fancy_colour_overtone": "text",
    "fluorescence_colour": "B",
    "fluorescence_intensity": "VS",
    "girdle_condition": "P",
    "girdle_thickness_from": "Extremely Thick",
    "girdle_thickness_to": "Extremely Thick",
    "grading_certificates": [
      {
        "description": "text",
        "filename": "text",
        "graded_date": "text",
        "grader_certificate_no": "text",
        "grader_inscription_no": "text",
        "grader_report_no": "text",
        "grading_lab": "text",
        "hash": "text"
      }
    ],
    "images": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "image_type": "default"
      }
    ],
    "length": 1,
    "pavillion_angle": 1,
    "pavillion_percent": 1,
    "polish_quality": "I",
    "scan": {
      "description": "text",
      "filename": "text",
      "hash": "text",
      "scan_device_manufacturer": "text",
      "scan_device_model": "text",
      "scan_software_name": "text",
      "scan_software_version": "text"
    },
    "scan_reports": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "scan_device_manufacturer": "text",
        "scan_device_model": "text",
        "scan_software_name": "text",
        "scan_software_version": "text"
      }
    ],
    "shape": "Asscher",
    "supplementary_files": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ],
    "symmetry": "I",
    "table_percent": 1,
    "videos": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ],
    "width": 1
  },
  "polished_objective_verification_results": [
    {
      "id": "text",
      "source": "diadna",
      "status": "in_progress"
    }
  ],
  "possession_state": "destroyed",
  "producer_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "provenance": {
    "country_code": "text",
    "is_country_code_available": true,
    "is_locked": false,
    "mine_name": "text",
    "provenance_name": "text",
    "provenance_type": "text"
  },
  "rough": {
    "carats": "text",
    "colour": "D",
    "display_colour": "text",
    "fancy_colour": "BK",
    "fancy_colour_intensity": "F",
    "fancy_colour_overtone": "text",
    "fluorescence_colour": "B",
    "fluorescence_intensity": "VS",
    "images": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "image_type": "default"
      }
    ],
    "model": "text",
    "plan": {
      "description": "text",
      "filename": "text",
      "hash": "text",
      "plan_software_manufacturer": "text",
      "plan_software_name": "text",
      "plan_software_version": "text",
      "scan_device_manufacturer": "text",
      "scan_device_model": "text"
    },
    "plan_reports": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "plan_software_manufacturer": "text",
        "plan_software_name": "text",
        "plan_software_version": "text",
        "scan_device_manufacturer": "text",
        "scan_device_model": "text"
      }
    ],
    "quality": "text",
    "scan": {
      "description": "text",
      "filename": "text",
      "hash": "text",
      "scan_device_manufacturer": "text",
      "scan_device_model": "text",
      "scan_software_name": "text",
      "scan_software_version": "text"
    },
    "scan_reports": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "scan_device_manufacturer": "text",
        "scan_device_model": "text",
        "scan_software_name": "text",
        "scan_software_version": "text"
      }
    ],
    "stress": "text",
    "supplementary_files": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ],
    "videos": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ]
  },
  "rough_check": true,
  "rough_objective_verification_results": [
    {
      "id": "text",
      "source": "diadna",
      "status": "in_progress"
    }
  ],
  "schema_version": "text",
  "sight_no": 1,
  "sight_year": 1,
  "supplementary_tags": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "system_timestamp": "2026-08-08T00:25:41.944Z",
  "three_d_plan_available": false,
  "unlock_status": "locked",
  "verification_description": "verified record",
  "verification_status": "Verified",
  "verification_status_modified_at": "2026-08-08T00:25:41.944Z",
  "version_id": "text"
}

Deprecated

Update Rough Diamond

patch

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/diamonds/{id}/rough

This endpoint is deprecated. Please use the /v2/diamond/{id}/rough endpoint instead.

Path parameters

idany ofRequired

The ID (UUID) of the diamond to update.

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

or

string · uuidOptional

Body

application/json

box_descriptionstring · nullableOptional

Box description
Tracr class: entity_specific

box_idstring · nullableOptional

System name and ID pairs identifying the source batch for the diamond.
Tracr class: entity_specific

participant_idstring · nullableOptional

User supplied identifier for the diamond, specific to this Tracr instance. Synonymous with ERP ID and Stock ID. This field must be unique within the box/shipment the diamond is registered against. Can be updated as long as the the diamond's possession_state is held.

Pattern: ^\S(.*\S)?$

participant_timestampstring · date-timeRequired

sight_nointeger · nullableOptional

Sight number
Tracr class: entity_specific

sight_yearinteger · nullableOptional

Sight year
Tracr class: entity_specific

Responses

200

Successful Response

application/json

A diamond as returned from V1 API endpoints.

archived_atstring · date-time · nullableOptional

Timestamp indicating when this diamond was archived.
Tracr Class: entity_specific

assurance_levelstring · enumRequired

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: entity_specific

Possible values:

box_descriptionstring · nullableOptional

Tracr Class: entity_specific

box_idstring · nullableOptional

Identifier of the box/lot/shipment the diamond is registered against.
Tracr Class: entity_specific

current_stagestring · enumRequired

Indicates whether the diamond is rough or polished.
Tracr Class: traceability

Possible values:

diamond_idstringRequired

The diamond's unique identifier assigned by Tracr. Synonymous with Tracr ID.
Tracr Class: traceability

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

diamond_parent_idstring · nullableOptional

Tracr ID of the diamond's parent.
Tracr Class: traceability

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

idstring · uuidRequired

Legacy identifier of the diamond, superseded by diamond_id. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

is_currentbooleanRequired

Indicates whether the version of the diamond returned from the API is the latest version. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: entity_specific

lifecycle_statestring · enumRequired

Tracr Class: traceability

Possible values:

parent_idstring · uuid · nullableOptional

Legacy identifier of the diamond's parent, superseded by diamond_parent_id. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

participant_idstring · nullableOptional

User supplied identifier for the diamond, specific to this Tracr instance. Synonymous with ERP ID and Stock ID.
Tracr Class: entity_specific

participant_parent_idstring · nullableOptional

ERP of the diamond's parent.
Tracr Class: entity_specific

participant_timestampstring · date-timeRequired

User supplied timestamp of when the diamond was last modified.
Tracr Class: entity_specific

possession_statestring · enumRequired

Tracr Class: supplementary

Possible values:

producer_uuidstring · uuidRequired

Tracr platform identifier of the producer that first registered this diamond.
Tracr Class: traceability

rough_checkbooleanRequired

Indicates whether this diamond has passed rough objective verification. Prior to a diamond being unlocked the Rough Check status will always be false.
Tracr Class: supplementary

schema_versionstring · nullableOptional

Indicates the internal schema version used when putting the diamond on blockchain. This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

sight_nointeger · nullableOptional

Tracr Class: entity_specific

sight_yearinteger · nullableOptional

Tracr Class: entity_specific

system_timestampstring · date-timeRequired

Tracr Class: entity_specific

three_d_plan_availablebooleanOptional

Indicates whether a 3D plan is available for the diamond.
Tracr Class: supplementary

Default: false

unlock_statusstring · enumRequired

Tracr Class: supplementary

Possible values:

verification_descriptionstringOptional

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

Default: verified record

verification_statusstring · enumOptional

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: supplementary

Default: VerifiedPossible values:

verification_status_modified_atstring · date-time · nullableOptional

This field is deprecated and will be removed in a future revision of the API.
Tracr Class: entity_specific

version_idstringRequired

The identifier of the diamond's current version. This changes to a new unique identifier each time the diamond is updated.
Tracr Class: traceability

401

Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource.

403

Forbidden: The application does not have sufficient permissions for this operation.

404

Diamond ID not found. A diamond, with the provided ID, does not exist.

409

Diamond is archived

412

Precondition check failed: The operation cannot be applied to the current state of the diamond.

422

Unprocessable Entity, request JSON body is not as per specification

500

Internal Server Error. If this error persists please contact the Platform Admin team.

patch/diamonds/{id}/rough

HTTPcURLJavaScriptPython

PATCH /diamonds/{id}/rough HTTP/1.1
Host: api.<id>.tracr.network
Content-Type: application/json
Accept: */*
Content-Length: 498

{
  "box_description": "text",
  "box_id": "text",
  "entity_specific_tags": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "participant_id": "text",
  "participant_timestamp": "2026-08-08T00:25:41.944Z",
  "rough": {
    "carats": 1,
    "colour": "text",
    "fancy_colour": "text",
    "fancy_colour_intensity": "text",
    "fancy_colour_overtone": "text",
    "fluorescence_colour": "text",
    "fluorescence_intensity": "text",
    "model": "text",
    "quality": "text",
    "stress": "text"
  },
  "sight_no": 1,
  "sight_year": 1,
  "supplementary_tags": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "archived_at": "2026-08-08T00:25:41.944Z",
  "assurance_level": "assured",
  "box_description": "text",
  "box_id": "text",
  "current_stage": "polished",
  "data_requests": [
    {
      "created_at": "2026-08-08T00:25:41.944Z",
      "data_request_type": "three_d_plan",
      "errors": [
        "text"
      ],
      "id": "text",
      "status": "pending",
      "updated_at": "2026-08-08T00:25:41.944Z"
    }
  ],
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "diamond_parent_id": "e1mv3nn4n10kd1lw6mde6sums",
  "entity_specific_tags": {
    "dit_session_id": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "grading": [
    {
      "carats": "text",
      "clarity": "FL",
      "colour": "D",
      "crown_angle": "text",
      "crown_height": "text",
      "culet_condition": "P",
      "culet_size": "EL",
      "cut_grade": "I",
      "depth": "text",
      "depth_percent": "text",
      "diameter_maximum": "text",
      "diameter_minimum": "text",
      "display_colour": "text",
      "fancy_colour": "BK",
      "fancy_colour_intensity": "F",
      "fancy_colour_overtone": "text",
      "fluorescence_colour": "B",
      "fluorescence_intensity": "VS",
      "girdle_condition": "P",
      "girdle_thickness_from": "Extremely Thick",
      "girdle_thickness_to": "Extremely Thick",
      "graded_date": "2026-08-08T00:25:41.944Z",
      "grader_certificate_number": "text",
      "grader_clarity_characteristics": "text",
      "grader_colour": "text",
      "grader_inscription_numbers": [
        "text"
      ],
      "grader_report_comments": "text",
      "grader_report_number": "text",
      "grader_report_type": "text",
      "grader_shape": "text",
      "grading_certificate_description": "text",
      "grading_certificate_filename": "text",
      "grading_certificate_hash": "text",
      "grading_lab": "AGS",
      "id": "text",
      "is_active": true,
      "is_selectable": true,
      "length": "text",
      "measurement_text": "text",
      "pavillion_angle": "text",
      "pavillion_percent": "text",
      "polish_quality": "I",
      "shape": "Asscher",
      "source": "gis",
      "supplementary_files": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "symmetry": "I",
      "table_percent": "text",
      "validation_level": "validation",
      "width": "text"
    }
  ],
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "is_current": true,
  "lifecycle_state": "destroyed",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "participant_id": "text",
  "participant_parent_id": "text",
  "participant_timestamp": "2026-08-08T00:25:41.944Z",
  "polished": {
    "carats": "text",
    "clarity": "FL",
    "colour": "D",
    "crown_angle": 1,
    "crown_height": 1,
    "culet_condition": "P",
    "culet_size": "EL",
    "cut_grade": "I",
    "depth": 1,
    "depth_percent": 1,
    "diameter_maximum": 1,
    "diameter_minimum": 1,
    "display_colour": "text",
    "fancy_colour": "BK",
    "fancy_colour_intensity": "F",
    "fancy_colour_overtone": "text",
    "fluorescence_colour": "B",
    "fluorescence_intensity": "VS",
    "girdle_condition": "P",
    "girdle_thickness_from": "Extremely Thick",
    "girdle_thickness_to": "Extremely Thick",
    "grading_certificates": [
      {
        "description": "text",
        "filename": "text",
        "graded_date": "text",
        "grader_certificate_no": "text",
        "grader_inscription_no": "text",
        "grader_report_no": "text",
        "grading_lab": "text",
        "hash": "text"
      }
    ],
    "images": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "image_type": "default"
      }
    ],
    "length": 1,
    "pavillion_angle": 1,
    "pavillion_percent": 1,
    "polish_quality": "I",
    "scan": {
      "description": "text",
      "filename": "text",
      "hash": "text",
      "scan_device_manufacturer": "text",
      "scan_device_model": "text",
      "scan_software_name": "text",
      "scan_software_version": "text"
    },
    "scan_reports": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "scan_device_manufacturer": "text",
        "scan_device_model": "text",
        "scan_software_name": "text",
        "scan_software_version": "text"
      }
    ],
    "shape": "Asscher",
    "supplementary_files": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ],
    "symmetry": "I",
    "table_percent": 1,
    "videos": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ],
    "width": 1
  },
  "polished_objective_verification_results": [
    {
      "id": "text",
      "source": "diadna",
      "status": "in_progress"
    }
  ],
  "possession_state": "destroyed",
  "producer_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "provenance": {
    "country_code": "text",
    "is_country_code_available": true,
    "is_locked": false,
    "mine_name": "text",
    "provenance_name": "text",
    "provenance_type": "text"
  },
  "rough": {
    "carats": "text",
    "colour": "D",
    "display_colour": "text",
    "fancy_colour": "BK",
    "fancy_colour_intensity": "F",
    "fancy_colour_overtone": "text",
    "fluorescence_colour": "B",
    "fluorescence_intensity": "VS",
    "images": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "image_type": "default"
      }
    ],
    "model": "text",
    "plan": {
      "description": "text",
      "filename": "text",
      "hash": "text",
      "plan_software_manufacturer": "text",
      "plan_software_name": "text",
      "plan_software_version": "text",
      "scan_device_manufacturer": "text",
      "scan_device_model": "text"
    },
    "plan_reports": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "plan_software_manufacturer": "text",
        "plan_software_name": "text",
        "plan_software_version": "text",
        "scan_device_manufacturer": "text",
        "scan_device_model": "text"
      }
    ],
    "quality": "text",
    "scan": {
      "description": "text",
      "filename": "text",
      "hash": "text",
      "scan_device_manufacturer": "text",
      "scan_device_model": "text",
      "scan_software_name": "text",
      "scan_software_version": "text"
    },
    "scan_reports": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text",
        "scan_device_manufacturer": "text",
        "scan_device_model": "text",
        "scan_software_name": "text",
        "scan_software_version": "text"
      }
    ],
    "stress": "text",
    "supplementary_files": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ],
    "videos": [
      {
        "description": "text",
        "filename": "text",
        "hash": "text"
      }
    ]
  },
  "rough_check": true,
  "rough_objective_verification_results": [
    {
      "id": "text",
      "source": "diadna",
      "status": "in_progress"
    }
  ],
  "schema_version": "text",
  "sight_no": 1,
  "sight_year": 1,
  "supplementary_tags": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "system_timestamp": "2026-08-08T00:25:41.944Z",
  "three_d_plan_available": false,
  "unlock_status": "locked",
  "verification_description": "verified record",
  "verification_status": "Verified",
  "verification_status_modified_at": "2026-08-08T00:25:41.944Z",
  "version_id": "text"
}

Deprecated

Get All Inbound Shipments

get

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/shipments/inbound

This endpoint is deprecated. Please use the /v2/shipment/inbound endpoint instead.

Responses

200

Successful Response

application/json

Details of multiple inbound shipments and the diamonds within them.

get/shipments/inbound

HTTPcURLJavaScriptPython

GET /shipments/inbound HTTP/1.1
Host: api.<id>.tracr.network
Accept: */*

200

Successful Response

{
  "items": [
    {
      "created_at": "2026-08-08T00:25:41.944Z",
      "diamonds": [
        {
          "carats": "text",
          "clarity": "FL",
          "colour": "text",
          "created_at": "2026-08-08T00:25:41.944Z",
          "cut_grade": "I",
          "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
          "shape": "Asscher",
          "transfer_state": "accepted",
          "updated_at": "2026-08-08T00:25:41.944Z"
        }
      ],
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "name": "text",
      "sender": "text"
    }
  ]
}

Deprecated

Get Inbound Shipment

get

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/shipments/inbound/{shipment_id}

This endpoint is deprecated. Please use the /v2/shipment/inbound/{shipment_id} endpoint instead.

Path parameters

shipment_idstringRequired

ID of the shipment assigned by Tracr

Responses

200

Successful Response

application/json

Details of the inbound shipment of a transfer and the diamonds within it.

created_atstring · date-timeRequired

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

namestringRequired

senderstringRequired

422

Validation Error

application/json

get/shipments/inbound/{shipment_id}

HTTPcURLJavaScriptPython

GET /shipments/inbound/{shipment_id} HTTP/1.1
Host: api.<id>.tracr.network
Accept: */*

{
  "created_at": "2026-08-08T00:25:41.944Z",
  "diamonds": [
    {
      "carats": "text",
      "clarity": "FL",
      "colour": "text",
      "created_at": "2026-08-08T00:25:41.944Z",
      "cut_grade": "I",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "shape": "Asscher",
      "transfer_state": "accepted",
      "updated_at": "2026-08-08T00:25:41.944Z"
    }
  ],
  "id": "e1mv3nn4n10kd1lw6mde6sums",
  "name": "text",
  "sender": "text"
}

Deprecated

Get All Outbound Shipments

get

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/shipments/outbound

This endpoint is deprecated. Please use the /v2/shipment/outbound endpoint instead.

Responses

200

Successful Response

application/json

Details of multiple outbound shipments and the diamonds within them.

get/shipments/outbound

HTTPcURLJavaScriptPython

GET /shipments/outbound HTTP/1.1
Host: api.<id>.tracr.network
Accept: */*

200

Successful Response

{
  "items": [
    {
      "created_at": "2026-08-08T00:25:41.944Z",
      "diamonds": [
        {
          "carats": "text",
          "clarity": "FL",
          "colour": "text",
          "created_at": "2026-08-08T00:25:41.944Z",
          "cut_grade": "I",
          "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
          "display_colour": "text",
          "inscription_numbers": [
            "text"
          ],
          "participant_id": "text",
          "shape": "Asscher",
          "transfer_state": "accepted",
          "updated_at": "2026-08-08T00:25:41.944Z"
        }
      ],
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "name": "text",
      "receiver": "text"
    }
  ]
}

Deprecated

Get Outbound Shipment

get

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/shipments/outbound/{shipment_id}

This endpoint is deprecated. Please use the /v2/shipment/outbound/{shipment_id} endpoint instead.

Path parameters

shipment_idstringRequired

ID of the shipment assigned by Tracr

Responses

200

Successful Response

application/json

Details of the outbound shipment of a transfer and the diamonds within it.

created_atstring · date-timeRequired

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

namestringRequired

receiverstringRequired

422

Validation Error

application/json

get/shipments/outbound/{shipment_id}

HTTPcURLJavaScriptPython

GET /shipments/outbound/{shipment_id} HTTP/1.1
Host: api.<id>.tracr.network
Accept: */*

{
  "created_at": "2026-08-08T00:25:41.944Z",
  "diamonds": [
    {
      "carats": "text",
      "clarity": "FL",
      "colour": "text",
      "created_at": "2026-08-08T00:25:41.944Z",
      "cut_grade": "I",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "display_colour": "text",
      "inscription_numbers": [
        "text"
      ],
      "participant_id": "text",
      "shape": "Asscher",
      "transfer_state": "accepted",
      "updated_at": "2026-08-08T00:25:41.944Z"
    }
  ],
  "id": "e1mv3nn4n10kd1lw6mde6sums",
  "name": "text",
  "receiver": "text"
}

Deprecated

Transfer In Accept

post

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/transfer/in/{shipment_id}/accept

This endpoint is deprecated. Please use the /v2/transfer/in/{shipment_id}/accept endpoint instead.

Path parameters

shipment_idstringRequired

ID of the shipment assigned by Tracr

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

Bodyobject · DiamondIdWithInscriptionNumber[]

application/json

An object containing a Diamond ID and associated inscription numbers.

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

inscription_numberstringRequired

Responses

200

Successful Response

application/json

Returned by transfer/in/accept for each diamond accepted.

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

inscription_numberstringRequired

statusstring · enumRequired

Represents the result of a transfer-in-accept operation.

Possible values:

422

Validation Error

application/json

post/transfer/in/{shipment_id}/accept

HTTPcURLJavaScriptPython

POST /transfer/in/{shipment_id}/accept HTTP/1.1
Host: api.<id>.tracr.network
Content-Type: application/json
Accept: */*
Content-Length: 72

[
  {
    "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
    "inscription_number": "text"
  }
]

[
  {
    "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
    "inscription_number": "text",
    "status": "success"
  }
]

Deprecated

Transfer Out Start

post

https://api.<id>.tracr.networkhttps://api.<id>.uat.tracr.network

/transfer/out/start

This endpoint is deprecated. Please use the /v2/transfer/out/start endpoint instead.

Body

application/json

A request to start a transfer out for a sequence of diamonds to the V1 transfer/out/start endpoint.

receiverstringRequiredPattern: ^https://api\..+\.tracr\.com$

shipment_namestringRequired

Responses

200

Successful Response

application/json

A response to a V1 transfer/out/start request.

or

400

Returned if:

• Sender and receiver are the same participant.
• Any of the diamond IDs passed in the request does not exist in the database.
• Any of the diamond IDs passed in the request are locked.
• Any of the diamond IDs passed is for a diamond which is not POLISHED.
• Any of the diamond IDs passed is for a POLISHED diamond which has no inscription numbers.
• Any of the diamond IDs passed is for a POLISHED diamond which has an in-flight data request.
• Any of the diamond IDs passed is for a diamond which is archived.

application/json

409

Returned if any of the specified diamonds are being updated as part of another process.

422

Validation Error

application/json

post/transfer/out/start

HTTPcURLJavaScriptPython

POST /transfer/out/start HTTP/1.1
Host: api.<id>.tracr.network
Content-Type: application/json
Accept: */*
Content-Length: 98

{
  "diamonds": [
    {
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums"
    }
  ],
  "receiver": "text",
  "shipment_name": "text"
}

{
  "diamonds": [
    {
      "diamond_id": "text",
      "diamond_parent_id": "text",
      "status": "text"
    }
  ],
  "shipment_id": "e1mv3nn4n10kd1lw6mde6sums",
  "shipment_name": "text",
  "message": "text"
}