API Reference

Complete API documentation for integrating Hanc.AI into your applications. Manage agents, fetch call data, place calls, and operate every part of the platform programmatically.

Every section below gives you the HTTP method and path, the parameters (path, query, and body), a ready‑to‑run example request, and a representative example response so you can integrate without guessing the payload shapes.

Quick overview


Base URL	`https://api.hanc.ai`
Version prefix	All routes are prefixed with `/v1`
Authentication	API key via the `x-api-key` header
Format	JSON (request and response)

Generate an API key from Integration → API Keys in the dashboard. You can have up to 3 keys per user — see the API Keys section in Integrations for setup, permissions, and security guidance.

curl -X GET "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Send your key in the x-api-key header on every request:

x-api-key: YOUR_API_KEY

The key resolves to the user that owns it, and every request is automatically scoped to that user — you never pass a user ID. A missing or invalid key is rejected with 401 Unauthorized / 403 Forbidden.

tip

Keep keys server‑side. Never embed an API key in a browser, mobile app, or any client the end‑user can inspect. If a key leaks, revoke it in Integration → API Keys and issue a new one.

Conventions

A few rules apply across the whole API. Reading these once will save you debugging time:

Version prefix — every path starts with /v1 (e.g. https://api.hanc.ai/v1/agent/list).
IDs are Mongo ObjectIds — any :id (and :agentActionId, :agentToolId, etc.) must be a 24‑character hex string. Malformed IDs return 400 Bad Request.
Unknown body fields are stripped — the API validates request bodies and silently drops properties it doesn't recognise, so a typo in a field name is ignored rather than stored.
Dates — analytics/export endpoints take date_from / date_to as YYYY-MM-DD. date_to is inclusive to the end of that day.
Array query params — where a filter accepts multiple values (e.g. agent_ids, direction), you can repeat the key (?direction=inbound&direction=outbound) or comma‑separate it (?direction=inbound,outbound).
Timestamps in responses are epoch milliseconds unless shown as an ISO‑8601 string.

Endpoint index

A quick map of everything available. Detailed docs for each follow below.

Calls

Action	Method	Endpoint
List calls	GET	`/v1/call/list`
Call details (transcript, sentiment, summary)	GET	`/v1/call/:id`
General analytics (totals over a range)	GET	`/v1/call/general-metrics`
Daily analytics	GET	`/v1/call/daily-metrics`
Sentiment statistics	GET	`/v1/call/sentiment-stats`
Cost breakdown	GET	`/v1/call/costs-breakdown`
Export calls (CSV)	GET	`/v1/call/list/export`
Export costs (CSV)	GET	`/v1/call/costs-breakdown/export`
Make a phone call	POST	`/v1/call/make-phone-call`
Make a web call	POST	`/v1/call/make-web-call`

Agents

Action	Method	Endpoint
List agents	GET	`/v1/agent/list`
Agent details	GET	`/v1/agent/:id`
Create agent	POST	`/v1/agent`
Update agent	PATCH	`/v1/agent/:id`
Delete agent	DELETE	`/v1/agent/:id`
Agent call statistics	GET	`/v1/agent/:id/call-stats`
List agent templates	GET	`/v1/agent/agent_template/list`
List actions	GET	`/v1/agent/:id/actions`
Add action	POST	`/v1/agent/:id/actions`
Update action	PATCH	`/v1/agent/:id/actions/:agentActionId`
Delete action	DELETE	`/v1/agent/:id/actions/:agentActionId`
List tools	GET	`/v1/agent/:id/tools`
Add tool	POST	`/v1/agent/:id/tools`
Update tool	PATCH	`/v1/agent/:id/tools/:agentToolId`
Delete tool	DELETE	`/v1/agent/:id/tools/:agentToolId`

Knowledge Base

Action	Method	Endpoint
List knowledge bases	GET	`/v1/knowledge-base/list`
Create (with first file)	POST	`/v1/knowledge-base`
Add a single file	POST	`/v1/knowledge-base/:id/file`
Add multiple files	POST	`/v1/knowledge-base/:id/files`
Delete file(s)	DELETE	`/v1/knowledge-base/:id/file`
Assign agents	PUT	`/v1/knowledge-base/:id/agents`

Phone Numbers

Action	Method	Endpoint
List numbers	GET	`/v1/phone-number/list`
Available numbers (by country)	GET	`/v1/phone-number/available`
Buy a number	POST	`/v1/phone-number/buy`
Import from Twilio	POST	`/v1/phone-number/import-twilio`
Connect to SIP	PATCH	`/v1/phone-number/connect-to-sip`

Voices · Subscription · Customers · Workspaces

Action	Method	Endpoint
List voices	GET	`/v1/voice/list`
Subscription details	GET	`/v1/subscription`
Configure auto top‑up	PATCH	`/v1/subscription/auto-top-up`
Set top‑up amount	PATCH	`/v1/subscription/top-up-amount`
List customers	GET	`/v1/customer/list`
Customer details	GET	`/v1/customer/:id`
Create customer	POST	`/v1/customer`
Update customer	PATCH	`/v1/customer/:id`
Delete customer	DELETE	`/v1/customer/:id`
List workspaces	GET	`/v1/workspaces/list`
Create workspace	POST	`/v1/workspaces`
Workspace details	GET	`/v1/workspaces/:id`
Update workspace	PATCH	`/v1/workspaces/:id`
Delete workspace	DELETE	`/v1/workspaces/:id`
Invite member	POST	`/v1/workspaces/:workspace_id/invite-member`
Remove member	DELETE	`/v1/workspaces/:workspace_id/remove-member`

Calls

Manage and analyse voice calls: list and inspect calls (transcript, sentiment, summary), pull aggregated metrics, export CSV reports, and place outbound phone and web calls.

List calls

GET /v1/call/list

List calls for your account with filtering, sorting, and pagination.

Query parameters

Name	Type	Required	Description
`agent_ids`	string[]	No	Filter by one or more agent IDs (repeat or comma‑separate).
`agent_id`	string	No	Filter by a single agent (legacy; prefer `agent_ids`).
`direction`	enum[]	No	`inbound` and/or `outbound`.
`call_status`	enum[]	No	`started`, `success`, `failed`, `pending`.
`call_type`	enum[]	No	`phone`, `web`.
`customer_id`	string	No	Filter by customer.
`workspace_id`	string	No	Filter by workspace.
`date_from` / `date_to`	string	No	Range filter (`YYYY-MM-DD`).
`sort_order`	enum	No	`asc` or `desc`.
`limit`	number	No	Max results to return.
`skip`	number	No	Results to skip (pagination offset).

Example request

curl -G "https://api.hanc.ai/v1/call/list" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "agent_ids=507f1f77bcf86cd799439042" \
  --data-urlencode "direction=inbound" \
  --data-urlencode "sort_order=desc" \
  --data-urlencode "limit=10"

Example response — 200 OK

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "call_type": "phone",
    "agent_id": "507f1f77bcf86cd799439042",
    "agent_name": "Customer Support Agent",
    "call_status": "success",
    "call_from": "+12345678900",
    "call_to": "+12345678911",
    "direction": "inbound",
    "start_timestamp": 1703302407333,
    "end_timestamp": 1703302428855,
    "recording_url": "https://recordings.example.com/12345",
    "disconnection_reason": "user_hangup",
    "sentiment": { "sentiment": "positive", "explanation": "Friendly, helpful tone." },
    "call_summary": "Customer issue resolved.",
    "task_achieved": true
  }
]

Get call details

GET /v1/call/:id

Retrieve full details of one call — transcript, sentiment, summary, credits, and performance metrics.

Path parameters

Name	Type	Required	Description
`id`	string	Yes	ID of the call.

Example request

curl "https://api.hanc.ai/v1/call/507f1f77bcf86cd799439011" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "call_type": "phone",
  "agent_id": "507f1f77bcf86cd799439042",
  "agent_name": "Customer Support Agent",
  "call_status": "success",
  "call_from": "+12345678900",
  "call_to": "+12345678911",
  "direction": "inbound",
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "recording_url": "https://recordings.example.com/12345",
  "transcription": [
    { "speaker": "agent", "content": "Hello, how can I help?", "timestamp": 1703302407333 },
    { "speaker": "user", "content": "I need help with my order.", "timestamp": 1703302410000 }
  ],
  "sentiment": { "sentiment": "positive", "explanation": "Friendly, helpful tone." },
  "call_summary": "Customer issue resolved.",
  "task_achieved": true,
  "call_credits_details": {
    "phone_call_credits": 1,
    "web_call_credits": 0,
    "text_message_credits": 0,
    "call_forwarding_credits": 0
  }
}

Returns 404 if the call does not exist or isn't owned by your account.

General metrics

GET /v1/call/general-metrics

Aggregate totals (call count, total and average duration) over a date range.

Query parameters

Name	Type	Required	Description
`date_from`	string	Yes	Start date (`YYYY-MM-DD`).
`date_to`	string	Yes	End date (`YYYY-MM-DD`, inclusive).
`agent_id` / `agent_ids`	string(s)	No	Restrict to one or more agents.
`customer_id`	string	No	Filter by customer.
`workspace_id`	string	No	Filter by workspace.
`direction` / `call_status` / `call_type`	enum[]	No	Same filters as List calls.

Omitting date_from or date_to returns 400 Bad Request.

Example request

curl -G "https://api.hanc.ai/v1/call/general-metrics" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31"

Example response — 200 OK

{ "total_calls": 128, "total_duration": 45230, "average_duration": 353 }

Daily metrics

GET /v1/call/daily-metrics

Per‑day total call duration over a date range — ideal for charting trends.

Query parameters — same as General metrics (date_from/date_to required, plus the optional agent/customer/workspace/direction/status/type filters).

Example request

curl -G "https://api.hanc.ai/v1/call/daily-metrics" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-07"

Example response — 200 OK

[
  { "date": "2026-05-01", "total_duration": 5400 },
  { "date": "2026-05-02", "total_duration": 7320 },
  { "date": "2026-05-03", "total_duration": 0 }
]

Sentiment statistics

GET /v1/call/sentiment-stats

Counts of calls by sentiment for one agent over a date range.

Query parameters

Name	Type	Required	Description
`agent_id`	string	Yes	Agent to report on.
`date_from`	string	Yes	Start date.
`date_to`	string	Yes	End date (inclusive).

Example request

curl -G "https://api.hanc.ai/v1/call/sentiment-stats" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "agent_id=507f1f77bcf86cd799439042" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31"

Example response — 200 OK

{ "positive": 84, "negative": 12, "neutral": 32 }

Costs breakdown

GET /v1/call/costs-breakdown

Cost/usage breakdown (calls, minutes, credits, tokens, per‑model detail) grouped by user, agent, or workspace.

Query parameters

Name	Type	Required	Description
`date_from`	string	Yes	Start date.
`date_to`	string	Yes	End date (inclusive).
`group_by`	enum	No	`user` (default), `agent`, or `workspace`.
`customer_id`	string	No	Filter by customer (agency access).
`workspace_id`	string	No	Filter by workspace.

Example request

curl -G "https://api.hanc.ai/v1/call/costs-breakdown" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31" \
  --data-urlencode "group_by=agent"

Example response — 200 OK

{
  "breakdown": [
    {
      "agent_id": "507f1f77bcf86cd799439042",
      "agent_name": "Customer Support Agent",
      "total_calls": 64,
      "total_duration_minutes": 380,
      "credits": { "phone_call": 60, "web_call": 4, "text_message": 0, "call_forwarding": 1, "total": 65 },
      "tokens": { "input": 920000, "output": 120000, "total": 1040000 }
    }
  ],
  "totals": { "total_calls": 64, "total_duration_minutes": 380, "total_credits": 65, "total_tokens": 1040000 },
  "period": { "from": 1746057600000, "to": 1748735999999 }
}

Export calls (CSV)

GET /v1/call/list/export

Download every call in a date range as a CSV file (with per‑call, per‑model token detail).

Query parameters

Name	Type	Required	Description
`date_from`	string	Yes	Start date.
`date_to`	string	Yes	End date (inclusive).

Response — a CSV file (Content-Type: text/csv), served as an attachment named call-details_<date_from>_<date_to>.csv.

Example request

curl -G "https://api.hanc.ai/v1/call/list/export" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31" \
  -o call-details.csv

Export costs (CSV)

GET /v1/call/costs-breakdown/export

Download the costs breakdown as a CSV file.

Query parameters — same as Costs breakdown (date_from/date_to required; optional group_by, customer_id, workspace_id).

Response — a CSV file served as costs-breakdown_<date_from>_<date_to>.csv.

Example request

curl -G "https://api.hanc.ai/v1/call/costs-breakdown/export" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31" \
  --data-urlencode "group_by=agent" \
  -o costs-breakdown.csv

Make a phone call

POST /v1/call/make-phone-call

Place an outbound phone call from one of your agents.

Request body

Field	Type	Required	Description
`agent_id`	string	Yes	Agent that will place the call.
`from_number`	string	Yes	Caller ID in E.164 format (e.g. `+1234567890`).
`to_number`	string	Yes	Recipient phone number.
`custom_data`	object	No	Arbitrary data attached to the call.
`dynamic_context`	object	No	Context passed into the conversation (e.g. customer name).

Example request

curl -X POST "https://api.hanc.ai/v1/call/make-phone-call" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "507f1f77bcf86cd799439042",
    "from_number": "+1234567890",
    "to_number": "+19876543210",
    "dynamic_context": { "customer_name": "Jane", "order_id": "12345" }
  }'

Example response — 201 Created

{
  "_id": "507f1f77bcf86cd799439011",
  "call_type": "phone",
  "agent_id": "507f1f77bcf86cd799439042",
  "call_status": "started",
  "call_from": "+1234567890",
  "call_to": "+19876543210",
  "direction": "outbound",
  "start_timestamp": 1703302407333
}

Make a web call

POST /v1/call/make-web-call

Create a browser/WebRTC call session for one of your agents.

Request body

Field	Type	Required	Description
`agent_id`	string	Yes	Agent that will handle the web call.
`custom_data`	object	No	Arbitrary data attached to the call.
`dynamic_context`	object	No	Context passed into the conversation.

Example request

curl -X POST "https://api.hanc.ai/v1/call/make-web-call" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "507f1f77bcf86cd799439042", "dynamic_context": { "topic": "billing" } }'

Example response — 201 Created

{
  "_id": "507f1f77bcf86cd799439077",
  "call_type": "web",
  "agent_id": "507f1f77bcf86cd799439042",
  "call_status": "started",
  "start_timestamp": 1703302407333
}

Agents

Create and manage voice agents, their actions (what they do during a call — send email/SMS/WhatsApp, call your API) and their tools (capabilities such as RAG search, appointment booking, call forwarding, calendar/CRM integrations).

List agents

GET /v1/agent/list

Return all agents owned by your account.

Query parameters

Name	Type	Required	Description
`customer_id`	string	No	Scope to a customer.
`workspace_id`	string	No	Scope to a workspace.

Example request

curl "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "agent_name": "Customer Support Agent",
    "llm_id": "60d21b4667d0d8992e610c86",
    "voice": { "voice_id": "60d21b4667d0d8992e610c87" },
    "interruption_sensitivity": 1.0,
    "call_settings": { "language": "en-US", "sentiment_analysis": false, "call_summary": false },
    "status": "active",
    "workspace_id": "60d21b4667d0d8992e610c87",
    "knowledge_base": ["60d21b4667d0d8992e610c89"]
  }
]

Get an agent

GET /v1/agent/:id

Return a single agent.

Path parameters

Name	Type	Required	Description
`id`	string	Yes	Agent ID.

Example request

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

Returns the agent object (same shape as one item from List agents), or 404 if not found.

Create an agent

POST /v1/agent

Create a new agent. Only agent_name and llm_id are required — everything else is optional and falls back to sensible defaults.

Query parameters — optional customer_id, workspace_id to associate the new agent.

Request body

Field	Type	Required	Description
`agent_name`	string	Yes	Display name.
`llm_id`	string	Yes	ID of the LLM that backs the agent.
`voice`	object	No	`{ "voice_id": "<id>" }`.
`interruption_sensitivity`	number	No	How easily the agent yields when interrupted (e.g. `0.5`).
`call_settings`	object	No	Language, reminders, silence timeout, sentiment analysis, call summary, `max_call_duration_minutes` (1–15).
`data_retrieval`	object[]	No	Fields the agent collects during a call.
`webhook_url`	string	No	URL notified of agent events.
`is_data_collection_active`	boolean	No	Enable the data‑collection form.

Example request

curl -X POST "https://api.hanc.ai/v1/agent" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Customer Support Agent",
    "llm_id": "507f1f77bcf86cd799439033",
    "voice": { "voice_id": "507f1f77bcf86cd799439035" },
    "interruption_sensitivity": 0.5,
    "call_settings": { "language": "en-US", "max_call_duration_minutes": 10 }
  }'

Example response — 201 Created (the created agent object).

Update an agent

PATCH /v1/agent/:id

Partially update an agent. All body fields are optional — send only what you want to change.

Path parameters — id (agent ID).

Request body — any subset of the create fields, plus folder, status (e.g. active), is_customer_memory_active, widget_settings, callback_settings. Inside call_settings you can also set recording_enabled, stt_languages (up to 4 BCP‑47 codes), and max_call_duration_minutes.

Example request

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_name": "Support Agent v2", "call_settings": { "language": "en-GB", "recording_enabled": false } }'

Example response — 200 OK (the updated agent object).

Delete an agent

DELETE /v1/agent/:id

Delete an agent.

Example request

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 204 No Content (empty body).

Agent call statistics

GET /v1/agent/:id/call-stats

Per‑day call counts for one agent over a date range.

Path parameters — id (agent ID).

Query parameters

Name	Type	Required	Description
`date_from`	string	Yes	Start date (`YYYY-MM-DD`).
`date_to`	string	Yes	End date (`YYYY-MM-DD`).

Example request

curl -G "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/call-stats" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "date_from=2026-05-01" \
  --data-urlencode "date_to=2026-05-31"

Example response — 200 OK

[
  { "date": "2026-05-28", "total_calls": 10 },
  { "date": "2026-05-29", "total_calls": 4 }
]

List agent templates

GET /v1/agent/agent_template/list

Return the catalog of pre‑built agent templates you can clone. No parameters.

Example request

curl "https://api.hanc.ai/v1/agent/agent_template/list" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "icon_url": "https://example.com/icon.png",
    "description": "A ready-made receptionist agent.",
    "agent": { "agent_name": "Receptionist", "call_settings": { "language": "en-US" } },
    "llm": { "model": "gpt-4o-mini", "begin_message": "Hello, how can I assist you today?" }
  }
]

Agent actions

Actions are things an agent performs during a call. Supported action_type values: send_email, send_sms, send_whatsapp, api_call. The settings object shape depends on the type.

List actions

GET /v1/agent/:id/actions

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions" \
  -H "x-api-key: YOUR_API_KEY"

Returns an array of action objects.

Add an action

POST /v1/agent/:id/actions

Request body

Field	Type	Required	Description
`action_type`	enum	Yes	`send_email`, `send_sms`, `send_whatsapp`, or `api_call`.
`settings`	object	Yes	Type‑specific configuration.
`is_active`	boolean	No	Defaults to `true`.

Example request

curl -X POST "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "send_email",
    "settings": {
      "name": "Welcome Email",
      "subject": "Welcome!",
      "message": "Thank you for joining us.",
      "direct_recipients": ["user@example.com"]
    }
  }'

Example response — 201 Created

{
  "_id": "60f5b1a8d1b9f7c1d0c0a6c6",
  "agent_id": "60d21b4667d0d8992e610c85",
  "action_type": "send_email",
  "settings": { "name": "Welcome Email", "subject": "Welcome!", "message": "Thank you for joining us.", "direct_recipients": ["user@example.com"] },
  "is_active": true
}

Update an action

PATCH /v1/agent/:id/actions/:agentActionId

Update an attached action's settings and/or is_active. Both body fields are optional.

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Returns 200 OK with the updated action object.

Delete an action

DELETE /v1/agent/:id/actions/:agentActionId

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY"

Returns 204 No Content.

Agent tools

Tools give an agent extra capabilities. Supported tool_type values: api_rag, appointment_booking, call_forwarding, end_call, google_calendar, hubspot_crm, outlook_calendar, agent_transfer, mcp. The settings object shape depends on the type.

List tools

GET /v1/agent/:id/tools

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools" \
  -H "x-api-key: YOUR_API_KEY"

Returns an array of tool objects.

Add a tool

POST /v1/agent/:id/tools

Request body

Field	Type	Required	Description
`tool_type`	enum	Yes	One of the supported tool types above.
`settings`	object	Yes	Type‑specific configuration.
`is_active`	boolean	No	Defaults to `true`.

Example request

curl -X POST "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_type": "call_forwarding",
    "settings": { "name": "Transfer to human", "phone_number": "+1234567890" }
  }'

Example response — 201 Created

{
  "_id": "60f5b1a8d1b9f7c1d0c0a6c6",
  "agent_id": "60d21b4667d0d8992e610c85",
  "tool_type": "call_forwarding",
  "settings": { "name": "Transfer to human", "phone_number": "+1234567890" },
  "is_active": true
}

Update a tool

PATCH /v1/agent/:id/tools/:agentToolId

Update an attached tool's settings and/or is_active (both optional).

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Returns 200 OK with the updated tool object.

Delete a tool

DELETE /v1/agent/:id/tools/:agentToolId

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools/60f5b1a8d1b9f7c1d0c0a6c6" \
  -H "x-api-key: YOUR_API_KEY"

Returns 204 No Content.

Knowledge Base

Upload documents your agents can search during a call, and control which agents use each knowledge base. File uploads use multipart/form-data.

List knowledge bases

GET /v1/knowledge-base/list

Query parameters — optional customer_id, workspace_id.

curl "https://api.hanc.ai/v1/knowledge-base/list" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "knowledge_base_name": "Company Policies",
    "knowledge_base_description": "Refund, shipping and warranty policies.",
    "files": [
      { "_id": "60d21b4667d0d8992e610c90", "file_name": "policies.pdf", "file_size": 2048000, "uploaded_at": "2026-05-24T07:34:23.980Z" }
    ],
    "agent_names": ["Sales Agent", "Support Bot"]
  }
]

