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

API V2

Get Diamond

get

Look up a single diamond in Tracr and return its data if it exists.

Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Responses
200

Successful Response

application/json

A simplified set of data about a Tracr-registered diamond.

caratsstringRequired

The weight of the diamond in carats

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,3}0*$
claritystring · enum · nullableOptional

Clarity of the diamond

Possible values:
colourstring · enum · nullableOptional

Colour of the diamond

Possible values:
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
display_colourstring · nullableOptional

Formatted Fancy colour (Intensity + Overtone + Colour) or colour from the standard scale

fancy_colourstring · enum · nullableOptional

The fancy colour of the diamond.

Possible values:
rough_checkbooleanRequired

Indicates whether the rough diamond has been verified by Tracr Rough Check

shapestring · enumRequired

Shape of polished diamond.

Possible values:
get/v2/diamonds/{diamond_id}

Upload Diamond Grading Certificate

post

Add a grading certificate to a diamond in Tracr.

Accepts a multipart/form-data request.

Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Body
caratsany of · nullableOptional

The diamonds carat weight expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
certificate_filestring · binaryRequired

The certificate file. Must be an application/pdf file, otherwise the upload will be rejected.

claritystring · enum · nullableOptional

The clarity of the diamond.

Permitted values:

FL, IF, LC, VVS1, VVS2, VS1, VS2, SI1, SI2, SI3, I1, I2, I3, P1, P2 or P3

Possible values:
colourstring · enum · nullableOptional

The colour of the diamond.

Permitted values:

D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y or Z

Possible values:
crown_angleany of · nullableOptional

The diamonds crown angle expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
crown_heightany of · nullableOptional

The diamonds crown height expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
culet_conditionstring · enum · nullableOptional

The culet condition of the diamond.

Permitted values:

P, A or C

Possible values:
culet_sizestring · enum · nullableOptional

The culet size of the diamond.

Permitted values:

EL, VL, L, SL, M, S, VS or N

Possible values:
cut_gradestring · enum · nullableOptional

The cut grade of the diamond.

Permitted values:

I, EX, VG, G, F, P or NA

Possible values:
depthany of · nullableOptional

The diamonds depth expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
depth_percentany of · nullableOptional

The diamonds depth percent expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
diameter_maximumany of · nullableOptional

The diamonds maximum diameter expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
diameter_minimumany of · nullableOptional

The diamonds minimum diameter expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
fancy_colourstring · enum · nullableOptional

The fancy colour of the diamond.

Permitted values:

BK, B, BN, CH, CM, CG, GY, G, O, P, PL, R, V, Y, W or X

Possible values:
fancy_colour_intensitystring · enum · nullableOptional

The fancy colour intensity of the diamond.

Permitted values:

F, VL, L, FL, FC, FCD, I, FV or D

Possible values:
fancy_colour_overtonestring · nullableOptional

The fancy colour overtone of the diamond.

fluorescence_colourstring · enum · nullableOptional

The fluorescence colour of the diamond.

Permitted values:

B, W, Y, O, R, G or N

Possible values:
fluorescence_intensitystring · enum · nullableOptional

The fluorescence intensity of the diamond.

Permitted values:

VS, S, M, F, SL, VSL or N

Possible values:
girdle_conditionstring · enum · nullableOptional

The girdle condition of the diamond.

Permitted values:

P, F or B

Possible values:
girdle_thickness_fromstring · enum · nullableOptional

The minimum girdle thickness of the diamond.

Permitted values:

Extremely Thick, Very Thick, Thick, Slightly Thick, Medium, Thin, Slightly Thin, Very Thin or Extremely Thin

Possible values:
girdle_thickness_tostring · enum · nullableOptional

The maximum girdle thickness of the diamond.

Permitted values:

Extremely Thick, Very Thick, Thick, Slightly Thick, Medium, Thin, Slightly Thin, Very Thin or Extremely Thin

Possible values:
graded_datestring · date-time · nullableOptional

The graded date of the diamond as an ISO 8601 string

grader_certificate_nostring · nullableOptional

The grader certificate number

grader_clarity_characteristicsstring · nullableOptional

The grader clarity characteristics.

grader_colourstring · nullableOptional

Free form representation of the diamonds colour.

grader_inscription_nostring · nullableOptional

The grader inscription number

grader_report_commentsstring · nullableOptional

The grader report comments.

grader_report_nostring · nullableOptional

The grader report number

grader_report_typestring · nullableOptional

Grader report type.

grader_shapestring · nullableOptional

Free form representation of the diamonds shape. This field will be populated on the Diamond Experience Grading page once the information is provided.

grading_certificate_descriptionstring · nullableOptional

Description of the grading certificate.

grading_labstring · enum · nullableOptional

The grading lab responsible for grading the diamond.

Permitted values:

AGS, CGL, DCLA, GCAL, GHI, GIA, GSI, HRD, IGI, IIDGR, IOD, NGTC, Other, PGS, RDC, RDR, SGL, VGR or SSEF

Possible values:
lengthany of · nullableOptional

The diamonds length expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
measurement_textstring · nullableOptional

The measurement text.

pavillion_angleany of · nullableOptional

The diamonds pavillion angle expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
pavillion_percentany of · nullableOptional

The diamonds pavillion percent expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
polish_qualitystring · enum · nullableOptional

The diamonds polish quality.

Permitted values:

I, EX, VG-EX, VG, G-VG, G, F-G, F or P

Possible values:
shapestring · enum · nullableOptional

The diamonds shape.

Permitted values:

Asscher, Baguette, Briolette, Bullets, Calf, Cushion, Cushion Modified Brilliant, Emerald, European Cut, Flanders, Half Moon, Heart, Hexagonal, Kite, Lozenge, Marquise, Octagonal, Old Miner, Oval, Pear, Pentagonal, Princess, Radiant, Rectangle, Rose, Round, Shield, Square, Square Emerald, Square Radiant, Star, Tapered Baguette, Tapered Bullet, Trapezoid, Triangle, Trilliant or Other

Possible values:
symmetrystring · enum · nullableOptional

The diamonds symmetry.

Permitted values:

I, EX, VG-EX, VG, G-VG, G, F-G, F or P

Possible values:
table_percentany of · nullableOptional

The diamonds table percent expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
validation_levelstring · enum · nullableOptional

The diamonds validation level.

Permitted values:

validation or verification

Possible values:
widthany of · nullableOptional

The diamonds width expressed as a decimal.

numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
Responses
201

Successful Response

application/json

Sent when a graded measurement has been added to a certificate.

graded_measurement_idstringRequired

The ID of the graded measurement.

hashstringRequired

The hash of the uploaded file.

post/v2/diamonds/{diamond_id}/certificate

Upload Grading Certificate File

post

Add a file to a grading certificate in Tracr.

Accepts a multipart/form-data request containing the following:

  • file: The file to upload.

  • file_type: [Optional] The type of file being uploaded.

Path parameters
certificate_idstringRequired
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Responses
201

Successful Response

application/json

Sent when a graded measurement has been added to a certificate.

graded_measurement_idstringRequired

The ID of the graded measurement.

hashstringRequired

The hash of the uploaded file.

post/v2/diamonds/{diamond_id}/grading-certificates/{certificate_id}/files

Add Diamond Inscription Number

post

Add an inscription number to a diamond in Tracr.

Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Body

The data required to add an inscription number to a diamond.

inscription_datestring · date-time · nullableOptional
inscription_numberstring · min: 1Required

The inscription number to add to the diamond. Must have a non-zero length.

Responses
201

Successful Response

application/json

Sent when an inscription number or certificate has been added to a diamond.

hashstringRequired

The hash of the uploaded inscription number data.

post/v2/diamonds/{diamond_id}/inscription-number

Qr Code For Diamond

get

Generate and return a QR linking to this diamond in the Diamond Experience.

Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Responses
200

Return a QR linking to this diamond in the Diamond Experience.

