Skip to Content
HallolaraDocs
Public APICalls & recordings

Trigger an outbound call

POST
/calls

Starts an outbound call. Provide exactly one of assistant_id or assistant_phone to select the assistant, and exactly one of to or target_phone for the destination number (to is preferred, target_phone is an alias retained for backwards compatibility).

introduction sets the greeting for this call only, in place of the assistant's introduction; details adds context to the assistant's prompt for this call. Neither changes the assistant.

This operation uses the per-key outbound_trigger bucket (60 requests per hour by default) and a separate one-outbound-call-per-assistant cooldown over a rolling 60-second window. A cooldown rejection is 429 rate_limit_exceeded without Retry-After.

If the normalized destination equals the selected assistant's normalized own phone number, or exactly matches a caller-blocking entry assigned to that assistant, no call is created and the operation returns 409 outbound_target_blocked. The own-number restriction is intrinsic. Caller-blocking lists and Assistant assignments are managed in Dashboard → Settings → Blocked callers; the Public API does not expose caller-blocking configuration. Retrying the same destination while it remains blocked returns the same rejection.

Authorization

bearerAuth
headerAuthorizationBearer <token>

API key in the Authorization: Bearer <key> header. Keys are created in the Hallolara dashboard (Settings → API Keys).

Request Body

application/json
  1. body

Provide exactly one of assistant_id or assistant_phone, and exactly one of to or target_phone (target_phone is a legacy alias).

assistant_id*string

The assistant that will make the call.

Match^[a-f0-9]{24}$
assistant_phone?string

Alternative to assistant_id - look up the assistant by its phone number in E.164 format (leading + followed by 6–20 digits).

Match^\+\d{6,20}$
to*string

Destination phone number in E.164 format (leading + followed by 6–20 digits).

Match^\+\d{6,20}$
target_phone?string

Legacy alias for to. Same E.164 format.

Match^\+\d{6,20}$
details?string

Optional free-text context passed to the assistant prompt.

Lengthlength <= 1000
introduction?string

Optional greeting for this call only. It replaces the assistant's introduction and is the first thing the assistant says, word for word; the person called cannot interrupt it. Write it in the assistant's language, and write dates and times the way they should be spoken (for example "on Friday, November 7, between 8 and 12 in the morning"). The placeholders of the assistant's introduction work here too: @firstName, @lastName and @gender come from the contact that matches the destination number and stay empty without one; @assistantName and @companyName come from the assistant. Fixed questions configured on the assistant still follow the greeting. Because it replaces the whole stored introduction, include any notice that the person is talking to an AI or that the call is recorded where you need one. Omitted or empty, the assistant's introduction is used. Use details for what the assistant should know during the conversation.

Lengthlength <= 1000
mailbox_detection?boolean

Opt-in one-shot detection using the first eight seconds of raw caller audio. A machine verdict (voicemail, IVR/call screening or an unavailable announcement) requests hangup only after its outcome is saved. Human, uncertain and failed detection leave the call running. Poll getCall for mailbox_detection and wait for done before retrying. Existing post-call analyses and actions still run. Default false. Detection currently supports German (de) assistants; for any other assistant language the call proceeds unchanged and reports skipped with reason language_not_supported. Outbound creation does not provide idempotency: do not blindly retry an ambiguous POST result.

Defaultfalse

Response Body

Call created and queued.

application/json
  1. response
data?
curl -X POST 'https://api.hallolara.ai/api/v1/calls' \  -H 'Content-Type: application/json' \  -d '{  "assistant_id": "65a1234567890abcdef01234",  "to": "+12025550123"}'
Example Response
{  "data": {    "call_id": "string",    "assistant_id": "string",    "assistant_phone": "string",    "to": "string",    "status": "string",    "created_at": "2019-08-24T14:15:22Z"  }}