Skip to main content
POST
Create a contact

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

The v2 view of a contact. Identical to Contact except for what a completed result reports:

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 nine-tier OptimalDial_Status value. Falls back to the Answer Intent value for contacts processed before identity.

Example:

"1 - Likely Right-Party Answer"

error_message
string | null
validation_tier
enum<string>

Validation pricing tier this contact was created with.

Available options:
standard,
max
optimaldial_answer_intent
string | null

Whether the number is likely to pick up, on its own.

Example:

"Likely Answer"

optimaldial_identity
enum<string> | null

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

Available options:
Very High,
High,
Medium,
Low,
Unknown,
null