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

Inventory

Individual diamond

To return data about a specific diamond, pass the Tracr Diamond ID to the /diamonds endpoint:

Call GET /diamonds/a2uj544df5t5awu5v792wyj6

{
    "assurance_level": "assured",
    "box_id": "demo_box",
    "current_stage": "polished",
    "diamond_id": "a2uj544df5t5awu5v792wyj6",
    "diamond_parent_id": "wemz3zvg7cvr5uugivhib1z0",
    "entity_specific_tags": {},
    "id": "14fe49ae-df4b-49f6-93c3-9a712016977e",
    "is_current": true,
    "lifecycle_state": "polished",
    "parent_id": "b0733d6f-a3b1-4532-be2b-d352bad46fd6",
    "participant_id": "demo_1_polished_1",
    "participant_parent_id": "demo_1",
    "participant_timestamp": "2024-05-31T11:59:52.456810+00:00",
    "polished": {
        "carats": 1.01,
        "cut_grade": "EX",
        "shape": "Round",
        "colour": "F",
        "clarity": "SI1",
        "scan_reports": [
            {
                "filename": "demo_polished_scan.xml",
                "description": "Polished diamond scan report",
                "hash": "c47c21bf48f7fe301de1efdce43a153ddd873d599195f7103bbf5053341b6c69",
                "scan_device_manufacturer": "Sarine",
                "scan_device_model": "DiaMension"
            }
        ],
        "videos": [
            {
                "filename": "polished_video.mp4",
                "description": "Polished 360 video",
                "hash": "dc897a179788e760b29497dd8ebfeb25051dd961f949e210203a5ae4e15b3dab"
            }
        ],
        "grading_certificates": [
            {
                "filename": "gia_sample_report.pdf",
                "hash": "84de6762dcebfc18dd385389fa5831ec25286fc4fee2e2c0279474d57ceb4a50",
                "grading_lab": "GIA",
                "graded_date": "2024-05-31",
                "grader_certificate_no": "2141438167",
                "grader_inscription_no": "GIA 2141438167"
            }
        ]
    },
    "possession_state": "held",
    "producer_uuid": "952e8987-9e49-437b-824c-5c9a77ce7eee",
    "provenance": {
        "provenance_name": "DTC",
        "provenance_type": "Entity",
        "is_locked": false,
        "is_country_code_available": false
    },
    "rough": {
        "carats": 1.52,
        "images": [
            {
                "filename": "demo_1_split_1.jpeg",
                "description": "Split Image",
                "hash": "219fe6f8cdc6f32091b310f6c6f5864f4fef97443cb8954a1d64bc9f26731986",
                "image_type": "default"
            }
        ]
    },
    "schema_version": "1.1.0",
    "sight_no": 2,
    "sight_year": 2024,
    "system_timestamp": "2024-05-31T13:35:31.094000+00:00",
    "verification_description": "verified record",
    "verification_status": "Verified",
    "version_id": "e11im52r7v8nmalm2btmjues",
    "verification_status_modified_at": "2024-05-31T12:22:44.693059+00:00",
    "grading": [
        {
            "id": "hpuxljkbhjil53unwyyc11vh",
            "graded_date": "2024-05-31T00:00:00+00:00",
            "grader_certificate_number": "2141438167",
            "grader_inscription_numbers": [
                "GIA 2141438167"
            ],
            "grading_certificate_filename": "gia_sample_report.pdf",
            "grading_certificate_hash": "84de6762dcebfc18dd385389fa5831ec25286fc4fee2e2c0279474d57ceb4a50",
            "grading_lab": "GIA"
        }
    ],
    "unlock_status": "locked",
    "rough_check": false
}

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

Participant ID – The participant ID is the unique ID of the diamond in the factory's ERP. This used to keep the relationship between a diamond in the ERP and the same diamond in Tracr.

Participant Timestamp – The timestamp of the enrolment of the rough diamond in the manufacturing process.

Diamond ID – Each diamond on the platform has a unique diamond_id (or tracr id) assigned by the API. You need to capture and keep this diamond_id since this identifier is used by other endpoints of the API.

Version – Each diamond on the platform is versioned after any data modification (metadata, files, and so on) or change of state (Verification Status, LifecycleState, Possession State, and so on). The field version_id contains the current version.

Lifecycle State - Current state of a diamond. Tracr has 4 lifecycle states

  • rough

  • split

  • polished

  • destroyed

Possession State - Tracr diamonds have 3 possession states

  • held : Diamond is live and owned by the current instance of Tracr

  • known : Diamond was previously owned by the instance of Tracr but has been transferred to another peer

  • destroyed : Diamond has been destroyed and is no longer live in the inventory

Verification status – The field verification_status provides the current verification status from Tracr based on the traceability data provided during the registration.

Paginating inventory

The Tracr API offers a paginated endpoint to query your entire inventory. Pagination is controlled by two query parameters:

size - The number of diamonds (between 1 and 1,000) to return per request. Defaults to 100 if not provided.

page - The page number to return. Defaults to 1 if not provided.

Results are ordered by the time when diamond was first added to the Tracr instance (either by rough registration or polished transfer). For example, GET /diamonds/?size=1&page=2 returns the second diamond added to the inventory:

Call /diamonds/?size=1&page=2

next - The url of the next page to query. This field will not appear in the response if there is no such page.

page - The current page number.

pages - The total number of pages available.

previous - The url of the previous page to query. This field will not appear in the response if there is no such page.

results - The paginated result set.

total - The total number of diamonds matching the query.

Query filters

Extra query parameters can be applied to the URL to filter the inventory. Some examples are shown below.

Querying by lifecycle state

Call to retrieve all live rough diamonds.

Call GET /diamonds/?lifecycle_state=rough

Querying by Participant ID (ERP ID)

Call GET /diamonds/?participant_id=demo_1_split_2

PreviousPolishNextUnlock

Last updated