Docs

API reference

Read contacts, calls and analytics, add contacts and place calls from your own systems. These are all 9 endpoints an API token can reach, generated from the API itself.

Start free

All docs

Before you start

Base URL: https://aicallstudio.com. Every path below starts with /api, with no trailing slash.
Make a token in your dashboard under Settings, Developers. It is shown once: store it like a password.
Your plan must include API access. Without it every request answers 402, and the token works again once the plan includes it.
A token acts for the whole workspace, not for one person, and reaches only the endpoints on this page. Anything else answers 403.

Authentication

Send the token on every request in the Authorization header. Tokens start with mtc_.

The header

Authorization: Bearer mtc_YOUR_TOKEN

Scopes

A token is given scopes when it is made. Each endpoint needs one; a token without it gets 403. You can only give a token what you may do yourself.

Scopes
Scope	On the Developers page	Endpoints
`analytics:read`	Read analytics: Summaries and breakdowns	GET /api/analytics/classification-breakdown, GET /api/analytics/disposition-breakdown, GET /api/analytics/summary
`calls:read`	Read calls: Call logs and analytics	GET /api/analytics/calls
`calls:write`	Place calls: Start calls through the API	POST /api/calls/dial
`contacts:read`	Read contacts: List and export contacts	GET /api/contacts, GET /api/contacts/export
`contacts:write`	Write contacts: Create and import contacts	POST /api/contacts, POST /api/sources/import/csv

Sandbox tokens

A token made as a sandbox token starts with mtc_sandbox_. It never writes, and it never reads your workspace's real data. There is no sample data behind it yet, so today it only proves that the token and its scopes are right: a request it is allowed to make answers 403 with a message saying so, and a request outside its scopes answers 403 naming the scope. Use a live token to read or change data.

Limits and errors

Each token may make 60 requests a minute, across every endpoint. The next request answers 429 with a Retry-After header giving the seconds to wait. Some endpoints have their own limit as well, stated on the endpoint.

Every error is JSON with a detail: a sentence you can show or log. For 422 it may be a list of the fields at fault.

An error

{ "detail": "This token does not have the 'contacts:write' scope." }

Contacts

List contacts

GET/api/contactsScope contacts:read

List your contacts, a page at a time.

Every filter is optional, and they combine. A page holds at most 200 contacts: read total, then ask for the next page until you have them all. Deleted contacts are never listed.

Query parameters
Parameter	Type	What it is
`page`	integer, at least 1	Default: 1.
`page_size`	integer, 1 to 200	Default: 50.
`search`	string, or null	Words found anywhere in the name, email or number, in any order. A number matches in any format.
`status`	string, or null	The contact's status, such as new.
`classification`	string, or null	Lead classification: hot, warm or cold.
`source`	string, or null	Where the contact came from, exactly as the contact's source field says.
`disposition`	string, or null	The contact's latest outcome key.
`min_score`	integer, or null	Has a call scored at least this (0 to 100).
`max_score`	integer, or null	Has a call scored at most this (0 to 100).
`min_duration`	integer, or null	Has a call at least this many seconds long.
`max_duration`	integer, or null	Has a call at most this many seconds long.
`campaign_id`	string (uuid), or null	Has a call placed by this campaign.
`lead_set`	string, or null	The lead set the contact was imported into.
`dnd`	boolean, or null	true: only Do-Not-Call contacts; false: only callable ones.
`needs`	one of: callback, stale_high, or null	callback: a call back is owed; stale_high: hot, callable, and not rung in the last 7 days.
`added_from`	string (date-time), or null	Added at or after this time (ISO 8601).
`added_to`	string (date-time), or null	Added at or before this time (ISO 8601).
`added_days`	integer, 1 to 366, or null	Added in the last N days
`agent_id`	string (uuid), or null	Has a call answered by this AI agent.
`team_id`	string (uuid), or null	Has a call answered by this AI team.
`answered_by`	one of: agent, team, or null	Has a call answered by any AI agent working alone, or by any AI team.
`assigned_to`	string, or null	Given to: a team member's user id, or `none`
`last_message_status`	string, up to 12 characters, or null	The latest campaign message to the contact has this status (delivered, read, replied, failed...)
`sort`	one of: name, source, score, last_called, added	Default: name.
`order`	one of: asc, desc	Default: asc.
`view`	one of: active, held	held: contacts held over the plan's contact limit. Default: active.

