Place Call

curl --request POST \
  --url https://app.thinnest.ai/api/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "to": "+91 98765 43210",
  "purpose": "I'm calling from Skyline Homes about your enquiry for Sky Towers.",
  "agent": "ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71",
  "name": "Asha Rao",
  "source": "99acres enquiry form",
  "reference": "LSQ-42",
  "variables": {
    "lead_name": "Asha",
    "project": "Sky Towers",
    "budget_asked": "2BHK"
  },
  "callingHours": {
    "start": "10:00",
    "end": "19:00",
    "days": [
      "mon",
      "tue",
      "wed",
      "thu",
      "fri",
      "sat"
    ]
  },
  "extract": [
    {
      "name": "budget",
      "type": "number",
      "description": "Budget in rupees"
    },
    {
      "name": "interest",
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    },
    {
      "name": "site_visit",
      "type": "boolean"
    }
  ],
  "summary": true,
  "metadata": {
    "deal_id": "D-19",
    "owner": "Ravi"
  },
  "retry": {
    "count": 2,
    "noAnswerMinutes": 60,
    "busyMinutes": 15
  },
  "from": "918045678901",
  "overrides": {
    "voice": "priya",
    "maxCallSeconds": 300
  }
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to: '+91 98765 43210',
    purpose: 'I\'m calling from Skyline Homes about your enquiry for Sky Towers.',
    agent: 'ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71',
    name: 'Asha Rao',
    source: '99acres enquiry form',
    reference: 'LSQ-42',
    variables: {lead_name: 'Asha', project: 'Sky Towers', budget_asked: '2BHK'},
    callingHours: {start: '10:00', end: '19:00', days: ['mon', 'tue', 'wed', 'thu', 'fri', 'sat']},
    extract: [
      {name: 'budget', type: 'number', description: 'Budget in rupees'},
      {name: 'interest', choices: ['Hot', 'Warm', 'Cold']},
      {name: 'site_visit', type: 'boolean'}
    ],
    summary: true,
    metadata: {deal_id: 'D-19', owner: 'Ravi'},
    retry: {count: 2, noAnswerMinutes: 60, busyMinutes: 15},
    from: '918045678901',
    overrides: {voice: 'priya', maxCallSeconds: 300}
  })
};

