Use PlaceCall to place a voice call, give the agent a task, and read what happened. This guide asks a business what time it closes today.
Before you start
You need a PlaceCall API key with credits, a terminal with curl and Python 3, and a US phone number you own or are authorized to call. PlaceCall does not call Indiana, Louisiana, Minnesota, Montana or Nebraska. Get an API key, set it as PLACECALL_API_KEY in your terminal or server environment, and keep it out of browser code and public repositories. See Authentication.
A request with a valid number places a real call and can use credits. The +1XXXXXXXXXX placeholder cannot be dialed; replace it with your number in E.164 format.
1. Describe the task
Give the agent one clear objective in brief: what to ask, what it needs to know, and when to finish.
| Field | What to send |
|---|---|
target_phone | Your US number with the +1 country code. Numbers in IN, LA, MN, MT and NE are refused. |
brief | The instructions the agent follows on the call. |
language | en for this English example. |
Optional: "voice": {"gender": "female"} (or "male") asks for a voice. It is best effort and never fails the call. female is met only in English, Japanese, Dutch, Russian and Turkish, and only where a female voice exists (English has one today); other languages answer male. The call reports voice.gender_used.
2. Place the call
Create a unique request ID once for this intended call, here with Python 3:
CALL_REQUEST_ID=$(python3 -c 'import uuid; print(uuid.uuid4())')
Send the request with that ID in the Idempotency-Key header:
curl --include --request POST https://api.voygr.tech/calls \
--header "X-API-Key: $PLACECALL_API_KEY" \
--header "Idempotency-Key: $CALL_REQUEST_ID" \
--header "Content-Type: application/json" \
--data '{
"target_phone": "+1XXXXXXXXXX",
"brief": "Ask what time the business closes today. Thank them and end the call.",
"language": "en"
}'
--include shows the HTTP status with the response. On api.voygr.tech every accepted call is queued, so expect 202 Accepted with the call ID at the top level. Only a deployment that dials immediately answers 201 Created. Save the call ID:
| HTTP status | Where to find the ID | What it means |
|---|---|---|
202 Accepted | call_id | Queued, waiting to start. |
201 Created | call.call_id | Created and dialing. |
Structured calls (intent + slots, deprecated: send a brief for new calls) return a top-level call_id for both 201 and 202. Read the top-level call_id, else call.call_id: response.get("call", response)["call_id"] in Python. Do not submit another call because this one is queued.
If the connection drops before you get a response, retry the same POST with the same request ID and unchanged body; do not generate a new ID for the retry. For 24 hours a replay returns the stored response with Idempotent-Replayed: true. Use a new ID only for another call; reusing an ID with a different body returns 409.
3. Follow progress
Set CALL_ID to the ID returned in step 2, then look up the call:
CALL_ID="REPLACE_WITH_RETURNED_CALL_ID"
curl "https://api.voygr.tech/calls/$CALL_ID" \
--header "X-API-Key: $PLACECALL_API_KEY"
This response carries the call fields directly, so read status, not call.status. Repeat the GET while the call runs; a queued call uses the same lookup. Never poll with an empty call_id. A 404 means the ID is wrong: stop and re-read call_id from the POST /calls response.
The call has finished when status is completed, failed, or cancelled. If a completed call still has a null result, check again: the outcome can land shortly after the call ends.
4. Read the outcome
| Field | What it tells you |
|---|---|
result | Whether the call got what it was placed for: goal_met, goal_partial, refused, goal_not_met, wrong_party, not_reached, aborted or pending (reserved, not returned yet; read any value you do not know as unfinished). |
ended_by | Why the call stopped: callee_hangup, agent_hangup, dropped, budget_timeout, dial_failed, customer_cancelled, system_error or compliance_stop. |
line_kind | What was on the line: human, voicemail, ivr, no_answer, recorded_announcement or hold_queue. |
result_reason | The detail where result alone is shared, such as booked, busy, short_hangup or language_barrier. Often null. |
outcome_summary | A short explanation of what happened. |
transcript_full | What the agent heard and what it said. After the call we check the recording: where it has a different number, yes or no, or name from your request, the row gets audio, and speech the agent likely missed is added as a heard: false row. |
transcript_status | live while that check is still expected, final once it has run or is no longer expected. Poll until it reads final, usually a minute or two after the call ends. When recording_declined is true it stays null for good, so stop polling. |
outcome_charge_cents | What the call cost, in credits (despite the field name). |
recording_declined | true when the callee declined recording. No transcript will ever come, so do not wait for one; the summary and outcome are still there. |
completed means the call ended; result says whether the agent got what you asked for. refused means the business declined even though the call reached it. Handle a missing result in your application rather than treating it as an answer.
outcome_type is deprecated: it still arrives, with its 19 values and no removal date, but branch on the fields above. Keep a value you do not recognize rather than discarding the response.
A PlaceCall call costs 10 credits when it obtains something (an answer, a refusal or a booking). Each call holds 30 credits while it runs, and the unused part is released. A call that obtains nothing is free, and so is a cancel within 30 seconds of the callee answering; a cancel 30 seconds or more after pickup is charged 10 credits.
Receive live events
For live updates and mid-call questions, stream the call’s events. Questions arrive as ask_user events whatever the call’s ask_user_mode (any, the default, and stream behave the same), and also on your webhook if it is subscribed to ask_user (the default):
curl --no-buffer "https://api.voygr.tech/calls/$CALL_ID/events?after_event_id=0" \
--header "X-API-Key: $PLACECALL_API_KEY"
Parse each SSE event as it arrives; do not wait for the response to finish. Ignore heartbeat events and SSE comments, keeping the last event ID when a heartbeat has no id. After a disconnect while the call is active, reconnect with after_event_id set to the last id you received; the Last-Event-ID header is not supported. Answer ask_user events promptly through the answer endpoint.
To be told when a call ends without polling or an open stream, register a webhook with "events": ["ask_user", "call_completed"]. It gets one signed call_completed event per call with the outcome. A failed delivery is retried with the same Webhook-Id header, so deduplicate on Webhook-Id. Until you set events, a webhook receives mid-call questions only.
Handle errors and retries
Read the error response before retrying:
| HTTP status | What to check |
|---|---|
400 | The Idempotency-Key is empty, too long or not printable ASCII. |
401 | The API key is missing or invalid. |
402 | The key does not have enough credits for the 30-credit hold. |
403 | The key cannot place calls, or the account is suspended (account_suspended; contact support). |
404 on lookup | Check the call ID and use the same API key that created it. |
409 | The idempotency key was reused with a different body, a request with it is still running (wait retry_after_seconds), or the first request stopped before recording whether it placed a call (idempotency_state_unknown: look for the call in GET /calls before placing another). A call over your concurrent-call limit is not refused; it waits as queued. |
422 | Read error_code: the phone number (missing_target_phone, invalid_target_phone), a destination we never call (region_not_supported, emergency_code_blocked, premium_rate_blocked and similar; do not retry that number), the brief (missing_brief, brief_policy_violation), unsupported_language, or the opening notice fields. The POST /calls reference lists every code. |
429 | Too many requests (follow Retry-After when returned), or daily_call_ceiling_reached: this account has created its calls for the UTC day; retry after resets_at. |
502 | error_code: BACKEND_ERROR: the call could not be started or queued. It is not proof that no call was placed: retry with the same request ID and body. |
503 | The service is temporarily unavailable; follow any retry guidance in the response. |
504 | error_code: BACKEND_TIMEOUT: the calling service did not answer in time, so the outcome is uncertain. Retry with the same request ID and body. |
Errors the gateway returns itself (401, 402, 403 and the 429 rate limit) put the message inside detail, for example {"detail": {"error": "invalid API key"}}. The 502 and 504 bodies come from the gateway too: error and error_code at the top level, with no request_id and no detail wrapper. For access help, contact support@voygr.tech.
See Place a call for the full request and response reference and its interactive playground.
On this page
