Upload Grading Data

What is it?

Once a diamond has been validated against the record Tracr holds, the lab can either upload the grading report with the grading data or upload the inscription number only that is associated with the diamond.

Add diamond grading report and grading data

How does it work?

The lab submits a POST request to /v2/diamonds/{diamond_id}/certificate (reference) with the required and recommended fields.

Required Data

Required Fields

• Tracr ID
• Certificate File

Recommended Fields

• Graded Date
• Grader Report Number
• Grader Report Comments
• Grader Clarity Characteristics
• Carat Weight
• Clarity
• Colour
• Cut Grade
• Measurement Text
• Polish Quality
• Shape
• Symmetry

Optional Fields

• Crown Angle
• Crown Height
• Culet Condition
• Culet Size
• Depth
• Depth Percent
• Diameter Maximum
• Diameter Minimum
• Fancy Colour
• Fancy Colour Intensity
• Fancy Colour Overtone
• Fluorescence Colour
• Fluorescence Intensity
• Girdle Condition
• Girdle Thickness From
• Girlde Thickness To
• Length
• Pavillion Angle
• Pavillion Percent
• Table Percent
• Width

Call POST /v2/diamonds/{diamond_id}/certificate

Form-data

Key	Value
certificate_file	sample_report.pdf
graded_date	2024-05-31T11:54:28.033+01:00
grader_report_no	214143811C
grader_report_comments	sample
grader_inscription_no	214143811C
grader_clarity_characteristics	Crystal
carats	0.52
clarity	VS2
colour	H
cut_grade	EX
measurement_text	5.10 - 5.12 x 3.18 mm
polish_quality	EX
shape	Round
symmetry	VG

Response

Response (201)

{
    "hash": "0ffa6a2313fff5db0048d47432a89615185873f08feeab5985451adac3a49930",
    "graded_measurement_id": "to55jz1yoiaoqyb34rmhi5n2"
}

HTTP response status code

201 : Success

Returned when the request has been successfully processed.

404 : Not Found

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

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

406 : Not Acceptable

Returned when certificate_file is not an application/pdf file.

{
    "detail": "certificate_file must have a mimetype of application/pdf."
}

409 : Conflict

Returned when a given grading report has already been uploaded for a given diamond.

{
    "detail": "Unable to upload certificate to Tracr instance: Another operation is in progress on one or more of the diamonds in this request."
}

422 : Unprocessable Entity

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

{
    "detail": [
        {
            "loc": [
                "certificate_file"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

500 : Internal Server Error

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

---

Add diamond inscription number

Submit a POST request to /v2/diamonds/{diamond_id}/inscription-number (reference) to update the inscription number.

GIS currently allows the lab to add an inscription number after a diamond passes verification. We recommend the lab to add a step to confirm the diamond has been validated before calling the update inscription API. This will be enforced by Tracr soon.

Example:

Call POST /v2/diamonds/kzsrfx4dxupa7a8uyn15wund/inscription-number

Request

Request Body

{
  "inscription_number": "247603711C",
  "inscription_date": "2024-12-10T09:29:46.550Z"
}

Response

Response (201)

{
    "hash": "2d130cfa113e4c7cb6df32b30a7225c083364be63415894e03e391ff4fb2deb1"
}

HTTP response status code

201 : Success

Returned when the request has been successfully processed.

404 : Not Found

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

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

409 : Conflict

Returned when a given inscription number has already been uploaded for a given diamond.

{
    "detail": "Unable to add inscription number to diamond: Inscription number 2476037113 has already been added to diamond kzsrfx4dxupa7a8uyn15wund"
}

422 : Unprocessable Entity

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

{
    "detail": [
        {
            "loc": [
                "body",
                "inscription_date"
            ],
            "msg": "invalid datetime format",
            "type": "value_error.datetime"
        }
    ]
}

500 : Internal Server Error

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