Trigger an outbound call
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.
bearerAuthAuthorizationBearer <token>API key in the Authorization: Bearer <key> header.
Keys are created in the Hallolara dashboard (Settings → API Keys).
application/json- 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*stringThe assistant that will make the call.
^[a-f0-9]{24}$assistant_phone?stringAlternative to assistant_id - look up the assistant by its phone number in E.164 format (leading + followed by 6–20 digits).
^\+\d{6,20}$to*stringDestination phone number in E.164 format (leading + followed by 6–20 digits).
^\+\d{6,20}$target_phone?stringLegacy alias for to. Same E.164 format.
^\+\d{6,20}$details?stringOptional free-text context passed to the assistant prompt.
length <= 1000introduction?stringOptional 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.
length <= 1000mailbox_detection?booleanOpt-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.
falseCall created and queued.
application/json- response
data?curl -X POST 'https://api.hallolara.ai/api/v1/calls' \ -H 'Content-Type: application/json' \ -d '{ "assistant_id": "65a1234567890abcdef01234", "to": "+12025550123"}'{ "data": { "call_id": "string", "assistant_id": "string", "assistant_phone": "string", "to": "string", "status": "string", "created_at": "2019-08-24T14:15:22Z" }}