Create Call | hail.so

Header Parameters

authorization?string|null

Idempotency-Key?string|null

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

recipient_consent*Recipient Consent

Attestation that you have obtained the lawful consent required to contact this recipient. Hail does not verify consent itself — you are responsible for a lawful basis under TCPA/ePrivacy/PECR/CAN-SPAM/GDPR as applicable. Rejected (422) if not true.

consent_source?|

Where/how consent was obtained (e.g. 'signup form', 'prior customer relationship'). Required (non-empty) when message_type is 'marketing'.

consent_obtained_at?|

When consent was obtained, if known.

message_type?Message Type

'marketing' additionally requires a non-empty consent_source. Use 'informational' for transactional/service communications.

Default"informational"

Value in

"marketing"
"informational"

to*To

Recipient phone number, E.164 format (e.g. +14155551234).

from?|

Caller-id phone number, E.164 format. Must be a number owned by the organization with the voice capability. Omitted: an active org-owned number is used if one exists, else a number is claimed from the shared pool.

system_prompt?|

Task instructions for the agent, sent as its leading system message. At least one of system_prompt or llm is required; both together is also valid.

llm?|

BYO LLM endpoint the call runs on instead of Hail's default model. At least one of system_prompt or llm is required; both together is also valid.

first_message?|

Opening line the agent speaks first. Omitted: the agent waits for the callee to speak first.

recording_enabled?|

Request best-effort audio recording. Requires workspace recording enabled. Null inherits the agent/workspace. Recording failure never prevents the call. The recording-enabled call rate applies regardless of capture outcome.

ai_disclosure?Ai Disclosure

Speak the AI self-disclosure line ('Hi, this is an AI assistant calling on behalf of ...') as the first thing on the call. Enabled by default. Disable only if you have verified the disclosure is not required for this call — 47 CFR 64.1200(b)(1) requires identifying the initiating business at the start of artificial-voice calls in the US, and several jurisdictions have AI bot-disclosure laws. Hail does not verify this for you. The agent still identifies itself as an AI if asked.

Defaulttrue

voice_config?

TTS voice, VAD, turn-detection, and spoken-language settings for this call.

metadata?

Free-form JSON object attached to the call and echoed back on reads. Not interpreted by Hail. Keys starting with 'recording_' are reserved and rejected.

tools?array<string>|

Agent tools to allow on this call. Omitted: every tool the organization's configured channels support (new channels appear automatically). Empty list: no tools. Tool names are validated against the server's registry.

agent_id?|

Place the call with a saved agent (POST /agents). The agent supplies system_prompt, first_message, ai_disclosure, recording_enabled, voice_config, tools and max duration; any of those given explicitly on this request wins. Satisfies the system_prompt or llm requirement on its own. A paused agent is refused with 409.

Response Body

`application/json`

curl -X POST "https://example.com/v1/calls" \  -H "Content-Type: application/json" \  -d '{    "recipient_consent": true,    "to": "string"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",  "from_e164": "string",  "to_e164": "string",  "direction": "outbound",  "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",  "status": "queued",  "end_reason": "string",  "provider_call_sid": "string",  "livekit_room": "string",  "initial_prompt": "string",  "recording_enabled": false,  "recording_status": "disabled",  "recording_duration_ms": 0,  "recording_s3_key": "string",  "requested_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "answered_at": "2019-08-24T14:15:22Z",  "ended_at": "2019-08-24T14:15:22Z"}

Header Parameters

Request Body

Response Body

201application/json

402

422application/json

429

`application/json`

`application/json`