Create a knowledge base

POST /v1/knowledge-base

Create a knowledge base together with its first file. This is a multipart/form-data request — there is no body‑only "create".

Query parameters — optional customer_id, workspace_id.

Form fields

Field	Type	Required	Description
`file`	file	Yes	The first document (e.g. a PDF).
`name`	string	Yes	Knowledge base name (1–100 chars).
`description`	string	Yes	Description (1–300 chars).
`folder`	string	No	Folder/category label (0–50 chars).

Example request

curl -X POST "https://api.hanc.ai/v1/knowledge-base" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./policies.pdf" \
  -F "name=Company Policies" \
  -F "description=Refund, shipping and warranty policies." \
  -F "folder=Sales"

Example response — 200 OK (the created knowledge base, same shape as a list item).

Add a single file

POST /v1/knowledge-base/:id/file

Add one file to an existing knowledge base. Multipart field name: file.

curl -X POST "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/file" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@./addendum.pdf"

Returns 200 OK with the updated knowledge base.

Add multiple files

POST /v1/knowledge-base/:id/files

Add several files at once. Multipart field name: files (repeat for each file). Optional customer_id, workspace_id query params.

curl -X POST "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/files" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "files=@./doc1.pdf" \
  -F "files=@./doc2.pdf"

Returns 200 OK with the updated knowledge base.

Delete file(s)

DELETE /v1/knowledge-base/:id/file

Remove one or more files by ID. Despite the singular path, the body takes an array.

Request body

Field	Type	Required	Description
`file_ids`	string[]	Yes	Non‑empty array of file IDs to delete.

curl -X DELETE "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/file" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_ids": ["60c72b2f9b1e8b001c8e4d3a", "60c72b2f9b1e8b001c8e4d3b"] }'

Returns 200 OK.

Assign agents

PUT /v1/knowledge-base/:id/agents

Set (replace) the full list of agents that use this knowledge base.

Request body

Field	Type	Required	Description
`agent_ids`	string[]	Yes	Agent IDs that should use this knowledge base.

curl -X PUT "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/agents" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_ids": ["60d21b4667d0d8992e610c85"] }'

Returns 200 OK.

Phone Numbers

List your numbers, find numbers available to buy, purchase one, import numbers from a connected Twilio account, or connect a number to a SIP trunk.

List phone numbers

GET /v1/phone-number/list

Query parameters — all optional: inbound_agent_id, outbound_agent_id, customer_id, workspace_id (and user_id, defaulting to you).

curl "https://api.hanc.ai/v1/phone-number/list" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "phone_number": "+1234567890",
    "formatted_number": "+1 (234) 567-8900",
    "country": "US",
    "provider": "twilio",
    "status": "active",
    "inbound_agent_id": "64bfb7b3f3d9ab3f1e2c109c",
    "inbound_agent_name": "Receptionist"
  }
]

Available numbers

GET /v1/phone-number/available

List numbers available to purchase for a country.

Query parameters

Name	Type	Required	Description
`country_code`	string	No	ISO country code (default `US`), e.g. `DE`, `AT`, `CH`.
`area_code`	string	No	Numeric area‑code filter.

curl -G "https://api.hanc.ai/v1/phone-number/available" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "country_code=US" \
  --data-urlencode "area_code=415"

Example response — 200 OK

[
  { "phone_number": "+14155550100", "formatted_number": "+1 (415) 555-0100", "country": "US", "area_code": "415", "setup_fee": 2, "subscription": 2, "currency": "EUR" }
]

Buy a number

POST /v1/phone-number/buy

Purchase a specific number. Optional customer_id, workspace_id query params.

Request body

Field	Type	Required	Description
`phone_number`	string	Yes	The number to buy (E.164).
`country_code`	string	Yes	Country of the number (e.g. `US`).

curl -X POST "https://api.hanc.ai/v1/phone-number/buy" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100", "country_code": "US" }'

Example response — 200 OK

{
  "message": "Phone number purchased successfully!",
  "phone_number": { "_id": "507f1f77bcf86cd799439011", "phone_number": "+14155550100", "country": "US", "provider": "twilio", "status": "active" }
}

Import from Twilio

POST /v1/phone-number/import-twilio

Import numbers from a connected Twilio account. Optional customer_id, workspace_id query params.

Request body

Field	Type	Required	Description
`sid`	string	Yes	Twilio Account SID (`AC…`).

curl -X POST "https://api.hanc.ai/v1/phone-number/import-twilio" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }'

