Diamonds API v4

Managing a vendor's diamonds published on Cutwise, with grades as plain string values.

Diamonds API v4 lets a vendor create, read, update and delete the diamonds it owns on Cutwise. Grades are plain strings, such as "VS2" or "Excellent". For grades as dictionary ids, see Diamonds API v3.

Example

This request returns the diamond with product ID 1234:

GET /v4/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,
  "isLabGrown": false,
  "cutShape": "Round",
  "carat": 0.73,
  "clarity": "VS2",
  "color": "G",
  "cutQuality": "Excellent",
  "polish": "Excellent",
  "symmetry": "Excellent",
  "fluorIntensity": "FNT",
  "fluorColor": "B",
  "fancyGrade":null,
  "colorHue":null,
  "colorModifier":null,
  "culetSize":"N",
  "girdle":"Thin-Medium",
  "date":"2014-11-27T21:11:00+00:00",
  "access": 1,
  "dataAccess": 0,
  "certifications": [
    {
      "id": 330,
      "laboratory": "GIA",
      "number": "33188",
      "url": "https://www.gia.edu/report-check?reportno=2136273512",
      "file": "https://d1d7qk4j7uzdqw.cloudfront.net/StoneCertificates/333/2136273512.pdf"
    }
  ],
  "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,
      "color": 4,
      "colorCode": "B",
      "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"
  }]
}
Field Format 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.
isLabGrown bool true if the diamond is lab-grown.
cutShape string Cut shape.
carat float | int Carat weight.
clarity string Clarity grade.
color string Color grade of a colorless diamond.
cutQuality string Cut quality grade.
polish string Polish grade.
symmetry string Symmetry grade.
fluorIntensity string Fluorescence intensity (strength) grade.
fluorColor string Fluorescence color.
fancyGrade string Color grade of a fancy colored diamond.
colorHue string Color hue (GIA) grade of a fancy colored diamond.
colorModifier string Color modifier of a fancy colored diamond.
culetSize string Culet size grade.
girdle string Girdle grade.
date string (ISO 8601) Date and time when the diamond was created on Cutwise.
access int General share access. See the accepted values.
dataAccess int Access to the cut data. See the accepted values.
certifications Certification[] List of certifications. See Certifications API v4.
scores object Cutwise Optical Performance Scores. See Optical Performance Scores.
_links object HATEOAS links to the diamond on the Cutwise Platform.

The values each field accepts are listed on the Accepted values page.

Authorization

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

List diamonds

  • Method and path: GET /v4/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 /v4/diamond HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Response:

[
  {
    "id": 31893,
    "sku": "RBC_Melee-6",
    "price": null,
    "isColored": false,
    "isLabGrown": false,
    "carat": 0.03,
    ...
  },
  {
    "id": 31892,
    "sku": "RBC_Melee-9",
    "price": null,
    "isColored": false,
    "isLabGrown": false,
    "carat": 0.03,
    ...
  },
  {
    "id": 31891,
    "sku": "RBC_Melee-8",
    "price": null,
    "isColored": false,
    "isLabGrown": false,
    "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 and date.

GET /v4/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 /v4/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 /v4/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 /v4/diamond/1234 HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Create a diamond

  • Method and path: POST /v4/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.
  • certifications: add a certification with the Certifications API.
  • scores: Cutwise calculates the scores after the diamond is created. This can take up to 1 hour.
  • _links: a virtual field.
POST /v4/diamond HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

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

The new diamond belongs to the user who owns the access token. The values each field accepts are listed on the Accepted values page.

Create diamonds in bulk

  • Method and path: POST /v4/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 /v4/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,
    "cutShape": 2,
    "carat": 0.03
  },
  {
    "sku": "RBC_Melee-7",
    "price": null,
    "isColored": false,
    "cutShape": 4,
    "carat": 0.025
  }]
}

Update a diamond

  • Method and path: PATCH /v4/diamond/{PRODUCT_ID} or PUT /v4/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 /v4/diamond/{PRODUCT_ID} HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

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

Update diamonds in bulk

  • Method and path: PATCH /v4/diamond/bulk or PUT /v4/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 /v4/diamond/bulk HTTP/1.1
Host: api.cutwise.com
Authorization: Bearer {CUTWISE_ACCESS_TOKEN}

Request body:

{
  "entries": [{
    "id": {PRODUCT_ID_1},
    "carat": 0.032
  },
  {
    "id": {PRODUCT_ID_2},
    "carat": 0.55
  }]
}

Delete a diamond

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

Delete diamonds in bulk

  • Method and path: DELETE /v4/diamond/bulk
  • Auth: Bearer token
  • Request: the product IDs in the entries array
DELETE /v4/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