{ "openapi": "3.0.3", "info": { "title": "telli API", "version": "1.0.0", "description": "API documentation for telli's V1 endpoints" }, "servers": [ { "url": "https://api.telli.com" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key must be provided as: Bearer ", "x-bearer-format": "Bearer" } }, "schemas": { "Contact": { "type": "object", "required": ["external_contact_id", "first_name", "last_name", "phone_number"], "properties": { "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "external_url": { "type": "string", "format": "uri", "description": "External URL linking to the contact in your CRM or external system" }, "salutation": { "type": "string", "description": "Formal title or greeting (e.g. 'Mr.', 'Ms.', 'Herr', 'Frau'). If empty, will auto guess based on first name for German calls." }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string", "description": "Contact's phone number in E.164 format (e.g. +4917642048466)" }, "email": { "type": "string", "format": "email" }, "contact_details": { "type": "object", "description": "Custom variables passed to the AI agent (should be discussed in advance). Please send variables in lowercase snake_case. This used to be called dynamic_variables, which still works but is deprecated and should be replaced with contact_details. Alternatively, you can send contact_details_ in the body instead of an object.", "additionalProperties": { "anyOf": [{ "type": "number" }, { "type": "string" }] } }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. Europe/Berlin). Defaults to account timezone if not set" } } }, "Error": { "type": "object", "properties": { "message": { "type": "string" } } }, "PhoneNumber": { "type": "object", "properties": { "type": { "type": "string", "enum": ["PhoneNumber"], "description": "Resource type identifier" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the phone number" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164 format (e.g. +4917642048466)" }, "inOutboundPool": { "type": "boolean", "description": "Whether this phone number is available for outbound calls" }, "phoneNumberType": { "type": "string", "enum": ["local", "mobile", null], "nullable": true, "description": "Type of phone number (local or mobile)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the phone number was added to the account" } } } } }, "security": [ { "apiKey": [] } ], "paths": { "/v1/verify-api-key": { "get": { "summary": "Verify API Key", "description": "Verifies if the provided API key is valid", "responses": { "200": { "description": "API key is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "API key is valid" } } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/add-contact": { "post": { "summary": "Add Contact", "description": "Adds a new contact to the system", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "responses": { "200": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/update-contact": { "patch": { "summary": "Update Contact", "description": "Updates an existing contact. Only provided fields will be updated, others remain unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contact_id"], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID received when creating the contact" }, "first_name": { "type": "string", "description": "First name of the contact" }, "last_name": { "type": "string", "description": "Last name of the contact" }, "phone_number": { "type": "string", "description": "Contact's phone number in E.164 format (e.g. +4917642048466)" }, "contact_details": { "type": "object", "description": "Custom variables passed to the AI agent. The entire object will be overwritten. This used to be called dynamic_variables, which still works but is deprecated and should be replaced with contact_details." }, "salutation": { "type": "string", "description": "Formal title or greeting (e.g. 'Mr.', 'Ms.', 'Herr', 'Frau')" }, "email": { "type": "string", "format": "email", "description": "Contact's email address" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. Europe/Berlin)" }, "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "external_url": { "type": "string", "format": "uri", "description": "External URL linking to the contact in your CRM or external system" } } } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/update-contacts-batch": { "patch": { "summary": "Update Contacts Batch", "description": "Updates multiple contacts in a single request. Limited to 1000 contacts per request. Only provided fields will be updated, others remain unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contacts"], "properties": { "contacts": { "type": "array", "items": { "type": "object", "required": ["contact_id"], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID received when creating the contact" }, "first_name": { "type": "string", "description": "First name of the contact" }, "last_name": { "type": "string", "description": "Last name of the contact" }, "phone_number": { "type": "string", "description": "Contact's phone number in E.164 format (e.g. +4917642048466)" }, "contact_details": { "type": "object", "description": "Custom variables passed to the AI agent. The entire object will be overwritten. This used to be called dynamic_variables, which still works but is deprecated and should be replaced with contact_details." }, "salutation": { "type": "string", "description": "Formal title or greeting (e.g. 'Mr.', 'Ms.', 'Herr', 'Frau')" }, "email": { "type": "string", "format": "email", "description": "Contact's email address" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. Europe/Berlin)" }, "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "external_url": { "type": "string", "format": "uri", "description": "External URL linking to the contact in your CRM or external system" } } }, "description": "Array of contacts to update. Maximum 1000 contacts per request." } } } } } }, "responses": { "200": { "description": "Contacts updated successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID" }, "status": { "type": "string", "enum": ["success", "error"], "description": "Status of the contact update" }, "error": { "type": "string", "description": "Error message (only present for failed updates)" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/get-contact/{contactId}": { "get": { "summary": "Get Contact", "description": "Retrieves detailed contact information including current call status and history", "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The telli contact ID" } ], "responses": { "200": { "description": "Contact details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID" }, "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "external_url": { "type": "string", "format": "uri", "description": "External URL linking to the contact in your CRM or external system" }, "created_at": { "type": "string", "format": "date-time", "description": "When the contact was created" }, "first_name": { "type": "string", "description": "First name of the contact" }, "last_name": { "type": "string", "description": "Last name of the contact" }, "phone_number": { "type": "string", "description": "Contact's phone number in E.164 format" }, "in_call_since": { "type": "string", "format": "date-time", "description": "Timestamp of when current call started, null if not in call" }, "reached_at": { "type": "string", "format": "date-time", "description": "When the contact was last successfully reached" }, "contact_details": { "type": "object", "description": "Custom variables passed to the AI agent" }, "call_attempts": { "type": "integer", "description": "Number of call attempts made to this contact" }, "next_call_at": { "type": "string", "format": "date-time", "description": "When the next call is scheduled, null if no call scheduled" }, "email": { "type": "string", "format": "email", "description": "Contact's email address" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. Europe/Berlin)" }, "salutation": { "type": "string", "description": "Formal title or greeting (e.g. 'Mr.', 'Ms.', 'Herr', 'Frau')" }, "status": { "type": "string", "enum": ["reached", "not_reached", "in_progress"], "description": "Current status of the contact" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/get-contacts-batch": { "post": { "summary": "Get Contacts Batch", "description": "Gets multiple contacts in a single request. Limited to 1000 contacts per request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contact_ids"], "properties": { "contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of telli contact IDs to retrieve. Maximum 1000 contacts per request." } } } } } }, "responses": { "200": { "description": "List of contacts retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": ["success", "error"], "description": "Status of the contact retrieval" }, "contact": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID" }, "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "external_url": { "type": "string", "format": "uri", "description": "External URL linking to the contact in your CRM or external system" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string", "description": "Contact's phone number in E.164 format" }, "email": { "type": "string", "format": "email" }, "salutation": { "type": "string", "description": "Formal title or greeting (e.g. 'Mr.', 'Ms.', 'Herr', 'Frau')" }, "contact_details": { "type": "object", "description": "Custom variables passed to the AI agent" }, "created_at": { "type": "string", "format": "date-time", "description": "When the contact was created" }, "in_call_since": { "type": "string", "format": "date-time", "description": "Timestamp of when current call started, null if not in call" }, "reached_at": { "type": "string", "format": "date-time", "description": "When the contact was last successfully reached" }, "call_attempts": { "type": "integer", "description": "Number of call attempts made to this contact" }, "next_call_at": { "type": "string", "format": "date-time", "description": "When the next call is scheduled, null if no call scheduled" } } }, "error": { "type": "string", "description": "Error message (only present for failed retrievals)" }, "contactId": { "type": "string", "format": "uuid", "description": "The contact ID that was attempted to be retrieved (only present for failed retrievals)" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/get-contact-by-external-id/{external_contact_id}": { "get": { "summary": "Get Contact by External ID", "description": "Retrieves detailed contact information including current call status and history using external contact id as an identifier", "parameters": [ { "name": "external_contact_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The telli contact ID" } ], "responses": { "200": { "description": "Contact details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID" }, "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "external_url": { "type": "string", "format": "uri", "description": "External URL linking to the contact in your CRM or external system" }, "created_at": { "type": "string", "format": "date-time", "description": "When the contact was created" }, "in_call_since": { "type": "string", "format": "date-time", "description": "Timestamp of when current call started, null if not in call" }, "reached_at": { "type": "string", "format": "date-time", "description": "When the contact was last successfully reached" }, "call_attempts": { "type": "integer", "description": "Number of call attempts made to this contact" }, "next_call_at": { "type": "string", "format": "date-time", "description": "When the next call is scheduled, null if no call scheduled" } } } } } } } } }, "/v1/get-call/{id}": { "get": { "summary": "Get Call", "description": "Retrieves detailed information about a specific call by its ID, including call metadata, transcript, analysis, and the associated contact.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The call ID" } ], "responses": { "200": { "description": "Call retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "type": "object", "properties": { "call_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the call" }, "attempt": { "type": "number", "description": "Which attempt number this call is within its loop" }, "from_number": { "type": "string", "description": "Caller phone number in E.164 format" }, "to_number": { "type": "string", "description": "Callee phone number in E.164 format" }, "direction": { "type": "string", "description": "Call direction: 'inbound' or 'outbound'" }, "external_contact_id": { "type": "string", "description": "Your external identifier for the contact" }, "contact_id": { "type": "string", "format": "uuid", "description": "telli contact ID" }, "contact_details": { "type": "object", "description": "Custom variables associated with the contact", "additionalProperties": true }, "agent_id": { "type": "string", "format": "uuid", "description": "ID of the agent that handled the call" }, "triggered_at": { "type": "number", "description": "Unix timestamp (ms) when the call was triggered" }, "triggered_at_iso": { "type": "string", "description": "ISO 8601 timestamp when the call was triggered" }, "started_at": { "type": "number", "description": "Unix timestamp (ms) when the call was answered" }, "started_at_iso": { "type": "string", "description": "ISO 8601 timestamp when the call was answered" }, "ended_at": { "type": "number", "description": "Unix timestamp (ms) when the call ended" }, "ended_at_iso": { "type": "string", "description": "ISO 8601 timestamp when the call ended" }, "call_length_min": { "type": "number", "description": "Duration of the call in minutes (rounded up)" }, "call_status": { "type": "string", "description": "Deprecated. Use state, status, and follow_up instead.", "deprecated": true, "enum": ["COMPLETED", "ANSWERED", "NOT_REACHED", "VOICEMAIL", "ERROR"] }, "transcript": { "type": "string", "description": "Plain text transcript of the call" }, "transcriptObject": { "type": "array", "description": "Structured transcript as an array of messages", "items": { "oneOf": [ { "type": "object", "description": "A spoken message from the user or agent", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["user", "agent"], "description": "Who spoke this message" }, "content": { "type": "string", "description": "The spoken text" } } }, { "type": "object", "description": "A tool activity performed by the agent during the call", "required": ["role", "toolActivity"], "properties": { "role": { "type": "string", "enum": ["agent"] }, "toolActivity": { "type": "string", "description": "Name of the tool that was invoked" }, "toolParameters": { "type": "object", "description": "Parameters passed to the tool", "additionalProperties": { "type": "string" } } } } ] } }, "call_analysis": { "type": "object", "description": "AI-generated analysis of the call. Keys are analysis field names configured on the agent.", "additionalProperties": { "type": "object", "properties": { "value": { "type": "boolean", "description": "Whether the analysis criterion was met" }, "details": { "type": "string", "description": "Additional details or explanation" } } } }, "call_outcome": { "type": "object", "description": "Structured outcome data extracted from the call. Keys are outcome field names configured on the agent.", "additionalProperties": { "type": "object", "properties": { "value": { "description": "The extracted value" }, "reason": { "type": "string", "description": "Explanation for the extracted value" }, "fieldSchema": { "type": "object", "description": "Schema definition for this outcome field" }, "error": { "type": "string", "description": "Error message if extraction failed" } } } }, "collected_data": { "type": "object", "description": "Data collected from the contact during the call via tasks (e.g. email, license plate). Keys are task names.", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": ["in_progress", "confirmed", "declined", "error"], "description": "Collection status for this data point" }, "value": { "type": "string", "description": "The collected value" } } } }, "booked_slot_for": { "type": "string", "description": "ISO 8601 timestamp of the booked appointment slot, if any" }, "recording_url": { "type": "string", "description": "URL to the call recording (only available when both parties have given consent)" }, "transfer": { "type": "object", "nullable": true, "description": "Transfer details when the call was transferred, or null if the call was not transferred", "properties": { "destination": { "type": "string", "description": "Transfer target the call was transferred to: an E.164 phone number or a tel:/sip: URI" }, "completed_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of when the call was transferred" } } }, "ended_reason": { "type": "string", "description": "Why the call ended", "enum": [ "agent-ended-call", "agent-forwarded-call", "agent-busy", "agent-did-not-answer", "contact-busy", "contact-ended-call", "contact-did-not-answer", "phone-provider-closed-connection", "other" ] }, "state": { "type": "string", "description": "Current call lifecycle state", "enum": ["queued", "ringing", "in_progress", "processing", "ended"] }, "status": { "type": "string", "nullable": true, "description": "Normalized terminal connection status. Null while the call is not terminal.", "enum": ["connected", "not_connected", "voicemail", "failed"] }, "follow_up": { "type": "object", "nullable": true, "description": "Scheduled follow-up call information, if the agent scheduled one.", "required": ["type", "scheduled_at"], "properties": { "type": { "type": "string", "enum": ["agent_follow_up"] }, "scheduled_at": { "type": "string", "format": "date-time", "description": "When the follow-up call is scheduled" } } } } }, "contact": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "external_url": { "type": "string", "description": "External URL linking to the contact in your CRM" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp when the contact was created" }, "gender": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": "string", "description": "Phone number in E.164 format" }, "in_call_since": { "type": "string", "description": "ISO 8601 timestamp if the contact is currently in a call" }, "reached_at": { "type": "string", "description": "ISO 8601 timestamp when the contact was last reached" }, "contact_details": { "type": "object", "description": "Custom variables associated with the contact", "additionalProperties": true }, "call_attempts": { "type": "number", "description": "Number of call attempts made to this contact" }, "next_call_at": { "type": "string", "description": "ISO 8601 timestamp of the next scheduled call" }, "email": { "type": "string" }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. Europe/Berlin)" }, "salutation": { "type": "string", "description": "Formal title or greeting (e.g. 'Mr.', 'Ms.')" }, "status": { "type": "string", "description": "Contact status", "enum": ["new", "pending", "closed", "reached"] } } } } } } } }, "400": { "description": "Invalid request - id must be a valid UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Call not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/list-calls": { "get": { "summary": "List Calls", "description": "Returns a paginated list of calls for the authenticated account, ordered by `triggered_at` descending. Optionally filter by `contact_id` to return only calls for a single contact, or by `agent_id` to return only calls for a single agent. `contact_id` and `agent_id` cannot be used together. Each item is a lean call payload: the response does not include a separate top-level `contact` object, and the `external_contact_id` and `contact_details` fields are omitted from each call (unlike [Get Call](/v1/endpoint/get-call)). Use the Contact endpoints if you need contact details.", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only return calls for this telli contact ID" }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Only return calls for this telli agent ID. Cannot be combined with `contact_id`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of calls to return (1-100, default 50)" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned as `next_cursor` from a previous response. Pass unchanged to fetch the next page." } ], "responses": { "200": { "description": "Calls retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "description": "Calls ordered by `triggered_at` descending", "items": { "type": "object", "properties": { "call_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the call" }, "attempt": { "type": "number", "description": "Which attempt number this call is within its loop" }, "from_number": { "type": "string", "description": "Caller phone number in E.164 format" }, "to_number": { "type": "string", "description": "Callee phone number in E.164 format" }, "direction": { "type": "string", "description": "Call direction: 'inbound' or 'outbound'" }, "contact_id": { "type": "string", "format": "uuid", "description": "telli contact ID" }, "agent_id": { "type": "string", "format": "uuid", "description": "ID of the agent that handled the call" }, "triggered_at": { "type": "number", "description": "Unix timestamp (ms) when the call was triggered" }, "triggered_at_iso": { "type": "string", "description": "ISO 8601 timestamp when the call was triggered" }, "started_at": { "type": "number", "description": "Unix timestamp (ms) when the call was answered" }, "started_at_iso": { "type": "string", "description": "ISO 8601 timestamp when the call was answered" }, "ended_at": { "type": "number", "description": "Unix timestamp (ms) when the call ended" }, "ended_at_iso": { "type": "string", "description": "ISO 8601 timestamp when the call ended" }, "call_length_min": { "type": "number", "description": "Duration of the call in minutes (rounded up)" }, "call_status": { "type": "string", "description": "Deprecated. Use state, status, and follow_up instead.", "deprecated": true, "enum": ["COMPLETED", "ANSWERED", "NOT_REACHED", "VOICEMAIL", "ERROR"] }, "transcript": { "type": "string", "description": "Plain text transcript of the call" }, "transcriptObject": { "type": "array", "description": "Structured transcript as an array of messages", "items": { "oneOf": [ { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["user", "agent"] }, "content": { "type": "string" } } }, { "type": "object", "required": ["role", "toolActivity"], "properties": { "role": { "type": "string", "enum": ["agent"] }, "toolActivity": { "type": "string" }, "toolParameters": { "type": "object", "additionalProperties": { "type": "string" } } } } ] } }, "call_analysis": { "type": "object", "description": "AI-generated analysis of the call", "additionalProperties": { "type": "object", "properties": { "value": { "type": "boolean" }, "details": { "type": "string" } } } }, "call_outcome": { "type": "object", "description": "Structured outcome data extracted from the call", "additionalProperties": { "type": "object", "properties": { "value": {}, "reason": { "type": "string" }, "fieldSchema": { "type": "object" }, "error": { "type": "string" } } } }, "collected_data": { "type": "object", "description": "Data collected from the contact during the call via tasks", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": ["in_progress", "confirmed", "declined", "error"] }, "value": { "type": "string" } } } }, "booked_slot_for": { "type": "string", "description": "ISO 8601 timestamp of the booked appointment slot, if any" }, "recording_url": { "type": "string", "description": "URL to the call recording (only available when both parties have given consent)" }, "transfer": { "type": "object", "nullable": true, "description": "Transfer details when the call was transferred, or null if the call was not transferred", "properties": { "destination": { "type": "string", "description": "Transfer target the call was transferred to: an E.164 phone number or a tel:/sip: URI" }, "completed_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of when the call was transferred" } } }, "ended_reason": { "type": "string", "description": "Why the call ended", "enum": [ "agent-ended-call", "agent-forwarded-call", "agent-busy", "agent-did-not-answer", "contact-busy", "contact-ended-call", "contact-did-not-answer", "phone-provider-closed-connection", "other" ] }, "state": { "type": "string", "description": "Current call lifecycle state", "enum": ["queued", "ringing", "in_progress", "processing", "ended"] }, "status": { "type": "string", "nullable": true, "description": "Normalized terminal connection status. Null while the call is not terminal.", "enum": ["connected", "not_connected", "voicemail", "failed"] }, "follow_up": { "type": "object", "nullable": true, "description": "Scheduled follow-up call information, if the agent scheduled one.", "required": ["type", "scheduled_at"], "properties": { "type": { "type": "string", "enum": ["agent_follow_up"] }, "scheduled_at": { "type": "string", "format": "date-time", "description": "When the follow-up call is scheduled" } } } } } }, "next_cursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` in the next request to fetch more results. `null` when there are no more pages." } } } } } }, "400": { "description": "Invalid request - malformed UUID, invalid cursor, or `contact_id` and `agent_id` used together", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/initiate-call": { "post": { "summary": "Initiate Call", "description": "[Not recommended] Initiates an immediate call to a contact. Will call even outside business hours, which is why we recommend using schedule-call instead. If contact cannot be reached and Auto Dialer is enabled, telli will continue trying according to Auto Dialer settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contact_id", "agent_id"], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "telli contact ID of the contact to call" }, "agent_id": { "type": "string", "description": "Agent ID to use for the call" }, "max_retry_days": { "type": "number", "description": "Optional number of days to retry the call. Defaults to the account's max retry days" }, "override_from_number": { "type": "string", "description": "Optional phone number to use as the caller ID. Must be a valid E.164 number that belongs to the account" } } } } } }, "responses": { "200": { "description": "Call initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "success" }, "call_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/schedule-call": { "post": { "summary": "Schedule Call", "description": "Schedules a call at the earliest opportunity within the dialer window. May occur immediately or on the next business day depending on settings. Requires the auto dialer to be enabled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contact_id", "agent_id"], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "telli contact ID of the contact to schedule a call with" }, "agent_id": { "type": "string", "description": "Agent ID to use for the call" }, "max_retry_days": { "type": "number", "description": "Optional number of days to retry the call. Defaults to the account's max retry days" }, "override_from_number": { "type": "string", "description": "Optional phone number to use as the caller ID. Must be a valid E.164 number that belongs to the account" }, "schedule": { "type": "object", "nullable": true, "properties": { "at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp in UTC to schedule the call at a specific time. Must be in the future (up to 90 days)", "example": "2024-01-01T10:00:00.000Z" }, "ignore_dialing_window": { "type": "boolean", "example": false, "default": false, "description": "Optional flag to bypass dialing window restrictions for the scheduled call. When true, calls at the scheduled time regardless of dialing windows. When false or omitted, respects dialing windows" } }, "required": ["at"], "description": "Optional schedule configuration. Use to schedule a call at a specific time, and optionally to bypass dialing window restrictions. Setting a schedule will override any existing schedule for the contact and agent." } } } } } }, "responses": { "200": { "description": "Call scheduled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "contact_id": { "type": "string", "format": "uuid" }, "loop_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remove-from-auto-dialer": { "post": { "summary": "Remove from Auto Dialer", "description": "Removes a contact from the auto dialer queue", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contact_id"], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "telli contact ID of the contact to remove from the auto dialer" } } } } } }, "responses": { "200": { "description": "Contact removed from auto dialer successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/remove-from-auto-dialer-batch": { "post": { "summary": "Remove from Auto Dialer Batch", "description": "Removes multiple contacts from the auto dialer queue. Limited to 50 contacts per request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contact_ids"], "properties": { "contact_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of telli contact IDs to remove from the auto dialer. Maximum 50 contacts per request." } } } } } }, "responses": { "200": { "description": "List of statuses for each contact ID", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID" }, "status": { "type": "string", "enum": ["success", "error"], "description": "Status of the removal operation" }, "error": { "type": "string", "description": "Error message (only present for failed removals)" } } } }, "example": [ { "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "success" }, { "contact_id": "invalid_contact_id", "status": "error", "error": "Invalid contact_id" }, { "contact_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "status": "success" }, { "contact_id": "d4e5f6a7-b8c9-0123-defg-h23456789012", "status": "error", "error": "Contact not found" } ] } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/add-contacts-batch": { "post": { "summary": "Add Contacts Batch", "description": "Adds multiple contacts in a single request. Limited to 1000 contacts per request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contacts"], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "description": "Array of contacts to add. Maximum 1000 contacts per request." } } } } } }, "responses": { "200": { "description": "Contacts processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_processed": { "type": "integer", "description": "Total number of contacts processed" }, "total_success": { "type": "integer", "description": "Number of contacts successfully added" }, "total_failed": { "type": "integer", "description": "Number of contacts that failed to be added" }, "result": { "type": "array", "items": { "type": "object", "properties": { "external_contact_id": { "type": "string", "description": "Your unique internal identifier for the contact" }, "status": { "type": "string", "enum": ["success", "error"], "description": "Status of the contact addition" }, "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID (only present for successful additions)" }, "error": { "type": "string", "description": "Error message (only present for failed additions)" } } } } } }, "example": { "total_processed": 4, "total_success": 3, "total_failed": 1, "result": [ { "external_contact_id": "ext123", "status": "success", "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "external_contact_id": "ext124", "status": "success", "contact_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, { "external_contact_id": "ext125", "status": "success", "contact_id": "c3d4e5f6-a7b8-9012-cdef-123456789012" }, { "external_contact_id": "ext125", "status": "error", "error": "External ID already exists, must be unique" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/schedule-calls-batch": { "post": { "summary": "Schedule Calls Batch", "description": "Schedules multiple calls in a single request. Limited to 50 contacts per request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["contacts"], "properties": { "contacts": { "type": "array", "items": { "type": "object", "required": ["contact_id", "agent_id"], "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "telli contact ID of the contact to schedule a call with" }, "agent_id": { "type": "string", "description": "Agent ID to use for the call" }, "max_retry_days": { "type": "number", "description": "Optional number of days to retry the call. Defaults to the account's max retry days" }, "override_from_number": { "type": "string", "description": "Optional phone number to use as the caller ID. Must be a valid E.164 number that belongs to the account" }, "schedule": { "type": "object", "nullable": true, "properties": { "at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp in UTC to schedule the call at a specific time. Must be in the future (up to 90 days)", "example": "2024-01-01T10:00:00.000Z" }, "ignore_dialing_window": { "type": "boolean", "example": false, "default": false, "description": "Optional flag to bypass dialing window restrictions for the scheduled call. When true, calls at the scheduled time regardless of dialing windows. When false or omitted, respects dialing windows" } }, "required": ["at"], "description": "Optional schedule configuration. Use to schedule a call at a specific time, and optionally to bypass dialing window restrictions. Setting a schedule will override any existing schedule for the contact and agent." } } }, "description": "Array of contacts to schedule calls for. Maximum 50 contacts per request." } } } } } }, "responses": { "200": { "description": "Calls scheduled successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "The telli contact ID (only present for successful scheduling)" }, "status": { "type": "string", "enum": ["success", "error"], "description": "Status of the call scheduling" }, "loop_id": { "type": "string", "format": "uuid", "description": "The call loop ID (only present for successful scheduling)" }, "error_message": { "type": "string", "description": "Error message (only present for failed scheduling)" }, "error_code": { "type": "integer", "description": "Error code (only present for failed scheduling)" } } } }, "example": [ { "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "success", "loop_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, { "contact_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "status": "success", "loop_id": "d4e5f6a7-b8c9-0123-defg-h23456789012" }, { "contact_id": "e5f6a7b8-c9d0-1234-efgh-i34567890123", "status": "error", "error_message": "Contact not found", "error_code": 400 } ] } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/delete-contact/{contact_id}": { "delete": { "summary": "Delete Contact", "description": "Permanently deletes a contact and any PII data associated with it from the system. This action cannot be undone. If you want to stop calling a contact, use the `v1/remove-from-auto-dialer` endpoint instead.", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The telli contact ID to delete" } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contact deleted successfully" }, "contact_id": { "type": "string", "format": "uuid", "description": "The ID of the deleted contact" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phone-numbers": { "get": { "summary": "List Phone Numbers", "description": "Retrieves all active phone numbers associated with the account", "responses": { "200": { "description": "Phone numbers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phone-numbers/{id}/replace": { "post": { "summary": "Replace Phone Number", "description": "Replaces an existing phone number with a new one with the same configuration. The old number is scheduled for deletion but remains active for callbacks for 30 days.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The phone number ID to replace" } ], "responses": { "200": { "description": "Phone number replaced successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "oldNumber": { "$ref": "#/components/schemas/PhoneNumber" }, "newNumber": { "$ref": "#/components/schemas/PhoneNumber" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phone-numbers/import": { "post": { "summary": "Import Phone Number", "description": "Imports a phone number from your own SIP trunk provider. This allows you to use existing phone numbers with telli by configuring custom SIP termination settings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["phoneNumber", "terminationUri", "authUsername", "authPassword"], "properties": { "phoneNumber": { "type": "string", "description": "Phone number in E.164 format (e.g. +4917642048466)" }, "terminationUri": { "type": "string", "description": "SIP termination URI for routing calls" }, "authUsername": { "type": "string", "description": "Username for SIP authentication" }, "authPassword": { "type": "string", "description": "Password for SIP authentication" }, "transport": { "type": "string", "enum": ["TCP", "UDP", "TLS"], "default": "TCP", "description": "SIP transport protocol for the imported number. Defaults to TCP." }, "inOutboundPool": { "type": "boolean", "default": true, "description": "Whether to include this phone number in the outbound call pool. Defaults to true." } } } } } }, "responses": { "200": { "description": "Phone number imported successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phone-numbers/{id}": { "delete": { "summary": "Delete Phone Number", "description": "Schedules a phone number for deletion. The number remains active for callbacks for 30 days and can be restored during this period.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The phone number ID to delete" } ], "responses": { "204": { "description": "Phone number deleted successfully" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone number not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }