Skip to main content
POST
Starts one outbound call. AlloMia checks the request, records the call and starts dialing before it answers. The call belongs to the clinic that owns the number you call from (phoneNumberId). See Outbound calls for how a call goes from start to result.

Before you start

  • The right key. Use a clinic key created by the clinic’s owner or by a Tenant Admin of your partner account, or a partner key created by the partner account’s owner or by a Tenant Admin. Any other key gets 403 Insufficient permissions. If the clinic creates the key, send its owner to Keys for connecting other software.
  • An AI agent set up for this call. Its instructions say what to do on the call.
  • The IDs of the agent and of the clinic number to call from. See Finding IDs.
Each request starts a new call. If a request times out, check before you send it again: the call may already be under way.

Headers

string
required
Bearer followed by your API key, for example Bearer sk-....
string
application/json.

Body

string
required
The number to call. Send it in E.164 format, such as +15145550187. See Phone number format for what else AlloMia accepts.
  • 10 to 20 characters.
  • Only digits, spaces, +, -, ( and ).
  • 10 to 15 digits.
string
required
The ID (UUID) of the AI agent that makes the call. It must belong to the same clinic as phoneNumberId.
string
required
The ID (UUID) of the clinic number to call from. The person called sees this number. It must be a phone number: a SIP address can’t be used. With a clinic key, the number must belong to that clinic. With a partner key, it must belong to a clinic in your partner account.
string
The name of the person you’re calling, up to 40 characters. AlloMia keeps it with the call request. The AI agent doesn’t see it: to let the agent use the name, also send it in dynamicVariables.
object
Details for this call, as an object whose keys and values are all strings. See Dynamic variables.
string
A URL where AlloMia sends the result when the call reaches a final status. Use an HTTPS URL. See Call-completed callback.

Phone number format

AlloMia removes spaces, dashes and parentheses, then:
  • A number that starts with + is used as is.
  • Otherwise, leading zeros are dropped. A 10-digit number gets +1 in front (Canada and the US). An 11-digit number that starts with 1 gets + in front. Any other number gets + in front, so AlloMia reads its first digits as a country code.
To avoid surprises, always send E.164 with the country code.

Dynamic variables

Each key in dynamicVariables becomes a variable in the AI agent’s instructions. Where the instructions contain the key between double curly braces, AlloMia puts the value in its place. For example, with "first_name": "Jane", the text {{ first_name }} in the instructions becomes Jane.
  • Variables work in the agent’s instructions. A fixed greeting is spoken exactly as written: variables in it aren’t replaced.
  • Which keys the agent expects depends on how its instructions are written. Agree on the names with whoever set up the agent.
  • Don’t use the keys now, date, time, month, day, year or customer. AlloMia uses those names for built-in variables.
  • The callback sends your dynamicVariables back to you, so you can use them to match the result to your own records.

Response

string
The call’s ID. Use it with Get outbound call status. The callback carries it too.
string
The ID of the person called, within this call.
string
calling when AlloMia started dialing. failed when the call couldn’t be placed.
string
Outbound call dispatched with calling. Outbound call failed to dispatch with failed.
A call that can’t be placed still returns HTTP 200, with "status": "failed". Always check status. No callback follows a failed response. Check the number you call from, then try again.

Errors

The three request problems above come back as 500 today, not as 4xx. Read the error message to tell them apart from a fault on AlloMia’s side. See Errors for the error format.