For developers

Place an AI call from your app

Send BE Voice a number, a goal and a brief. It rings the number from one of your business's numbers, and its AI holds the conversation until the goal is met or clearly can't be. Nothing needs setting up in the console first.

How to place a call

1. Get an API key and check your account includes Calls through the API and MCP. See API keys and basics.
2. Send POST /v1/calls with to and a task that has at least a goal.
3. Keep the id from the reply (cal_…). The phone is already ringing.
4. Follow the call and read its result with GET /v1/calls/{id}/result, or have the result sent to your callback_url. See Follow, steer and get results.

curl https://voice.binaryelements.com/v1/calls \
  -H "Authorization: Bearer $BE_VOICE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to": "+61400000000",
       "task": {"goal": "Confirm Sam can take delivery of order A1002 on Friday morning"}}'

A full example

Harbour Plumbing's job system asks a customer which delivery window suits, and sends the answer back to itself.

curl https://voice.binaryelements.com/v1/calls \
  -H "Authorization: Bearer $BE_VOICE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: delivery-A1002" \
  -d '{
    "to": "+61400000000",
    "from": "+61370000000",
    "task": {
      "goal": "Confirm Sam can take delivery of order A1002 on Friday, and in which window",
      "prompt": "You are Alex from Harbour Plumbing in Port Melbourne. Sam ordered a hot water unit (order A1002). Offer Friday 8-12 or 12-5. If neither works, find a weekday next week that does. Be brief and friendly.",
      "context": {"customer_name": "Sam", "order": "A1002", "item": "hot water unit"},
      "questions": [
        {"key": "window", "ask": "Which delivery window suits you?", "type": "choice",
         "choices": ["Friday 8-12", "Friday 12-5", "Another day"], "required": true},
        {"key": "other_day", "ask": "Which day suits instead?", "type": "date"},
        {"key": "gate_code", "ask": "Is there a gate code or anything the driver should know?", "type": "text"}
      ],
      "human": {"target": "ext:101", "then": "+61370000000"},
      "greeting": "Hi, it is Alex from Harbour Plumbing, about your hot water delivery.",
      "closing": "Thanks Sam, see you then.",
      "voicemail_message": "Hi Sam, it is Alex from Harbour Plumbing about your delivery. Please call us back on 03 7000 0000.",
      "max_call_sec": 300
    },
    "callback_url": "https://app.example.com/hooks/be-voice",
    "metadata": {"order": "A1002", "job": "job_48213"}
  }'

The reply is the new call, with 201 Created:

{
  "id": "cal_7h2kq9m4x8pz3vd61wtn",
  "tenant_id": "tnt_8f2kd0w3m5q7r9t1v4xz",
  "direction": "outbound",
  "from": "+61370000000",
  "to": "+61400000000",
  "cli_presented": "+61370000000",
  "case_id": "",
  "status": "queued",
  "metadata": {"order": "A1002", "job": "job_48213"},
  "duration_sec": 0,
  "created_at": "2026-10-10T05:12:03.418Z",
  "answered_at": null,
  "ended_at": null
}

status is queued while the phone rings. tenant_id is your account ID. Sending the same request again with the same Idempotency-Key returns this call with 200 instead of ringing Sam twice.

The request

The task: the call's brief

Only goal is required. Everything else shapes how the AI goes about it.

Questions

Each question is an object:

key

Required. The answer's name in the result: lower-case letters, digits and _, starting with a letter (gate_code), unique in the call.

ask

Required, up to 300 characters. The question as you'd ask it. The AI asks it in its own words and comes back to it if the answer doesn't fit.

type

text (the default, up to 300 characters), number, yes_no, choice or date (returned as YYYY-MM-DD).

choices

For choice only: 2 to 12 options, each up to 60 characters. The answer is one of them.

required

true if the call isn't complete without it. If the person skips it, the AI asks once more.

Outcomes

The AI ends every call with one outcome, returned as outcome in the result. Without your own list, the outcomes are achieved and not_achieved, or with questions completed (every required question answered), partial and not_achieved.

To use your own, send outcomes: each has a name (lower-case, like a key), a description of when it applies (up to 300 characters), and optionally up to 10 fields, details the AI records with that outcome (returned in result.details). If you send questions as well, your list must include completed and partial.

"outcomes": [
  {"name": "booked", "description": "they chose a delivery time", "fields": ["day", "window"]},
  {"name": "call_back", "description": "they asked us to call another time"},
  {"name": "not_achieved", "description": "they couldn't or wouldn't arrange delivery (say why in the note)"}
]

Talking to a person

human is where the call goes if the person asks for a human: {"target": "ext:101", "then": "+61370000000", "ring_sec": 20}.

• target is one of your extensions (ext:101), a ring group or queue (ring_group:rg_…, queue:q_…), or a phone number.
• then is tried if the first doesn't answer. ring_sec is how long each rings, 5 to 120 seconds (default 20).
• A transfer to a phone number goes out from the call's own number.
• Without human, the AI tells the person nobody is available and carries on.

When a call is refused

A refused call isn't placed, and nobody is rung. The reply is an error with a code:

Rules that still apply

BE Voice adds very little to your brief: what the AI says is up to your prompt. These still apply to every call:

• Do-not-call. If the person asks not to be called again, the AI adds their number to your account's do-not-call list, and the result has "opt_out": true. Later calls to that number, from your app, an AI assistant or a campaign, are refused. You can see and edit the list in the console (see Campaign results).
• Your numbers only. Calls show one of your business's numbers. Emergency numbers are never called, and premium 190 numbers can't be transfer targets.
• Calls at once. Your account's limit on calls going out at the same time applies.
• Calling hours are yours to keep. An API call rings as soon as you place it, whatever the time. Unlike campaigns, it has no calling window, so your app decides when it's right to call, and your prompt should have the AI say who it is and who it's calling for, as the rules for your kind of call require.