Answer (200): these fields
Field	Type	What it is
`total`required	integer	Contacts matching the filters, across every page.
`page`required	integer	—
`page_size`required	integer	—
`sort`required	string	—
`order`required	string	—
`items`required	list of objects	—
`items[].id`required	string (uuid)	—
`items[].name`required	string	—
`items[].phone`required	string	—
`items[].email`required	string, or null	—
`items[].lead_type`required	string, or null	—
`items[].status`required	string	—
`items[].classification`required	string, or null	—
`items[].disposition`required	string, or null	—
`items[].dnd_flag`required	boolean	—
`items[].source`	string, or null	—
`items[].language`	string, or null	—
`items[].created_at`	string (date-time), or null	—
`items[].last_called_at`	string (date-time), or null	—
`items[].score`	number, or null	—
`items[].assigned_user_id`	string (uuid), or null	—

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

GET /api/contacts with curl

curl "https://aicallstudio.com/api/contacts?page_size=50" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN"

Create a contact

POST/api/contactsScope contacts:write

Add one contact.

name and phone are required. One number is one contact: the same number in another format ("98765 43210", "+919876543210") is refused with 409. A number deleted earlier brings that contact back with its history. Adding a contact starts the workspace's New Contact workflows, as adding one by hand does, and those may call or message the person.

Request body (application/json)
Field	Type	What it is
`name`required	string, up to 255 characters	The person's name.
`phone`required	string, up to 20 characters	8 to 15 digits, optionally starting with +. Stored in one canonical form.
`email`	string, or null	Optional. Must look like name@example.com.
`custom_fields`	object	Your own fields for this contact, by field name. A contact type's required fields must be here.
`lead_type`	string, or null	The contact type's key, which decides the fields it needs. Blank: general.
`source`	string, or null	Where the contact came from, in your words.
`dnd_flag`	boolean	true puts the number on Do-Not-Call: it is never rung. Default: false.
`status`	string	Default: new.
`classification`	string, or null	hot, warm or cold.
`disposition`	string, or null	An outcome key defined in your workspace.
`language`	string, or null	The language the person prefers, as a code or a name, such as hi-IN or Hindi.

Answer (201): these fields
Field	Type	What it is
`id`required	string (uuid)	—
`org_id`required	string (uuid)	—
`name`required	string	—
`phone`required	string	—
`email`required	string, or null	—
`custom_fields`required	object	—
`lead_type`required	string, or null	—
`source`required	string, or null	—
`dnd_flag`required	boolean	—
`status`required	string	—
`classification`required	string, or null	—
`disposition`required	string, or null	—
`language`	string, or null	—
`best_time`	object, or null	—
`assigned_user_id`	string (uuid), or null	—

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access. The plan's contact limit is reached.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`409`	A contact already has this number, in any format.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

POST /api/contacts with curl

curl -X POST "https://aicallstudio.com/api/contacts" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Asha Verma","phone":"+919876543210"}'

Export contacts

GET/api/contacts/exportScope contacts:read

Download every contact matching the filters as one file, CSV or Excel.

The same filters as listing contacts, in one file with no paging. Pass ids to export just those contacts (at most 1,000), still inside the other filters.

