Skip to main content
POST
Create phone call
Places one outbound call. You name the number to call and one of your workspace’s phone numbers to call from; Verbeo dials the destination and connects your assistant. Dynamic variables you pass are filled into the assistant’s system prompt for this call, so you can personalize each call without creating separate assistants.
This is version 2 of the endpoint, and the one to build on. It answers the standard envelope every other resource uses. Version 1 (POST /calls) is unchanged and keeps working for integrations built on it.

Endpoint

Body

string
required
The number to call, in E.164 format: +14155550123. Spaces, dashes and brackets are accepted and removed. Always send the + and the country code. A number without the + passes validation and is dialed exactly as sent, but Verbeo’s destination rules read it as if it began with +: a national number such as 808 555 0123 is then read as a +808 number and refused with 403, and whatever is not refused is left to your carrier to read.
string
required
The number to call from, exactly as it appears in your workspace (phone_number on the phone number object). It must be an active number of your workspace.
string
UUID of the assistant that handles the call. Optional — leave it out and the call uses the outbound assistant set on from_number. If that number has none either, the request is rejected.
object
Values for the {{variables}} in the assistant’s system prompt, by name. Every value must be a string. A name that starts with two underscores (__) is reserved: it is ignored, whatever it holds.
The workspace comes from your API key, so the body names none.
The response returns immediately, as soon as the call is created — it does not wait for the destination to answer, and a 201 does not mean the phone rang. A call that then fails to connect (no answer, busy, a carrier error) is reported by its call_ended webhook. Track the outcome with the call_started, call_ended and call_analyzed webhooks: their call_id is the id this endpoint returns.

Request

Response

201 Created as soon as the call is created.
string
required
UUID of the call. It is the call_id of the call’s webhook events.
string
required
The status the call starts in: queued — it has been created and is being placed.
string
required
The number dialed, without the separators you may have sent.
string
required
The number the call is placed from.
string
required
UUID of the assistant on the call — the one you named, or the number’s outbound assistant.
string
required
That assistant’s name.

Errors

Every error uses the standard error envelope. Branch on error.code.

Retrying

To personalize calls at scale, put placeholders like {{customer_name}} in your assistant’s system prompt and pass the values through dynamic_variables on each call.

Coming from version 1

Rename every field. Version 2 reads only its own names and ignores version 1’s without an error: a body that still sends agentId places the call with the number’s outbound assistant instead, and one that still sends dynamicVariables places it with no variables.