Create a contact
Submits one phone number for processing. Charges 1 credit and stores the
contact in queued status.
The identical request to POST /api/v1/contacts — same credits, same
idempotency semantics, same callbacks, same underlying contact. Only the
response differs, carrying the v2 result fields (null until processing
completes).
Re-posting with the same idempotency_key returns the existing contact
without an additional credit charge.
Authorizations
OptimalDial API key, prefixed od_live_, sent as Authorization: Bearer ....
Mint keys in the in-app developer panel; they are scoped to a single organization.
Body
Any common format. Normalized to E.164. Must be US or Canadian.
"+15551234567"
Validation pricing tier. standard (default) charges 1 credit.
max is more thorough and is billed so a batch of contacts totals
ceil(1.5 × count) credits — a lone MAX contact costs 2, and each
additional pair adds 3 (exactly 1.5×). The amount deducted for this
contact is returned as credits_charged. Case-insensitive.
standard, max Arbitrary extra fields echoed back in the result payload. Use these to correlate the result with your own row IDs.
Optional per-contact webhook URL. Receives a signed POST when the contact's result is ready, with the same retry semantics as registered org-level webhook endpoints (6 attempts with backoff).
HMAC-SHA256 secret used to sign the callback_url payload.
Optional. Re-posting with the same key returns the existing contact without an extra credit charge. Scoped per (organization, api_key).
255Response
Contact created (or returned via idempotency).
The v2 view of a contact. Identical to Contact except for what a
completed result reports:
E.164-normalized phone number (US/CA only).
"+15551234567"
Arbitrary extra fields echoed back from creation.
queued, processing, completed, failed, discarded x >= 0The nine-tier OptimalDial_Status value. Falls back to the Answer Intent value for contacts processed before identity.
"1 - Likely Right-Party Answer"
Validation pricing tier this contact was created with.
standard, max Whether the number is likely to pick up, on its own.
"Likely Answer"
How strongly the signals indicate the number belongs to your contact. Null when the batch had no name columns mapped. Note Unknown means no signal either way — it is not "safe".
Very High, High, Medium, Low, Unknown, null