Query parameters
Parameter	Type	What it is
`format`	string	csv or xlsx. Default: csv.
`search`	string, or null	Words found anywhere in the name, email or number, in any order. A number matches in any format.
`status`	string, or null	The contact's status, such as new.
`classification`	string, or null	Lead classification: hot, warm or cold.
`source`	string, or null	Where the contact came from, exactly as the contact's source field says.
`disposition`	string, or null	The contact's latest outcome key.
`min_score`	integer, or null	Has a call scored at least this (0 to 100).
`max_score`	integer, or null	Has a call scored at most this (0 to 100).
`min_duration`	integer, or null	Has a call at least this many seconds long.
`max_duration`	integer, or null	Has a call at most this many seconds long.
`campaign_id`	string (uuid), or null	Has a call placed by this campaign.
`lead_set`	string, or null	The lead set the contact was imported into.
`dnd`	boolean, or null	true: only Do-Not-Call contacts; false: only callable ones.
`needs`	one of: callback, stale_high, or null	callback: a call back is owed; stale_high: hot, callable, and not rung in the last 7 days.
`added_from`	string (date-time), or null	Added at or after this time (ISO 8601).
`added_to`	string (date-time), or null	Added at or before this time (ISO 8601).
`added_days`	integer, 1 to 366, or null	Added in the last N days
`agent_id`	string (uuid), or null	Has a call answered by this AI agent.
`team_id`	string (uuid), or null	Has a call answered by this AI team.
`answered_by`	one of: agent, team, or null	Has a call answered by any AI agent working alone, or by any AI team.
`assigned_to`	string, or null	Given to: a team member's user id, or `none`
`last_message_status`	string, up to 12 characters, or null	The latest campaign message to the contact has this status (delivered, read, replied, failed...)
`ids`	string, or null	Comma-separated contact ids: export just this selection

Answer: 200. The file, as an attachment: CSV by default, an Excel workbook with format=xlsx.

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

GET /api/contacts/export with curl

curl "https://aicallstudio.com/api/contacts/export" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN" \
  -o contacts.csv

Import contacts from a file

POST/api/sources/import/csvScope contacts:write

Import contacts from a spreadsheet: one contact per row.

Send the file as multipart/form-data. Rows without a name or a dialable phone number are skipped and listed in errors. A number already in the workspace updates that contact, or is skipped with dedupe=skip. New contacts over the plan's contact limit are saved but held, and counted in held. New contacts start the New Contact workflows, which may call or message them. One import runs in a workspace at a time, and an address may start at most 3 a minute.

Request body (multipart/form-data)
Field	Type	What it is
`file`required	file	A .csv or .xlsx file with a header row. It needs a name and a phone column. At most 50 MB.
`lead_set`	string, or null	A lead set to put every imported contact in.
`clean_names`	boolean	true tidies each name: title case, honorifics and extra spaces removed. Default: false.
`dedupe`	string	A number that is already a contact: update (the default) refreshes that contact, skip leaves it. Default: update.
`lead_type`	string, or null	The contact type every row is imported as.
`mapping`	string, or null	JSON: which column fills each field, as {"field name": "Column header"}.

Answer (200): these fields
Field	Type	What it is
`source_id`required	string (uuid)	The import, as a lead source in your workspace.
`created`required	integer	New contacts added.
`updated`required	integer	Existing contacts refreshed from the file.
`skipped`required	integer	Rows not imported: rows with a problem (see errors), and existing contacts with dedupe=skip.
`held`	integer	New contacts over the plan's contact limit: saved, and held until the plan has room. Default: 0.
`errors`required	list of string	Why each skipped row was skipped, by row number.

Errors
Code	When
`400`	The file is not .csv or .xlsx, is empty, cannot be read, or has no name or phone column.
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`413`	The file is over 50 MB.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

POST /api/sources/import/csv with curl

curl -X POST "https://aicallstudio.com/api/sources/import/csv" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN" \
  -F "file=@contacts.csv"

Calls

List calls

GET/api/analytics/callsScope calls:read

The call log, a page at a time, newest first, with totals for everything that matches.

Each call comes with its outcome, score, summary, cost and who answered it, and stats counts every matching call, not just this page. By default the last 30 days; date_from and date_to (IST calendar days) pick a range instead. Test calls are left out unless asked for. A page holds at most 200 calls. A recording link expires: fetch the call again when you need it.

