Skip to main content
POST
Create a contact (legacy — no identity)

Authorizations

Authorization
string
header
required

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

application/json
phone
string
required

Any common format. Normalized to E.164. Must be US or Canadian.

Example:

"+15551234567"

validation_tier
enum<string>
default:standard

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.

Available options:
standard,
max
properties
object

Arbitrary extra fields echoed back in the result payload. Use these to correlate the result with your own row IDs.

callback_url
string<uri>

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).

callback_secret
string

HMAC-SHA256 secret used to sign the callback_url payload.

idempotency_key
string

Optional. Re-posting with the same key returns the existing contact without an extra credit charge. Scoped per (organization, api_key).

Maximum string length: 255

Response

Contact created (or returned via idempotency).

id
string<uuid>
required
organization_id
string<uuid>
required
phone
string
required

E.164-normalized phone number (US/CA only).

Example:

"+15551234567"

properties
object
required

Arbitrary extra fields echoed back from creation.

status
enum<string>
required
Available options:
queued,
processing,
completed,
failed,
discarded
credits_charged
integer
required
Required range: x >= 0
created_at
string<date-time>
required
updated_at
string<date-time>
required
optimaldial_status
string | null

The 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.

error_message
string | null
validation_tier
enum<string>

Validation pricing tier this contact was created with.

Available options:
standard,
max