Skip to content
OnCoreDocs
Calls

POSThttps://core-api.heysadie.ai/calls

assistantId from to firstMessage promptVariables customPrompts metadata promptId prompt toolIds voicemailDetection success data id status direction createdAt timestamp version path error code message details field

Place an outbound call

Place an outbound call through your own connected Twilio account. `from` must be a number you imported from that account; Twilio bills you for the call directly. The call is created before anything is dialed, so it has an id even if the person never answers. `firstMessage`, `promptVariables` and `customPrompts` apply to this call only and win over what your assistant-request webhook returns. `promptId` or `prompt` replaces the assistant's prompt for this call, and `toolIds` replaces its linked tools. - 201 with the call, status `ringing` once the dial is accepted. - 200 with the call already created under a repeated `Idempotency-Key`. Nothing is dialed. - 400 `FROM_NUMBER_NOT_IMPORTED` when `from` is not a number you imported. - 400 `TOOL_NOT_FOUND` when a `toolIds` entry is not one of your tools. `details.toolIds` lists them. - 404 when the assistant is not yours. - 404 `PROMPT_NOT_FOUND` when `promptId` is not one of your voice prompts. - 409 `TWILIO_NOT_CONNECTED`: connect Twilio in Integrations. - 502 `OUTBOUND_DIAL_FAILED` when the call could not be dialed. The call is kept with status `failed`, so retrying with the same `Idempotency-Key` returns it; send a new key to dial again.

Try it in the API Explorer

Example request

Terminal
curl -X POST "https://core-api.heysadie.ai/calls" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "value",
    "from": "value",
    "to": "value"
  }'

Authentication

Authenticate with an API key in the Authorization header using the ApiKey scheme. See Authentication for how keys work and where to get them.

Authorizationstringrequired

API key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.

X-Tenant-Idstring (uuid)optional

Required when authenticating with an organization key: it selects the tenant the request acts on. Omit with tenant keys.

Request

Body application/json · required

assistantIdanyoptional

Required. The assistant that talks on the call (UUID).

fromanyoptional

Required. Caller ID, E.164. Must be a number you imported from your connected Twilio account.

toanyoptional

Required. The number to call, E.164. Must differ from `from`.

firstMessageanyoptional

What the assistant says once the callee answers, up to 2000 characters. Overrides the assistant's and your webhook's first message for this call.

promptVariablesanyoptional

Object of up to 50 string prompt variables for this call. Each key wins over the same key from your webhook.

customPromptsanyoptional

Up to 10 `{ title, content }` prompt sections for this call, added after the ones your webhook returns.

metadataanyoptional

Your own object, up to 8 KB serialized. Stored on the call and sent to your assistant-request webhook when the call starts; never shown to the assistant.

promptIdanyoptional

A voice prompt of yours (UUID) that replaces the assistant's prompt for this call. Prompt variables and custom prompts still apply on top. Cannot be sent with `prompt`.

promptanyoptional

Prompt text, up to 50000 characters, that replaces the assistant's prompt for this call. Prompt variables and custom prompts still apply on top. Cannot be sent with `promptId`.

toolIdsanyoptional

1 to 50 unique ids of your tools. For this call they replace the tools linked to the assistant; built-in tools such as ending or transferring the call stay.

voicemailDetectionanyoptional

Boolean, default `false`. Send `true` to listen when the callee picks up and, if voicemail answered, hang up without greeting and end the call as not answered (`customer-did-not-answer`). Adds a short pause before the greeting.

Responses

200Repeated Idempotency-Key: the call it first created
successbooleanrequired

true on every 2xx

dataobjectoptional

The result

Show 7 child properties
idstringrequired

The call id GET /calls/:id takes

statusstring | nullrequired

queued, then ringing once the dial is accepted; failed if it was not. Later statuses come from the call itself.

directionstringrequired

Always outbound

fromstring | nullrequired
tostring | nullrequired
assistantIdstring | nullrequired
createdAtstring (date-time) | string (date) | number | nullrequired
metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

201Dialing
successbooleanrequired

true on every 2xx

dataobjectoptional

The result

Show 7 child properties
idstringrequired

The call id GET /calls/:id takes

statusstring | nullrequired

queued, then ringing once the dial is accepted; failed if it was not. Later statuses come from the call itself.

directionstringrequired

Always outbound

fromstring | nullrequired
tostring | nullrequired
assistantIdstring | nullrequired
createdAtstring (date-time) | string (date) | number | nullrequired
metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

400The request is invalid. `details` lists each field that failed
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 3 child properties
codeenumrequired

A parameter or body field broke a rule

Allowed values:"VALIDATION_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

detailsobject[]optional

One entry per field that failed

Show 2 item properties
fieldstringrequired

The offending field

messagestringrequired

The rule it broke

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

401Missing or invalid credentials
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

No valid credentials

Allowed values:"UNAUTHORIZED"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

403The credentials are valid but may not use this route
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

The credentials may not use this route

Allowed values:"FORBIDDEN"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

404Not found, or outside the caller's scope
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An id names nothing the caller can see

Allowed values:"RESOURCE_NOT_FOUND"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

500An unexpected server error
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An unexpected server failure

Allowed values:"INTERNAL_SERVER_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested