Schemas

Agent id (agent_...).

Always agent.

Mode of the key that read it. Agents are shared configuration, readable in both modes.

Agent name.

What the agent is for, as written in the console. Null when not set.

Whether the agent is switched on in the console. active agents can place calls; paused and draft agents cannot. Open enum: unknown values mean the agent cannot be assumed callable.

True when the agent has a published version that calls use. Null when the publication state could not be read right now; use the readiness endpoint for a definite answer.

Number of the published version, when known.

True for the workspace's default agent.

True only for the built-in Sample agent that exists in test mode.

When the agent was created.

When the agent's configuration last changed, when known.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Agents on this page.

Always agent_readiness.

Mode of the key that asked.

The agent checked.

True when reasons is empty.

Every reason the agent cannot place calls. Empty when ready.

When the check ran.

Machine-readable reason. Open enum: agent_paused (switched off in the console), agent_not_connected (setup not finished: open the agent in the console and save it once), agent_not_published (no published version, or its live version is paused), no_outbound_number (no outbound number assigned to the agent), calling_not_configured (no telephony account or number in the workspace), telephony_disconnected, account_inactive (trial ended or account suspended), spend_limit_reached, insufficient_balance.

What to do about it, for an operator.

pending, ready, absent or failed. Open enum.

Call id (call_...).

Always call.

true for a live call, false for a simulated test-mode call.

Where the call is in its lifecycle. Open enum. unknown means the state could not be confirmed for an unusually long time; it is not a success.

How the call ended. Null until status is ended. completed: answered and a conversation took place. no_response: answered but nobody spoke (this includes most voicemail greetings). no_answer, busy: not answered. failed: could not be connected. unknown: the result could not be determined. Open enum.

Why the call ended. Null until status is ended. hangup: a normal end of a connected call. no_answer, busy, invalid_number, network_error: the call was not connected for that reason. insufficient_balance: ended because the workspace balance ran out. not_confirmed: the start was never confirmed, so the call is treated as failed and is not charged (whether the number briefly rang cannot be known). refused: the call was refused before it started. unknown. Open enum.

Always outbound today. Open enum.

api (placed with POST /v1/calls), console, or campaign. Open enum.

The agent that handled the call. Null only if the agent was deleted.

The campaign that placed the call, if any.

The workspace number the call was placed from, once known.

The caller number shown to the person called (E.164), once known. Null when not known in full.

The number called (E.164), always in full. Null only for some calls recorded before 2026-08-14 whose number was stored partially at the time; a partial number is never shown in place of a full one.

Your own key-value data, stored with the object and returned as sent. Up to 16 keys; keys up to 40 characters (letters, digits, _, -, .), values strings up to 500 characters. Never sent to the person called and never used by the agent. Do not put secrets here.

When the call was accepted.

When the call ended.

Talk time in seconds once known. Final when settled is true.

Minutes charged (whole minutes, rounded up). Zero for calls that are not charged. Final when settled is true.

What the workspace was charged for this call. Null until known; always zero in test mode.

Readiness of each artifact of the call. pending: not ready yet. ready: available from its endpoint. absent: there is none for this call (for example a call that was not answered has no recording). failed: it could not be produced. Open enum.

True when outcome, duration, artifacts and charge are all final.

When the call settled.

Always call_analysis.

Mode of the call.

The call.

Overall state: pending while any part is still being produced, ready when every part has finished (a part may still be failed), absent when the call produced nothing to analyse. Open enum.

True for a test-mode fixture.

A short written summary of the conversation.

Fields the agent is configured (in the console) to extract from the conversation.

Whether the call met the agent's goal, when the agent is configured to report it. Null otherwise.

State of one call artifact.

State of one call artifact.

State of one call artifact.

The agent that makes the call (agent_...). It must be ready (see the agent readiness endpoint).

The number to call, in E.164 format (a plus, then 8 to 15 digits, the first not 0).

The workspace number to call from (pn_...). Optional: by default the agent's outbound number is used. Required when the agent has more than one outbound number.

Values the agent can use in the conversation, for example {"first_name": "Asha"}. Up to 50 keys; keys are lowercase letters, digits and _, starting with a letter, up to 64 characters; values are strings up to 500 characters. If the destination matches a contact, the contact's name and custom fields are added automatically; values here take precedence.

Your own key-value data, stored with the object and returned as sent. Up to 16 keys; keys up to 40 characters (letters, digits, _, -, .), values strings up to 500 characters. Never sent to the person called and never used by the agent. Do not put secrets here.

Event id (evt_...). The same event can be delivered more than once; use this to discard duplicates.

Always event.

The call event type.

When the event happened.

Mode of the event.

Version of the payload format, a date. Today 2026-10-21.

Event data.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Calls on this page.

Always call_recording.

Mode of the call.

The call.

pending, ready, absent (no recording exists for this call) or failed. Open enum.

True for the short synthetic audio file used in test mode.

Short-lived link to the audio. Null unless state is ready.

When url stops working.

Media type of the audio, for example audio/ogg or audio/mpeg (audio/wav for test-mode audio). Null when not known in advance; the download's Content-Type is authoritative.

Always call_transcript.

Mode of the call.

The call.

pending, ready, absent (nothing was said or the call was not connected) or failed. turns is empty unless ready. Open enum.

True for a test-mode fixture transcript.

Turns in the order they were spoken.

Campaign id (cmp_...).

Always campaign.

true for a live campaign, false for a test-mode campaign.

Campaign name.

The agent that makes the calls. Null if the agent was deleted; the campaign cannot start until one is set.

draft (never started), running, paused, stopped, completed (the run finished), failed (the run ended in failure), unknown. Open enum.

Which actions the campaign allows in its current status.

Most calls the campaign places at the same time. Lowered at start to the plan maximum (limits.campaign_max_concurrency on the workspace). Campaigns created in the console can hold a higher value than the API accepts on a write.

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Null for no cap.

Before the first start, the recipients added to the campaign. From a start on, the recipients that run calls: recipients left out by compliance screening at that start are not counted.

Call counts for the current or latest run. A call is counted in in_progress until it ends, and only then in connected, no_answer or failed. Updated as calls end; can lag by up to a minute.

What the current or latest run has cost so far. Always zero in test mode, which never charges.

How many runs the campaign has had. 0 before the first start.

When the campaign was created.

enforced (numbers on the do-not-call list are left out at every start and block a resume) or disabled_in_console (a person switched screening off for this campaign in the console; the API refuses to start or resume it with 409 campaign_dnc_override_enabled). Read-only. Open enum.

POST .../start is allowed.

POST .../pause is allowed.

POST .../resume is allowed.

POST .../stop is allowed.

PATCH is allowed.

POST .../recipients is allowed.

Campaign name.

The agent that makes the calls.

Most simultaneous calls. Defaults to 1. Lowered at start to the plan maximum.

The spend at which the campaign is paused. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time. Omit or null for no cap.

Contacts to add as recipients now. You can also add them later, while the campaign is draft.

Event id (evt_...). The same event can be delivered more than once; use this to discard duplicates.

Always event.

The campaign event type.

When the event happened.

Mode of the event.

Version of the payload format, a date. Today 2026-10-21.

Event data.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Campaigns on this page.

Calls placed.

Ended calls that were answered.

Ended calls that were not answered or were busy.

Every other ended call (it could not be connected, or it ended with an outcome that is not known).

Calls not yet ended.

Recipient id (rcp_...).

Always campaign_recipient.

Mode of the campaign.

The campaign.

The contact.

The number that is (or was) called.

pending (not yet called in this run), in_progress, completed (called; see outcome), failed (every attempt failed), suppressed (left out by compliance screening, see suppression_reason), cancelled (the run stopped before reaching them), unknown. Open enum. In live mode a recipient left out by screening at start is not recorded per recipient yet: it shows pending while the run is open and unknown once the run has ended. Test mode records it as suppressed.

Call attempts made in this run.

The most recent call to this recipient, if any.

Outcome of the most recent call, using the call outcome values. Null if not called yet.

Why the recipient was left out, when status is suppressed. Open enum dnc_listed, consent_required, contact_daily_limit_reached, unknown.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Recipients on this page.

Contacts to add. Contacts already in the campaign are skipped, not duplicated.

Always campaign_recipients_added.

Mode of the campaign.

The campaign.

Recipients newly added by this request (contacts already in the campaign are not counted).

Total recipients in the campaign now.

Campaign name.

The agent that makes the calls.

Most simultaneous calls.

The spend at which the campaign is paused, or null to remove the cap. When the campaign's spend reaches the cap the campaign is paused. The check runs about every 15 minutes, so spend can exceed the cap by the calls placed in that time.

Contact id (ct_...).

Always contact.

true for a live contact, false for a test-mode contact.

The contact's number. E.164 for contacts created through this API; contacts created earlier in the console may hold the number in the format it was entered.

Display name.

Preferred language, as free text or a language code.

Country code as entered, for example IN.

Whether the contact has consented to be called. When the workspace requires consent (a console compliance setting), calls to a contact without consent are refused. Setting this through the API records that consent was given; only set it when it really was. Consent is never recorded on a contact that is on the do-not-call list: it stays false there, and removing the entry does not restore it.

True when the contact's number is on the do-not-call list. Read-only here: manage it with the do-not-call endpoints. Adding a number to the list also withdraws the contact's consent.

Values of the workspace's custom fields for this contact, by field name. Fields are defined in the console.

When the contact was created. Null for some contacts created before this was recorded.

The contact's number in E.164 format.

Display name.

Preferred language.

Country code, for example IN.

Set to true only when the person has consented to be called. Recorded with the time and the API as its source.

Custom field values by field name. Each key must be a custom field defined in the console; an unknown name is 422 custom_field_not_found. Values are strings up to 500 characters. On update, a null value clears that field and omitted fields are left unchanged.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Contacts on this page.

New number in E.164 format. Must not belong to another contact.

Display name. Null clears it.

Preferred language. Null clears it.

Country code. Null clears it.

True records that consent was given; false records that it was withdrawn.

Custom field values by field name. Each key must be a custom field defined in the console; an unknown name is 422 custom_field_not_found. Values are strings up to 500 characters. On update, a null value clears that field and omitted fields are left unchanged.

The contact's number in E.164 format. Identifies the contact.

Display name. Null clears it.

Preferred language. Null clears it.

Country code. Null clears it.

Set to true only when the person has consented to be called; false records withdrawal. Omit to leave unchanged.

Custom field values by field name. Each key must be a custom field defined in the console; an unknown name is 422 custom_field_not_found. Values are strings up to 500 characters. On update, a null value clears that field and omitted fields are left unchanged.

Id of the deleted object.

Type of the deleted object, for example contact.

true for live mode, false for test mode.

Always true.

Entry id (dnc_...).

Always dnc_entry.

Mode of the entry. Test-mode entries apply only to test-mode calls.

The number.

The contact with this number, if there is one.

When the number was added to the list. Recorded in test mode; null in live mode, where the time is not stored yet.

The number in E.164 format.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Entries on this page.

The error.

Event id (evt_...). The same event can be delivered more than once; use this to discard duplicates.

Always event.

An event type. Open enum; new types can be added.

When the event happened.

Mode of the event.

Version of the payload format, a date. Today 2026-10-21.

Field name as configured on the agent.

Declared type of the field, for example string, number, boolean. Open enum.

ready, pending, absent (not mentioned in the call) or failed. Open enum.

The extracted value, typed per type. Null unless state is ready.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Amount in the minor unit of currency. Never negative.

ISO 4217 currency code. Open enum; today always INR.

Amount in the minor unit of currency (for INR, paise). At least 1.

ISO 4217 code. Must be INR today.

Phone number id (pn_...).

Always phone_number.

Mode of the key that read it. Numbers are shared configuration, readable in both modes.

The number in E.164 format.

Label given in the console, if any.

active numbers can be used. pending numbers are still being set up. Open enum.

What the number supports.

The agent of this workspace that answers calls to this number, if any.

Agents of this workspace that call from this number.

True only for the built-in sample number that exists in test mode.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Phone numbers on this page.

Requests per minute allowed for one key.

Requests per minute allowed across all keys of the workspace in this mode.

Position of the turn, from 0.

agent or caller (the person called). Open enum.

What was said.

Start of the turn in milliseconds from the start of the call, when known.

End of the turn in milliseconds from the start of the call, when known.

Delivery id (wd_...).

Always webhook_delivery.

Mode of the event.

The endpoint.

The event delivered (evt_...). Also sent as the RelationsAI-Event-Id header.

An event type. Open enum; new types can be added.

pending (first attempt not made yet), retrying (failed, another attempt is scheduled), succeeded (your server answered 2xx), failed (every attempt failed). Open enum.

Attempts made so far.

When the last attempt was made.

When the next attempt is scheduled, if any.

HTTP status of your server's last answer, if it answered.

How long the last attempt took.

Why the last attempt failed: timeout (no answer in 10 seconds), connection_failed (including a host name that did not resolve in time), tls_error, blocked_destination (the URL resolved to a non-public address), http_error (a non-2xx answer), signing_failed (RelationsAI could not sign the delivery; nothing was sent, the attempt still counts, and the delivery fails after its last attempt like any other; contact support if it persists). Null if it succeeded. Open enum.

When the delivery was created.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Deliveries on this page.

Endpoint id (we_...).

Always webhook_endpoint.

The endpoint receives events of this mode only.

Where events are delivered.

Your note about the endpoint.

Event types delivered to this endpoint. The test event is delivered on request regardless of this list.

enabled endpoints receive deliveries; disabled ones do not. Open enum.

Last four characters of the current signing secret, to tell secrets apart.

When the endpoint was created.

When the endpoint was last changed.

The most recent delivery attempt, or null if none yet.

Must start with https://; any other scheme is refused with 400 validation_error (issue invalid_format) before the URL is checked. Then: port 443 only, no user name or password, not a RelationsAI host, and the host must resolve only to public internet addresses, otherwise 422 webhook_url_not_allowed. Checked when created, when changed, and again on every delivery.

Event types to deliver. webhook_endpoint.test cannot be subscribed to (the test operation always delivers it).

Your note about the endpoint.

Always list.

True when more objects exist after this page.

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

Endpoints on this page.

Must start with https://; any other scheme is refused with 400 validation_error (issue invalid_format) before the URL is checked. Then: port 443 only, no user name or password, not a RelationsAI host, and the host must resolve only to public internet addresses, otherwise 422 webhook_url_not_allowed. Checked when created, when changed, and again on every delivery.

Your note about the endpoint. Null clears it.

Event types to deliver. Replaces the current list. webhook_endpoint.test cannot be subscribed to (the test operation always delivers it).

enabled or disabled.

Endpoint id (we_...).

Always webhook_endpoint.

The endpoint receives events of this mode only.

Where events are delivered.

Your note about the endpoint.

Event types delivered to this endpoint. The test event is delivered on request regardless of this list.

enabled endpoints receive deliveries; disabled ones do not. Open enum.

Last four characters of the current signing secret, to tell secrets apart.

When the endpoint was created.

When the endpoint was last changed.

The most recent delivery attempt, or null if none yet.

The signing secret (whsec_...), shown only in the first response to the create or rotate request. null on an idempotent replay of that request (same Idempotency-Key): the secret is stored only encrypted and is never returned again. If it was lost, rotate the secret.

Hours during which every delivery carries two signatures, one per secret, so you can deploy the new secret without dropping events. 0 retires every previous secret immediately (always allowed, also during a grace period). A value above 0 during a running grace period keeps the oldest secret still signing until its original grace end and discards the one in between.

Event id (evt_...). The same event can be delivered more than once; use this to discard duplicates.

Always event.

Always webhook_endpoint.test.

When the event happened.

Mode of the event.

Version of the payload format, a date. Today 2026-10-21.

Event data.

Workspace id (ws_...).

Always workspace.

true when the key is a live key, false for a test key.

Workspace name as shown in the console.

IANA timezone of the workspace. Calling hours (if enabled in the console) are evaluated in it.

Currency calls are charged in (ISO 4217). Open enum; today always INR.

The API key this request was authenticated with. The secret itself is never returned.

What this workspace can do through the API. A false here means the feature is not offered today, so a client can adapt instead of discovering it from errors.

Limits that apply to this key and workspace in the key's mode.

Key id (key_...). Shown in the console next to the key.

The name given to the key when it was created.

test for rai_test_ keys, live for rai_live_ keys.

Scopes this key can use right now: the scopes it was created with, limited to what its creator's current role allows.

When the key was created.

When the key stops working. Null for a test key created without expiry.

Running campaigns can be paused.

Paused campaigns can be resumed (continuing the same run).

Calls report a separate ringing status. When false, a call goes from queued straight to in_progress or ended.

Transcripts can be read while a call is in progress. When false, transcripts are available after the call ends.

Call analysis includes sentiment. When false, analysis has a summary, extracted fields and the goal outcome only.

Calls can be hung up through the API.

Agents can be created or edited through the API. When false, use the console.

Inbound calls appear in the call list.

Webhook endpoints can be created and events are delivered.

Requests per minute by rate-limit class. Each operation shows its class as x-rate-limit-class.

Calls this workspace may place through the API per UTC day in live mode. Null in test mode, which has no daily cap.

Most simultaneous calls a campaign can run with on the workspace's plan. A higher concurrency_limit is lowered to this at start.