Create a call

Queue one bounded phone task and receive durable task and call IDs.

Content reviewed 2026-10-04 · Maintained by Cleo Powered · Report a documentation issue · Verification basis

POST/v1/callsHTTPS

This endpoint places a real call

Use your own phone for an initial test. A task must pass purpose screening and workspace calling checks before execution.

Headers

Header: Authorization
Required: Yes
Value: Bearer <API_KEY>
Header: Idempotency-Key
Required: Yes
Value: A unique, non-empty key of up to 200 characters. A UUID works well.
Header: Content-Type
Required: Yes
Value: application/json
Header: User-Agent
Required: Recommended
Value: YourApplication/1.0

Header	Required	Value
`Authorization`	Yes	`Bearer <API_KEY>`
`Idempotency-Key`	Yes	A unique, non-empty key of up to 200 characters. A UUID works well.
`Content-Type`	Yes	`application/json`
`User-Agent`	Recommended	`YourApplication/1.0`

Request body

Field: to
Type: string · required
Description: Destination in E.164 format: + followed by country code and number (8–15 digits total).
Field: objective
Type: string · required
Description: What Cleo should accomplish. Between 1 and 4,000 characters.
Field: result_schema
Type: object · required
Description: A valid JSON Schema describing the answers to extract. Published results must pass schema and recipient-evidence checks; missing answers may leave the result incomplete or null.
Field: context
Type: object
Description: Provider-bound background information needed for the call. Defaults to an empty object. Use protected_context for values that must be withheld.
Field: protected_context
Type: object of strings
Description: Optional encrypted answers withheld from the voice flow. Up to 20 fields; names match [a-z][a-z0-9_]{0,63}; each value is 1–2,000 characters; combined UTF-8 value bytes must fit 16 KiB.
Field: constraints
Type: string[]
Description: Boundaries on what the assistant may do. Defaults to []. Up to 50 entries, each at most 500 characters.
Field: success_criteria
Type: string[]
Description: What would count as a useful outcome. Defaults to []. Up to 50 entries, each at most 500 characters.
Field: limits.max_duration_seconds
Type: integer
Description: Requested maximum duration. Default 300; schema range 30–3,600. Other call limits can be lower.

Field	Type	Description
`to`	string · required	Destination in E.164 format: + followed by country code and number (8–15 digits total).
`objective`	string · required	What Cleo should accomplish. Between 1 and 4,000 characters.
`result_schema`	object · required	A valid JSON Schema describing the answers to extract. Published results must pass schema and recipient-evidence checks; missing answers may leave the result incomplete or null.
`context`	object	Provider-bound background information needed for the call. Defaults to an empty object. Use protected_context for values that must be withheld.
`protected_context`	object of strings	Optional encrypted answers withheld from the voice flow. Up to 20 fields; names match [a-z][a-z0-9_]{0,63}; each value is 1–2,000 characters; combined UTF-8 value bytes must fit 16 KiB.
`constraints`	string[]	Boundaries on what the assistant may do. Defaults to []. Up to 50 entries, each at most 500 characters.
`success_criteria`	string[]	What would count as a useful outcome. Defaults to []. Up to 50 entries, each at most 500 characters.
`limits.max_duration_seconds`	integer	Requested maximum duration. Default 300; schema range 30–3,600. Other call limits can be lower.

Unknown top-level fields are rejected. There is no simulation selector or per-request assistant selector; the API uses the assistant associated with your key’s project.

The schema is not a guarantee of generated output

Cleo checks the requested schema and extracts answers from available recipient evidence after the call. Missing required information, invalid candidates, or unavailable processing can leave the result null. Inspect result_extraction; do not infer business success from call completion or schema validity alone.

Example request

Download self-test.json, replace its to value with your own phone number, and save it in the folder where you run the example. Both snippets read that file. The quickstart explains the task.

The two headers use different values: CLEO_API_KEY is your secret key from Settings; IDEMPOTENCY_KEY is a separate UUID that you generate for this intended call. Do not use your API key as the idempotency key.

For cURL, set the variables in Bash, using Git Bash or WSL on Windows. Python 3 is used to generate UUIDs. The Python tab handles its own inputs and does not need this Bash setup:

Bash

# Bash (for Windows, use Git Bash or WSL)
read -rsp "Cleo API key: " CLEO_API_KEY; echo
export CLEO_API_KEY
read -rp "Existing idempotency key for retry (Enter for a NEW call): " IDEMPOTENCY_KEY
if [ -z "$IDEMPOTENCY_KEY" ]; then
  IDEMPOTENCY_KEY="$(python -c 'import uuid; print(uuid.uuid4())')"
fi
export IDEMPOTENCY_KEY
printf "Idempotency key: %s\n" "$IDEMPOTENCY_KEY"

Save the printed idempotency key before sending. Both examples accept an existing key for a retry, or generate a new one when you press Enter. Use one example language per intended call; preserve the same key and JSON file if you switch languages during recovery.

curl --fail-with-body https://api.cleolabs.com/v1/calls \
  -H "Authorization: Bearer $CLEO_API_KEY" \
  -H "User-Agent: CleoDocs/1.0" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @self-test.json

The snippets submit once; they do not automatically poll, retry, or cancel. An HTTP timeout does not stop a call. If no call ID was returned, recover with the original idempotency key.

Response

Returns 202 Accepted with a call object. Save its call id, owning task_id, and the original idempotency key. The accepted task, call, usage reservation, frozen snapshot, and execution job have been persisted together. Acceptance does not confirm dialing. Inspect execution.stage, execution.error_code, and call state.

Replaying an identical request with the same idempotency key returns the existing call. It does not dial again. See idempotency and retries.

Errors

Common failures include missing or invalid authentication, a missing idempotency key, invalid task fields, disabled calling, and a conflicting replay. See the error reference for status codes and recovery guidance.

PreviousAuthentication

NextGet a call