Guides

Quickstart

Create one phone call, keep its ID, and wait for a structured result.

These examples use the production Calls API. For SDK examples, install TypeScript or Python SDK 1.0.

Connect to the API

Terminal
export CALLE_BASE_URL="https://api.heycall-e.com"
export CALLE_API_KEY="<YOUR_CALLE_API_KEY>"

Get a key from the dashboard. Keep it on your server. See Authentication for key handling. Check Regions & languages before choosing a destination; availability also depends on the account and line configuration.

Create one call

Replace <AUTHORIZED_E164_PHONE> with a number you own or are authorized to call. Running this request can place a real phone call. Persist the request and its idempotency key before sending it.

Terminal
curl --fail-with-body --silent --show-error \
  --request POST "$CALLE_BASE_URL/v2/calls" \
  --header "Authorization: Bearer $CALLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: hello-test-001" \
  --data '{
    "task": "Say hello in English, allow a brief reply, then politely end the call.",
    "phone": "<AUTHORIZED_E164_PHONE>",
    "result_schema": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "greeting_delivered": {"type": "boolean"},
        "summary": {"type": "string"}
      },
      "required": ["greeting_delivered", "summary"]
    },
    "metadata": {"test_case": "hello-test-001"}
  }'

This example omits the optional region and locale: the destination is inferred from the phone, and the task explicitly requests English. You may supply them when needed, but they must match your intended destination and language; a phone/region conflict returns 422 input_incomplete instead of silently changing the region.

A successful create returns 202 Accepted with id, object: "call", status: "queued", result: null, and error: null. Acceptance does not mean the phone has connected. Save the returned call_... ID.

Creation waits for task preparation before returning 202. If it returns 422 input_incomplete, no Call was created: collect the facts listed in error.details.missing_inputs, update the task, and submit again. See Calls for the response and retry behavior.

Wait for the result

Terminal
export CALLE_CALL_ID="<CALL_ID_FROM_CREATE>"

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $CALLE_API_KEY" \
  "$CALLE_BASE_URL/v2/calls/$CALLE_CALL_ID"

Poll at a reasonable interval, such as every two seconds:

Response	What to do
`result_status == "pending"`	Keep waiting, including when `status` is `completed`.
`result_status == "available"`	Consume the validated business result. An empty object is also ready.
`result_status == "unavailable"`	Stop waiting. No schema-valid business result is available; both result and error may be null.
`result_status == "not_applicable"`	Stop waiting. Inspect cancellation or the technical error.

An illustrative ready result is {"greeting_delivered": true, "summary": "The recipient replied hello."}. Use Webhooks to receive the result without polling.

Every response includes transcript, which may be empty, and a nullable call_id for Billing lookup. status: completed alone is not proof of business success or result readiness. Keep the API resource id for reads, events and cancellation.

Use the SDKs

The SDK guide includes installation and complete TypeScript and Python examples. For tests, explicitly set CALLE_BASE_URL=https://test-api.heycall-e.com and use a test-compatible key.

Retry without calling twice

If the create response is lost, retry the same request with the same key. Do not switch interfaces or generate a fresh key because of a timeout. Changing input under the same key returns 409 idempotency_conflict.

If waiting times out, keep the Call ID and query it again. A polling timeout does not cancel the call. A new key is for an intentionally new logical call.

Repeated creation returns the same Call's current state, even after completion, failure or cancellation; it does not redial. If the first request is still being created, 409 idempotency_conflict with details.reason_code: creation_in_progress means back off and retry unchanged. A definitive input rejection before acceptance lets you correct the body and reuse the key. Keep omitted region/locale omitted on retries instead of copying their inferred values from the response.

Read the Call retry decisions for the full contract. If you already have an integration, use the migration guide.

Authentication