Diamonds API v3

Managing a vendor's diamonds, with grades as ids from the Constants API dictionaries.

Diamonds API v3 lets a vendor create, read, update and delete the diamonds it owns on Cutwise. Grades are ids from the Constants API dictionaries. For grades as plain strings, see Diamonds API v4.

Example

This request returns the diamond with product ID 1234:

GET /v3/diamond/1234 HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

The response is one Diamond object, described in the next section.

Diamond object

Example of a Diamond object:

{
  "id": 337,
  "sku": "MSSRBC13",
  "price": null,
  "isColored": false,
  "isPublished": true,
  "cutShape": 2,
  "carat": 0.73,
  "clarity": 6,
  "color": 18,
  "cutQuality": 1,
  "polish": 1,
  "symmetry": 1,
  "fluorIntensity": 1,
  "fluorColor": null,
  "fancyGrade": null,
  "colorHue": null,
  "colorModifier": null,
  "date": "2014-11-27T21:11:00+00:00",
  "scores": {
    "integral": {
      "val": 0.95,
      "rg": 1.02,
      "d": 0.05,
      "ver": "1.1.0"
    },
    "spread": {
      "ct": -0.19,
      "pc": -14.2,
      "d": 0.1,
      "ver": "1.0.0"
    },
    "fire": {
      "val": 0.73,
      "rg": 1.02,
      "d": 0.05,
      "ver": "fire-2018-01-26-6525426815546393815"
    },
    "brilliance": {
      "val": 1.03,
      "rg": 1.03,
      "d": 0.02,
      "faceup": 1.01,
      "avg": 0.98,
      "ver": "5.4.2018-06-29-3890169345"
    },
    "fluor": {
      "n": 1,
      "f": 0,
      "m": 0,
      "s": 0,
      "vs": 0,
      "ver": "5.4.2018-06-29-770653064"
    },
    "symmetry": {
      "val": 8.55,
      "pav": 8.71,
      "crown": 8.39,
      "d": 0.05,
      "ver": "1.3.0"
    }
  },
  "_links": [{
    "rel": "page.report",
    "href": "https:\/\/cutwise.com\/diamond\/337"
  }]
}

The Constants column names the Constants API dictionary that holds the field's ids.

Field Format Constants Description
id int — Product ID on Cutwise.
sku string — Diamond SKU, set by the client.
price float | int | null — Diamond price. null if not set.
isColored bool — true if the diamond is graded as fancy colored.
isPublished bool — true if the diamond has the Published status on the Cutwise Platform.
cutShape int dict.cutShape Cut shape.
carat float | int — Carat weight.
clarity int dict.clarity Clarity grade.
color int dict.color Color grade of a colorless diamond.
cutQuality int dict.cutQuality Cut quality grade.
polish int dict.polish Polish grade.
symmetry int dict.symmetry Symmetry grade.
fluorIntensity int dict.fluorIntensity Fluorescence intensity (strength) grade.
fluorColor int dict.fluorColor Fluorescence color.
fancyGrade int dict.fancyGrade Color grade of a fancy colored diamond.
colorHue int dict.colorHue Color hue (GIA) grade of a fancy colored diamond.
colorModifier int dict.colorModifier Color modifier of a fancy colored diamond.
date string (ISO 8601) — Date and time when the diamond was created on Cutwise.
scores object — Cutwise Optical Performance Scores. See Optical Performance Scores.
_links object — HATEOAS links to the diamond on the Cutwise Platform.

Authorization

Every request needs an OAuth 2.0 Bearer token in the Authorization header. See Authorization.

List diamonds

  • Method and path: GET /v3/diamond
  • Auth: Bearer token
  • Request: optional filter and pagination parameters
  • Response: JSON array of Diamond objects

The list contains only the diamonds of the user who owns the access token.

GET /v3/diamond HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Response:

[
  {
    "id": 31893,
    "sku": "RBC_Melee-6",
    "price": null,
    "isColored": false,
    "isPublished": true,
    "cutShape": 2,
    "carat": 0.03,
    ...
  },
  {
    "id": 31892,
    "sku": "RBC_Melee-9",
    "price": null,
    "isColored": false,
    "isPublished": true,
    "cutShape": 2,
    "carat": 0.03,
    ...
  },
  {
    "id": 31891,
    "sku": "RBC_Melee-8",
    "price": null,
    "isColored": false,
    "isPublished": true,
    "cutShape": 2,
    "carat": 0.03,

    ...
  }
]