fetch('https://app.thinnest.ai/api/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.thinnest.ai/api/v1/calls"

payload = {
    "to": "+91 98765 43210",
    "purpose": "I'm calling from Skyline Homes about your enquiry for Sky Towers.",
    "agent": "ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71",
    "name": "Asha Rao",
    "source": "99acres enquiry form",
    "reference": "LSQ-42",
    "variables": {
        "lead_name": "Asha",
        "project": "Sky Towers",
        "budget_asked": "2BHK"
    },
    "callingHours": {
        "start": "10:00",
        "end": "19:00",
        "days": ["mon", "tue", "wed", "thu", "fri", "sat"]
    },
    "extract": [
        {
            "name": "budget",
            "type": "number",
            "description": "Budget in rupees"
        },
        {
            "name": "interest",
            "choices": ["Hot", "Warm", "Cold"]
        },
        {
            "name": "site_visit",
            "type": "boolean"
        }
    ],
    "summary": True,
    "metadata": {
        "deal_id": "D-19",
        "owner": "Ravi"
    },
    "retry": {
        "count": 2,
        "noAnswerMinutes": 60,
        "busyMinutes": 15
    },
    "from": "918045678901",
    "overrides": {
        "voice": "priya",
        "maxCallSeconds": 300
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "out_9f2c1a44-6b0e-4c1d-8a7f-2e5b3c9d1f60",
  "to": "919876543210",
  "from": "918045678901",
  "status": "ringing",
  "reference": "LSQ-42"
}

Calls

Place Call

Your agent rings a customer, opens with your purpose (spoken aloud, so 300 characters or fewer), then holds a normal conversation. A number that is not a contact yet becomes one with the name and source you send; someone who opted out or is on your do-not-call list is refused. Outside the calling hours you set with callingHours (any hour of any day when you set none), in the customer’s own time, or with scheduledAt, the call is queued and answers status: "scheduled" with a sch_… id; otherwise it rings now with an out_… id. Each call is billed from your balance, refused with 402 when it cannot pay, held to your plan’s concurrent lines and 60 requests a minute; what it learned arrives as call.analysed or from Get Call. Needs a full key.

POST

calls

Place Call

curl --request POST \
  --url https://app.thinnest.ai/api/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "to": "+91 98765 43210",
  "purpose": "I'm calling from Skyline Homes about your enquiry for Sky Towers.",
  "agent": "ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71",
  "name": "Asha Rao",
  "source": "99acres enquiry form",
  "reference": "LSQ-42",
  "variables": {
    "lead_name": "Asha",
    "project": "Sky Towers",
    "budget_asked": "2BHK"
  },
  "callingHours": {
    "start": "10:00",
    "end": "19:00",
    "days": [
      "mon",
      "tue",
      "wed",
      "thu",
      "fri",
      "sat"
    ]
  },
  "extract": [
    {
      "name": "budget",
      "type": "number",
      "description": "Budget in rupees"
    },
    {
      "name": "interest",
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    },
    {
      "name": "site_visit",
      "type": "boolean"
    }
  ],
  "summary": true,
  "metadata": {
    "deal_id": "D-19",
    "owner": "Ravi"
  },
  "retry": {
    "count": 2,
    "noAnswerMinutes": 60,
    "busyMinutes": 15
  },
  "from": "918045678901",
  "overrides": {
    "voice": "priya",
    "maxCallSeconds": 300
  }
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    to: '+91 98765 43210',
    purpose: 'I\'m calling from Skyline Homes about your enquiry for Sky Towers.',
    agent: 'ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71',
    name: 'Asha Rao',
    source: '99acres enquiry form',
    reference: 'LSQ-42',
    variables: {lead_name: 'Asha', project: 'Sky Towers', budget_asked: '2BHK'},
    callingHours: {start: '10:00', end: '19:00', days: ['mon', 'tue', 'wed', 'thu', 'fri', 'sat']},
    extract: [
      {name: 'budget', type: 'number', description: 'Budget in rupees'},
      {name: 'interest', choices: ['Hot', 'Warm', 'Cold']},
      {name: 'site_visit', type: 'boolean'}
    ],
    summary: true,
    metadata: {deal_id: 'D-19', owner: 'Ravi'},
    retry: {count: 2, noAnswerMinutes: 60, busyMinutes: 15},
    from: '918045678901',
    overrides: {voice: 'priya', maxCallSeconds: 300}
  })
};

