Calls and call batches

A call is one attempt to place or answer a phone call with a Call Agent. Each call has its own ID, status, transcript, recording, analysis, and charge.

Place a call

POST /v1/calls queues one outbound call and answers 202 Accepted at once. The phone has not rung yet when you get the response.

Field	Required	What it does
call_agent_id	Yes	The Call Agent that handles the call.
to_phone_number	Yes	The destination, in E.164 format, such as +12125550142.
inputs	When the agent needs them	Values that match the agent's input_schema.
from_phone_number	No	A number your organization owns. If you leave it out, Resia uses its default caller number.
knowledge_base_id	No	A ready knowledge base that the agent can search during this call.
client_reference	No	Your own label, such as an order ID. Resia stores it, returns it on every read, and lets you filter GET /v1/calls by it.
call_ended_webhook_url	No	Overrides the agent's result webhook for this call only.
additional_participants	No	Numbers for a multi-party call.

Resia calls numbers in the United States and Canada only, and refuses premium-rate numbers.

Idempotency

Send an Idempotency-Key header with a new UUID for each call. If you repeat a request with the same key, Resia returns the call from the first request and does not dial again. The first request's inputs and webhook URL stay on that call, even if a retry sends different values.

Call status

Status	Meaning	Final?
queued	Resia accepted the call. It is waiting for its turn.	No
initiated	The call is being placed.	No
in_progress	The call is connected.	No
post_processing	The call ended. Resia is preparing the transcript and analysis.	No
completed	The call ended normally, and the results are ready.	Yes
error	The call failed. Read failure for the reason.	Yes
canceled	The call was stopped before it was dialed.	Yes
unknown	Resia could not read the live status at this moment. Read the call again.	No

Read calls

• GET /v1/calls/{call_id} returns one call with its transcript, analysis, and failure.
• GET /v1/calls lists calls, newest first. Filter by call_agent_id, status, or client_reference. Follow next_cursor for the next page.
• GET /v1/calls/{call_id}/recording downloads the call recording.
• GET /v1/call-charges lists what each call cost.

Call batches

A call batch queues up to 1,000 outbound calls that use the same Call Agent, in one request. Resia dials from a queue at the pace your rate limits allow, so a large list does not fail with a wall of 429 errors.

• The response lists one call_id for each accepted call, in the order you submitted them. Each call reads through GET /v1/calls/{call_id} like any other call.
• Resia checks each entry on its own. A bad entry does not reject the whole batch. It is returned in rejected_calls with its position, number, client_reference, and reason.
• If a destination appears twice, Resia calls the first entry and rejects the later ones.
• Idempotency-Key is required.

Batch status is in_progress, completed, or canceled. Cancel a batch with POST /v1/call-batches/{batch_id}/cancel. This stops the calls that are still queued. Calls that already started run to their end.

See Call a list of numbers for a full example.

API reference

Calls · Call Batches