Skip to content

Place a voice call

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.

FieldWhat to send
target_phoneYour US number with the +1 country code. Numbers in IN, LA, MN, MT and NE are refused.
briefThe instructions the agent follows on the call.
languageen 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 statusWhere to find the IDWhat it means
202 Acceptedcall_idQueued, waiting to start.
201 Createdcall.call_idCreated 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

FieldWhat it tells you
resultWhether 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_byWhy the call stopped: callee_hangup, agent_hangup, dropped, budget_timeout, dial_failed, customer_cancelled, system_error or compliance_stop.
line_kindWhat was on the line: human, voicemail, ivr, no_answer, recorded_announcement or hold_queue.
result_reasonThe detail where result alone is shared, such as booked, busy, short_hangup or language_barrier. Often null.
outcome_summaryA short explanation of what happened.
transcript_fullWhat 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_statuslive 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_centsWhat the call cost, in credits (despite the field name).
recording_declinedtrue 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 statusWhat to check
400The Idempotency-Key is empty, too long or not printable ASCII.
401The API key is missing or invalid.
402The key does not have enough credits for the 30-credit hold.
403The key cannot place calls, or the account is suspended (account_suspended; contact support).
404 on lookupCheck the call ID and use the same API key that created it.
409The 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.
422Read 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.
429Too 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.
502error_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.
503The service is temporarily unavailable; follow any retry guidance in the response.
504error_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.