Get Started with Tracr Search Authenticated_copy

Who is this document for?

3rd Party Blockchain Integrations

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

There is no transferring of a digital asset

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