{ "openapi": "3.1.0", "info": { "title": "Voxiora REST API", "version": "1.0.0", "summary": "Calls, transcripts, appointments, contacts, tasks, SMS and outbound calls of a Voxiora AI phone assistant account.", "description": "Voxiora is an AI phone assistant (receptionist) for businesses. This API reads and manages one account's data.\n\nAuthentication: send an API key (`Authorization: Bearer tf_live_…`, created in the dashboard → Developers → API keys) or an OAuth 2.0 access token from the client_credentials grant (client_id = API key id, client_secret = API key).\n\nLists use cursor pagination: pass `next_cursor` as `cursor`. Rate limits depend on the plan; see the X-RateLimit-* response headers.\n\nThe same operations are available to AI agents over MCP at https://voxiora.com/api/mcp.", "contact": { "name": "AI AGENT HUB P.S.A.", "email": "support@aiagenthub.pl", "url": "https://voxiora.com/en/developers" } }, "externalDocs": { "description": "Developer documentation", "url": "https://voxiora.com/en/developers" }, "servers": [ { "url": "https://voxiora.com/api/v1", "description": "Production" } ], "tags": [ { "name": "account" }, { "name": "assistants" }, { "name": "phone-numbers" }, { "name": "calls" }, { "name": "appointments" }, { "name": "contacts" }, { "name": "tasks" }, { "name": "messages" } ], "security": [ { "bearerAuth": [] }, { "oauth2": [] } ], "paths": { "/me": { "get": { "operationId": "me", "summary": "Get the current account", "description": "Returns the account the API key belongs to. Handy as a “test connection” call.\n\nWorks with any valid API key or access token.", "tags": [ "account" ], "security": [ { "bearerAuth": [] }, { "oauth2": [] } ], "responses": { "200": { "description": "Get the current account", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "account", "id": "1f2e3d4c-5b6a-4789-8a7b-6c5d4e3f2a1b", "name": "Smile Dental", "timezone": "Europe/Warsaw", "locale": "en", "country": "PL", "currency": "PLN", "status": "active", "plan": { "id": "team", "billing_cycle": "month", "trial_ends_at": null, "period_start": "2026-10-01T00:00:00Z", "period_end": "2026-11-01T00:00:00Z", "recording_history_days": 365 }, "minutes": { "included": 3000, "extra": 100, "total": 3100, "used": 412.5, "remaining": 2687.5 }, "api_key_id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d", "scopes": [ "read:calls", "read:appointments", "read:contacts", "read:tasks" ], "limits": { "plan": "team", "requests_per_minute": 180, "requests_per_day": 50000, "max_api_keys": 10, "max_webhook_endpoints": 10 } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/assistants": { "get": { "operationId": "listAssistants", "summary": "List assistants", "description": "Your assistants with their language, status and assigned phone numbers. Use an id as assistant_id when filtering calls.\n\nWorks with any valid API key or access token.", "tags": [ "assistants" ], "security": [ { "bearerAuth": [] }, { "oauth2": [] } ], "responses": { "200": { "description": "List assistants", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "object": "assistant", "name": "Nova", "language": "en", "languages": [ "en", "pl" ], "status": "live", "recording_enabled": true, "phone_numbers": [ "+48221234567" ], "created_at": "2026-08-01T10:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/assistants/{id}": { "get": { "operationId": "getAssistant", "summary": "Retrieve an assistant", "description": "One assistant with language, status and phone numbers. With the read:assistants (or write:assistants) scope it also returns the prompt: instructions, greeting, company_profile and updated_at.\n\nWorks with any valid API key or access token.", "tags": [ "assistants" ], "security": [ { "bearerAuth": [] }, { "oauth2": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The assistant ID." }, "description": "The assistant ID." } ], "responses": { "200": { "description": "Retrieve an assistant", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "object": "assistant", "name": "Nova", "language": "en", "languages": [ "en", "pl" ], "status": "live", "recording_enabled": true, "phone_numbers": [ "+48221234567" ], "created_at": "2026-08-01T10:00:00Z", "instructions": "## Conversation style\n- Speak briefly, one question at a time.\n\n## Ending the call\n- Always offer a free 15-minute consultation.", "greeting": "Hi, this is Nova, the AI assistant of Smile Dental. How can I help?", "company_profile": "Smile Dental is a family dental clinic in Warsaw. Open Mon–Fri 8:00–20:00.", "updated_at": "2026-10-09T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateAssistant", "summary": "Update the assistant's prompt", "description": "Changes the instructions, greeting or company profile. Omitted fields stay unchanged. Same limits as the dashboard: instructions up to 40,000 characters, company profile up to 10,000, greeting 5–600 characters and it must say the caller is talking to an AI (otherwise 400 with code ai_disclosure). Every change is saved in the assistant's version history (source API) and applies from the next call. The platform's honesty rules (AI disclosure, recording notice) always apply on top of your instructions.\n\nRequired scope: `write:assistants`.", "tags": [ "assistants" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:assistants" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The assistant ID." }, "description": "The assistant ID." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "instructions": { "type": "string", "description": "The assistant's instructions (system prompt), up to 40,000 characters. Replaces the whole text." }, "greeting": { "type": "string", "description": "The first sentence of every call, 5–600 characters. Must say the caller is talking to an AI assistant." }, "company_profile": { "type": "string", "description": "Facts about the business the assistant uses in calls, up to 10,000 characters." } }, "required": [] }, "example": { "instructions": "## Conversation style\n- Speak briefly, one question at a time.\n\n## Ending the call\n- Always offer a free 15-minute consultation." } } } }, "responses": { "200": { "description": "Update the assistant's prompt", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "object": "assistant", "name": "Nova", "language": "en", "languages": [ "en", "pl" ], "status": "live", "recording_enabled": true, "phone_numbers": [ "+48221234567" ], "created_at": "2026-08-01T10:00:00Z", "instructions": "## Conversation style\n- Speak briefly, one question at a time.\n\n## Ending the call\n- Always offer a free 15-minute consultation.", "greeting": "Hi, this is Nova, the AI assistant of Smile Dental. How can I help?", "company_profile": "Smile Dental is a family dental clinic in Warsaw. Open Mon–Fri 8:00–20:00.", "updated_at": "2026-10-09T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/phone-numbers": { "get": { "operationId": "listPhoneNumbers", "summary": "List phone numbers", "description": "Your account's phone numbers with country, type, status and the assistant that answers them.\n\nWorks with any valid API key or access token.", "tags": [ "phone-numbers" ], "security": [ { "bearerAuth": [] }, { "oauth2": [] } ], "responses": { "200": { "description": "List phone numbers", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "4d3c2b1a-0f9e-4d8c-b7a6-958473625140", "object": "phone_number", "number": "+48221234567", "country": "PL", "kind": "geo", "status": "assigned", "assistant_id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "assigned_at": "2026-08-01T10:05:00Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/calls": { "get": { "operationId": "listCalls", "summary": "List calls", "description": "Calls newest first, without transcripts. Demo calls are never included.\n\nRequired scope: `read:calls`.", "tags": [ "calls" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:calls" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items to return, 1–100 (default 25)." }, "description": "Number of items to return, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous page." }, "description": "The next_cursor value from the previous page." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "in_progress", "completed", "failed", "missed" ], "description": "Filter by status." }, "description": "Filter by status." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound", "widget", "web" ], "description": "Filter by direction." }, "description": "Filter by direction." }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "booked", "transferred", "message", "info", "spam", "other" ], "description": "Filter by outcome." }, "description": "Filter by outcome." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only calls that started at or after this time (ISO 8601)." }, "description": "Only calls that started at or after this time (ISO 8601)." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only calls that started before this time (ISO 8601)." }, "description": "Only calls that started before this time (ISO 8601)." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only items linked to this contact." }, "description": "Only items linked to this contact." }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only calls handled by this assistant." }, "description": "Only calls handled by this assistant." } ], "responses": { "200": { "description": "List calls", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "object": "call", "assistant_id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "phone_number_id": "4d3c2b1a-0f9e-4d8c-b7a6-958473625140", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "direction": "inbound", "status": "completed", "from": "+48601234567", "to": "+48221234567", "started_at": "2026-10-01T09:14:03Z", "ended_at": "2026-10-01T09:17:41Z", "duration_sec": 218, "summary": "Anna Kowalska booked a first consultation for Friday 10:00.", "outcome": "booked", "sentiment": "positive", "tags": [ "new-customer" ], "has_recording": true, "end_reason": "caller_hangup", "page_url": null, "page_title": null, "continued_from": null, "callback_id": null, "external_id": null, "outreach": null, "callback_return": false } ], "has_more": true, "next_cursor": "MjAyNi0xMC0wMVQwOToxNDowM1o" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/calls/{id}": { "get": { "operationId": "getCall", "summary": "Retrieve a call", "description": "One call with the full transcript and the appointments booked during it.\n\nRequired scope: `read:calls`.", "tags": [ "calls" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:calls" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The call ID." }, "description": "The call ID." } ], "responses": { "200": { "description": "Retrieve a call", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "object": "call", "assistant_id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "phone_number_id": "4d3c2b1a-0f9e-4d8c-b7a6-958473625140", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "direction": "inbound", "status": "completed", "from": "+48601234567", "to": "+48221234567", "started_at": "2026-10-01T09:14:03Z", "ended_at": "2026-10-01T09:17:41Z", "duration_sec": 218, "summary": "Anna Kowalska booked a first consultation for Friday 10:00.", "outcome": "booked", "sentiment": "positive", "tags": [ "new-customer" ], "has_recording": true, "end_reason": "caller_hangup", "page_url": null, "page_title": null, "continued_from": null, "callback_id": null, "external_id": null, "outreach": null, "callback_return": false, "transcript": [ { "role": "assistant", "text": "Hi, this is Nova, the AI assistant of Smile Dental. How can I help?", "at": 0.4 }, { "role": "caller", "text": "I'd like to book a consultation this week.", "at": 4.1 } ], "caller_spoke": true, "caller_words": 6, "appointments": [ { "id": "c3d2e1f0-a9b8-4c7d-8e6f-5a4b3c2d1e0f", "object": "appointment", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "customer_email": "anna.kowalska@example.com", "service": "First consultation", "starts_at": "2026-10-03T08:00:00Z", "ends_at": "2026-10-03T08:30:00Z", "status": "booked", "external_id": "google:7h3k9s2l1m0n", "created_at": "2026-10-01T09:16:20Z" } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/calls/{id}/recording": { "get": { "operationId": "getCallRecording", "summary": "Get a call recording", "description": "Signed links, valid for 1 hour, to play and download the call's MP3 recording (stereo: caller on the left, assistant on the right). A recording older than your plan's recording history returns 403 plan_required with recording_history_days; a call without a recording returns 404.\n\nRequired scope: `read:calls`.", "tags": [ "calls" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:calls" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The call ID." }, "description": "The call ID." } ], "responses": { "200": { "description": "Get a call recording", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "recording", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "format": "mp3", "duration_sec": 217, "channels": { "left": "caller", "right": "assistant" }, "url": "https://…/storage/v1/object/sign/telofia-recordings/…?token=…", "download_url": "https://…/storage/v1/object/sign/telofia-recordings/…?token=…&download=call-2026-10-01-1114.mp3", "expires_at": "2026-10-01T10:20:00Z", "history_days": 365 } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/appointments": { "get": { "operationId": "listAppointments", "summary": "List appointments", "description": "Upcoming appointments in start order (from now by default).\n\nRequired scope: `read:appointments`.", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:appointments" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items to return, 1–100 (default 25)." }, "description": "Number of items to return, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous page." }, "description": "The next_cursor value from the previous page." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Start of the range (ISO 8601). Defaults to now." }, "description": "Start of the range (ISO 8601). Defaults to now." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "End of the range (ISO 8601)." }, "description": "End of the range (ISO 8601)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "booked", "canceled", "done", "no_show" ], "description": "Filter by status." }, "description": "Filter by status." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only items linked to this contact." }, "description": "Only items linked to this contact." }, { "name": "call_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only items from this call." }, "description": "Only items from this call." } ], "responses": { "200": { "description": "List appointments", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "c3d2e1f0-a9b8-4c7d-8e6f-5a4b3c2d1e0f", "object": "appointment", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "customer_email": "anna.kowalska@example.com", "service": "First consultation", "starts_at": "2026-10-03T08:00:00Z", "ends_at": "2026-10-03T08:30:00Z", "status": "booked", "external_id": "google:7h3k9s2l1m0n", "created_at": "2026-10-01T09:16:20Z" } ], "has_more": true, "next_cursor": "MjAyNi0xMC0wMVQwOToxNDowM1o" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/appointments/{id}": { "get": { "operationId": "getAppointment", "summary": "Retrieve an appointment", "description": "One appointment of your account.\n\nRequired scope: `read:appointments`.", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:appointments" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The appointment ID." }, "description": "The appointment ID." } ], "responses": { "200": { "description": "Retrieve an appointment", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c3d2e1f0-a9b8-4c7d-8e6f-5a4b3c2d1e0f", "object": "appointment", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "customer_email": "anna.kowalska@example.com", "service": "First consultation", "starts_at": "2026-10-03T08:00:00Z", "ends_at": "2026-10-03T08:30:00Z", "status": "booked", "external_id": "google:7h3k9s2l1m0n", "created_at": "2026-10-01T09:16:20Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/appointments/{id}/cancel": { "post": { "operationId": "cancelAppointment", "summary": "Cancel an appointment", "description": "Cancels an upcoming appointment, removes it from the connected Google calendar and sends the appointment.canceled webhook. calendar_sync tells you whether the calendar was updated.\n\nRequired scope: `write:appointments`.", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:appointments" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The appointment ID." }, "description": "The appointment ID." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Optional reason, included in the appointment.canceled webhook." } }, "required": [] }, "example": { "reason": "Customer asked to cancel by e-mail" } } } }, "responses": { "200": { "description": "Cancel an appointment", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c3d2e1f0-a9b8-4c7d-8e6f-5a4b3c2d1e0f", "object": "appointment", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "customer_email": "anna.kowalska@example.com", "service": "First consultation", "starts_at": "2026-10-03T08:00:00Z", "ends_at": "2026-10-03T08:30:00Z", "status": "canceled", "external_id": "google:7h3k9s2l1m0n", "created_at": "2026-10-01T09:16:20Z", "calendar_sync": "synced" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/appointments/{id}/reschedule": { "post": { "operationId": "rescheduleAppointment", "summary": "Reschedule an appointment", "description": "Moves an upcoming appointment to a new time. Fails with 409 if the time overlaps another appointment or a busy time in the connected calendar. Without ends_at the length stays the same. Sends the appointment.rescheduled webhook.\n\nRequired scope: `write:appointments`.", "tags": [ "appointments" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:appointments" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The appointment ID." }, "description": "The appointment ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "starts_at": { "type": "string", "format": "date-time", "description": "New start time, ISO 8601 with a time zone offset." }, "ends_at": { "type": "string", "format": "date-time", "description": "New end time. Defaults to keeping the current length." } }, "required": [ "starts_at" ] }, "example": { "starts_at": "2026-10-06T14:30:00+02:00" } } } }, "responses": { "200": { "description": "Reschedule an appointment", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c3d2e1f0-a9b8-4c7d-8e6f-5a4b3c2d1e0f", "object": "appointment", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "customer_email": "anna.kowalska@example.com", "service": "First consultation", "starts_at": "2026-10-06T12:30:00Z", "ends_at": "2026-10-06T13:00:00Z", "status": "booked", "external_id": "google:7h3k9s2l1m0n", "created_at": "2026-10-01T09:16:20Z", "previous_starts_at": "2026-10-03T08:00:00Z", "previous_ends_at": "2026-10-03T08:30:00Z", "calendar_sync": "synced" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "description": "Your callers, newest first. The assistant remembers them across calls.\n\nRequired scope: `read:contacts`.", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:contacts" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items to return, 1–100 (default 25)." }, "description": "Number of items to return, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous page." }, "description": "The next_cursor value from the previous page." }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string", "description": "Exact phone number in E.164 format, e.g. +48601234567." }, "description": "Exact phone number in E.164 format, e.g. +48601234567." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "description": "Exact email address." }, "description": "Exact email address." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Search by name, part of the phone number or email." }, "description": "Search by name, part of the phone number or email." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string", "description": "Only contacts with this tag, e.g. lead or customer." }, "description": "Only contacts with this tag, e.g. lead or customer." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only items created at or after this time (ISO 8601)." }, "description": "Only items created at or after this time (ISO 8601)." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only items created before this time (ISO 8601)." }, "description": "Only items created before this time (ISO 8601)." } ], "responses": { "200": { "description": "List contacts", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "object": "contact", "phone": "+48601234567", "name": "Anna Kowalska", "name_source": "call", "email": "anna.kowalska@example.com", "email_source": "call", "notes": null, "tags": [ "customer" ], "blocked": false, "calls_count": 3, "last_call_at": "2026-10-01T09:14:03Z", "created_at": "2026-08-12T15:02:11Z" } ], "has_more": true, "next_cursor": "MjAyNi0xMC0wMVQwOToxNDowM1o" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createContact", "summary": "Create a contact", "description": "Adds a contact, for example from your CRM, so the assistant knows the caller's name. Name and email saved through the API are marked manual and the assistant never overwrites them. Returns 409 with contact_id if the phone number already exists. Sends the contact.created webhook.\n\nRequired scope: `write:contacts`.", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:contacts" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "phone": { "type": "string", "description": "Phone number in E.164 format, e.g. +48601234567. One contact per number." }, "name": { "type": [ "string", "null" ], "description": "Full name, up to 120 characters. null clears it." }, "email": { "type": [ "string", "null" ], "description": "Email address. null or an empty string clears it." }, "notes": { "type": [ "string", "null" ], "description": "Internal notes, up to 5,000 characters. null clears them." }, "blocked": { "type": "boolean", "description": "true: the assistant politely ends calls from this number." } }, "required": [ "phone" ] }, "example": { "phone": "+48601234567", "name": "Anna Kowalska", "email": "anna.kowalska@example.com" } } } }, "responses": { "201": { "description": "Create a contact", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "object": "contact", "phone": "+48601234567", "name": "Anna Kowalska", "name_source": "manual", "email": "anna.kowalska@example.com", "email_source": "manual", "notes": null, "tags": [], "blocked": false, "calls_count": 0, "last_call_at": null, "created_at": "2026-10-01T09:20:00Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "summary": "Retrieve a contact", "description": "One contact with name, email, tags, notes and where the name and email came from (call, system or manual).\n\nRequired scope: `read:contacts`.", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:contacts" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The contact ID." }, "description": "The contact ID." } ], "responses": { "200": { "description": "Retrieve a contact", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "object": "contact", "phone": "+48601234567", "name": "Anna Kowalska", "name_source": "call", "email": "anna.kowalska@example.com", "email_source": "call", "notes": null, "tags": [ "customer" ], "blocked": false, "calls_count": 3, "last_call_at": "2026-10-01T09:14:03Z", "created_at": "2026-08-12T15:02:11Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "description": "Changes the name, email, notes or blocked flag. Omitted fields stay unchanged and null clears a field. A changed name or email is marked manual, so the assistant won't overwrite it. The phone number can't be changed.\n\nRequired scope: `write:contacts`.", "tags": [ "contacts" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:contacts" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The contact ID." }, "description": "The contact ID." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ], "description": "Full name, up to 120 characters. null clears it." }, "email": { "type": [ "string", "null" ], "description": "Email address. null or an empty string clears it." }, "notes": { "type": [ "string", "null" ], "description": "Internal notes, up to 5,000 characters. null clears them." }, "blocked": { "type": "boolean", "description": "true: the assistant politely ends calls from this number." } }, "required": [] }, "example": { "name": "Anna Nowak", "notes": "VIP customer" } } } }, "responses": { "200": { "description": "Update a contact", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "object": "contact", "phone": "+48601234567", "name": "Anna Nowak", "name_source": "manual", "email": "anna.kowalska@example.com", "email_source": "call", "notes": "VIP customer", "tags": [ "customer" ], "blocked": false, "calls_count": 3, "last_call_at": "2026-10-01T09:14:03Z", "created_at": "2026-08-12T15:02:11Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/tasks": { "get": { "operationId": "listTasks", "summary": "List tasks", "description": "Callback requests, messages and other tasks from calls, newest first.\n\nRequired scope: `read:tasks`.", "tags": [ "tasks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:tasks" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items to return, 1–100 (default 25)." }, "description": "Number of items to return, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous page." }, "description": "The next_cursor value from the previous page." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "done", "dismissed" ], "description": "Filter by status." }, "description": "Filter by status." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "callback", "follow_up", "message", "order", "appointment" ], "description": "Filter by task type." }, "description": "Filter by task type." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only items linked to this contact." }, "description": "Only items linked to this contact." }, { "name": "call_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only items from this call." }, "description": "Only items from this call." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only items created at or after this time (ISO 8601)." }, "description": "Only items created at or after this time (ISO 8601)." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only items created before this time (ISO 8601)." }, "description": "Only items created before this time (ISO 8601)." } ], "responses": { "200": { "description": "List tasks", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "7e6d5c4b-3a29-4817-9f6e-5d4c3b2a1908", "object": "task", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "appointment_id": null, "kind": "callback", "title": "Call back about the invoice", "details": "Asked for a copy of the September invoice.", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "due_at": "2026-10-01T14:00:00Z", "status": "open", "created_at": "2026-10-01T09:17:45Z" } ], "has_more": true, "next_cursor": "MjAyNi0xMC0wMVQwOToxNDowM1o" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/tasks/{id}": { "get": { "operationId": "getTask", "summary": "Retrieve a task", "description": "One task of your account.\n\nRequired scope: `read:tasks`.", "tags": [ "tasks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:tasks" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The task ID." }, "description": "The task ID." } ], "responses": { "200": { "description": "Retrieve a task", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "7e6d5c4b-3a29-4817-9f6e-5d4c3b2a1908", "object": "task", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "appointment_id": null, "kind": "callback", "title": "Call back about the invoice", "details": "Asked for a copy of the September invoice.", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "due_at": "2026-10-01T14:00:00Z", "status": "open", "created_at": "2026-10-01T09:17:45Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateTask", "summary": "Update a task", "description": "Sets the task status to open, done or dismissed, for example after your team has called the customer back.\n\nRequired scope: `write:tasks`.", "tags": [ "tasks" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:tasks" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The task ID." }, "description": "The task ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "open", "done", "dismissed" ], "description": "New status: open, done or dismissed." } }, "required": [ "status" ] }, "example": { "status": "done" } } } }, "responses": { "200": { "description": "Update a task", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "7e6d5c4b-3a29-4817-9f6e-5d4c3b2a1908", "object": "task", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "appointment_id": null, "kind": "callback", "title": "Call back about the invoice", "details": "Asked for a copy of the September invoice.", "customer_name": "Anna Kowalska", "customer_phone": "+48601234567", "due_at": "2026-10-01T14:00:00Z", "status": "done", "created_at": "2026-10-01T09:17:45Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/calls/outbound": { "post": { "operationId": "outbound", "summary": "Create an outbound call", "description": "Your assistant calls one person from your business number with the goal you give, like a step of an onboarding sequence. The call goes out now or at call_at, always within calling hours (Mon–Sat, 9:00–20:00 in your account's time zone; outside them it moves to the next allowed time and call_at shows when). If nobody answers, it tries up to 3 times, 2 hours apart. Returns 202 with the call in status scheduled. Errors: 400 consent_missing, invalid_phone, number_not_callable, international or invalid_call_at; 409 opted_out (the person asked not to be called), already_scheduled (with existing_id), assistant_not_live, over_quota or no_outbound_number; 429 daily_outbound_limit with limit (200 calls per 24 hours by default). The outcome arrives in the call.completed and outbound_call.finished webhooks with your external_id.\n\nRequired scope: `write:calls`.", "tags": [ "calls" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:calls" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "phone": { "type": "string", "description": "Number to call, in E.164 format (+48601234567) or a national number of your account's country." }, "goal": { "type": "string", "description": "What the call should achieve, 10–1,000 characters. The assistant steers the conversation toward it." }, "consent": { "type": "boolean", "description": "Must be true: the person agreed to be called by your business." }, "assistant_id": { "type": "string", "format": "uuid", "description": "Which assistant should call (defaults to your main assistant)." }, "context": { "type": "string", "description": "What the assistant should know for this call, up to 1,000 characters (data, not instructions)." }, "name": { "type": "string", "description": "The person's name, up to 120 characters, used in the greeting." }, "external_id": { "type": "string", "description": "Your ID for this request, up to 120 characters. Returned in the response and in webhooks." }, "call_at": { "type": "string", "format": "date-time", "description": "When to call (ISO 8601), from now up to 30 days ahead. Defaults to now; outside calling hours the call moves to the next allowed time." } }, "required": [ "phone", "goal", "consent" ] }, "example": { "phone": "+48601234567", "goal": "Help Jan add the company name and tax ID in the profile, then agree on the next step.", "context": "Registered 3 days ago; next step: company data", "name": "Jan", "external_id": "gapli-evt-1842", "consent": true } } } }, "responses": { "202": { "description": "Create an outbound call", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e", "object": "outbound_call", "status": "scheduled", "source": "api", "phone": "+48601234567", "assistant_id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "call_at": "2026-10-09T08:00:00Z", "attempts": 0, "max_attempts": 3, "call_id": null, "external_id": "gapli-evt-1842", "last_error": null, "outreach": null, "created_at": "2026-10-09T07:59:58Z", "updated_at": "2026-10-09T07:59:58Z", "limits": { "per_day": 200, "remaining_today": 199 } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/calls/outbound/{id}": { "get": { "operationId": "getOutbound", "summary": "Retrieve an outbound call", "description": "Status of a scheduled outbound call: scheduled, dialing, done (with call_id of the conversation), failed (last_error, e.g. no_answer after all attempts) or canceled. Also works with the callback_id from webhooks for onboarding and callback calls.\n\nRequired scope: `write:calls`.", "tags": [ "calls" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:calls" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The outbound call ID (id from the create response or callback_id from a webhook)." }, "description": "The outbound call ID (id from the create response or callback_id from a webhook)." } ], "responses": { "200": { "description": "Retrieve an outbound call", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e", "object": "outbound_call", "status": "done", "source": "api", "phone": "+48601234567", "assistant_id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "call_at": "2026-10-09T08:00:00Z", "attempts": 1, "max_attempts": 3, "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "external_id": "gapli-evt-1842", "last_error": null, "outreach": null, "created_at": "2026-10-09T07:59:58Z", "updated_at": "2026-10-09T08:04:12Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "delete": { "operationId": "cancelOutbound", "summary": "Cancel an outbound call", "description": "Cancels an outbound call created through the API that is still scheduled. Repeating it is safe (already canceled returns 200). Returns 409 not_cancelable when the call is dialing or finished, or for onboarding calls (remove the person with POST /api/outreach/unenroll instead).\n\nRequired scope: `write:calls`.", "tags": [ "calls" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:calls" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The outbound call ID (id from the create response or callback_id from a webhook)." }, "description": "The outbound call ID (id from the create response or callback_id from a webhook)." } ], "responses": { "200": { "description": "Cancel an outbound call", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e", "object": "outbound_call", "status": "canceled", "source": "api", "phone": "+48601234567", "assistant_id": "0e6f4c8a-3b2d-4a1e-8f7c-5d9b2a1c3e4f", "call_at": "2026-10-09T08:00:00Z", "attempts": 0, "max_attempts": 3, "call_id": null, "external_id": "gapli-evt-1842", "last_error": "canceled_by_api", "outreach": null, "created_at": "2026-10-09T07:59:58Z", "updated_at": "2026-10-09T08:00:30Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/messages": { "get": { "operationId": "listMessages", "summary": "List SMS messages", "description": "SMS your account sent and customer replies, newest first. phone is the customer's number (recipient or sender of a reply). generated_by: template, ai or manual; charged_from: plan or credits.\n\nRequired scope: `read:messages`.", "tags": [ "messages" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "read:messages" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items to return, 1–100 (default 25)." }, "description": "Number of items to return, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "The next_cursor value from the previous page." }, "description": "The next_cursor value from the previous page." }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "outbound", "inbound" ], "description": "outbound (sent by you) or inbound (customer replies)." }, "description": "outbound (sent by you) or inbound (customer replies)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "sent", "delivered", "failed", "blocked", "skipped", "received" ], "description": "Filter by status: queued, sent, delivered, failed, blocked, skipped or received (replies)." }, "description": "Filter by status: queued, sent, delivered, failed, blocked, skipped or received (replies)." }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string", "description": "Exact phone number in E.164 format, e.g. +48601234567." }, "description": "Exact phone number in E.164 format, e.g. +48601234567." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only items linked to this contact." }, "description": "Only items linked to this contact." }, { "name": "call_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Only items from this call." }, "description": "Only items from this call." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only items created at or after this time (ISO 8601)." }, "description": "Only items created at or after this time (ISO 8601)." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Only items created before this time (ISO 8601)." }, "description": "Only items created before this time (ISO 8601)." } ], "responses": { "200": { "description": "List SMS messages", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "object": "message", "direction": "outbound", "phone": "+48601234567", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "call_id": "5b1f0c6e-2a8d-4f3e-9d51-7c0a4e2b9f10", "appointment_id": null, "type": "appointment_reminder", "status": "delivered", "error": null, "text": "Smile Dental: reminder of your appointment for First consultation on Fri 10/3 10:00. To reschedule, call +48 22 123 45 67.", "segments": 1, "source": "automation", "generated_by": "template", "charged_from": "plan", "created_at": "2026-10-02T10:00:04Z", "updated_at": "2026-10-02T10:00:09Z" } ], "has_more": true, "next_cursor": "MjAyNi0xMC0wMVQwOToxNDowM1o" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "sendMessage", "summary": "Send an SMS", "description": "Sends an SMS to one of your contacts or callers: your own text, or one of your account's templates with vars (date, time, name, service, link, amount). Counts toward your plan's SMS allowance and extra SMS. Errors: 400 invalid_request (consent_missing, invalid_phone, too_long, missing_vars); 409 conflict (opted_out — the customer replied STOP, over_quota, recipient_not_allowed — create the contact first, blocked_destination); 429 rate_limited.\n\nRequired scope: `write:messages`.", "tags": [ "messages" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "write:messages" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "to": { "type": "string", "description": "End of the range (ISO 8601)." }, "text": { "type": "string", "description": "Message text, up to 3 SMS parts (459 characters, or 201 with special characters). Use text or template." }, "template": { "type": "string", "enum": [ "booking_confirmation", "appointment_reminder", "missed_call", "callback_confirmation", "payment_link" ], "description": "One of your account's templates (dashboard → SMS → Templates), filled with vars." }, "vars": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Template values: name, date, time, service, link, amount (strings)." }, "consent": { "type": "boolean", "description": "Must be true: the recipient agreed to get SMS from your business." } }, "required": [ "to", "consent" ] }, "example": { "to": "+48601234567", "text": "Smile Dental: your crown is ready. You can pick it up from tomorrow, 9:00-17:00.", "consent": true } } } }, "responses": { "201": { "description": "Send an SMS", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "object": "message", "direction": "outbound", "phone": "+48601234567", "contact_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "call_id": null, "appointment_id": null, "type": "custom", "status": "sent", "error": null, "text": "Smile Dental: your crown is ready. You can pick it up from tomorrow, 9:00-17:00.", "segments": 1, "source": "api", "generated_by": "manual", "charged_from": "plan", "created_at": "2026-10-09T09:12:00Z", "updated_at": "2026-10-09T09:12:01Z" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (tf_live_…) or OAuth access token (JWT)", "description": "Create a key in API keys and send it as a Bearer token. Keys start with tf_live_ and belong to one account." }, "oauth2": { "type": "oauth2", "description": "Client credentials: client_id = API key id (api_key_id from GET /me), client_secret = the API key. Granted scopes are the requested scopes that the key has.", "flows": { "clientCredentials": { "tokenUrl": "https://voxiora.com/api/oauth/token", "scopes": { "read:calls": "Read calls, summaries and transcripts", "read:appointments": "Read appointments", "write:appointments": "Cancel and reschedule appointments", "read:contacts": "Read contacts", "write:contacts": "Create and update contacts", "read:tasks": "Read tasks and callback requests", "write:tasks": "Update task status", "write:calls": "Start outbound calls, check and cancel them", "read:messages": "Read SMS messages and customer replies", "write:messages": "Send SMS to your contacts", "read:assistants": "Read the assistant's prompt (instructions, greeting, company profile)", "write:assistants": "Change the assistant's prompt" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "Error400": { "description": "invalid_request — a parameter is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "unauthorized — missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "insufficient_scope — the key lacks the endpoint's scope; plan_required — the account has no active plan, or the recording is older than the plan's recording history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "not_found — the object doesn't exist in your account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "conflict — the time is already taken, the appointment can't be changed, a contact with this phone number already exists, or an outbound call can't be made (code: opted_out, already_scheduled, assistant_not_live, over_quota, no_outbound_number, not_cancelable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "rate_limited — too many requests; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error500": { "description": "server_error — something went wrong on our side", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "service_unavailable — a temporary problem; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }