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

Validation

What is it?

GIS uses multiple data points to verify the diamond received by the lab is the same diamond as declared by the manufacturer in Tracr. GIS extracts those data points from the polished report uploaded by the manufacturer.

How does it work?

1

Submit a validation request

The lab submits a POST request to /v2/diamonds/{diamond_id}/validate-json (reference) with the Tracr ID and the required fields. Each value will be compared and accepted within the tolerance (refer to the Tolerance table below). The endpoint returns a request_id.

Required Data

  • Shape Group : Shape

  • Estimated Carat Weight : Estimated weight in carat based on the volume and diamond density. This measurement is computed by the software producing the report.

  • Girdle Average : Girdle bezel average size in mm.

  • Table Size Average : Table average size in mm.

  • Total Depth : Diamond depth in mm.

Depending on availability, Tracr will compare 2 additional fields:

  • crown_angle_avg_deg : Average angle of each crown facets with the centre axis in degrees

  • pavilion_angle_avg_deg : Average angle of each pavilion facets with the centre axis in degrees

If a measurement is missing, equal to 0 or is outside of the tolerance the validation status will not be affected, but Tracr will report back to the lab the reason for the failure for the affected field.

Example request and initial response:

{
    "shape_group": "Round",
    "estimated_weight_crt": 0.284,
    "girdle_avg_mm": 0.145,
    "table_avg_mm": 2.365,
    "total_depth_mm": 2.607,
    "crown_angle_deg": 34.08, 
    "pavillion_angle_deg": 40.99 
}
{
    "diamond_id": "kzsrfx4dxupa7a8uyn15wund",
    "request_id": "un33utr58f8zm6twyl6eaqym",
    "status_url": "https://api.gis.uat.tracr.com/v2/diamonds/kzsrfx4dxupa7a8uyn15wund/validate/un33utr58f8zm6twyl6eaqym",
    "verification_status": "Pending"
}
2

Poll the request status

The lab polls /v2/diamonds/{diamond_id}/validate/{request_id} (reference) to retrieve the status of a specific request.

Responses may indicate a verified or unverifiable result. Examples:

{
    "diamond_id": "kzsrfx4dxupa7a8uyn15wund",
    "request_id": "un33utr58f8zm6twyl6eaqym",
    "requested_at": "2025-04-30T12:04:06.783242+00:00",
    "verification_status": "Verified",
    "verification_description": null,
    "verification_error": null,
    "parameters": {
        "crown_angle_avg_deg": {
            "validation_result": "matched",
            "tracr_value": 34.08,
            "lab_value": 33.9875,
            "difference": 0.0925,
            "tolerance": 1.1
        },
        "estimated_weight_crt": {
            "validation_result": "matched",
            "tracr_value": 0.284,
            "lab_value": 0.284,
            "difference": 0.0,
            "tolerance": 0.02
        },
        "girdle_avg_mm": {
            "validation_result": "matched",
            "tracr_value": 0.145,
            "lab_value": 0.115,
            "difference": 0.03,
            "tolerance": 0.5
        },
        "pavilion_angle_avg_deg": {
            "validation_result": "matched",
            "tracr_value": 40.99,
            "lab_value": 40.9375,
            "difference": 0.0525,
            "tolerance": 0.27
        },
        "shape": {
            "validation_result": "matched",
            "tracr_value": "Round",
            "lab_value": "Round"
        },
        "table_avg_mm": {
            "validation_result": "matched",
            "tracr_value": 2.365,
            "lab_value": 2.331,
            "difference": 0.034,
            "tolerance": 0.143
        },
        "total_depth_mm": {
            "validation_result": "matched",
            "tracr_value": 2.607,
            "lab_value": 2.615,
            "difference": 0.008,
            "tolerance": 0.073
        }
    }
}

Tolerance

Data Point
Tolerance (+/-)

Estimated Carat Weight

0.02 carats

Girdle Average

0.5 mm

Table Size Average

0.143 mm

Total Depth

0.073 mm

Crown Angle Average

1.1 degree

Pavilion Angle Average

0.27 degree

If a diamond matches within tolerance, it can be updated with the grading certificate, inscription number and relevant grading data.

3

Retrieve historical requests

The lab can call /V2/diamodns/{diamond_id}/validate/historic to get all answered or errored validation requests for a Tracr diamond_id.

Example:

Call GET /v2/diamonds/kzsrfx4dxupa7a8uyn15wund/validate/historic

Response:

[
    {
        "diamond_id": "kzsrfx4dxupa7a8uyn15wund",
        "request_id": "un33utr58f8zm6twyl6eaqym",
        "requested_at": "2025-04-30T12:04:06.783242+00:00",
        "verification_status": "Verified",
        "verification_description": null,
        "verification_error": null,
        "expired": false
    },
    {
     "diamond_id": "kzsrfx4dxupa7a8uyn15wund",
      "request_id": "jft9plva8qt00qb2kn5vkc5g",
      "requested_at": "2025-04-30T12:32:01.799216+00:00",
      "verification_status": "Unverifiable",
      "verification_description": null,
      "verification_error": null,
      "expired": false
    }
]

HTTP response status codes

202 : Success

Returned when a validation request is accepted for processing.

404 : Not Found

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

Response example:

{
    "detail": "Diamond cannot be found in Tracr"
}
410 : Gone

Returned when the diamond has been deleted.

Response example:

{
    "reason": "diamond_has_been_deleted",
    "detail": null
}
412 : Precondition Failed

Returned when there has not been a successful verify request for this diamond.

Response example:

422 : Unprocessable Entity

Returned when the request doesn't match the endpoint data requirements.

Response example:

500 : Internal Server Error

Returned when an internal error occurred within GIS. Please contact Tracr Support if you meet with this issue.

PreviousVerificationNextUpload Grading Data

Last updated