---
title: "Request a jeweler consultation"
method: POST
path: "/api/v1/consultations"
tags: ["Appointments"]
---

# Request a jeweler consultation

`POST /api/v1/consultations`

## Request

- Base URL: `https://www.adadiamonds.com`
- URL: `https://www.adadiamonds.com/api/v1/consultations`
- Auth: OAuth 2 (authorization code, authorization URL `https://www.adadiamonds.com/oauth/authorize`, token URL `https://www.adadiamonds.com/api/oauth/token`; client credentials, token URL `https://www.adadiamonds.com/api/oauth/token`, scopes: `appointments:write`)

Creates a real consultation request that a jeweler answers by email within one business day. Requires the `appointments:write` scope, which is only issued through the authorization code flow, so the customer has approved the request. Send an `Idempotency-Key` so a retried request cannot create a duplicate lead; sandbox credentials get a 201 without creating anything.

## Headers

- `Idempotency-Key` string

## Request body

- ConsultationRequest
  - `email` string, email, required
  - `name` string
  - `phone` string
  - `topic` 'engagement_ring' | 'loose_diamond' | 'wedding_band' | 'fine_jewelry' | 'custom_design' | 'other'
  - `message` string
  - `budget_usd` number
  - `product_url` string, uri

## Response `201`

The request was recorded.

- ConsultationResponse
  - `object` 'consultation_request', required
  - `id` string, required
  - `status` 'received', required
  - `sandbox` boolean
  - `note` string
  - `next_step` string
  - `email` string, email

## Other responses

- `400`: The request was malformed. `error_description` says which field.
- `401`: A credential is required. The `WWW-Authenticate` header carries the RFC 9728 `resource_metadata` pointer; follow it to the authorization server, or send a self-serve API key.
- `403`: The credential is valid but lacks the required scope, or the scope cannot be self-issued.
- `409`: A request with this `Idempotency-Key` is still in flight. Retry shortly.
- `422`: This `Idempotency-Key` was already used with a different request body. Use a new key.
- `429`: Over the rate limit. Wait `Retry-After` seconds; a credential raises the limit.
- `502`: A catalog or content feed is temporarily unavailable. Retry in a few seconds.

---

[API](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api.md) · [All operations](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/revisions/2b2ed3201815?raw)