Query parameters
Parameter	Type	What it is
`page`	integer, at least 1	Default: 1.
`page_size`	integer, 1 to 200	Default: 50.
`sort`	string	By start time: newest or oldest first. Default: newest.
`days`	integer, 1 to 365	The last this many days, 1 to 365. date_from overrides it. Default: 30.
`status`	string, or null	The call's status, such as completed, no_answer, busy or failed.
`classification`	string, or null	Lead classification: hot, warm or cold.
`agent_id`	string, or null	Calls answered by this AI agent.
`team_id`	string, or null	Calls answered by this AI team.
`contact_id`	string, or null	Calls with this contact.
`direction`	string, or null	inbound or outbound.
`campaign_id`	string, or null	Calls this campaign placed.
`disposition`	string, or null	Calls with this outcome key.
`initiator`	string, or null	What started the call, comma-separated: manual,campaign,web,inbound,workflow,workspace,test,api,callback
`missed`	boolean, or null	true: calls where nobody spoke to the customer (not answered, a machine, or a failed attempt); false: the others.
`search`	string, or null	Text to find in the contact's name, a number on the call, or the summary.
`date_from`	string (date), or null	IST calendar day, YYYY-MM-DD. Beats `days`.
`date_to`	string (date), or null	IST calendar day, inclusive.
`campaign_only`	boolean	Only calls a campaign placed. Default: false.
`did`	string, or null	Comma-separated: your own numbers. Matches every stored spelling of each line (+91…, 91…, 0…, national).
`handover`	one of: yes, no, answered, missed, not_rung, or null	Handed to a person: yes, no, answered (someone came on), missed (someone was rung, nobody came on) or not_rung (nobody was rung: outside the hours).
`handover_user`	string (uuid), or null	Only hand-overs this staff member answered.
`answered_by`	one of: agent, team, staff, or null	Any AI agent working alone, any AI team, or staff (a person's own call from the Workspace, no AI on it).
`staff_user`	string (uuid), or null	Calls this staff member took: hand-overs they answered and calls they dialled from the Workspace.
`ids`	string, or null	Comma-separated call ids (at most 500): the rows someone selected.
`desk_id`	string (uuid), or null	Calls attributed to this desk: to or from one of its numbers, or handed over through an 'A desk' step and taken by someone on it.
`channel`	one of: phone, web, or null	What carried the call: phone (a phone line) or web (in a browser). With direction=inbound, web is the website widget's calls.
`hide_test`	boolean	Leave out test calls (the default, as on Home and Analytics). initiator=test shows them regardless. Default: true.
`scored`	one of: yes, no, or null	Whether the call has a score (Call Scoring's coverage).
`qa`	one of: graded, not_graded, pass, review, fail, disputed, or null	Call QA: graded, not_graded, or by the call's QA band (the worst of its grades: pass, review, fail), or disputed (a grade with an open dispute).
`mode`	one of: ai, power, or null	Campaign mode: power (calls a power-dialer campaign placed for your staff) or ai (every other call).
`insights`	one of: none, read, or null	Conversation insights: none (connected, 15 seconds or longer, with a transcript, not read yet: what Intelligence counts as unread) or read.
`call_class`	one of: ai, human, hybrid, or null	Who worked the call: ai (the AI alone), human (people only) or hybrid (the AI, then a person who came on).

Answer (200): these fields
Field	Type	What it is
`total`required	integer	—
`page`required	integer	—
`page_size`required	integer	—
`items`required	list of objects	—
`items[].id`required	string (uuid)	—
`items[].direction`	string, or null	inbound or outbound.
`items[].initiator`	string, or null	What started the call: manual, campaign, web, inbound, workflow, workspace, test, api or callback. Null on older calls.
`items[].status`	string, or null	—
`items[].started_at`	string (date-time), or null	—
`items[].duration_sec`	integer, or null	—
`items[].billed_minutes`	number, or null	—
`items[].classification`	string, or null	Lead classification: hot, warm or cold.
`items[].disposition`	string, or null	The call's outcome key.
`items[].score`	number, or null	Lead score, 0 to 100.
`items[].sentiment`	string, or null	—
`items[].summary`	string, or null	—
`items[].cost`	number, or null	What the call cost in all, in rupees.
`items[].languages_used`	list of string, or null	—
`items[].agent_id`	string (uuid), or null	—
`items[].agent_name`	string, or null	—
`items[].team_id`	string (uuid), or null	—
`items[].team_name`	string, or null	—
`items[].answered_by`	string, or null	The name of the agent, team or person who took the call.
`items[].placed_by`	string, or null	The person who placed the call, when a person did.
`items[].campaign_id`	string (uuid), or null	—
`items[].campaign_name`	string, or null	—
`items[].contact_id`	string (uuid), or null	Null when there is no contact, or it was deleted.
`items[].contact_deleted`	boolean	Default: false.
`items[].contact_name`	string, or null	—
`items[].contact_phone`	string, or null	—
`items[].did`	string, or null	Your own number on the call.
`items[].has_recording`	boolean	Default: false.
`items[].recording_url`	string, or null	A link to play the recording. It expires: fetch it when you need it.
`items[].missed`	boolean	Nobody spoke to the customer: not answered, a machine, or a failed attempt. Default: false.
`items[].disposed_by`	string, or null	Who set the outcome.
`items[].callback_requested`	boolean	Default: false.
`items[].callback_time`	string, or null	—
`items[].handover`	string, or null	Handed to a person: answered, missed or not_rung; null if never.
`items[].qa`	object, or null	The call's quality grade; null when it was never graded.
`stats`required	object	—
`stats.total`required	integer	Calls matching the filters, across every page.
`stats.completed`required	integer	Of those, calls someone picked up.
`stats.talk_minutes`required	integer	—
`stats.total_cost`	number, or null	What those calls cost in all, in rupees.

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

GET /api/analytics/calls with curl

curl "https://aicallstudio.com/api/analytics/calls?page_size=50&days=30" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN"

Place a call

POST/api/calls/dialScope calls:write

Ring one number now, with an AI agent or team speaking. A real call, billed like any other.

Send phone (a 10-digit Indian mobile) or contact_id, and exactly one of agent_id or team_id. The same checks as any outbound call apply first: the plan, Do-Not-Call, the agent's calling hours and the calls-at-once limits. The answer means ringing has started, not that anyone picked up: the outcome arrives with the call.completed webhook and in the call log.

Request body (application/json)
Field	Type	What it is
`phone`	string, or null	A 10-digit Indian mobile number starting with 6 to 9, without +91. Send this or contact_id.
`contact_id`	string (uuid), or null	A contact to call, by id: the contact's own number is rung.
`agent_id`	string (uuid), or null	The AI agent that speaks. Send this or team_id, not both.
`team_id`	string (uuid), or null	The AI team that speaks. Send this or agent_id, not both.

Answer (200): these fields
Field	Type	What it is
`status`required	string	Always dialing: the number is being rung.
`phone`required	string	The number rung, with +91.
`answerer`required	string	The name of the agent or team that will speak.
`room`required	string	An id for this call attempt.

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access. The plan has no calls left, or does not include this voice tier.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow. The number cannot be called: on a Do-Not-Call or Do-Not-Disturb list, no consent, or outside the workspace's calling window.
`404`	The agent, team or contact was not found, or is switched off.
`409`	The call cannot start now: the plan's calls-at-once limit, the agent's own limit, the agent's calling hours, a draft or paused agent, or no phone line to call from.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.
`502`	The call could not be started. Nothing was rung; try again.
`503`	Calling is halted for a moment by the platform.

POST /api/calls/dial with curl

curl -X POST "https://aicallstudio.com/api/calls/dial" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phone":"9876543210","agent_id":"YOUR_AGENT_ID"}'

Analytics

Calls by classification

GET/api/analytics/classification-breakdownScope analytics:read

Calls counted by lead classification (hot, warm, cold, unclassified), most common first.

By default the last 30 days; date_from and date_to (IST calendar days) pick a range instead.

Query parameters
Parameter	Type	What it is
`days`	integer, 1 to 365	The last this many days, 1 to 365. date_from overrides it. Default: 30.
`date_from`	string (date), or null	IST calendar day, YYYY-MM-DD. Beats `days`.
`date_to`	string (date), or null	IST calendar day, inclusive (default today).
`agent_id`	string (uuid), or null	Only calls this AI agent answered.
`team_id`	string (uuid), or null	Only calls this AI team answered.
`mode`	one of: ai, power, or null	Campaign mode: power or ai.
`desk_id`	string (uuid), or null	Calls attributed to this desk: to or from one of its numbers, or handed over through an 'A desk' step and taken by someone on it.
`staff_user`	string (uuid), or null	One team member's calls, as Call Logs' Person filter counts them: hand-overs they answered, calls they dialled from the Workspace, and calls passed or put through to them.
`campaign_id`	string (uuid), or null	Calls this campaign placed.
`direction`	one of: inbound, outbound, or null	Calls in or out. A web call is inbound, as on Call Logs.

Answer (200): a list, each item with these fields
Field	Type	What it is
`classification`required	string	hot, warm, cold, or unclassified.
`count`required	integer	—

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

GET /api/analytics/classification-breakdown with curl

curl "https://aicallstudio.com/api/analytics/classification-breakdown?days=30" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN"

Calls by outcome

GET/api/analytics/disposition-breakdownScope analytics:read

Calls counted by outcome, most common first, each with its name in your workspace.

By default the last 30 days; date_from and date_to (IST calendar days) pick a range instead.

Query parameters
Parameter	Type	What it is
`days`	integer, 1 to 365	The last this many days, 1 to 365. date_from overrides it. Default: 30.
`date_from`	string (date), or null	IST calendar day, YYYY-MM-DD. Beats `days`.
`date_to`	string (date), or null	IST calendar day, inclusive (default today).
`agent_id`	string (uuid), or null	Only calls this AI agent answered.
`team_id`	string (uuid), or null	Only calls this AI team answered.
`mode`	one of: ai, power, or null	Campaign mode: power or ai.
`desk_id`	string (uuid), or null	Calls attributed to this desk: to or from one of its numbers, or handed over through an 'A desk' step and taken by someone on it.
`staff_user`	string (uuid), or null	One team member's calls, as Call Logs' Person filter counts them: hand-overs they answered, calls they dialled from the Workspace, and calls passed or put through to them.
`campaign_id`	string (uuid), or null	Calls this campaign placed.
`direction`	one of: inbound, outbound, or null	Calls in or out. A web call is inbound, as on Call Logs.

Answer (200): a list, each item with these fields
Field	Type	What it is
`disposition`required	string	The outcome key, or unknown for calls with none.
`label`required	string	The outcome's name in your workspace.
`group`	string, or null	The group the outcome belongs to.
`count`required	integer	—

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

GET /api/analytics/disposition-breakdown with curl

curl "https://aicallstudio.com/api/analytics/disposition-breakdown?days=30" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN"

Call summary

GET/api/analytics/summaryScope analytics:read

Call totals for the last days days: calls, connected calls, minutes, duration and score.

A connected call is one someone picked up; an answering machine does not count.

Query parameters
Parameter	Type	What it is
`days`	integer, 1 to 365	The period: the last this many days, 1 to 365. Default: 30.
`agent_id`	string (uuid), or null	Only calls this AI agent answered.
`team_id`	string (uuid), or null	Only calls this AI team answered.
`mode`	one of: ai, power, or null	Campaign mode: power or ai.
`campaign_only`	boolean	Count only calls a campaign placed. Default: false.

Answer (200): these fields
Field	Type	What it is
`period_days`required	integer	The period counted: the last `days` days.
`total_calls`required	integer	—
`completed_calls`required	integer	Calls someone picked up. The same number as `connected_calls`.
`connected_calls`required	integer	Calls someone picked up. An answering machine does not count.
`completion_rate`required	number	Connected calls as a percentage of all calls, to one decimal place.
`total_billed_minutes`	number, or null	Minutes billed for these calls.
`avg_duration_sec`required	number	—
`avg_qa_score`	number, or null	Average lead score of the scored calls; null when none was scored.

Errors
Code	When
`401`	The token is missing, unknown or revoked, or its workspace was deleted.
`402`	The workspace's plan does not include API access. The token is paused, not revoked: it works again as soon as the plan includes API access.
`403`	The token does not have this endpoint's scope, it is a sandbox token, the workspace is suspended, or the request came from a network the workspace does not allow.
`422`	A field is missing or not in the form this endpoint takes. `detail` says which, and why.
`429`	This token has made more than 60 requests a minute. The Retry-After header says how many seconds to wait.

GET /api/analytics/summary with curl

curl "https://aicallstudio.com/api/analytics/summary?days=30" \
  -H "Authorization: Bearer mtc_YOUR_TOKEN"

Webhooks

Instead of asking for changes, give a URL under Settings, Developers and pick the events it should receive. Each event is a POST of JSON to that URL, signed with the webhook's own signing secret (it starts with whsec_ and is shown once, when the webhook is made or its secret is changed).

Events
Event	When it is sent
`call.completed`	Call completed. After every call, with transcript and score.
`call.wrapped_up`	Outcome updated. When a person saves their outcome after Call completed went: an update of that call.
`campaign.status_changed`	Campaign status. When a campaign starts, finishes or is cancelled.
`test`	Only when you press Send test event on the Developers page.

The body is always { "event", "data", "ts", "id" }: the event's name, its data, the time it happened (Unix seconds) and the delivery's id. Each request also carries these headers:

X-Aicallstudio-Signature: sha256= and the hex HMAC-SHA256 of the raw body, keyed with your signing secret.
X-Aicallstudio-Event: the event's name.
X-Aicallstudio-Delivery: one id per event, the same on every retry. Keep the ids you have handled and ignore a repeat.

call.completed, an example

{
  "event": "call.completed",
  "ts": 1772633868,
  "id": "4f1c2b9e8d7a4e3f9b6a5c4d3e2f1a0b",
  "data": {
    "call": {
      "id": "uuid",
      "status": "completed",
      "duration_seconds": 142,
      "direction": "outbound",
      "disposition": "ptp",
      "disposition_label": "Promise to pay",
      "classification": "hot",
      "score": 82,
      "summary": "Contact expressed strong interest.",
      "contact_id": "uuid",
      "campaign_id": null,
      "transcript": "Agent: Hi...\nLead: Yes I'm interested...\nStaff: Hello, this is Priya...",
      "transcript_turns": [
        { "speaker": "agent", "text": "Hi..." },
        { "speaker": "lead", "text": "Yes I'm interested..." },
        { "speaker": "staff", "name": "Priya", "text": "Hello, this is Priya..." }
      ],
      "placed_by": { "kind": "ai_agent", "id": "uuid", "name": "Collections desk" },
      "cost_inr": 4.75
    }
  }
}

call.wrapped_up, an example

{
  "event": "call.wrapped_up",
  "ts": 1772634211,
  "id": "9a8b7c6d5e4f43a2b1c0d9e8f7a6b5c4",
  "data": {
    "call": {
      "id": "uuid",
      "contact_id": "uuid",
      "disposition": "callback",
      "disposition_label": "Callback requested",
      "disposition_by": "staff",
      "previous_disposition": "interested",
      "wrap_up": {
        "disposition": "callback",
        "note": "Call after 6 pm",
        "fields": {},
        "callback": { "at": "2026-11-14T18:00:00+05:30" },
        "by_name": "Priya"
      }
    }
  }
}

campaign.status_changed, an example

{
  "event": "campaign.status_changed",
  "ts": 1772634500,
  "id": "1b2c3d4e5f6a47b8c9d0e1f2a3b4c5d6",
  "data": { "campaign_id": "uuid", "status": "running" }
}

Check the signature

Work out the signature from the raw body before parsing it, and refuse any request where it does not match.

Node.js

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a Buffer), before any JSON parsing.
function isFromAiCallStudio(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(signatureHeader || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// isFromAiCallStudio(req.rawBody, req.get("X-Aicallstudio-Signature"), process.env.WEBHOOK_SECRET)

Python

import hashlib, hmac

def is_from_ai_call_studio(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

# is_from_ai_call_studio(request.body, request.headers["X-Aicallstudio-Signature"], WEBHOOK_SECRET)

Answers, retries and pausing

Answer with any 2xx within 10 seconds. Anything else, or no answer, is retried up to 5 times, after 1, 2, 4, 8, 16 minutes. After 50 failed deliveries in a row the webhook is paused and your workspace is told; nothing is sent until you resume it, and events in between are skipped, not sent later.

Costs and what to watch

Place a call rings a real person and is billed like any call, at your plan's rates.
Adding or importing contacts starts your New Contact workflows, as adding them by hand does, and those may call or message the person.
A token acts as the workspace, with everyone's data in reach of its scopes. Give each system its own token with only the scopes it needs, and revoke one you no longer use.