Developer Documentation
Nivoda GraphQL API
Embed real-time diamond and gemstone data directly on your website. Our GraphQL API gives you full control over filtering, ordering, and integrating Nivoda's inventory into your platform.
Environments
Start with the staging environment to build and test your queries. Once ready, contact us to provision production access with live inventory data.
Staging
diamonds-graphiql ↗gemstones-graphiql ↗
Explorerusername: contact us
password: contact us
Auth usercontact us
password: contact us
Production
diamonds ↗diamonds-graphiql ↗
Explorerusername: contact us
password: contact us
AuthYour Nivoda login
Ready for production? Send your website URL
and company name to
tech@nivoda.com to get your
account upgraded to the live environment.
Getting Started
Open the GraphiQL Explorer
Navigate to the staging GraphiQL URL and log in with the explorer credentials above. This is your interactive playground for building and testing queries.
Authenticate to get a token
Run the
authenticate
query using the test credentials. Tokens are valid
for 6 hours.
GraphQL
{
authenticate {
username_and_password(
username: "testaccount@sample.com",
password: "staging-nivoda-22"
) {
token
}
}
}
Add the token to query variables
Copy the returned token and paste it into the
Variables panel in GraphiQL. All
subsequent queries require this token passed as
$token.
Run your first query
Test a diamonds query to confirm your setup is working.
Queries
Use these queries to retrieve diamond and gemstone data. The staging environment may have inconsistencies — use it to validate your filtering logic, then switch to production for live data.
Note: Staging data
may be incomplete or inconsistent. It's for query validation
only — production will return accurate, live inventory.
Diamonds
| Query | What it does | Input |
|---|---|---|
| authenticate | Generates an auth token (valid 6 hours) required for all other queries/mutations | Platform email + password |
| diamonds_by_query | Returns a filtered list of diamonds with offer IDs. Supports pagination, sorting, and full filter set | Filters, fields, limit, offset, order |
|
diamonds_by_query (WISE) |
Returns WISE-certified diamonds including WISE-specific fields like bowtie, girdleCondition, loupe360 videos |
Filters including
certificate_lab: [WISE]
|
| get_diamond_by_id | Returns full details and offer ID for a single diamond | Diamond ID |
| gemstones_by_query | Returns a filtered list of gemstones with offer IDs | Filters, fields, limit, offset, order |
| get_gemstone_by_id | Returns full details and offer ID for a single gemstone | Gemstone ID |
Example: diamonds_by_query
GraphQL
query ($token: String!) { as(token: $token) { diamonds_by_query( query: { labgrown: true, dollar_value: { from: 0, to: 63395 }, has_image: true, sizes: { from: 0.5, to: 16 }, returns: true, color: [D, E], clarity: [VVS2, VS1], cut: [EX], shapes: "OVAL", eyeClean: Yes, sue: false }, offset: 0, limit: 5, order: { type: price, direction: ASC } ) { items { id diamond { id video image mine_of_origin certificate { id lab shape certNumber } } price discount } total_count } } }
Example: get_diamond_by_id
GraphQL
query ($token: String!) { as(token: $token) { get_diamond_by_id( diamond_id: "e2c27aa3-d623-446c-aa19-a51db57678f5" ) { id diamond { availability } price } } }
Mutations Pro API only
Mutations allow you to place orders and holds directly on the Nivoda platform. You must be on the Pro API to use these — ensure you have followed the instructions for Pro API activation.
| Mutation | What it does | Required input |
|---|---|---|
| create_order | Places an order for stones on the Nivoda platform. Accepts offer ID, optional comments, reference number, return option, and destination ID |
"DIAMOND/<offerID>"
|
| create_hold | Places stones on hold and returns a hold ID for reference | Product ID + Product type |
Example: create_hold
GraphQL
mutation($token: String!) { as(token: $token) { create_hold( ProductId: "5c215e94-e1ad-474d-a6da-8fe047214c7c", ProductType: Diamond ) { id denied until } } }
Query Inputs Reference
All available filter inputs for
diamonds_by_query.
Use the search to find a specific parameter.
| Input | Description | Type | Values / Range | Notes |
|---|---|---|---|---|
| availability | Shows diamond availability status | List | AVAILABLE · NOT_AVAILABLE · ON_HOLD · ON_MEMO | For truly available: set availability: AVAILABLE, orderID: null, hide_memo: true |
| hide_memo | Hides non-purchasable diamonds | Boolean | true / false | true = remove non-available diamonds |
| preferredCurrency | Currency for returned prices | List | USD · GBP · EUR · AUD · CAD · AED · HKD · INR · ZAR · CHF | |
| price | Search on diamond price | Boolean | true / false | true = search on price |
| search_on_markup_price | Search on diamond price + markup | Boolean | true / false | true = search on markup price |
| labgrown | Lab-grown vs natural diamond | Boolean | true / false | false = natural diamond |
| labgrown_type | Lab-grown treatment type | List | HPHT · CVD · IIA | e.g. ["HPHT", "CVD"] |
| treated | Natural diamond with treatment | Boolean | true / false | true = treated |
| returns | Returnable diamond | Boolean | true / false | true = returnable |
| cut | Cut quality | List | P · F · G · VG · EX · ID · EIGHTX | Old names: PR, FR, GD. Pear/Marquise/Old Miner/Star shapes may return null |
| polish | Polish quality | List | P · F · G · VG · EX · ID · EIGHTX | |
| symmetry | Symmetry quality | List | P · F · G · VG · EX · ID · EIGHTX | |
| color | Diamond colour grade | List | D–Z scale + FANCY | Use FANCY to enable fancyColor filter |
| fancyColor | Fancy diamond colour | List | Yellow · Pink · Blue · Red · Green · Purple · Orange · Violet · Gray · Black · Brown · Champagne · Cognac · Chameleon · White · Other · Salt and Pepper | Requires color: [FANCY] |
| sizes | Carat weight range | FloatRange | 0.001 – 30.0 | {from: 0.5, to: 16} |
| shapes | Diamond shape | List | ROUND · OVAL · PRINCESS · CUSHION · EMERALD · PEAR · MARQUISE · RADIANT · ASSCHER · HEART · and more | "OVAL" or ["ROUND", "OVAL"] |
| flouresence | Fluorescence intensity | List | NON · VSL · SLT · FNT · MED · STG · STN · VST | |
| flouresence_color | Fluorescence colour | List | Blue · Black · Brown · Champagne · Cognac · Gray · Green · Orange · Pink · Purple · Red · Violet · White · Yellow | |
| clarity | Clarity grade | List | FL · IF · VVS1 · VVS2 · VS1 · VS2 · SI1 · SI2 · SI3 · I1 · I2 · I3 | |
| girdle | Girdle size | List | ACT · ETK · VTK · THK · STK · MED · STN · THN · VTN · ETN · ANY | |
| culet | Culet grade | List | NON · VSM · SML · MED · SLG · LGE · VLG · ELG | |
| discount | Discount percentage | IntRange | 0 – 100 | [from: 20, to: 50] |
| dollar_value | Total diamond cost | IntRange | 0 – 5,000,000 | $100.00 = 10000 (no punctuation) |
| dollar_per_carat | Per-carat cost | IntRange | 0 – 5,000,000 | Same dollar encoding as dollar_value |
| table_percentage | Table % | FloatRange | 0.0 – 100 | 0.1 = 10% |
| depth_percentage | Depth % | FloatRange | 0.0 – 100 | 0.1 = 10% |
| pav_percentage | Pavilion % | FloatRange | 0.0 – 100 | 0.1 = 10% |
| length_mm | Length (mm) | FloatRange | 0.0 – 100 | |
| width_mm | Width (mm) | FloatRange | 0.0 – 100 | |
| depth_mm | Depth/height (mm) | FloatRange | 0.0 – 100 | |
| pav_angle | Pavilion angle | FloatRange | 0.0 – 100 | |
| crown_angle | Crown angle | FloatRange | 0.0 – 100 | |
| star_length | Star length | FloatRange | 0.0 – 100 | |
| ratio | Length-to-width ratio | FloatRange | 0.0 – 100 | |
| has_image | Diamond has an image | Boolean | true / false | May be inaccurate in staging; 100% accurate in production |
| has_v360 | Diamond has a video | Boolean | true / false | May be inaccurate in staging |
| cv | Corrected front-facing video | Boolean | true / false | |
| has_certpdf | Diamond has a certificate | Boolean | true / false | May be inaccurate in staging |
| certificate_lab | Certificate lab | List | GIA · IGI · HRD · GCAL · IIDGR · SGL · EGL · AGS · WISE · NONE · noncert · STOCKID · OTHER · GGL · DSEF · CDC · FGL · GRS · AGL · ICL · GUBELIN · RGL · TGL · AIGS · LOTUS · SSEF · ZG · GSI · ALGT | To exclude unspecified, list all values except NONE |
| eyeClean | Eye-clean status | List | Yes · No · Borderline | |
| sue | Show unknown eye-clean | Boolean | true / false | true = include diamonds where eye-clean rating is unknown |
| luster | Luster rating | Int | 0=Excellent · 1=VVL Milky · 2=VL Milky · 3=L Milky · 4=Milky · 5=H Milky · 6=VH Milky | [0,1,2,3] |
| sul | Show unknown luster | Boolean | true / false | |
| brown | Brown tinge | Int | 0=false · 1=true | |
| green | Green tinge | Int | 0=false · 1=true | |
| blue | Blue tinge | Int | 0=false · 1=true | |
| gray | Gray tinge | Int | 0=false · 1=true | |
| other | Other tinge | Int | 0=false · 1=true | |
| noBGM | Not blue/green/milky | Int | 0=false · 1=true | |
| sub | Show unknown shade | Boolean | true / false | true = include diamonds where shade rating is unknown |
| inclusion_color | Inclusion colour | List | black · white | |
| inclusion_table | Inclusion severity (table) | List | HEAVY · MEDIUM · MINOR · NONE · HAIRLINE · PINPOINT | |
| inclusion_sides | Inclusion severity (sides) | List | HEAVY · MEDIUM · MINOR · NONE · HAIRLINE · PINPOINT | |
| open_inclusion_table | Open inclusion (table) | List | HEAVY · MEDIUM · MINOR · NONE · HAIRLINE · PINPOINT | |
| open_inclusion_sides | Open inclusion (sides) | List | HEAVY · MEDIUM · MINOR · NONE · HAIRLINE · PINPOINT | |
| fancyIntensity | Fancy colour intensity | List | Faint · Very_Light · Light · Fancy_Light · Fancy · Fancy_Dark · Fancy_Intense · Fancy_Vivid · Fancy_Deep | |
| fancyOvertone | Fancy colour overtone | List | None · Yellow · Yellowish · Pink · Pinkish · Blue · Blueish · Red · Reddish · Green · Greenish · Purple · Purplish · Orange · Orangey · Violet · Gray · Grayish · Black · Brown · Brownish · Champagne · Cognac · Chameleon · White · Other | |
| delivery_time | Delivery time (business days) | List | 1, 2, 3, 4, 5... | [2,3,4] |
| is_fbn | Nivoda Express (1–2 day delivery) | Boolean | true / false | |
| rjc | Responsible Jewellery Council certified | Boolean | true / false | |
| post_growth | Post-growth treatment | Boolean | true / false | |
| sustainability_rated_diamond | Sustainability rated | Boolean | true / false | |
| hearts_arrows | Hearts and arrows certificate | Boolean | true / false | |
| has_scs_certificate | SCS 007 certificate | Boolean | true / false | |
| canada_mark_eligible | Canada Mark eligible (no cert) | Boolean | true / false | |
| bowtie | Bowtie effect (WISE only) | — | — | Available in Diamond object. WISE diamonds only — other products return null |
| girdleCondition | Girdle condition (WISE only) | — | — | Available in certificate object. WISE diamonds only |
| culet_conditional | Culet condition (WISE only) | — | — | Available in certificate object. WISE diamonds only |