The list is sorted by creation date. If no diamonds match the filters, the API returns HTTP 204 with no content.

Filters

You can filter the list by id, sku, isColored, isPublished and date.

GET /v3/diamond?f[id][]=1&f[id][]=2&f[sku][]=EJ50&f[sku][]=EJ51&f[dateFrom]=20050809T183142+0330&f[dateTo]=20150809T183142+0330 HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

In this example, f[id][] and f[sku][] take several values each. f[dateFrom] and f[dateTo] set the date range.

Pagination

The list uses limit and offset. The default limit is 25. The default offset is 0.

GET /v3/diamond?limit=50&offset=50 HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

The X-Total-Count response header holds the total number of diamonds that match the filters.

Get one diamond

  • Method and path: GET /v3/diamond/{PRODUCT_ID}
  • Auth: Bearer token
  • Request: the product ID (the id field of the Diamond object) in the path
  • Response: one Diamond object
GET /v3/diamond/1234 HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Create a diamond

  • Method and path: POST /v3/diamond
  • Auth: Bearer token
  • Request: a Diamond object as JSON in the request body
  • Response: the created Diamond object

Do not send these fields:

  • id: Cutwise creates it.
  • date: Cutwise sets it.
  • scores: Cutwise calculates the scores after the diamond is created. This can take up to 1 hour.
  • _links: a virtual field.
POST /v3/diamond HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

{
  "sku": "RBC_Melee-6",
  "price": null,
  "isColored": false,
  "isPublished": true,
  "cutShape": 2,
  "carat": 0.03
}

The new diamond belongs to the user who owns the access token.

Create diamonds in bulk

  • Method and path: POST /v3/diamond/bulk
  • Auth: Bearer token
  • Request: up to 500 Diamond objects in the entries array. Each object follows the rules of Create a diamond.
  • Response: list of the created Diamond objects
POST /v3/diamond/bulk HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

{
  "entries": [{
    "sku": "RBC_Melee-6",
    "price": null,
    "isColored": false,
    "isPublished": true,
    "cutShape": 2,
    "carat": 0.03
  },
  {
    "sku": "RBC_Melee-7",
    "price": null,
    "isColored": false,
    "isPublished": true,
    "cutShape": 4,
    "carat": 0.025
  }]
}

Update a diamond

  • Method and path: PATCH /v3/diamond/{PRODUCT_ID} or PUT /v3/diamond/{PRODUCT_ID}
  • Auth: Bearer token
  • Request: the fields to change, as JSON in the request body
  • Response: the updated Diamond object

Fields you leave out stay unchanged. To remove a value, send null.

PATCH /v3/diamond/{PRODUCT_ID} HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

{
  "cutShape": 2,
  "carat": 0.031,
  "cutQuality": null
}

Update diamonds in bulk

  • Method and path: PATCH /v3/diamond/bulk or PUT /v3/diamond/bulk
  • Auth: Bearer token
  • Request: up to 500 objects in the entries array. Each object must contain the id field.
  • Response: list of the updated Diamond objects
PATCH /v3/diamond/bulk HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

{
  "entries": [{
    "id": {PRODUCT_ID_1},
    "isPublished": false,
    "cutShape": 2,
    "carat": 0.032
  },
  {
    "id": {PRODUCT_ID_2},
    "isPublished": false
  }]
}

Delete a diamond

  • Method and path: DELETE /v3/diamond/{PRODUCT_ID}
  • Auth: Bearer token
  • Request: the product ID in the path
DELETE /v3/diamond/{PRODUCT_ID} HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Delete diamonds in bulk

  • Method and path: DELETE /v3/diamond/bulk
  • Auth: Bearer token
  • Request: the product IDs in the entries array
DELETE /v3/diamond/bulk HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

{
  "entries": [{
    "id": {PRODUCT_ID_1},
  },
  {
    "id": {PRODUCT_ID_2},
  }]
}

Errors and limits

  • A bulk create or bulk update request takes up to 500 entries.
  • Scores are ready up to 1 hour after a diamond is created.
  • A list request with no matching diamonds returns HTTP 204 with no content.
  • HTTP 401 and 403 mean a missing or insufficient access token. See Authorization.
  • The error body format is on the Error handling page.

Related pages