Create a contact (legacy — no identity)
Legacy. Fully supported with no removal planned, but the response does not include OptimalDial Identity.
POST /api/v2/contacts takes the identical request and returns the same
contact with the identity fields. Existing integrations can stay here
indefinitely.
Submits one phone number for processing. Charges 1 credit and stores
the contact in queued status. 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).
E.164-normalized phone number (US/CA only).
"+15551234567"
Arbitrary extra fields echoed back from creation.
queued, processing, completed, failed, discarded x >= 0The Answer Intent classification — e.g. "Likely Answer",
"Likely Voicemail". Populated when status == "completed".
This field is frozen on v1: it keeps returning the Answer Intent
value even for contacts processed with OptimalDial Identity, so
existing filters keep working. Use /api/v2/contacts for the
nine-tier status and the identity band.
Validation pricing tier this contact was created with.
standard, max