Skip to main content
The Outbound Calls API lets your software ask AlloMia to phone someone, such as a patient, with one of a clinic’s AI agents. You then get the result by checking the call’s status, by receiving a callback, or both.

Create outbound call

Start a call.

Get outbound call status

Check where a call stands.

Call-completed callback

Get the result sent to your server.

Which keys work

These endpoints accept fewer keys than the rest of the API. Who created the key matters. A key created by anyone else gets 403 Insufficient permissions. A partner key on the status endpoint gets 401. See Authentication for how keys work.

How a call works

1

Start the call

Send POST /api/outbound with the number to call, the AI agent (assistantId), and the clinic number to call from (phoneNumberId). You can add the person’s name, details for the agent (dynamicVariables) and a callbackUrl. AlloMia checks the request, records the call and starts dialing before it answers. See Create outbound call.
2

Read the immediate response

A successful request returns HTTP 200 with an outboundCallId and a status. Check status, not only the HTTP code:
  • calling: AlloMia started dialing.
  • failed: the call couldn’t be placed, even though the HTTP status is 200. No callback follows.
Keep the outboundCallId. You need it to check the call.
3

Wait for the call to end

The status stays calling while the phone rings and during the conversation. When the call ends, the status becomes final: completed, busy, no-answer or failed.
4

Get the result

If you sent a callbackUrl, AlloMia sends one call.completed callback to it when the status becomes final. See Call-completed callback. You can also check the status at any time with GET /api/outbound/{id}/status. See Get outbound call status.

Statuses

AlloMia doesn’t tell a person from voicemail: a call picked up by voicemail ends as completed. AlloMia doesn’t call again after busy or no-answer. To try again, start a new call.
A call can occasionally stay calling and never reach a final status. If a call is still calling well after it should have ended, treat its result as unknown.

How the end reason sets the status

Once a call is final, callDetails.endedReason says why it ended. It sets the status like this: A call that failed before dialing (the failed status in the first response) has no endedReason. See How a call can end for what each reason means.

Usage

Only calls that connect count toward the clinic’s usage. A call that is never answered (busy or no-answer) records no billable time, and neither does a call that couldn’t be placed.

Reading the conversation

The status and the callback tell you how the call ended. The summary, transcript and recording are on the call’s record in the Calls, with callType set to Outbound. The status and callback don’t include that record’s ID. To find it:
  1. Call List calls with callType=Outbound, search set to the number you called (digits only, such as 5145550187), and from set to callDetails.startedAt.
  2. Take the matching call’s id and call Get call.
The summary and transcript are added shortly after the call ends, so they can still be null when the callback arrives. If they are, try again a little later. A call that was never answered has no record in List calls, and no summary, transcript or recording.

Limits

Requests to these endpoints count toward your rate limit. See Rate limits.