Skip to main content
POST
Attach contacts to a run
Attaches existing contacts to a run.

Overview

Contacts arrive here rather than at create, and this endpoint is idempotent: an id already on the run is skipped, not attached twice. That is what makes retries and overlapping chunks safe.
Send the same body again and you get { "attached": 0, "skipped": 2, "totalContacts": 2 }. The counts report rows actually changed, so they tell you what your request did rather than what it asked for.

Attaching to a run that is already going

This is the point of the endpoint, not an edge case. A run is a rolling sequence, not a frozen batch:
Because a COMPLETED run reopens, do not treat COMPLETED as “this run is finished forever” if anything in your system still attaches to it.
Attaching into a RUNNING run spends money, so it runs the same all-or-nothing billing admission a launch does. Without that, attach would simply be the way around the gate: launch one contact, attach 999.

Batch bounds

Up to 500 contact ids per request. More is a 400, not a silent truncation — a caller told “attached 500” out of 900 has no way to know which 400 were dropped. Chunking is yours to do and safe to do, precisely because attaching an id twice is a no-op:
A run’s total contact count is deliberately unbounded. Only the per-request batch is capped.

Contacts must already exist

This endpoint attaches existing contacts; it does not create them. Create them first with Create Contact. An id that is not an active contact in your company is a 422 naming the ids it could not find, and nothing is attached.

Error Scenarios

  • 400 Bad Request: more than 500 ids, an empty list, or a malformed id
  • 402 Payment Required: attaching into a live run the company cannot afford. Nothing is attached and nothing is dispatched
  • 404 Not Found: the run does not exist, or belongs to another company
  • 422 Unprocessable Entity: the run is cancelled, or an id is not a contact in this company
  • 403 Forbidden: the API key does not hold write:runs and read:contacts

Detach Contact

Remove a contact from a draft

Launch Run

Fan the draft out into conversations

Create Contact

Create the people first

Runs Resource Guide

How a run batches conversations

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

id
string<uuid>
required

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
contactIds
string<uuid>[]
required

Contact ids to attach. Max 500 per request; send more in separate requests, which is safe because attaching an id twice is a no-op.

Required array length: 1 - 500 elements
Example:

Response

Contacts attached

attached
number
required

Contacts newly attached by this request

Example:

8

skipped
number
required

Ids already on the run, so this request did nothing for them. Repeating a batch is safe.

Example:

2

totalContacts
number
required

Contacts on the run after this request

Example:

10

queued
number
required

Conversations queued by this attach. Non-zero only on an already-launched run; zero on a draft, which dials nothing until launched.

Example:

8