Your first call

Four steps: make a key, pick a script, ask TeliTask to call someone, then read what they said. TeliTask makes a real phone call and holds a real conversation; your system gets the result.

1. Make a key

In TeliTask, open Settings, then Connections, then Your own system (API), and press Create key. Name it after the system that will use it, such as Shop or Bookings. Turn on “can start calls”. Turn on “can add people and orders” too if your system will send its customers and orders.

The key is shown once. Keep it on your server, never in a browser or an app. Send it on every request as Authorization: Bearer tt_live_….

2. Pick a script

A script is what the agent says and what it finds out. Scripts are written in the dashboard; the API lists them, with the inputs each one needs and the outcome it reports.

curl https://app.telitask.ai/api/v1/scripts \
  -H "Authorization: Bearer $TELITASK_KEY"

{
  "scripts": [{
    "slug": "confirm-delivery",
    "name": "Confirm delivery",
    "inputs":  [{ "key": "order", "label": "Order number", "required": true }],
    "outcome": [{ "key": "result", "values": ["confirmed", "reschedule", "wrong_number"] }]
  }]
}

3. Place the call

Send the script’s slug, who to call and the script’s inputs. Instead of a phone number you can send "person": { "external_id": "cust_2291" } for someone you already added with POST /api/v1/people.

curl https://app.telitask.ai/api/v1/calls \
  -H "Authorization: Bearer $TELITASK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: delivery-48301" \
  -d '{
    "script": "confirm-delivery",
    "phone": "+254722123456",
    "inputs": { "order": "ORD-48301" },
    "external_ref": "48301"
  }'

{
  "id": "6f1c2b9e-3a5d-4c1e-9b7a-2d8e4f0a1b2c",
  "status": "queued",
  "script": "confirm-delivery",
  "external_ref": "48301",
  "attempts": 0,
  "dials_at": "2026-10-03T11:02:00.000Z",
  "outcome": null,
  …the same fields as reading the call, below
}

• Leave out at to call now, or at the next allowed calling time. Send a time to call then.
• The Idempotency-Key header makes a retry safe: if your request times out and you send it again with the same key, the person still gets one call.
• Your calling hours, the Don’t call list and your daily limit apply to API calls exactly as they do in the dashboard.

4. Read the result

One id covers every try. If nobody answers and the script retries, the id stays the same. Read it whenever you like:

curl https://app.telitask.ai/api/v1/calls/6f1c2b9e-3a5d-4c1e-9b7a-2d8e4f0a1b2c \
  -H "Authorization: Bearer $TELITASK_KEY"

{
  "id": "6f1c2b9e-3a5d-4c1e-9b7a-2d8e4f0a1b2c",
  "status": "done",
  "script": "confirm-delivery",
  "attempts": 1,
  "started_at": "2026-10-03T14:02:11+03:00",
  "ended_at": "2026-10-03T14:03:40+03:00",
  "duration_seconds": 89,
  "outcome": { "result": "confirmed" },
  "summary": "Grace confirmed delivery for this afternoon.",
  "callback": null,
  "transcript_url": "https://app.telitask.ai/api/v1/calls/6f1c…/transcript"
}

status is one of queued, calling, done, no_answer, failed or cancelled. outcome follows the script’s outcome fields, so it differs from script to script. If the person asked to be called back, callback says when.

Rather than asking again and again, give TeliTask a web address and it will tell you when each call finishes. See Messages back.

Errors and limits

• Every error has the same shape: {"error": {"code": "person_not_found", "message": "…", "field": "person.external_id"}}
• Each key may make 120 requests a minute.
• Lists return 50 at a time, with a next link for the rest.

Every endpoint, with its fields and examples, is in the API reference.