Get Started with Tracr Search -Authenticated

Tracr Search V1 Authenticated is an API allowing non-participants to search for a diamond across all of Tracr and return traceability data for both locked and unlocked diamonds.

You need to know

The Tracr Search API V1 Authenticated is only available for authenticated users. For more details please contact [e-mail].

Before you start

• Contact Tracr Support ([e-mail]) to obtain authentication credentials.
• Obtain the Tracr ID of the diamond that you want to look up.

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

Request

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

Response

{
  "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.

Authorization: <access_token>

Look up a diamond in Tracr

Retrieve single diamond details

Call GET /v1/diamonds/sm9og0cgxhpqy78vvo51btem1

Request

Response

{
  "diamond_id": "sm9og0cgxhpqy78vvo51btem1",
  "diamond_parent_id": "snbp04qev51mz7whoz1ttmjhy",
  "lifecycle_state": "polished",
  "current_stage": "polished",
  "assurance_level": "assured",
  "provenance": {
    "provenance_name": "DTC",
    "provenance_type": "Entity",
    "mine_name": null
  },
  "rough": {
    "carats": 23.42,
    "colour": "D",
    "fancy_colour": null,
    "fancy_colour_intensity": null,
    "fancy_colour_overtone": null,
    "fluorescence_colour": null,
    "fluorescence_intensity": "N",
    "images": [
      {
        "filename": "demo-split-206-1F.jpg",
        "description": null,
        "hash": "7c869b7844242c3355c9333d6444ae3883df9cff5e7f9343e4cb68c4ad35ca3e",
        "image_type": "default"
      }
    ],
    "model": null,
    "plan": null,
    "plan_reports": null,
    "quality": null,
    "scan": null,
    "scan_reports": null,
    "silhouettes": null,
    "stress": null,
    "supplementary_files": null,
    "videos": null
  },
  "polished": {
    "carats": 10.1,
    "clarity": "FL",
    "colour": "D",
    "crown_angle": null,
    "crown_height": null,
    "culet_condition": null,
    "culet_size": null,
    "cut_grade": "EX",
    "depth": null,
    "depth_percent": null,
    "diameter_maximum": null,
    "diameter_minimum": null,
    "fancy_colour": null,
    "fancy_colour_intensity": null,
    "fancy_colour_overtone": null,
    "fluorescence_colour": null,
    "fluorescence_intensity": "N",
    "girdle_condition": null,
    "girdle_thickness_from": null,
    "girdle_thickness_to": null,
    "grading_certificates": [
      {
        "filename": "5212039959.pdf",
        "description": null,
        "hash": "476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce",
        "grading_lab": "GIA",
        "graded_date": null,
        "grader_certificate_no": null,
        "grader_report_no": "5212039959",
        "grader_inscription_no": null
      }
    ],
    "length": null,
    "model": null,
    "pavillion_angle": null,
    "pavillion_percent": null,
    "polish_quality": "EX",
    "plan": null,
    "plan_reports": null,
    "quality": null,
    "scan": {
      "filename": "demo-polished-206-1F.stl",
      "description": null,
      "hash": "cf32f03ad4230538cdc195a024f3c126133c8228386b89348f0063f0b81f56f6",
      "scan_device_manufacturer": null,
      "scan_device_model": null,
      "scan_software_name": null,
      "scan_software_version": null
    },
    "scan_reports": [
      {
        "filename": "demo-polished-206-1F.html",
        "description": null,
        "hash": "275eab5473a8d5845256f99e375f650e29cb2abe2b55a53a01f9018e9b823495",
        "scan_device_manufacturer": null,
        "scan_device_model": null,
        "scan_software_name": null,
        "scan_software_version": null
      }
    ],
    "shape": "Emerald",
    "silhouettes": null,
    "symmetry": "EX",
    "table_percent": null,
    "supplementary_files": null,
    "unlocked_status": "unlocked",
    "width": null,
    "images": [
      {
        "filename": "demo-polished-206-1F_P.jpg",
        "description": null,
        "hash": "d3d3db369db95f944bf7f153622d933971eb3622ce435ab9cfd95149a8ea0db5",
        "image_type": "default"
      }
    ],
    "videos": null
  }
}

Here the API returns an object called a diamond record. A diamond record represents the current version of the digital asset in Tracr.

• Diamond ID – Each diamond on the platform has a unique diamond_id (or tracr id).
• Diamond Parent ID – The identifier of the parent diamond.
• Lifecycle State – The current state of a diamond. Tracr has four lifecycle states:

  • rough
  • split
  • polished
  • destroyed
• Rough – The object related to the rough state of the diamond before being polished. For a rough diamond having multiple cuts, the rough section represents one of the cuts. The parent diamond will represent the original rough diamond.
• Polished – The object related to the polished state of the diamond.

Retrieve diamond ancestors

Call GET /v1/diamonds/sm9og0cgxhpqy78vvo51btem1/history

Request

Response

{
  "content": {
    "current": {
      "diamond_id": "sm9og0cgxhpqy78vvo51btem1",
      "diamond_parent_id": "snbp04qev51mz7whoz1ttmjhy",
      "lifecycle_state": "polished",
      "current_stage": "polished",
      "assurance_level": "assured",
      "provenance": {
        "provenance_name": "DTC",
        "provenance_type": "Entity",
        "mine_name": null
      },
      "rough": {
        "carats": 23.42,
        "colour": "D",
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": "N",
        "images": [
          {
            "filename": "demo-split-206-1F.jpg",
            "description": null,
            "hash": "7c869b7844242c3355c9333d6444ae3883df9cff5e7f9343e4cb68c4ad35ca3e",
            "image_type": "default"
          }
        ],
        "model": null,
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "silhouettes": null,
        "stress": null,
        "supplementary_files": null,
        "videos": null
      },
      "polished": {
        "carats": 10.1,
        "clarity": "FL",
        "colour": "D",
        "crown_angle": null,
        "crown_height": null,
        "culet_condition": null,
        "culet_size": null,
        "cut_grade": "EX",
        "depth": null,
        "depth_percent": null,
        "diameter_maximum": null,
        "diameter_minimum": null,
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": "N",
        "girdle_condition": null,
        "girdle_thickness_from": null,
        "girdle_thickness_to": null,
        "grading_certificates": [
          {
            "filename": "5212039959.pdf",
            "description": null,
            "hash": "476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce",
            "grading_lab": "GIA",
            "graded_date": null,
            "grader_certificate_no": null,
            "grader_report_no": "5212039959",
            "grader_inscription_no": null
          }
        ],
        "length": null,
        "model": null,
        "pavillion_angle": null,
        "pavillion_percent": null,
        "polish_quality": "EX",
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": {
            "filename": "demo-polished-206-1F.stl",
            "description": null,
            "hash": "cf32f03ad4230538cdc195a024f3c126133c8228386b89348f0063f0b81f56f6",
            "scan_device_manufacturer": null,
            "scan_device_model": null,
            "scan_software_name": null,
            "scan_software_version": null
        },
        "scan_reports": [
          {
            "filename": "demo-polished-206-1F.html",
            "description": null,
            "hash": "275eab5473a8d5845256f99e375f650e29cb2abe2b55a53a01f9018e9b823495",
            "scan_device_manufacturer": null,
            "scan_device_model": null,
            "scan_software_name": null,
            "scan_software_version": null
          }
        ],
        "shape": "Emerald",
        "silhouettes": null,
        "symmetry": "EX",
        "table_percent": null,
        "supplementary_files": null,
        "unlocked_status": "unlocked",
        "width": null,
        "images": [
          {
            "filename": "demo-polished-206-1F_P.jpg",
            "description": null,
            "hash": "d3d3db369db95f944bf7f153622d933971eb3622ce435ab9cfd95149a8ea0db5",
            "image_type": "default"
          }
        ],
        "videos": null
      }
    },
    "snbp04qev51mz7whoz1ttmjhy": {
      "diamond_id": "snbp04qev51mz7whoz1ttmjhy",
      "diamond_parent_id": null,
      "lifecycle_state": "split",
      "current_stage": "rough",
      "assurance_level": "assured",
      "provenance": {
        "provenance_name": "DTC",
        "provenance_type": "Entity",
        "mine_name": null
      },
      "rough": {
        "carats": 129.71,
        "colour": "D",
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": "N",
        "images": [
          {
            "filename": "demo-rough-206-1.jpg",
            "description": null,
            "hash": "60505ac214dda6a8b72a6ded5da32dc1a15bc0480f26027909d786ce510511c4",
            "image_type": "default"
          }
        ],
        "model": null,
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "silhouettes": null,
        "stress": null,
        "supplementary_files": null,
        "videos": [
          {
              "filename": "demo-rough-206-1.mp4",
              "description": null,
              "hash": "5ce066c86dfcdc245f1985199a59fd1fbf62f046303eb06d88ce9fd8f7549691"
          }
        ]
      },
      "polished": {
        "carats": null,
        "clarity": null,
        "colour": null,
        "crown_angle": null,
        "crown_height": null,
        "culet_condition": null,
        "culet_size": null,
        "cut_grade": null,
        "depth": null,
        "depth_percent": null,
        "diameter_maximum": null,
        "diameter_minimum": null,
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": null,
        "girdle_condition": null,
        "girdle_thickness_from": null,
        "girdle_thickness_to": null,
        "grading_certificates": null,
        "length": null,
        "model": null,
        "pavillion_angle": null,
        "pavillion_percent": null,
        "polish_quality": null,
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "shape": null,
        "silhouettes": null,
        "symmetry": null,
        "table_percent": null,
        "supplementary_files": null,
        "width": null,
        "images": null,
        "videos": null
      }
    }
  }
}

Retrieve a file

Call GET /v1/diamonds/sm9og0cgxhpqy78vvo51btem1/files/476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce

Request

Response

HTTP Code : 302

Headers:

location: https://5aa4ed9b-c04a-45b0-82fb-b09c771600dd.tracr.com/diamond-assets/87f7a020-09fe-4c59-a5b0-74942ca57fae/476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce