Core concepts
The API is built around a small set of objects. This page defines each one, how they relate and which identifier prefix it uses, so the rest of the documentation reads naturally.
Text
Workspace (ws_)
Your organisation in RelationsAI. Every key, object and charge belongs to one workspace, and nothing is ever shared between workspaces: another workspace's id answers resource_not_found. GET/workspace returns your workspace with its name, timezone, currency, the current key, its capabilities (what the API offers this workspace today) and its limits.
Inside a workspace, every key works in one mode, test or live, and activity data never crosses between modes. Every object says which with livemode. See Environments.
Agent (agent_)
An AI voice agent: what the person called hears and how the conversation goes. Agents are created, configured, published and switched on in the console; a call always uses the agent's published version. The API lists agents, returns one, and checks whether one can place calls right now with GET/agents/{agent_id}/readiness, which returns every problem it finds (for example agent_not_published or no_outbound_number).
status is active, paused, draft or unknown; only active agents can call. Test mode adds the built-in Sample agent.
Phone number (pn_)
A number your workspace calls from, in E.164 format. Numbers are added and assigned to agents in the console. Each lists the agents that call from it (outbound_agent_ids) and the agent that answers it (inbound_agent_id). A call uses the agent's outbound number unless you choose one with phone_number_id.
Contact (ct_)
A person you may call, identified by phone number (unique per workspace and mode), with a name, language, whether they consented to be called (consent_granted), whether they are on the do-not-call list (do_not_call) and custom field values. When you call a number that matches a contact, the contact's name and custom fields are passed to the agent as call variables. POST/contacts/upsert creates or updates a contact by phone number, which is the easiest way to sync from a CRM.
Do-not-call entry (dnc_)
A number your workspace must not call, in that mode. Calls to it are refused with dnc_listed, and campaigns leave it out when they start or resume. A campaign that is already running is not screened again: pause and resume it, or stop it, after adding a number. Matching ignores formatting. Each mode has its own list.
Call (call_)
One outbound phone conversation placed by an agent, from the API, the console or a campaign (source). A call moves through these statuses:
status | Meaning |
|---|---|
queued | Accepted; being placed. POST /v1/calls returns the call in this status. |
ringing | Not reported today; see capabilities.call_ringing_status. |
in_progress | Connected. |
ended | Finished. outcome and end_reason say how. |
unknown | The state could not be confirmed for an unusually long time. Never a success. |
outcome is completed (a conversation took place), no_response (answered but nobody spoke, including most voicemail), no_answer, busy, failed or unknown. After a call ends, its three artifacts become available, each with its own state (pending, ready, absent or failed):
- the transcript, turn by turn and verbatim;
- the recording, through a short-lived link;
- the analysis: a summary, the fields the agent extracts, and whether the call met its goal.
When outcome, duration, artifacts and charge are all final, settled becomes true. Treat a call's outcome, duration_seconds and cost as final only once it is settled.
Campaign (cmp_) and recipient (rcp_)
A campaign calls a list of recipients with one agent, a number of calls at a time (concurrency_limit) and an optional budget cap. The budget cap pauses the campaign when spend reaches it; it is checked about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Each recipient is a contact in the campaign, with what happened to them in the current or latest run.
status | Meaning |
|---|---|
draft | Created, never started. Recipients can be added only now. |
running | Calling recipients. |
paused | No new calls; resume continues the same run. Can also happen automatically, for example when the budget cap is reached. |
stopped | Ended by request. |
completed | The run called every recipient. |
failed | The run ended in failure. |
Every start and resume screens recipients against the do-not-call list, consent and the per-number daily limit; a running campaign is not screened again. dnc_screening is enforced, or disabled_in_console when a person switched do-not-call screening off for that campaign in the console, in which case the API refuses to start or resume it. Campaigns and contacts carry an ETag for safe updates (see Concurrency).
Webhook endpoint (we_), event (evt_) and delivery (wd_)
A webhook endpoint is an HTTPS URL on your server that receives events of one mode. An event is a signed JSON notification such as call.ended, call.settled or campaign.completed, carrying a snapshot of the object. A delivery is one event's attempts to reach one endpoint, which you can list and retry. See Webhooks.
Identifiers
Ids are strings with a type prefix, at most 64 characters, for example call_6Vb3Nm8Qw2Er5Ty9Ui4Op7. Treat them as opaque: store them as strings and do not parse them or build them yourself. Every response also has a request id (req_...) in the X-Request-Id header. See Data types.