Place Batch Calls

curl --request POST \
  --url https://app.thinnest.ai/api/v1/calls/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "agent": "Skyline Sales",
  "purpose": "I'm calling from Skyline Homes about the new tower launching at Baner.",
  "callingHours": {
    "start": "10:00",
    "end": "19:00",
    "days": [
      "mon",
      "tue",
      "wed",
      "thu",
      "fri",
      "sat"
    ]
  },
  "extract": [
    {
      "name": "interest",
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    }
  ],
  "summary": true,
  "variables": {
    "project": "Sky Towers"
  },
  "retry": {
    "count": 1
  },
  "calls": [
    {
      "to": "919876543210",
      "name": "Asha Rao",
      "reference": "LSQ-42",
      "variables": {
        "lead_name": "Asha"
      }
    },
    {
      "to": "+91 99200 11223",
      "name": "Vikram Shah",
      "reference": "LSQ-43"
    },
    {
      "to": "12345",
      "reference": "LSQ-44"
    }
  ]
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: 'Skyline Sales',
    purpose: 'I\'m calling from Skyline Homes about the new tower launching at Baner.',
    callingHours: {start: '10:00', end: '19:00', days: ['mon', 'tue', 'wed', 'thu', 'fri', 'sat']},
    extract: [{name: 'interest', choices: ['Hot', 'Warm', 'Cold']}],
    summary: true,
    variables: {project: 'Sky Towers'},
    retry: {count: 1},
    calls: [
      {
        to: '919876543210',
        name: 'Asha Rao',
        reference: 'LSQ-42',
        variables: {lead_name: 'Asha'}
      },
      {to: '+91 99200 11223', name: 'Vikram Shah', reference: 'LSQ-43'},
      {to: '12345', reference: 'LSQ-44'}
    ]
  })
};

fetch('https://app.thinnest.ai/api/v1/calls/batch', 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/batch"

payload = {
    "agent": "Skyline Sales",
    "purpose": "I'm calling from Skyline Homes about the new tower launching at Baner.",
    "callingHours": {
        "start": "10:00",
        "end": "19:00",
        "days": ["mon", "tue", "wed", "thu", "fri", "sat"]
    },
    "extract": [
        {
            "name": "interest",
            "choices": ["Hot", "Warm", "Cold"]
        }
    ],
    "summary": True,
    "variables": { "project": "Sky Towers" },
    "retry": { "count": 1 },
    "calls": [
        {
            "to": "919876543210",
            "name": "Asha Rao",
            "reference": "LSQ-42",
            "variables": { "lead_name": "Asha" }
        },
        {
            "to": "+91 99200 11223",
            "name": "Vikram Shah",
            "reference": "LSQ-43"
        },
        {
            "to": "12345",
            "reference": "LSQ-44"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "accepted": [
    {
      "id": "sch_2d7b0e91-4f3a-4c88-9b1e-7a6c5d4e3f21",
      "to": "919876543210",
      "reference": "LSQ-42",
      "from": null,
      "status": "scheduled",
      "scheduledFor": "2026-10-06T05:12:44.019Z"
    },
    {
      "id": "sch_7e1f4a20-9c3b-4d5e-8f6a-1b2c3d4e5f60",
      "to": "919920011223",
      "reference": "LSQ-43",
      "from": null,
      "status": "scheduled",
      "scheduledFor": "2026-10-06T05:12:44.019Z"
    }
  ],
  "refused": [
    {
      "to": "12345",
      "reference": "LSQ-44",
      "error": "That number could not be read — too short to be a phone number."
    }
  ],
  "limit": 200
}

Calls

Place Batch Calls

Rings up to 200 people with one request. Every option Place Call takes may be set once for the batch and again on an entry, the entry winning (an entry’s variables sit on top of the batch’s); purpose and agent are the batch’s. Every entry is queued and paced inside your plan’s lines and balance — none rings inline — and each gets its own sch_… id that reports through call.analysed and Get Call. A bad entry is listed under refused and does not stop the rest. Needs a full key.

POST

calls

batch

Place Batch Calls

curl --request POST \
  --url https://app.thinnest.ai/api/v1/calls/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "agent": "Skyline Sales",
  "purpose": "I'm calling from Skyline Homes about the new tower launching at Baner.",
  "callingHours": {
    "start": "10:00",
    "end": "19:00",
    "days": [
      "mon",
      "tue",
      "wed",
      "thu",
      "fri",
      "sat"
    ]
  },
  "extract": [
    {
      "name": "interest",
      "choices": [
        "Hot",
        "Warm",
        "Cold"
      ]
    }
  ],
  "summary": true,
  "variables": {
    "project": "Sky Towers"
  },
  "retry": {
    "count": 1
  },
  "calls": [
    {
      "to": "919876543210",
      "name": "Asha Rao",
      "reference": "LSQ-42",
      "variables": {
        "lead_name": "Asha"
      }
    },
    {
      "to": "+91 99200 11223",
      "name": "Vikram Shah",
      "reference": "LSQ-43"
    },
    {
      "to": "12345",
      "reference": "LSQ-44"
    }
  ]
}
EOF

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent: 'Skyline Sales',
    purpose: 'I\'m calling from Skyline Homes about the new tower launching at Baner.',
    callingHours: {start: '10:00', end: '19:00', days: ['mon', 'tue', 'wed', 'thu', 'fri', 'sat']},
    extract: [{name: 'interest', choices: ['Hot', 'Warm', 'Cold']}],
    summary: true,
    variables: {project: 'Sky Towers'},
    retry: {count: 1},
    calls: [
      {
        to: '919876543210',
        name: 'Asha Rao',
        reference: 'LSQ-42',
        variables: {lead_name: 'Asha'}
      },
      {to: '+91 99200 11223', name: 'Vikram Shah', reference: 'LSQ-43'},
      {to: '12345', reference: 'LSQ-44'}
    ]
  })
};

fetch('https://app.thinnest.ai/api/v1/calls/batch', 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/batch"

payload = {
    "agent": "Skyline Sales",
    "purpose": "I'm calling from Skyline Homes about the new tower launching at Baner.",
    "callingHours": {
        "start": "10:00",
        "end": "19:00",
        "days": ["mon", "tue", "wed", "thu", "fri", "sat"]
    },
    "extract": [
        {
            "name": "interest",
            "choices": ["Hot", "Warm", "Cold"]
        }
    ],
    "summary": True,
    "variables": { "project": "Sky Towers" },
    "retry": { "count": 1 },
    "calls": [
        {
            "to": "919876543210",
            "name": "Asha Rao",
            "reference": "LSQ-42",
            "variables": { "lead_name": "Asha" }
        },
        {
            "to": "+91 99200 11223",
            "name": "Vikram Shah",
            "reference": "LSQ-43"
        },
        {
            "to": "12345",
            "reference": "LSQ-44"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "accepted": [
    {
      "id": "sch_2d7b0e91-4f3a-4c88-9b1e-7a6c5d4e3f21",
      "to": "919876543210",
      "reference": "LSQ-42",
      "from": null,
      "status": "scheduled",
      "scheduledFor": "2026-10-06T05:12:44.019Z"
    },
    {
      "id": "sch_7e1f4a20-9c3b-4d5e-8f6a-1b2c3d4e5f60",
      "to": "919920011223",
      "reference": "LSQ-43",
      "from": null,
      "status": "scheduled",
      "scheduledFor": "2026-10-06T05:12:44.019Z"
    }
  ],
  "refused": [
    {
      "to": "12345",
      "reference": "LSQ-44",
      "error": "That number could not be read — too short to be a phone number."
    }
  ],
  "limit": 200
}

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.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Body

application/json

Up to 200 calls with one purpose and one agent. The options below apply to every entry unless the entry says otherwise.

purpose

string

required

Said aloud first on every call. Under 300 characters.

Required string length: 1 - 299

calls

object[]

required

The people to ring.

Required array length: 1 - 200 elements

Show child attributes

agent

string

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

idempotencyKey

string

The same as the Idempotency-Key header. One key covers the whole batch.

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.

Show child attributes

callingHours

object

When this person may be rung, in their own time. Leave it out for any day, 09:00 to 21:00.

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 (2026-10-07T10: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.

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

The entries queued and the entries refused.

accepted

object[]

required

Show child attributes

refused

object[]

required

Show child attributes

limit

integer

required

The most entries one request may hold (200).

Get started

Agents

Knowledge

Actions

Tools

Channels

Calls

Post-call

Recordings

Conversations

Messages

One-time codes

Contacts

Events

Templates

Campaigns

Sequences

Forms

Phone numbers

Voices

Voice clones

Models

Bring your own keys

Webhooks

Usage

Analytics

Customers

Workspace

Projects

Teams

Members

Invitations

Notifications

Saved replies

Place Batch Calls

Authorizations

Headers

Body

Response