Example response — 200 OK (the imported phone‑number record).

Connect to SIP

PATCH /v1/phone-number/connect-to-sip

Connect an existing number to a SIP trunk.

Request body

Field	Type	Required	Description
`phone_number`	string	Yes	The number to connect (E.164).

curl -X PATCH "https://api.hanc.ai/v1/phone-number/connect-to-sip" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+1234567890" }'

Returns 200 OK (empty body).

Voices

List voices

GET /v1/voice/list

List available voices. Filter by language or provider, and include a customer's private clones.

Query parameters

Name	Type	Required	Description
`language`	string	No	Filter by language, e.g. `?language=de`.
`provider`	string	No	`11-Labs`, `openai`, `qwen`, or `azure`.
`customer_id`	string	No	Also include this customer's private voice clones.

curl -G "https://api.hanc.ai/v1/voice/list" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "language=de"

Example response — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "voice_id": "voice_12345",
    "name": "Emma",
    "gender": "female",
    "accent": "British",
    "languages": ["english", "spanish"],
    "provider": "11-Labs",
    "sample_url": "https://example.com/sample.mp3"
  }
]

Subscription

Subscription details

GET /v1/subscription

Return your current subscription, including credit balances and top‑up settings.

curl "https://api.hanc.ai/v1/subscription" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

{
  "_id": "507f191e810c19729de860ea",
  "payment_plan_id": "507f191e810c19729de860ec",
  "currency": "EUR",
  "package_credits": 1000,
  "package_credits_used": 100,
  "auto_top_up_enabled": false,
  "top_up_amount": 50,
  "extra_credits_payed": 1000,
  "extra_credits_used": 100,
  "billing_cycle": "monthly",
  "next_credit_reset": "2026-06-15T03:00:00.000Z",
  "is_cancelled": false
}

Returns 404 if no subscription record exists.

Configure auto top‑up

PATCH /v1/subscription/auto-top-up

Enable or disable automatic credit top‑up.

Request body

Field	Type	Required	Description
`enabled`	boolean	Yes	Turn auto top‑up on or off.
`amount`	number	No	Amount to top up by (20–1000). Set when enabling.

curl -X PATCH "https://api.hanc.ai/v1/subscription/auto-top-up" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "amount": 50 }'

Returns 200 OK with the updated subscription.

Set top‑up amount

PATCH /v1/subscription/top-up-amount

Update the configured top‑up amount.

Request body

Field	Type	Required	Description
`top_up_amount`	number	Yes	New amount (1–100).

curl -X PATCH "https://api.hanc.ai/v1/subscription/top-up-amount" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "top_up_amount": 10 }'

Returns 200 OK with the updated subscription.

Customers

Manage the customers under your agency. These endpoints require your account to belong to an agency.

List customers

GET /v1/customer/list

curl "https://api.hanc.ai/v1/customer/list" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

[
  {
    "_id": "60d21b4667d0d8992e610c85",
    "email": "customer@example.com",
    "name": "John Doe",
    "account_status": "active",
    "agents_count": 3
  }
]

Customer details

GET /v1/customer/:id

curl "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

Returns the customer object, or 404 if not found.

Create a customer

POST /v1/customer

Request body

Field	Type	Required	Description
`email`	string	Yes	Customer login email.
`initial_password`	string	Yes	Initial password (8–128 chars).
`name`	string	Yes	Account/company name.
`user_full_name`	string	Yes	Full name of the customer user.
`visibility`	object	No	Per‑section visibility flags.
`opt_out_promotions`	boolean	No	Opt the customer out of promo messaging.

curl -X POST "https://api.hanc.ai/v1/customer" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "initial_password": "Password123!",
    "name": "Acme Co.",
    "user_full_name": "John Doe"
  }'

Returns 201 Created with the new customer. Returns 400 if the email already exists or your account isn't part of an agency.

Update a customer

PATCH /v1/customer/:id

Request body — all optional: name, email, phone, address.

curl -X PATCH "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corporation", "phone": "+1234567890" }'

Returns 200 OK with the updated customer.

Delete a customer

DELETE /v1/customer/:id

curl -X DELETE "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
  -H "x-api-key: YOUR_API_KEY"

Example response

{ "message": "Customer deleted successfully" }

Workspaces

Group agents, numbers, and knowledge bases into workspaces and manage their members.

List workspaces

GET /v1/workspaces/list

Optional customer_id query param.

curl "https://api.hanc.ai/v1/workspaces/list" \
  -H "x-api-key: YOUR_API_KEY"

Example response — 200 OK

