Agent-ready APIs

How it works

A business connects your API to its AI agent once, with no code:

1. A connection: your API's base address and one sign-in header.
2. Tools: one per endpoint the agent may use. Each has a path, the values the agent must collect from the caller (an order number, a date), and a line saying when to use it.
3. What the agent gets: the fields of your reply worth saying, and the business's notes on how to read them ("BO means back-ordered: offer a call back").

On a call, the agent collects the values, BE Voice sends the request, and the agent words its answer from your reply. A business can also give a fixed sentence filled from your reply, for wording that must be exact.

Caller:  "Where's my order? It's A1001."
Agent    → GET https://api.yourshop.example/v2/orders/A1001
Your API → {"order": {"number": "A1001", "status": "SHP", "eta": "2026-10-07", "carrier": "Australia Post"}}
Agent:   "It shipped with Australia Post and should arrive on Tuesday the 7th."

Address and sign-in

Checking a request came from BE Voice

Every request carries X-BE-Voice-Timestamp (Unix seconds) and X-BE-Voice-Signature: sha256= followed by the hex HMAC-SHA256 of <timestamp>.<raw body>, keyed with the business's webhook secret. The body is empty for a GET. Compute it over the raw bytes and reject timestamps more than 5 minutes old. BE Voice has no fixed source addresses to allow-list.

Requests

Which call is this?

Rules for your API

Replies

The agent reads your reply, together with the business's notes on what the values mean, and words the answer itself.

{
  "order": {
    "number": "A1002",
    "status": "BO",
    "eta": null,
    "restock_date": "2026-10-13",
    "items": [{"name": "Tap washer kit", "qty": 3}]
  }
}

Optional: word the answer yourself

If your system can say it better than a general assistant would, return a top-level "answer" sentence with the record under "data". The agent is given your sentence first.

{"answer": "Order A1002 is waiting on stock, due back in on Monday 13 October.", "data": {"status": "BO"}}

Status codes

Errors the agent can act on

Send refusals as a sentence a person could act on. It is read from error (a string, or an object with message), or else message or detail, up to 300 characters, and it may be said to the caller, so keep it plain and free of internals. A refusal with no sentence is treated as a failure.

HTTP 409
{"error": "That time has just been taken. The next free times are 2:30 pm and 4 pm.", "code": "slot_taken"}

Timing and limits

Writes

POST /invoices/INV-881/promises
Idempotency-Key: cal_8f2…:record_promise_to_pay:3b1c9a0e5d7f2a44
{"amount": "500", "date": "2026-10-10", "source": "phone"}

HTTP 201
{"promise": {"id": "pr_1042", "invoice": "INV-881", "amount": "500.00", "date": "2026-10-10"}}

Who is on the line

BE Voice can't prove that a caller is who they say. An API that returns personal or account details makes that decision itself.

Describing your API

A business sets up each tool from your documentation. Give it, for every endpoint the agent may use:

Starting the AI from your system

The same connection works the other way: your system can have the AI place calls and hear how they went.

Put the IDs your endpoints need (an invoice number, an appointment ID) in the facts you send with each call, so the agent never has to ask the person for them. The full API reference is available to customers.

Checklist

• HTTPS, public, one base address, one fixed sign-in header
• Lookups by something a caller knows; loose input accepted
• Small JSON replies with one named record and a fixed list of statuses
• 404 for not found; refusals as {"error": "a sentence"} with 400, 409 or 422
• Answers in under 2 seconds, always within 10
• Writes check the Idempotency-Key and return what was created
• Nothing in a reply that a caller mustn't hear; personal data needs a second value
• Each endpoint documented with its purpose, status values, safe fields and an example

To check your API, the business adds a connection and a tool in its BE Voice console and presses Test with real values. It shows your reply as it came, and exactly what the agent would be told.

Place a call

Send the number, the goal and your brief. Nothing needs setting up in BE Voice first: the AI works from what you send, opens the call in its own words (or with your greeting), and finishes when the goal is met or clearly can't be. Calls come from one of your account's numbers.

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",
      "prompt": "You are Alex from Acme Parts dispatch. Offer Friday 8-12 or 12-5; if neither works, find a day that does.",
      "context": {"customer_name": "Sam", "order": "A1002"},
      "questions": [{"key": "window", "ask": "Which window suits you?", "type": "choice",
                     "choices": ["Friday 8-12", "Friday 12-5", "Other"], "required": true}],
      "human": {"target": "ext:101"}
    },
    "callback_url": "https://app.example.com/hooks/be-voice",
    "metadata": {"ref": "ord_A1002"}
  }'

The reply is the call, with its id. If the person asks not to be called again, their number goes on your account's do-not-call list, and calls to numbers on that list are refused with do_not_call.

When the person answers with "hello", the AI waits until they finish, then says your greeting. If nobody speaks, it speaks first. Without a greeting, it opens in its own words.

Steer a call

While the call is on, you can give the AI a new instruction. The person doesn't hear it; the AI acts on it at the next natural moment, and it shows in the transcript as an instruction line.

curl https://voice.binaryelements.com/v1/calls/$CALL_ID/steer \
  -H "Authorization: Bearer $BE_VOICE_KEY" \
  -d '{"instruction": "Also ask whether Saturday works."}'

409 means there is no conversation to steer right now: the phone is still ringing, the call is being transferred, or it has ended.

Get the result

Ask for it, optionally waiting until the call is done (wait in seconds), or let it come to your callback_url as a call.result webhook, signed as described above.

curl "https://voice.binaryelements.com/v1/calls/$CALL_ID/result?wait=60" -H "Authorization: Bearer $BE_VOICE_KEY"

{
  "call_id": "cal_…", "status": "completed", "final": true, "duration_sec": 74,
  "outcome": "completed",
  "result": {"outcome": "completed", "answers": {"window": "Friday 8-12"}, "note": "Gate code 4411."},
  "summary": "Sam will take delivery Friday morning.",
  "transcript": [{"speaker": "agent", "text": "…"}, {"speaker": "caller", "text": "…"}],
  "metadata": {"ref": "ord_A1002"}
}

Connect an AI assistant

BE Voice is also an MCP server, so an AI assistant can place calls, follow them, steer them and read the results itself. Add it to any MCP client that supports remote servers:

{
  "mcpServers": {
    "be-voice": {
      "type": "http",
      "url": "https://voice.binaryelements.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_BE_VOICE_KEY" }
    }
  }
}

Then just ask: "Call Sam on +61 400 000 000 and confirm Friday morning works for the delivery; tell me what they say." Placing calls through the API and MCP is switched on per account: ask Binary Elements.