image/png
get/v2/diamonds/{diamond_id}/qr
Deprecated

Validate Diamond With Scan File

post

This endpoint is deprecated. Please use the /v2/diamonds/{diamond_id}/validate-json endpoint instead.

Validate that diamond data in a GIA DAT scan file matches that stored in Tracr.

The success or failure of this operation can be determined by GETing
/v2/diamonds/{diamond_id}/validate/{request_id}.

**Notice:** This endpoint currently only supports validating _round_ diamonds.
Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Body
scan_report_filestring · binaryRequired
Responses
202

Returned when a validation request is accepted for processing.

application/json

A response to a scan-report-based request for the validation of a diamond.

diamond_idstringRequired

The ID of the diamond for which validation has been requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
request_idstringRequired

The unique ID for this validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
status_urlstringRequired

The URL from which to fetch the status of this validation request via an HTTP GET

verification_statusstringOptional

The current status of the verification request

Default: Pending
post/v2/diamonds/{diamond_id}/validate

Validate Diamond With Parameters

post

Validate that a set of diamond data matches that stored in Tracr.

All diamonds, regardless of shape, require the following fields:

  • carat_weight

  • girdle_average

  • table_size_average

  • total_depth

The success or failure of this operation can be determined by GETing /v2/diamonds/{diamond_id}/validate/{request_id}.

Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Body
or
Responses
202

Returned when a validation request is accepted for processing.

application/json

A response to a scan-report-based request for the validation of a diamond.

diamond_idstringRequired

The ID of the diamond for which validation has been requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
request_idstringRequired

The unique ID for this validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
status_urlstringRequired

The URL from which to fetch the status of this validation request via an HTTP GET

verification_statusstringOptional

The current status of the verification request

Default: Pending
post/v2/diamonds/{diamond_id}/validate-json

Get Historic Validation Requests For Diamond

get

Return all answered or errored validation requests for a diamond.

Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Responses
200

Successful Response

application/json

A ValidationFeedback object used for reporting historic data.

diamond_idstringRequired

The ID of the diamond for which validation was requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
expiredbooleanRequired

True if DiamondID did not respond to the request in a timely fashion.

request_idstringRequired

The unique ID of the validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
requested_atstring · date-timeRequired

The UTC datetime at which the validation request was created.

verification_descriptionstring · nullableOptional

A message from DiamondID describing the validation status.

verification_statusstring · enumOptional

The validation status returned by DiamondID.

Default: PendingPossible values:
get/v2/diamonds/{diamond_id}/validate/historic

Get Validation Request Status

get

Return the status of a validation request.

Path parameters
request_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Responses
200

Successful Response

application/json

The full feedback on a V2 validation operation, as returned by GIS.

diamond_idstringRequired

The ID of the diamond for which validation was requested.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
request_idstringRequired

The unique ID of the validation request.

Example: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
requested_atstring · date-timeRequired

The UTC datetime at which the validation request was created.

verification_descriptionstring · nullableRequired

A message detailing the validation status if there were issues.

verification_statusstring · enumRequired

The validation status for this request.

Possible values:
get/v2/diamonds/{diamond_id}/validate/{request_id}

Verify Diamond

post

Verify a diamond against provided parameters.

Path parameters
diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$
Body

Params for a diamond verify request.

carat_weightany ofRequired
numberOptional
or
stringOptionalPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
shape_groupstring · enumRequired

An enum of the possible values for the shape_group of a diamond.

This enum is intended to cover different shape groups used by grading labs for verification and validation. For context, grading labs have different shape definitions that may or may not correspond directly to members of the Shape enum.

Note that this enum MUST contain all of the same members as the Shape enum from tracr_core.types.enums, but will contain extras to account for variance across labs.

Possible values:
Responses
200

Successful Response

application/json

HTTP response for a diamond verify request.

is_lockedboolean · nullableOptional
statusstring · enumRequired

Potential values for a diamond verification.

Possible values:
post/v2/diamonds/{diamond_id}/verify

Last updated