[
  {
    "_id": "64b1f2d2f3d92c5b8c5e1e22",
    "name": "Workspace A",
    "description": "For the A team.",
    "owner_user_id": "64b1f2d2f3d92c5b8c5e1e10",
    "members": [
      { "user_id": "64b1f2d2f3d92c5b8c5e1e11", "full_name": "John Doe", "email": "john.doe@example.com" }
    ]
  }
]

Create a workspace

POST /v1/workspaces

Request body

Field	Type	Required	Description
`name`	string	Yes	Workspace name (2–100 chars).
`description`	string	No	Description (0–500 chars).

curl -X POST "https://api.hanc.ai/v1/workspaces" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Development Team", "description": "For the dev team." }'

Returns 201 Created with the workspace.

Workspace details

GET /v1/workspaces/:id

curl "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
  -H "x-api-key: YOUR_API_KEY"

Returns the workspace object.

Update a workspace

PATCH /v1/workspaces/:id

Request body — name (2–100) and/or description (0–500).

curl -X PATCH "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed Workspace" }'

Returns 200 OK with the updated workspace.

Delete a workspace

DELETE /v1/workspaces/:id

curl -X DELETE "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
  -H "x-api-key: YOUR_API_KEY"

Example response

{ "message": "Workspace deleted successfully" }

Invite a member

POST /v1/workspaces/:workspace_id/invite-member

Request body

Field	Type	Required	Description
`email`	string	Yes	Email of the user to invite.

curl -X POST "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22/invite-member" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "teammate@example.com" }'

Returns 201 Created with the workspace (the new member appears in members).

Remove a member

DELETE /v1/workspaces/:workspace_id/remove-member

Request body

Field	Type	Required	Description
`email`	string	Yes	Email of the member to remove.

curl -X DELETE "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22/remove-member" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "teammate@example.com" }'

Returns 200 OK with the updated workspace.

What's not available via API

Some operations are only available through the dashboard:

Feature	Reason
API key management	Security — keys can't create other keys
Phone number setup	Requires interactive setup
Google Calendar integration	Requires interactive authorization
Billing & payments	Managed through the dashboard

Need help?

Contact our support team at support@hanc.ai for API-related questions.

Quick overview​

Authentication​

Conventions​

Endpoint index​

Calls​

Agents​

Knowledge Base​

Phone Numbers​

Voices · Subscription · Customers · Workspaces​

Calls

List calls​

Get call details​

General metrics​

Daily metrics​

Sentiment statistics​

Costs breakdown​

Export calls (CSV)​

Export costs (CSV)​

Make a phone call​

Make a web call​

Agents

List agents​

Get an agent​

Create an agent​

Update an agent​

Delete an agent​

Agent call statistics​

List agent templates​

Agent actions​

List actions​

Add an action​

Update an action​

Delete an action​

Agent tools​

List tools​

Add a tool​

Update a tool​

Delete a tool​

Knowledge Base

List knowledge bases​

Create a knowledge base​

Add a single file​

Add multiple files​

Delete file(s)​

Assign agents​

Phone Numbers

List phone numbers​

Available numbers​

Buy a number​

Import from Twilio​

Connect to SIP​

Voices

List voices​

Subscription

Subscription details​

Configure auto top‑up​

Set top‑up amount​

Customers

List customers​

Customer details​

Create a customer​

Update a customer​

Delete a customer​

Workspaces

List workspaces​

Create a workspace​

Workspace details​

Update a workspace​

Delete a workspace​

Invite a member​

Remove a member​

What's not available via API​

Need help?​

Quick overview

Authentication

Conventions

Endpoint index

Calls

Agents

Knowledge Base

Phone Numbers

Voices · Subscription · Customers · Workspaces

List calls

Get call details

General metrics

Daily metrics

Sentiment statistics

Costs breakdown

Export calls (CSV)

Export costs (CSV)

Make a phone call

Make a web call

List agents

Get an agent

Create an agent

Update an agent

Delete an agent

Agent call statistics

List agent templates

Agent actions

List actions

Add an action

Update an action

Delete an action

Agent tools

List tools

Add a tool

Update a tool

Delete a tool

List knowledge bases

Create a knowledge base

Add a single file

Add multiple files

Delete file(s)

Assign agents

List phone numbers

Available numbers

Buy a number

Import from Twilio

Connect to SIP

List voices

Subscription details

Configure auto top‑up

Set top‑up amount

List customers

Customer details

Create a customer

Update a customer

Delete a customer

List workspaces

Create a workspace

Workspace details

Update a workspace

Delete a workspace

Invite a member

Remove a member

What's not available via API

Need help?