Contacts

The Contacts API accepts one phone number per request and returns an OptimalDial Status classification (e.g. "Likely Answer", "Likely Voicemail") once processing finishes. Use it when your tooling enriches one row at a time and the bulk Uploads API doesn’t fit. It’s available to every account with an API key — no special access needed. Each contact costs 1 credit at the default standard tier, or 1.5x at max — see Validation tiers.

Lifecycle

POST /api/v2/contacts — submit one phone number. We charge credits per the validation tier (1 credit at the default standard) and return immediately with a contact_id in queued state.
Processing happens asynchronously. Typical turnaround is within 24-48 hours.
When processing finishes, the contact transitions to completed (with optimaldial_status set) or failed (with error_message).
You learn the result via either:
- The callback_url you provided on creation (a signed POST per contact — recommended for integrations that can listen for webhooks), or
- Your registered org-level webhook endpoints (contact.completed / contact.failed), or
- Polling GET /api/v2/contacts/{contact_id}.

The Contact object

Field	Type	Notes
`id`	string (UUID)	Stable identifier.
`organization_id`	string (UUID)	Org the contact belongs to.
`phone`	string	E.164-normalized phone (US/CA only).
`properties`	object	Whatever extra fields you sent on creation, echoed back in result payloads.
`status`	enum	One of: `queued`, `processing`, `completed`, `failed`, `discarded`.
`optimaldial_status`	string \| null	On v2, the nine-tier value — e.g. `"1 - Likely Right-Party Answer"`. On v1, the Answer Intent value — e.g. `"Likely Answer"`. Populated when `status == "completed"`.
`optimaldial_answer_intent`	string \| null	v2 only. Whether the number is likely to pick up, on its own.
`optimaldial_identity`	string \| null	v2 only. `Very High` / `High` / `Medium` / `Low` / `Unknown`. Null when the batch had no name columns mapped.
`error_message`	string \| null	Populated when `status == "failed"`.
`message`	string \| null	Human-readable note about the current state. Populated while the contact is still `queued`/`processing` (e.g. “Contact has not been processed yet…”); `null` once it reaches a terminal state.
`validation_tier`	`"standard"` \| `"max"`	Tier this contact was submitted at, locked at creation. Defaults to `standard`.
`credits_charged`	integer	Credits deducted for this contact — always `1` at `standard`. At `max` the per-contact amount alternates; see Validation tiers. Refunded in full if the contact is discarded or fails.
`created_at`	string (ISO 8601)	UTC timestamp.
`updated_at`	string (ISO 8601)	UTC timestamp of the last status change.

Statuses

Status	Meaning
`queued`	Submitted, awaiting processing.
`processing`	Processing in progress.
`completed`	Result is on `optimaldial_status`.
`failed`	Processing finished but did not produce a result; see `error_message`.
`discarded`	Discarded by OptimalDial; credit refunded. Rare.

v2 — the current version

The identity fields below come from OptimalDial Identity, currently in public beta. The response shape is stable; we’re still tuning the thresholds. Feedback welcome at support@optimaldial.com.

/api/v2/contacts mirrors every v1 route — create, list, and retrieve — and additionally reports the nine-tier OptimalDial_Status and the Identity band.

	v1	v2
Create	`POST /api/v1/contacts`	`POST /api/v2/contacts`
List	`GET /api/v1/contacts`	`GET /api/v2/contacts`
Retrieve	`GET /api/v1/contacts/{id}`	`GET /api/v2/contacts/{id}`

Requests are identical — same fields, same credits, same idempotency semantics, same callbacks. Only the response differs:

Field	v1	v2
`optimaldial_status`	`"Likely Answer"`	`"1 - Likely Right-Party Answer"` (the tier)
`optimaldial_answer_intent`	—	`"Likely Answer"`
`optimaldial_identity`	—	`"Very High"`

{
  "id": "8a1f…",
  "status": "completed",
  "optimaldial_status": "1 - Likely Right-Party Answer",
  "optimaldial_answer_intent": "Likely Answer",
  "optimaldial_identity": "Very High"
}

v1 is legacy — supported indefinitely, with no removal planned. It simply doesn’t include identity: optimaldial_status there keeps returning the Answer Intent value, so existing filters keep working exactly as before.There is no migration. Both versions operate on the same contacts, so one created on v1 can be read on v2 and vice versa. Point your calls at /api/v2/ whenever you’re ready — or don’t, and stay on v1.The two new fields are null on contacts whose batch was processed without identity.

The contact.completed webhook payload gains optimaldial_tier and optimaldial_identity alongside the existing optimaldial_status, which is unchanged. Existing consumers need no action.

Validation tiers

Each contact runs at one of two tiers. Pass validation_tier on Create a contact; it defaults to standard.

Tier	Credits per number	Notes
`standard`	1	Optimized for speed and volume.
`max`	1.5	More thorough; identifies more likely answerers over a longer window.

The value is case-insensitive, and anything other than standard or max returns 400. max is available on this endpoint at any volume, including a single contact. The 100-number minimum documented on the bulk Uploads API applies only there — if your pipeline produces a handful of numbers at a time, submit them here per-row rather than accumulating to reach that floor.

curl -X POST https://api.optimaldial.com/api/v2/contacts \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+15551234567", "validation_tier": "max" }'

How `max` is billed per contact

Credits are whole-number ledger entries, so max can’t charge a fraction on a single-contact request. It bills marginally instead: successive max contacts are charged 2, 1, 2, 1, … credits. The alternation runs across your current queued batch — the max contacts you’ve submitted that haven’t moved to processing yet. Whatever that batch ends up holding, its total is exactly ceil(N × 1.5): the same price as submitting those N numbers as one max upload.

`max` contacts in the batch	Total credits
1	2
2	3
5	8
40	60

So there’s no cost penalty for submitting one at a time instead of batching. Because the charge alternates, the subtotal for any one run depends on where it lands in the batch: five max contacts cost 8 credits when they open a fresh batch, or 7 when they land mid-alternation. A run of n is never charged more than ceil(n × 1.5). Read credits_charged on each response for the exact amount deducted rather than assuming a fixed per-contact cost.

Create a contact

POST /api/v2/contacts

Submits one phone for processing. Returns 201 with the new contact in queued status.

POST /api/v1/contacts accepts an identical request and is still supported — it just returns the legacy response shape, without the identity fields.

Request body

Field	Type	Required	Notes
`phone`	string	yes	Any common format. Normalized to E.164 server-side. Must be US or Canadian.
`validation_tier`	`"standard"` \| `"max"`	no	Validation tier (defaults to `standard`). Case-insensitive. `max` is more thorough and costs 1.5 credits/number, with no minimum submission size — see Validation tiers.
`properties`	object	no	Arbitrary extra fields echoed back in result payloads. Use these to correlate the result with your own row IDs.
`callback_url`	string (HTTPS)	no	Optional per-contact webhook. We POST to it when the contact’s result is ready. Signed with `callback_secret` if provided. Same retry semantics as registered org webhooks (6 attempts with exponential backoff).
`callback_secret`	string	no	HMAC-SHA256 secret used to sign the `callback_url` payload.
`idempotency_key`	string	no	Optional. Re-posting with the same key returns the existing contact without an extra credit charge. Scoped per `(organization, api_key)`.

cURL
Node.js
Python

curl -X POST https://api.optimaldial.com/api/v2/contacts \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "properties": { "row_id": "abc123", "first_name": "Alex" },
    "callback_url": "https://hooks.example.com/optimaldial-contact",
    "callback_secret": "shared-secret-for-hmac",
    "idempotency_key": "row-abc123"
  }'

const res = await fetch("https://api.optimaldial.com/api/v2/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPTIMALDIAL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone: "+15551234567",
    properties: { row_id: "abc123", first_name: "Alex" },
    callback_url: "https://hooks.example.com/optimaldial-contact",
    callback_secret: process.env.CALLBACK_SECRET,
    idempotency_key: "row-abc123",
  }),
});
const contact = await res.json();

resp = requests.post(
    "https://api.optimaldial.com/api/v2/contacts",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIMALDIAL_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "phone": "+15551234567",
        "properties": {"row_id": "abc123", "first_name": "Alex"},
        "callback_url": "https://hooks.example.com/optimaldial-contact",
        "callback_secret": os.environ["CALLBACK_SECRET"],
        "idempotency_key": "row-abc123",
    },
)
contact = resp.json()

Response

201 Created:

{
  "id": "9b1f4f5e-0a8a-4c4c-8d2e-d9d0f9b4a1f1",
  "organization_id": "...",
  "phone": "+15551234567",
  "properties": { "row_id": "abc123", "first_name": "Alex" },
  "status": "queued",
  "optimaldial_status": null,
  "error_message": null,
  "message": "Contact has not been processed yet. Poll this endpoint or wait for the contact.completed webhook.",
  "validation_tier": "standard",
  "credits_charged": 1,
  "created_at": "2026-05-04T18:01:23+00:00",
  "updated_at": "2026-05-04T18:01:23+00:00"
}

Errors

Status	When
`400`	`validation_tier` is not `standard` or `max`
`401`	Missing, invalid, or revoked API key
`402`	Organization out of credits
`422`	Phone is unparseable or not US/CA
`429`	Rate limit hit

Retrieve a contact

GET /api/v2/contacts/{contact_id}

Returns the latest snapshot. Use as a fallback if you missed a webhook delivery, or to poll until status == "completed".

curl "https://api.optimaldial.com/api/v2/contacts/$CONTACT_ID" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

List contacts

GET /api/v2/contacts

Cursor-paginated, newest first. Optional status filter.

Param	Type	Default	Notes
`status`	enum	—	Filter by one of the statuses.
`limit`	integer (1–100)	50	Page size.
`cursor`	string	—	Pass back `next_cursor` from the previous response.

curl "https://api.optimaldial.com/api/v2/contacts?status=completed&limit=100" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

{
  "data": [ /* Contact, Contact, … */ ],
  "next_cursor": "2026-05-04T17:55:00+00:00"
}

Result delivery

When a contact reaches completed or failed, OptimalDial fires up to two notifications:

Per-contact callback — if you provided callback_url on creation, we POST a signed JSON body to it. Same signature scheme and retry semantics as org-level webhooks: HMAC-SHA256 of f"{ts}.{body}" using your callback_secret, 6 attempts with exponential backoff. Headers include X-OptimalDial-Signature and X-OptimalDial-Timestamp.
Org-level webhooks — your registered webhook endpoints receive contact.completed / contact.failed events for every contact that finishes. Useful for fan-out to internal systems independent of the per-contact callback.

Both delivery paths emit the same payload shape, wrapping the Contact object:

{
  "id": "evt_contact_...",
  "type": "contact.completed",
  "created_at": "2026-05-04T19:30:01+00:00",
  "data": {
    "contact": {
      "id": "9b1f4f5e-0a8a-4c4c-8d2e-d9d0f9b4a1f1",
      "phone": "+15551234567",
      "properties": { "row_id": "abc123", "first_name": "Alex" },
      "status": "completed",
      "optimaldial_status": "Likely Answer",
      "validation_tier": "max",
      "credits_charged": 2,
      "created_at": "2026-05-04T18:01:23+00:00"
    }
  }
}

The properties object on the result echoes back exactly what you sent on creation — use it to correlate the result with your own row IDs without storing the OptimalDial contact_id.

Get started

Endpoint guides

Webhooks

API Reference

Resources

Lifecycle

The Contact object

Statuses

v2 — the current version

Validation tiers

How `max` is billed per contact

Create a contact

Request body

Response

Errors

Retrieve a contact

List contacts

Result delivery

​Lifecycle

​The Contact object

​Statuses

​v2 — the current version

​Validation tiers

​How max is billed per contact

​Create a contact

​Request body

​Response

​Errors

​Retrieve a contact

​List contacts

​Result delivery

Lifecycle

The Contact object

Statuses

v2 — the current version

Validation tiers

How `max` is billed per contact

Create a contact

Request body

Response

Errors

Retrieve a contact

List contacts

Result delivery