Contacts (Enterprise)

Documentation Index

Fetch the complete documentation index at: https://docs.optimaldial.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Lifecycle

1. POST /api/v1/contacts — submit one phone number. We charge 1 credit and return immediately with a contact_id in queued state.
2. Processing happens asynchronously. Typical turnaround is within 24-48 hours.
3. When processing finishes, the contact transitions to completed (with optimaldial_status set) or failed (with error_message).
4. You learn the result via either:
   • The callback_url you provided on creation (a signed POST per contact — recommended for integrations that can listen for webhooks), or
   • Your registered org-level webhook endpoints (contact.completed / contact.failed), or
   • Polling GET /api/v1/contacts/{contact_id}.

​

The Contact object

​

Statuses

​

Create a contact

POST /api/v1/contacts

​

Request body

curl -X POST https://api.optimaldial.com/api/v1/contacts \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "properties": { "row_id": "abc123", "first_name": "Alex" },
    "callback_url": "https://hooks.example.com/optimaldial-contact",
    "callback_secret": "shared-secret-for-hmac",
    "idempotency_key": "row-abc123"
  }'

const res = await fetch("https://api.optimaldial.com/api/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPTIMALDIAL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone: "+15551234567",
    properties: { row_id: "abc123", first_name: "Alex" },
    callback_url: "https://hooks.example.com/optimaldial-contact",
    callback_secret: process.env.CALLBACK_SECRET,
    idempotency_key: "row-abc123",
  }),
});
const contact = await res.json();

resp = requests.post(
    "https://api.optimaldial.com/api/v1/contacts",
    headers={
        "Authorization": f"Bearer {os.environ['OPTIMALDIAL_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "phone": "+15551234567",
        "properties": {"row_id": "abc123", "first_name": "Alex"},
        "callback_url": "https://hooks.example.com/optimaldial-contact",
        "callback_secret": os.environ["CALLBACK_SECRET"],
        "idempotency_key": "row-abc123",
    },
)
contact = resp.json()

​

Response

{
  "id": "9b1f4f5e-0a8a-4c4c-8d2e-d9d0f9b4a1f1",
  "organization_id": "...",
  "phone": "+15551234567",
  "properties": { "row_id": "abc123", "first_name": "Alex" },
  "status": "queued",
  "optimaldial_status": null,
  "error_message": null,
  "credits_charged": 1,
  "created_at": "2026-05-04T18:01:23+00:00",
  "updated_at": "2026-05-04T18:01:23+00:00"
}

​

Errors

​

Retrieve a contact

GET /api/v1/contacts/{contact_id}

curl "https://api.optimaldial.com/api/v1/contacts/$CONTACT_ID" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

​

List contacts

GET /api/v1/contacts

curl "https://api.optimaldial.com/api/v1/contacts?status=completed&limit=100" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

{
  "data": [ /* Contact, Contact, … */ ],
  "next_cursor": "2026-05-04T17:55:00+00:00"
}

​

Result delivery

1. Per-contact callback — if you provided callback_url on creation, we POST a signed JSON body to it. Same signature scheme and retry semantics as org-level webhooks: HMAC-SHA256 of f"{ts}.{body}" using your callback_secret, 6 attempts with exponential backoff. Headers include X-OptimalDial-Signature and X-OptimalDial-Timestamp.
2. Org-level webhooks — your registered webhook endpoints receive contact.completed / contact.failed events for every contact that finishes. Useful for fan-out to internal systems independent of the per-contact callback.

{
  "id": "evt_contact_...",
  "type": "contact.completed",
  "created_at": "2026-05-04T19:30:01+00:00",
  "data": {
    "contact": {
      "id": "9b1f4f5e-0a8a-4c4c-8d2e-d9d0f9b4a1f1",
      "phone": "+15551234567",
      "properties": { "row_id": "abc123", "first_name": "Alex" },
      "status": "completed",
      "optimaldial_status": "Likely Answer",
      "created_at": "2026-05-04T18:01:23+00:00"
    }
  }
}