Add contacts

POST/api/v2/jobs/{jobId}/contactskey or session

The job must allow manual contacts (a toggle on the job, on by default). Job status is not checked here, but only running jobs actually dial.

Body

One contact, or a contacts array. Both work.

{ "contactPhone": "+358401234567", "contactName": "Ada Lovelace" }

{
  "contacts": [
    { "contactPhone": "+358401234567", "contactName": "Ada" },
    { "contactEmail": "grace@example.com", "contactName": "Grace", "contactMetadata": { "plan": "pro" } }
  ]
}

contactPhonestring

E.164. Required unless contactEmail is set.

contactEmailstring

Required unless contactPhone is set.

contactNamestring

contactMetadataobject

Anything. The worker sees it during the conversation. Put order ids, CRM links, context here.

sourcestring

Free text label. trigger, manual, import are the conventional ones.default manual

Max 500 per request. Retry attempts per contact come from the job's outbound strategy, not from you.

Response

201 all added, 207 some failed, 400 none added. Same body in every case:

{
  "data": {
    "jobId": "…",
    "totalRequested": 2,
    "successful": 1,
    "failed": 1,
    "results": [
      { "success": true, "id": "9f3c1a20-…" },
      { "success": false, "error": "Invalid phone number format (E.164 required, e.g. +14155552671)" }
    ]
  },
  "meta": { "timestamp": "…" }
}

results is positional. Match by index.

Gotchas

Not idempotent. Post the same phone twice, get two contacts, two calls. Dedupe on your side.
403 means the job has manual contacts switched off.
404 means wrong id or not your org.
Needs job:update. Viewers can't.

Body

Response

Gotchas

On this page