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

The POST /api/v2/contacts request body: everything in ContactCreate plus optional name fields that enable OptimalDial Identity for the contact. Supply full_name, or both first_name and last_name. Supplying only one of first_name / last_name returns 422 with "Identity requires either full_name, or both first_name and last_name." When full_name and the first/last pair are all present, full_name is what identity is scored against. Names are trimmed of surrounding whitespace; a blank value is treated as absent. Names placed inside properties are echoed back but are not used for identity. Identity carries no extra credit charge.

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
full_name
string

The contact's full name. Enables OptimalDial Identity on its own. Takes precedence over first_name / last_name when all three are supplied.

Maximum string length: 200
Example:

"Alex Rivera"

first_name
string

Enables OptimalDial Identity when supplied together with last_name. Not sufficient on its own.

Maximum string length: 200
Example:

"Alex"

last_name
string

Enables OptimalDial Identity when supplied together with first_name. Not sufficient on its own.

Maximum string length: 200
Example:

"Rivera"

Response

Contact created (or returned via idempotency).

The v2 view of a contact. Identical to Contact except that it echoes the submitted name fields and reports the identity result:

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

queued → processing → one of completed, failed, or discarded. failed means processing finished without a result for this contact; discarded means OptimalDial dropped it before processing. Both refund the credit, both set error_message, and both are delivered as a contact.failed event to your webhook endpoints and the contact's callback_url — check status on the payload to tell them apart.

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

Why the contact is failed or discarded; null otherwise.

validation_tier
enum<string>

Validation pricing tier this contact was created with.

Available options:
standard,
max
full_name
string | null

The full_name submitted on creation, or null.

Example:

"Alex Rivera"

first_name
string | null

The first_name submitted on creation, or null.

last_name
string | null

The last_name submitted on creation, or null.

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. Requires a name on creation (full_name, or both first_name and last_name). Null when no contact in the processing batch supplied a name; Unknown when this contact had no name but another contact in its batch did, or when there was no signal either way. Unknown is not "safe".

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