Quickstart: your first call
This guide creates a simple Call Agent and uses it to call your own phone. It takes about five minutes.
This places a real phone call, and normal call charges apply. You need a phone in the United States or Canada. Resia does not call premium-rate numbers.
Before you start: complete Get access, and keep the terminal open with RESIA_API_BASE and RESIA_API_KEY set.
Create a Call Agent
A Call Agent stores the instructions for a phone conversation. The two schemas describe the inputs the agent accepts and the result you get back after the call. This agent needs no inputs.
cat > first-agent.json <<'JSON'
{
"name": "My first Resia call",
"instructions": "You are a friendly test assistant. Say hello and explain that this is a Resia test call. Ask whether the person can hear you clearly. Thank them and end the call.",
"input_schema": {"type": "object", "properties": {}, "additionalProperties": false},
"analysis_prompt": "Summarize the conversation in one sentence.",
"analysis_schema": {
"type": "object",
"properties": {"summary": {"type": "string"}},
"required": ["summary"],
"additionalProperties": false
},
"agent_speaks_first": true,
"should_leave_voicemail": false
}
JSON
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/call-agents" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @first-agent.json \
--output agent-response.json
jq '{id, review_status, is_active}' agent-response.json
Expected result: HTTP 201 with an id. Continue when review_status is approved and is_active is true.
You can also create and edit Call Agents in the portal under Agents → New agent.

If the agent is pending_review, contact Resia. Do not create the same agent again. If the name is already in use, pick another name or use the existing agent's id.
Call your phone
Enter your number in E.164 format: a +, the country code, and the number, such as +12125550142. See Number format.
CALL_AGENT_ID=$(jq -er '.id' agent-response.json)
read -r -p 'Your phone number, including + and country code: ' TO_PHONE_NUMBER
CALL_REQUEST_KEY=$(uuidgen)
jq -n --arg agent "$CALL_AGENT_ID" --arg phone "$TO_PHONE_NUMBER" \
'{call_agent_id: $agent, to_phone_number: $phone, inputs: {}}' > first-call.json
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/calls" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: $CALL_REQUEST_KEY" \
--data-binary @first-call.json \
--output call-response.json
jq '{id, status}' call-response.json
Expected result: HTTP 202 with a call id. Resia accepted the request. The phone has not rung yet. Answer it when it rings.
The Idempotency-Key makes a retry safe. If you are not sure whether a request arrived, send it again with the same key and body, and Resia returns the original call instead of dialing twice. Use a new key for each new call.
This example uses Resia's default caller number. To call from a number your organization owns, add from_phone_number to the body.
To run a call on a speech-to-speech model, such as gpt-live-1, set model_architecture and speech_to_speech_model on the Call Agent. Such an agent has some limits. See Speech-to-speech models.
Read the result
CALL_ID=$(jq -er '.id' call-response.json)
curl --fail-with-body --silent --show-error \
"$RESIA_API_BASE/v1/calls/$CALL_ID" \
--header "Authorization: Bearer $RESIA_API_KEY" \
--output call-result.json
jq '{id, status, transcript, analysis, failure}' call-result.json
Every call also appears in the portal under History → Calls, with its status, From and To numbers, duration, and charge. See Calls in the portal.

Read the call again after you hang up. The final status is completed, error, or canceled. An unknown status means that Resia cannot read the live status at that moment. It is not a final result, so read the call again. The analysis object follows the analysis_schema you defined, so here it contains a one-sentence summary.
Place the call from code
The same request in other languages:
import os
import uuid
import requests
response = requests.post(
"https://api.resia.ai/v1/calls",
headers={
"Authorization": f"Bearer {os.environ['RESIA_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"call_agent_id": "YOUR_CALL_AGENT_ID",
"to_phone_number": "+12125550142",
"inputs": {},
},
timeout=30,
)
response.raise_for_status()
print(response.json()["id"])
import { randomUUID } from "node:crypto";
const response = await fetch("https://api.resia.ai/v1/calls", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RESIA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({
call_agent_id: "YOUR_CALL_AGENT_ID",
to_phone_number: "+12125550142",
inputs: {},
}),
});
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).id);
If something fails
| Response | Meaning | What to do |
|---|---|---|
401 |
Resia did not accept your key. | Check the key. See Get access. |
402 |
Your prepaid balance is $0.00 or less. | Add funds. See Billing. |
422 |
The inputs or the agent are not valid. The message names the problem. |
Fix the request. Do not retry it unchanged. |
429 |
Your calls in progress reached your concurrent call limit. | Try again after a call ends. See Concurrent calls. |
If Resia accepted the call but it failed, read its failure field.
completed means that the call ended normally. It does not prove that a person answered or that the task succeeded. Check the transcript and the analysis.
Next steps
Get results after a call
Receive a webhook when every call ends.
Personalize each call with inputs
Give the agent a name and a time for each call.
Receive an inbound call
Put the agent on your own number.
Call a list of numbers
Queue up to 1,000 calls in one request.