fetch('https://app.thinnest.ai/api/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.thinnest.ai/api/v1/calls"

payload = {
    "to": "+91 98765 43210",
    "purpose": "I'm calling from Skyline Homes about your enquiry for Sky Towers.",
    "agent": "ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71",
    "name": "Asha Rao",
    "source": "99acres enquiry form",
    "reference": "LSQ-42",
    "variables": {
        "lead_name": "Asha",
        "project": "Sky Towers",
        "budget_asked": "2BHK"
    },
    "callingHours": {
        "start": "10:00",
        "end": "19:00",
        "days": ["mon", "tue", "wed", "thu", "fri", "sat"]
    },
    "extract": [
        {
            "name": "budget",
            "type": "number",
            "description": "Budget in rupees"
        },
        {
            "name": "interest",
            "choices": ["Hot", "Warm", "Cold"]
        },
        {
            "name": "site_visit",
            "type": "boolean"
        }
    ],
    "summary": True,
    "metadata": {
        "deal_id": "D-19",
        "owner": "Ravi"
    },
    "retry": {
        "count": 2,
        "noAnswerMinutes": 60,
        "busyMinutes": 15
    },
    "from": "918045678901",
    "overrides": {
        "voice": "priya",
        "maxCallSeconds": 300
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "out_9f2c1a44-6b0e-4c1d-8a7f-2e5b3c9d1f60",
  "to": "919876543210",
  "from": "918045678901",
  "status": "ringing",
  "reference": "LSQ-42"
}

Authorizations

Authorization

string

header

required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Idempotency-Key

string

Any unique string. A retry with the same key within 24 hours returns the first request's answer instead of acting twice.

Maximum string length: 255

Thinnest-Workspace

string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace. Refused with 404 (Workspace not found.) when the id is unknown, is not one of your customers, or is not an org_… id; 410 when that customer was deleted (restore it with POST /customers/{id}/restore until it is erased); 403 when the key belongs to one customer workspace (it cannot act as another); 400 when your workspace is not a developer workspace. /customers/* and GET /customers/usage are your own workspace's and refuse the header with 400: call them without it.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Body

application/json

One call to place.

string

required

The customer's number. Include the + and the country code (a leading 00 works too); spaces are fine. A number without its country code is refused: nothing is assumed to be Indian or anywhere else.

Example:

"+91 98765 43210"

purpose

string

required

Why you are calling, as you would say it — the first thing the customer hears. 300 characters or fewer.

Required string length: 1 - 300

Example:

"I'm calling from Skyline Homes about your enquiry for Sky Towers."

agent

string

Which agent calls — its ag_… id or its name. Needed only when more than one agent answers the phone.

Example:

"ag_5c4a5f93-2b1e-4d7a-9f60-8e2d1c3b4a71"

idempotencyKey

string

The same as the Idempotency-Key header, for clients that cannot set headers. The header wins.

name

string

The lead's name. A number that is not a contact yet becomes one with this name; an existing contact's name is never overwritten.

Maximum string length: 120

source

string

Where the lead came from, e.g. 99acres enquiry form — recorded on a new contact.

Maximum string length: 120

reference

string

Your own id for this lead, never interpreted. It comes back on the response, every report and both call webhooks.

Maximum string length: 200

variables

object

Values the agent's instructions use as {{name}}. Up to 20; names are lower-cased with spaces turned into _, values cut to 150 characters. When the number is a contact of yours, its name, first_name, phone and email are filled in underneath — a value you send here wins — and the agent is told who it is speaking with.

Show child attributes

callingHours

object

When this person may be rung, in their own time. Leave it out and the call may ring at any hour of any day.

Show child attributes

ifOutsideHours

enum<string>

default:schedule

Outside the calling hours right now: schedule queues the call for the minute they open; refuse answers 409 with nextOpening and does nothing. Does not apply to a call with scheduledAt, nor to a batch (which always queues).

Available options:

schedule,

refuse

extract

object[]

The details to fill from the call, keyed back exactly as named. A value that does not fit its type is left out rather than sent wrong. Leave it out for the agent's own collected fields.

Maximum array length: 30

Show child attributes

summary

boolean

true writes two or three sentences about the call, false skips it. Leave it out to follow the agent's own switch.

metadata

object

Your own flat data, returned exactly as sent on every report and webhook. Up to 20 keys of 1–60 characters, 4,000 characters serialised; values are strings, numbers, booleans or null — a nested object or list is refused.

Show child attributes

scheduledAt

string<date-time>

Don't ring before this instant, written with its offset (2027-03-08T10:00:00+05:30). Up to 30 days ahead; queued, then rung at this time or the next opening of the calling hours after it. A time already past means now.

retry

object

Try again when the person was not reached (no answer, busy, an answering machine, or a pick-up the agent never reached). A declined call, a dead number and a call somebody answered are never retried. A retry keeps the same id, rings only inside the calling hours, and is checked again against opt-outs and the do-not-call list.

Show child attributes

Example:

{
  "count": 2,
  "noAnswerMinutes": 60,
  "busyMinutes": 15
}

from

string

Which of the agent's numbers rings — its own, or one lent to it for calling (List Phone Numbers). Leave it out for the agent's own line. On an agent with several numbers, a chosen number places at most 200 calls a day.

ringSeconds

integer

How long the phone rings before the call is given up, in whole seconds. Leave it out for the agent's voice.ringSeconds (30 unless set). A call nobody answers in that time is reported as no_answer — the hangup of call.completed — and is retried as one when retry asks. Kept for a scheduled call and for each retry.

Required range: 10 <= x <= 60

overrides

object

Changes to the agent for this call only; the agent itself is not edited. Any other key is refused by name.

Show child attributes

Example:

{
  "voice": "priya",
  "language": "Hindi",
  "maxCallSeconds": 300
}

Response

Accepted: ringing now (out_…), or queued for later (sch_…, with scheduledFor).

string

required

The call's id — out_… when ringing now, sch_… when queued. Every later report and webhook carries it.

Example:

"out_9f2c1a44-6b0e-4c1d-8a7f-2e5b3c9d1f60"

string

required

The number as it will be dialled.

Example:

"919876543210"

from

string | null

required

The number it rings from. Null on a queued call that will use the agent's own line.

Example:

"918045678901"

status

enum<string>

required

Ringing now, or queued.

Available options:

ringing,

scheduled

reference

string | null

required

Your reference, echoed.

scheduledFor

string<date-time>

When a queued call will ring. Only on scheduled.