> For the complete documentation index, see [llms.txt](https://docs.tracr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tracr.com/api-reference/grading-integration-service-gis-api/validation.md). # 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? {% stepper %} {% step %} ### Submit a validation request The lab submits a POST request to `/v2/diamonds/{diamond_id}/validate-json` ([reference](/api-reference/grading-integration-service-gis-api/references/api-v2.md#post-v2-diamonds-diamond_id-validate-json)) 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`. {% hint style="info" %} ## 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. {% endhint %} Example request and initial response: {% tabs %} {% tab title="Request" %} ```json { "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 } ``` {% endtab %} {% tab title="Response" %} ```json { "diamond_id": "kzsrfx4dxupa7a8uyn15wund", "request_id": "un33utr58f8zm6twyl6eaqym", "status_url": "https://api.gis.uat.tracr.com/v2/diamonds/kzsrfx4dxupa7a8uyn15wund/validate/un33utr58f8zm6twyl6eaqym", "verification_status": "Pending" } ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} ### Poll the request status The lab polls `/v2/diamonds/{diamond_id}/validate/{request_id}` ([reference](/api-reference/grading-integration-service-gis-api/references/api-v2.md#get-v2-diamonds-diamond_id-validate-request_id)) to retrieve the status of a specific request. Responses may indicate a verified or unverifiable result. Examples: {% tabs %} {% tab title="Response — Verified" %} ```json { "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 } } } ``` {% endtab %} {% tab title="Response — Unverifiable" %} ```json { "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, "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": "match_failed", "tracr_value": 0.384, "lab_value": 0.284, "difference": 0.1, "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 } } } ``` {% endtab %} {% endtabs %} ## 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. {% endstep %} {% step %} ### 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: ```json [ { "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 } ] ``` {% endstep %} {% endstepper %} ## 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: ```json { "detail": "Diamond cannot be found in Tracr" } ```
410 : Gone Returned when the diamond has been deleted. Response example: ```json { "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: ```json { "detail": "A successful request to verify the diamond must have been carried out before proceeding to validation." } ```
422 : Unprocessable Entity Returned when the request doesn't match the endpoint data requirements. Response example: ```json { "detail": [ { "loc": [ "path", "diamond_id" ], "msg": "string does not match regex \"^[a-z\\d]{20,98}$\"", "type": "value_error.str.regex", "ctx": { "pattern": "^[a-z\\d]{20,98}$" } } ] } ```
500 : Internal Server Error Returned when an internal error occurred within GIS. Please contact Tracr Support if you meet with this issue.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tracr.com/api-reference/grading-integration-service-gis-api/validation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.