{ "openapi": "3.0.3", "info": { "title": "Allo API", "description": "Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages.\n\nAll requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation.", "version": "1.0.0", "contact": { "name": "Allo Support" } }, "servers": [ { "url": "https://api.withallo.com", "description": "Production server" } ], "tags": [ { "name": "Summary Templates", "description": "Manage call summary templates that control how AI-generated call summaries are structured for your team." }, { "name": "Webhooks", "description": "Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret." }, { "name": "Calls", "description": "Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number." }, { "name": "Contacts", "description": "Search and retrieve contact information with sorting and pagination. Includes engagement level tracking." }, { "name": "SMS", "description": "Send SMS messages to phone numbers using your Allo numbers." }, { "name": "Phone Numbers", "description": "Retrieve information about your Allo phone numbers." }, { "name": "Analytics", "description": "Pre-computed call metrics, team performance, and outbound dial funnel" }, { "name": "CRM", "description": "Manage people, companies, and deals in your CRM." } ], "paths": { "/v2/api/numbers/{number}/default_summary_template": { "put": { "summary": "Set number default summary template", "description": "Sets or clears the default summary template used for a phone number's call summaries. Pass `summary_template_id` to set it, or null/omit to clear it.", "operationId": "setNumberDefaultSummaryTemplate", "tags": [ "Summary Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "number", "in": "path", "required": true, "description": "Allo phone number in E.164 format", "schema": { "type": "string", "example": "+14155551234" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary_template_id": { "type": "string", "nullable": true, "description": "Summary template ID (`tst-*`) to set as the default, or null to clear.", "example": "tst-abc123" } } }, "example": { "summary_template_id": "tst-abc123" } } } }, "responses": { "200": { "description": "Default summary template updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "number": { "type": "string", "example": "+14155551234" }, "default_summary_template_id": { "type": "string", "nullable": true, "example": "tst-abc123" } } } } }, "example": { "data": { "number": "+14155551234", "default_summary_template_id": "tst-abc123" } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/summary_templates": { "get": { "summary": "List summary templates", "description": "Returns the team's call summary templates.", "operationId": "listSummaryTemplates", "tags": [ "Summary Templates" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of summary templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryTemplate" } } } }, "example": { "data": [ { "id": "tst-abc123", "name": "Sales call", "call_context": "B2B SaaS sales calls", "icon": "📞", "sections": [ { "title": "Pain points", "instructions": "List the prospect's pain points", "order": 0 }, { "title": "Next steps", "instructions": "What was agreed", "order": 1 } ], "created_at": "2026-06-01T10:00:00", "updated_at": "2026-06-01T10:00:00" } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "post": { "summary": "Create summary template", "description": "Creates a call summary template for the team.", "operationId": "createSummaryTemplate", "tags": [ "Summary Templates" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name.", "example": "Sales call" }, "call_context": { "type": "string", "nullable": true, "description": "Background context that helps the AI summarize calls (max 4000 characters).", "example": "B2B SaaS sales calls" }, "icon": { "type": "string", "nullable": true, "description": "Optional icon (e.g. an emoji).", "example": "📞" }, "sections": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/SummaryTemplateSection" }, "description": "Ordered sections that make up the summary (max 10)." } }, "required": [ "name" ] }, "example": { "name": "Sales call", "call_context": "B2B SaaS sales calls", "icon": "📞", "sections": [ { "title": "Pain points", "instructions": "List the prospect's pain points", "order": 0 }, { "title": "Next steps", "instructions": "What was agreed", "order": 1 } ] } } } }, "responses": { "201": { "description": "Summary template created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SummaryTemplate" } } }, "example": { "data": { "id": "tst-abc123", "name": "Sales call", "call_context": "B2B SaaS sales calls", "icon": "📞", "sections": [ { "title": "Pain points", "instructions": "List the prospect's pain points", "order": 0 }, { "title": "Next steps", "instructions": "What was agreed", "order": 1 } ], "created_at": "2026-06-01T10:00:00", "updated_at": "2026-06-01T10:00:00" } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/summary_templates/{id}": { "get": { "summary": "Get summary template", "description": "Returns a single call summary template by ID.", "operationId": "getSummaryTemplate", "tags": [ "Summary Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Summary template ID (`tst-*`)", "schema": { "type": "string", "example": "tst-abc123" } } ], "responses": { "200": { "description": "Summary template", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SummaryTemplate" } } }, "example": { "data": { "id": "tst-abc123", "name": "Sales call", "call_context": "B2B SaaS sales calls", "icon": "📞", "sections": [ { "title": "Pain points", "instructions": "List the prospect's pain points", "order": 0 }, { "title": "Next steps", "instructions": "What was agreed", "order": 1 } ], "created_at": "2026-06-01T10:00:00", "updated_at": "2026-06-01T10:00:00" } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "put": { "summary": "Update summary template", "description": "Replaces a summary template's name, call context, icon, and sections.", "operationId": "updateSummaryTemplate", "tags": [ "Summary Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Summary template ID (`tst-*`)", "schema": { "type": "string", "example": "tst-abc123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name.", "example": "Sales call" }, "call_context": { "type": "string", "nullable": true, "description": "Background context that helps the AI summarize calls (max 4000 characters).", "example": "B2B SaaS sales calls" }, "icon": { "type": "string", "nullable": true, "description": "Optional icon (e.g. an emoji).", "example": "📞" }, "sections": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/SummaryTemplateSection" }, "description": "Ordered sections that make up the summary (max 10)." } }, "required": [ "name" ] }, "example": { "name": "Sales call", "call_context": "B2B SaaS sales calls", "icon": "📞", "sections": [ { "title": "Pain points", "instructions": "List the prospect's pain points", "order": 0 }, { "title": "Next steps", "instructions": "What was agreed", "order": 1 } ] } } } }, "responses": { "200": { "description": "Summary template updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SummaryTemplate" } } }, "example": { "data": { "id": "tst-abc123", "name": "Sales call", "call_context": "B2B SaaS sales calls", "icon": "📞", "sections": [ { "title": "Pain points", "instructions": "List the prospect's pain points", "order": 0 }, { "title": "Next steps", "instructions": "What was agreed", "order": 1 } ], "created_at": "2026-06-01T10:00:00", "updated_at": "2026-06-01T10:00:00" } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "delete": { "summary": "Delete summary template", "description": "Soft-deletes (deactivates) a summary template.", "operationId": "deleteSummaryTemplate", "tags": [ "Summary Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Summary template ID (`tst-*`)", "schema": { "type": "string", "example": "tst-abc123" } } ], "responses": { "204": { "description": "Summary template deleted" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/webhooks": { "get": { "summary": "List webhooks", "description": "Returns all webhook endpoints configured for your account.", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of webhook endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookApiResponse" } } } }, "example": { "data": [ { "id": "ep_2NfDKEm9sF8xK3pQr1Zt", "url": "https://example.com/webhooks/allo", "topics": [ "call.received", "sms.received" ], "description": "Production event stream", "enabled": true, "created_at": "2026-04-21T14:30:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "post": { "summary": "Create webhook", "description": "Creates a webhook endpoint subscribed to one or more event topics. The `signing_secret` is returned only in this response — store it to verify delivery signatures.", "operationId": "createWebhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookApiRequest" }, "example": { "url": "https://example.com/webhooks/allo", "topics": [ "call.received", "sms.received" ], "description": "Production event stream" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookApiResponse" } } }, "example": { "data": { "id": "ep_2NfDKEm9sF8xK3pQr1Zt", "url": "https://example.com/webhooks/allo", "topics": [ "call.received", "sms.received" ], "description": "Production event stream", "enabled": true, "signing_secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD", "created_at": "2026-04-21T14:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/webhooks/{webhook_id}": { "get": { "summary": "Get webhook", "description": "Returns a single webhook endpoint by ID, including its `signing_secret`.", "operationId": "getWebhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The webhook endpoint ID (e.g. \"ep_2NfDKEm9sF8xK3pQr1Zt\").", "schema": { "type": "string", "example": "ep_2NfDKEm9sF8xK3pQr1Zt" } } ], "responses": { "200": { "description": "Webhook endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookApiResponse" } } }, "example": { "data": { "id": "ep_2NfDKEm9sF8xK3pQr1Zt", "url": "https://example.com/webhooks/allo", "topics": [ "call.received", "sms.received" ], "description": "Production event stream", "enabled": true, "signing_secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD", "created_at": "2026-04-21T14:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "put": { "summary": "Update webhook", "description": "Updates a webhook endpoint. Only the fields you provide are changed. Omitted fields are left untouched.", "operationId": "updateWebhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The webhook endpoint ID (e.g. \"ep_2NfDKEm9sF8xK3pQr1Zt\").", "schema": { "type": "string", "example": "ep_2NfDKEm9sF8xK3pQr1Zt" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookApiRequest" }, "example": { "topics": [ "call.received", "call.completed" ], "enabled": false } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookApiResponse" } } }, "example": { "data": { "id": "ep_2NfDKEm9sF8xK3pQr1Zt", "url": "https://example.com/webhooks/allo", "topics": [ "call.received", "sms.received" ], "description": "Production event stream", "enabled": true, "created_at": "2026-04-21T14:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "delete": { "summary": "Delete webhook", "description": "Permanently deletes a webhook endpoint and its delivery history.", "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The webhook endpoint ID (e.g. \"ep_2NfDKEm9sF8xK3pQr1Zt\").", "schema": { "type": "string", "example": "ep_2NfDKEm9sF8xK3pQr1Zt" } } ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/webhooks/event_types": { "get": { "summary": "List event types", "description": "Returns the catalog of event topics you can subscribe a webhook to.", "operationId": "listWebhookEventTypes", "tags": [ "Webhooks" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Available event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventTypeApiResponse" } } } }, "example": { "data": [ { "name": "call.received", "description": "Inbound call received" }, { "name": "sms.sent", "description": "Outbound sms sent" } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v1/api/calls": { "get": { "summary": "Search Calls", "description": "Search and filter calls for a specific Allo phone number with pagination support.", "operationId": "searchCalls", "tags": [ "Calls" ], "security": [ { "CallsAuth": [] } ], "parameters": [ { "name": "size", "in": "query", "description": "Number of results per page. Must be between 1 and 100.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "page", "in": "query", "description": "Page number (0-indexed).", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "allo_number", "in": "query", "description": "Your Allo phone number to filter calls by. Must be in E.164 format (e.g., `+1234567890`).", "required": true, "schema": { "type": "string", "example": "+1234567890" } }, { "name": "contact_number", "in": "query", "description": "Filter calls by contact phone number. Only returns calls with this specific contact. Must be in E.164 format (e.g., `+1234567890`).", "required": false, "schema": { "type": "string", "example": "+0987654321" } } ], "responses": { "200": { "description": "Calls retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCallsApiResponse" }, "example": { "data": { "results": [ { "id": "call_abc123", "from_number": "+1234567890", "to_number": "+0987654321", "length_in_minutes": 5.5, "type": "INBOUND", "summary": "Customer called about order status.", "tag": "support", "recording_url": "https://storage.withallo.com/recordings/abc123.mp3", "start_date": "2024-01-15T10:30:00", "transcript": [ { "source": "AGENT", "text": "Hello, how can I help you today?", "time": "2024-01-15T10:30:05", "start_seconds": 5, "end_seconds": 8.5 }, { "source": "EXTERNAL", "text": "Hi, I'm calling about my order status.", "time": "2024-01-15T10:30:10", "start_seconds": 10, "end_seconds": 14 } ] } ], "metadata": { "total_pages": 5, "current_page": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/api/contacts": { "get": { "summary": "Search Contacts", "description": "Search and filter contacts with sorting and pagination support. Returns contacts with engagement level information.", "operationId": "searchContacts", "tags": [ "Contacts" ], "security": [ { "ContactsAuth": [] } ], "parameters": [ { "name": "size", "in": "query", "description": "Number of results per page. Must be between 1 and 100.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "page", "in": "query", "description": "Page number (0-indexed).", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Contacts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchContactsApiResponse" }, "example": { "data": { "results": [ { "id": "cnt_abc123", "name": "John", "last_name": "Doe", "company": { "name": "Acme Corp", "id": "com_xyz789" }, "job_title": "Manager", "website": null, "status": "active", "is_archived": false, "created_at": "2024-01-10T08:00:00", "updated_at": "2024-01-15T10:30:00", "numbers": [ "+1234567890" ], "is_whitelisted": true, "last_activity_date": "2024-01-15T10:30:00", "engagement": "ENGAGED" } ], "metadata": { "pagination": { "total_pages": 5, "current_page": 0 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "summary": "Create Contact", "description": "Create a new contact in your Allo account. At least one phone number is required.", "operationId": "createContact", "tags": [ "Contacts" ], "security": [ { "ContactsWriteAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactRequest" }, "example": { "name": "John", "last_name": "Doe", "job_title": "CEO", "website": "https://acme.com", "emails": [ "john@acme.com" ], "numbers": [ "+15551234567" ] } } } }, "responses": { "200": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactApiResponse" }, "example": { "data": { "id": "cnt_abc123", "name": "John", "last_name": "Doe", "job_title": "CEO", "website": "https://acme.com", "status": null, "is_archived": false, "created_at": "2024-01-21T10:30:00", "updated_at": "2024-01-21T10:30:00", "numbers": [ "+15551234567" ], "is_whitelisted": false, "last_activity_date": "2024-01-21T10:30:00", "engagement": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/api/contacts/{contact_id}": { "put": { "summary": "Update Contact", "description": "Update an existing contact. Only provided fields will be updated. Arrays (emails, numbers, addresses) replace existing values entirely.", "operationId": "updateContact", "tags": [ "Contacts" ], "security": [ { "ContactsWriteAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "description": "The unique identifier of the contact to update (e.g., \"cnt_abc123\")", "required": true, "schema": { "type": "string", "example": "cnt_abc123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactRequest" }, "example": { "name": "John", "last_name": "Smith", "job_title": "CTO", "emails": [ "john.smith@acme.com", "john@personal.com" ] } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactApiResponse" }, "example": { "data": { "id": "cnt_abc123", "name": "John", "last_name": "Smith", "job_title": "CTO", "website": "https://acme.com", "status": null, "is_archived": false, "created_at": "2024-01-21T10:30:00", "updated_at": "2024-01-21T11:00:00", "numbers": [ "+15551234567" ], "is_whitelisted": false, "last_activity_date": "2024-01-21T11:00:00", "engagement": null } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "CONTACT_NOT_FOUND", "details": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/api/sms": { "post": { "summary": "Send SMS (US)", "description": "Send an SMS message to a US phone number using one of your Allo phone numbers. The recipient must be in the same country as your Allo number.", "operationId": "sendSMS", "tags": [ "SMS" ], "security": [ { "SmsAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSMSRequest" }, "example": { "from": "+1234567890", "to": "+0987654321", "message": "Hello, this is a test message" } } } }, "responses": { "200": { "description": "SMS sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSMSResponse" }, "example": { "data": { "from_number": "+1234567890", "sender_id": null, "to_number": "+0987654321", "type": "OUTBOUND", "content": "Hello, this is a test message", "start_date": "2024-01-15T10:30:00" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "fromNumberNotFound": { "summary": "From number not found", "value": { "code": "FROM_NUMBER_NOT_FOUND", "details": null } }, "invalidToNumber": { "summary": "Invalid to number", "value": { "code": "INVALID_TO_NUMBER", "details": null } }, "toNumberCountryMismatch": { "summary": "Country mismatch", "value": { "code": "TO_NUMBER_COUNTRY_MISMATCH", "details": null } }, "invalidLength": { "summary": "Invalid message length", "value": { "code": "INVALID_LENGTH", "details": null } }, "providerNotSupported": { "summary": "Provider not supported", "value": { "code": "PROVIDER_NOT_SUPPORTED", "details": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/api/sms#france": { "post": { "summary": "Send SMS (France)", "description": "Send an SMS message to a French phone number using a verified Sender ID. The Sender ID must be verified by the Allo team before use. Contact support to register your Sender ID.", "operationId": "sendSMSFrance", "tags": [ "SMS" ], "security": [ { "SmsAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSMSFranceRequest" }, "example": { "sender_id": "MyCompany", "to": "+33612345678", "message": "Bonjour, ceci est un message de test" } } } }, "responses": { "200": { "description": "SMS sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendSMSResponse" }, "example": { "data": { "from_number": null, "sender_id": "MyCompany", "to_number": "+33612345678", "type": "OUTBOUND", "content": "Bonjour, ceci est un message de test", "start_date": "2024-01-15T10:30:00" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidSenderId": { "summary": "Invalid Sender ID", "value": { "code": "INVALID_SENDER_ID", "details": null } }, "senderIdNotActive": { "summary": "Sender ID not active", "value": { "code": "SENDER_ID_NOT_ACTIVE", "details": null } }, "invalidToNumber": { "summary": "Invalid to number", "value": { "code": "INVALID_TO_NUMBER", "details": null } }, "invalidLength": { "summary": "Invalid message length", "value": { "code": "INVALID_LENGTH", "details": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/api/numbers": { "get": { "summary": "Get Phone Numbers", "description": "Retrieve all Allo phone numbers associated with your account. Returns basic information about each number including country, name, and sharing status.", "operationId": "getNumbers", "tags": [ "Phone Numbers" ], "security": [ { "CallsAuth": [] } ], "responses": { "200": { "description": "Phone numbers retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNumbersResponse" }, "example": { "data": [ { "number": "+1234567890", "name": "Main Line", "country": "US", "is_shared_number": false }, { "number": "+33612345678", "name": "France Office", "country": "FR", "is_shared_number": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/api/contact/{contact_id}": { "get": { "summary": "Get Contact", "description": "Get detailed information for a specific contact by ID.", "operationId": "getContactContext", "tags": [ "Contacts" ], "security": [ { "ContactsAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "description": "The unique identifier of the contact (e.g., \"cnt_abc123\")", "required": true, "schema": { "type": "string", "example": "cnt_abc123" } }, { "name": "extend", "in": "query", "description": "Comma-separated list of additional data to include. Available options: `engagement` (includes engagement level), `activity` (includes recent communication activities).", "required": false, "schema": { "type": "string", "example": "engagement,activity" } } ], "responses": { "200": { "description": "Contact context retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactContextResponse" }, "example": { "data": { "id": "cnt_abc123", "name": "John", "last_name": "Doe", "numbers": [ "+1234567890" ], "emails": [ "john@acme.com" ], "company": { "name": "Acme Corp", "id": "com_xyz789" }, "job_title": "CEO", "website": "https://acme.com", "integration_data": { "HUBSPOT": { "contact_id": "12345", "deal_stage": "Negotiation" } }, "custom_properties": { "preferred_language": "English", "vip_status": true }, "engagement": "ENGAGED", "activity": [ { "type": "INBOUND_CALL", "made_by": "John Doe", "made_at": "2024-01-15T10:30:00", "allo_number": "+1234567890", "content": null }, { "type": "OUTBOUND_SMS", "made_by": "Jane Smith", "made_at": "2024-01-14T09:15:00", "allo_number": null, "content": "Thank you for your call. We will follow up shortly." } ], "conversation_url": "/v1/api/contact/cnt_abc123/conversation" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "CONTACT_NOT_FOUND", "details": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/api/contact/{contact_id}/conversation": { "get": { "summary": "Search Conversations", "description": "Search calls and SMS for a specific contact. Returns paginated results including call recordings, transcripts, AI summaries, and text messages.", "operationId": "getContactConversation", "tags": [ "Conversations" ], "security": [ { "CallsAuth": [] } ], "parameters": [ { "name": "contact_id", "in": "path", "description": "The unique identifier of the contact (e.g., \"cnt_abc123\")", "required": true, "schema": { "type": "string", "example": "cnt_abc123" } }, { "name": "size", "in": "query", "description": "Number of results per page. Must be between 1 and 100.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "page", "in": "query", "description": "Page number (0-indexed).", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "allo_number", "in": "query", "description": "Filter conversations by a specific Allo phone number (E.164 format).", "required": false, "schema": { "type": "string", "example": "+1234567890" } } ], "responses": { "200": { "description": "Conversation retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetContactConversationResponse" }, "example": { "data": { "results": [ { "type": "CALL", "call": { "id": "call_abc123", "from_number": "+1234567890", "to_number": "+0987654321", "length_in_minutes": 5.5, "type": "INBOUND", "summary": "Customer called about order status.", "tag": "support", "tags": [ "support", "order" ], "recording_url": "https://storage.withallo.com/recordings/abc123.mp3", "start_date": "2024-01-15T10:30:00", "transcript": [ { "source": "AGENT", "text": "Hello, how can I help you today?", "time": "2024-01-15T10:30:05", "start_seconds": 5, "end_seconds": 8.5 } ] }, "message": null }, { "type": "TEXT_MESSAGE", "call": null, "message": { "from_number": "+1234567890", "to_number": "+0987654321", "type": "OUTBOUND", "content": "Thank you for contacting us!", "start_date": "2024-01-15T11:00:00" } } ], "metadata": { "pagination": { "total_pages": 5, "current_page": 0 } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "CONTACT_NOT_FOUND", "details": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/api/conversations": { "get": { "summary": "List conversations", "description": "Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity.", "operationId": "listConversations", "tags": [ "Conversations" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "allo_number", "in": "query", "required": true, "description": "Filter by Allo number (E.164). Required — list your numbers with GET /v2/api/numbers to find the right one.", "schema": { "type": "string", "example": "+14155550100" } }, { "name": "last_activity_since", "in": "query", "description": "Only return conversations with activity after this timestamp (ISO 8601). Ideal for incremental sync.", "schema": { "type": "string", "format": "date-time", "example": "2026-04-20T10:00:00Z" } }, { "name": "unread", "in": "query", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "$ref": "#/components/parameters/Extend" } ], "responses": { "200": { "description": "List of conversations", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationSummary" } } } }, { "$ref": "#/components/schemas/PaginatedResponse" } ] }, "example": { "data": [ { "contact_number": "+14155551234", "contacts": [ { "id": "cnt-abc123", "name": "Sarah Johnson", "company": { "id": "com-xyz789", "name": "Acme Corp" }, "deals": [ { "id": "dea-def456", "name": "Enterprise Plan", "status": "open" } ] } ], "last_activity": "2026-04-21T14:30:00Z", "last_item": { "id": "cll-abc123", "type": "CALL", "direction": "INBOUND", "date": "2026-04-21T14:30:00Z", "summary": "Customer called about upgrading their plan.", "result": "ANSWERED", "duration": 145 } } ], "pagination": { "page": 1, "size": 20, "total_count": 156, "total_pages": 8, "has_more": true } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/conversations/items/search": { "post": { "summary": "Search all conversations", "description": "Search and filter items across all conversations. Supports keyword search across transcripts, summaries, and message content.", "operationId": "searchAllConversations", "tags": [ "Conversations" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemSearchRequest" }, "example": { "search": "billing issues", "type": "CALL", "sort": "RELEVANCE", "date": { "from": "2026-01-01", "to": "2026-04-21" } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationItem" } } } }, { "$ref": "#/components/schemas/PaginatedResponse" } ] }, "example": { "data": [ { "id": "cll-abc123", "type": "CALL", "direction": "INBOUND", "allo_number": "+14155550100", "contact_number": "+14155551234", "contacts": [ { "id": "cnt-abc123", "name": "Sarah Johnson" } ], "user": { "id": "usr-abc123", "name": "Alex Kim" }, "date": "2026-04-21T14:30:00Z", "duration": 145, "result": "ANSWERED", "recording_url": "https://storage.withallo.com/recordings/cll-abc123.mp3", "summary": "Customer called about a billing issue on their last invoice.", "tags": [ "billing", "support" ] } ], "pagination": { "page": 1, "size": 20, "total_count": 1, "total_pages": 1, "has_more": false } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/conversations/items/{id}": { "get": { "summary": "Get conversation item", "description": "Returns a single call or SMS message by its ID.", "operationId": "getConversationItem", "tags": [ "Conversations" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item ID (`cll-*` for calls, `msg-*` for messages)", "schema": { "type": "string", "example": "cll-abc123" } }, { "$ref": "#/components/parameters/Extend" } ], "responses": { "200": { "description": "Conversation item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationItem" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/conversations/items/{id}/summary": { "patch": { "summary": "Update call summary", "description": "Replace the markdown content of a call's AI-generated summary.\n\nOnly call items have summaries — passing an SMS ID (`msg-*`) returns `400 INVALID_ITEM_ID`. If multiple completed summary templates exist on the same call, set `template_key` to disambiguate.", "operationId": "updateCallSummary", "tags": [ "Conversations" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID (`cll-*`)", "schema": { "type": "string", "example": "cll-abc123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Full replacement markdown content. Max 100,000 characters.", "maxLength": 100000 }, "template_key": { "type": "string", "nullable": true, "enum": [ "MARKDOWN_CLASSIC", "MARKDOWN_SHORT_CALL" ], "description": "Required only when the call has more than one completed summary template." } }, "required": [ "content" ] }, "example": { "content": "# Summary\n\nCustomer asked about pricing for the Pro plan and confirmed a follow-up call next Tuesday." } } } }, "responses": { "200": { "description": "Updated summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CallSummary" } } }, "example": { "data": { "id": "cll-abc123", "content": "# Summary\n\nCustomer asked about pricing for the Pro plan and confirmed a follow-up call next Tuesday.", "version": 4, "updated_at": "2026-05-12T14:32:11", "updated_by": { "id": "usr-abc123", "name": "Alex Kim" } } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/me": { "get": { "summary": "Me", "description": "Returns information about the authenticated API key: its scopes, available endpoints, team, and rate limits. No specific scope is required — any valid API key can call this endpoint.\n\nAgents should call this endpoint first to discover their capabilities before making other API calls.", "operationId": "getMe", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "API key info retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeResponse" } } }, "example": { "data": { "api_key_id": "api-abc123def456", "scopes": [ "CONVERSATIONS_READ", "PHONE_NUMBERS_READ", "TAGS_READ", "TAGS_WRITE", "USERS_READ" ], "endpoints": [ { "method": "GET", "path": "/v2/api/conversations", "description": "List conversations grouped by contact number", "scope": "CONVERSATIONS_READ" }, { "method": "POST", "path": "/v2/api/conversations/items/search", "description": "Search calls and SMS with filters and keyword search", "scope": "CONVERSATIONS_READ" }, { "method": "GET", "path": "/v2/api/tags", "description": "List all available tags", "scope": "TAGS_READ" }, { "method": "GET", "path": "/v2/api/users", "description": "List team members with roles and assigned numbers", "scope": "USERS_READ" }, { "method": "GET", "path": "/v2/api/numbers", "description": "List phone numbers with capabilities and member access", "scope": "PHONE_NUMBERS_READ" } ], "team": { "id": "team-xyz789", "name": "Acme Sales" }, "rate_limits": { "read_per_second": 20, "write_per_second": 5 } } } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v2/api/users": { "get": { "summary": "List users", "description": "Returns all team members.", "operationId": "listUsers", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "role", "in": "query", "schema": { "type": "string", "enum": [ "ADMIN", "MANAGER", "MEMBER" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ACTIVE", "BLOCKED" ], "default": "ACTIVE" } } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } }, "example": { "data": [ { "id": "usr-abc123", "name": "Alex Kim", "email": "alex@acme.com", "role": "ADMIN", "status": "ACTIVE", "image_url": "https://storage.withallo.com/avatars/usr-abc123.jpg" }, { "id": "usr-def456", "name": "Jordan Lee", "email": "jordan@acme.com", "role": "MEMBER", "status": "ACTIVE", "image_url": null } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/users/{id}": { "get": { "summary": "Get user", "description": "Returns a single team member by their ID.", "operationId": "getUser", "tags": [ "Users" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "usr-abc123" } } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/tags": { "get": { "summary": "List tags", "description": "Returns all tags configured on the team.", "operationId": "listTags", "tags": [ "Tags" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of tags", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } }, "example": { "data": [ { "id": "tag-abc123", "name": "qualified", "color": "#00AA00" }, { "id": "tag-def456", "name": "follow_up", "color": "#FF8800" } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/numbers": { "get": { "summary": "List phone numbers", "description": "Returns all phone numbers and sender IDs on your team.", "operationId": "listNumbers", "tags": [ "Phone Numbers" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of phone numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "example": { "data": [ { "number": "+14155550100", "name": "Sales US", "country": "US", "type": "NUMBER", "capabilities": [ "VOICE", "SMS", "MMS" ], "users": [ { "id": "usr-abc123", "name": "Adrien", "email": "adrien@company.com" } ] }, { "number": "+33612345678", "name": "Support FR", "country": "FR", "type": "NUMBER", "capabilities": [ "VOICE" ], "users": [ { "id": "usr-abc123", "name": "Adrien", "email": "adrien@company.com" }, { "id": "usr-def456", "name": "Marie", "email": "marie@company.com" } ] }, { "number": null, "name": "Acme Corp", "country": "FR", "type": "SENDER_ID", "capabilities": [ "SMS" ], "users": [] } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/conversations/items/{id}/tags": { "post": { "summary": "Add tags", "description": "Add one or more tags to a conversation item.", "operationId": "addTags", "tags": [ "Tags" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID (`cll-*`)", "schema": { "type": "string", "example": "cll-abc123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag keys to add" } }, "required": [ "tags" ] }, "example": { "tags": [ "qualified", "follow_up" ] } } } }, "responses": { "200": { "description": "Tags added successfully" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/conversations/items/{id}/tags/{tag}": { "delete": { "summary": "Remove tag", "description": "Remove a tag from a conversation item.", "operationId": "removeTag", "tags": [ "Tags" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call ID (`cll-*`)", "schema": { "type": "string", "example": "cll-abc123" } }, { "name": "tag", "in": "path", "required": true, "description": "Tag key to remove", "schema": { "type": "string", "example": "qualified" } } ], "responses": { "200": { "description": "Tag removed successfully" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/conversations/items/batch": { "post": { "summary": "Get many conversation items", "description": "Returns multiple conversation items by their IDs in a single request. Use this to fetch full details (summary, tags, recording, etc.) for items returned by the analytics drilldown or any other list.", "operationId": "batchGetConversationItems", "tags": [ "Conversations" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Array of conversation item IDs (max 100)", "maxItems": 100 } }, "required": [ "ids" ] }, "example": { "ids": [ "cll-abc123", "cll-def456", "cll-ghi789" ] } } } }, "responses": { "200": { "description": "Conversation items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationItem" } } } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/dialing-queues/current": { "get": { "summary": "List current queue numbers", "description": "Returns the numbers in the Power Dialer queue currently assigned to the authenticated user, paginated and ordered by `position` ascending. `data` is the list of numbers (use `page`/`size` and read `pagination` to page through them); the `queue` key carries the queue's metadata (id, name, settings) without its numbers. To target a teammate's queue, pass either `user_id` or `email` as a query parameter (`user_id` wins when both are sent); the target must belong to the same team as the API key owner. When the user has no queue, the response is `200` with an empty `data` array, a zeroed `pagination`, and no `queue` (not a `404`).", "operationId": "getCurrentDialingQueue", "tags": [ "Power Dialer" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "description": "ID of a teammate to read the queue for. Resolve teammate ids via [GET /v2/api/users](/en/v2/api-reference/users/list-users). Wins over `email` when both are provided.", "schema": { "type": "string", "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220" } }, { "name": "email", "in": "query", "required": false, "description": "Email of a teammate to read the queue for. Ignored when `user_id` is also supplied.", "schema": { "type": "string", "format": "email", "example": "teammate@acme.com" } }, { "name": "page", "in": "query", "required": false, "description": "1-indexed page number for the queue's `numbers`.", "schema": { "type": "integer", "default": 1, "minimum": 1, "example": 1 } }, { "name": "size", "in": "query", "required": false, "description": "Number of `numbers` per page (max 100).", "schema": { "type": "integer", "default": 20, "maximum": 100, "example": 20 } } ], "responses": { "200": { "description": "A page of the current queue's numbers, ordered by position. Empty `data` array with zeroed `pagination` when the user has no queue.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueueNumber" } }, "queue": { "$ref": "#/components/schemas/DialingQueueMeta" } } }, { "$ref": "#/components/schemas/PaginatedResponse" } ] }, "example": { "data": [ { "number_to": "+12125550010", "position": 0, "created_at": "2026-04-30T10:00:00", "updated_at": "2026-04-30T10:00:00", "call_start_date": null, "call_id": null, "routing_result": null, "sync_status": "NOT_SYNCED" } ], "pagination": { "page": 1, "size": 20, "total_count": 137, "total_pages": 7, "has_more": true }, "queue": { "id": "pdl_2xGh7kLmNpQr", "name": "My Queue", "creator_id": "usr_abc123", "assignee_id": "usr_abc123", "voicemail_handling": "NO_SKIP", "do_not_disturb": "DISABLED", "created_at": "2026-04-30T10:00:00", "updated_at": "2026-04-30T10:00:00" } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "description": "Assignee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "assignee_not_found": { "summary": "user_id or email does not match a teammate", "value": { "error": { "type": "not_found_error", "code": "ASSIGNEE_NOT_FOUND", "message": "No team member found for the provided 'user_id' or 'email'.", "retryable": false, "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email." } } } } } } }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "post": { "summary": "Reset current queue", "description": "Creates a fresh, empty queue assigned to the authenticated user. Any older queue with the same assignee stops being returned by `GET /current` (the newest queue wins). Send `user_id` or `email` to create the queue for a teammate instead — the API key owner is recorded as `creator_id`, the teammate as `assignee_id`. `user_id` wins when both are provided.", "operationId": "resetCurrentDialingQueue", "tags": [ "Power Dialer" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetDialingQueueRequest" }, "examples": { "self": { "summary": "Reset your own queue", "value": { "name": "Monday cold calls" } }, "teammate_by_pid": { "summary": "Reset a teammate's queue by user_id", "value": { "name": "Monday cold calls", "user_id": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220" } }, "teammate_by_email": { "summary": "Reset a teammate's queue by email", "value": { "name": "Monday cold calls", "email": "teammate@acme.com" } } } } } }, "responses": { "200": { "description": "The newly created (empty) queue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DialingQueue" } } }, "example": { "data": { "id": "pdl_2xGh7kLmNpQr", "name": "Monday cold calls", "creator_id": "usr_abc123", "assignee_id": "usr_abc123", "voicemail_handling": "NO_SKIP", "do_not_disturb": "DISABLED", "numbers": [], "created_at": "2026-05-06T10:00:00", "updated_at": "2026-05-06T10:00:00" } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "description": "Authenticated user or assignee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "user_not_found": { "summary": "Authenticated user not found", "value": { "error": { "type": "not_found_error", "code": "USER_NOT_FOUND", "message": "User not found.", "retryable": false } } }, "assignee_not_found": { "summary": "user_id or email does not match a teammate", "value": { "error": { "type": "not_found_error", "code": "ASSIGNEE_NOT_FOUND", "message": "No team member found for the provided 'user_id' or 'email'.", "retryable": false, "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email." } } } } } } }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "patch": { "summary": "Upsert current queue", "description": "Creates or updates the config of the queue assigned to the authenticated user. Send `user_id` or `email` to act on a teammate's queue instead — `user_id` wins when both are provided.", "operationId": "upsertCurrentDialingQueue", "tags": [ "Power Dialer" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertDialingQueueRequest" }, "examples": { "self": { "summary": "Update your own queue", "value": { "name": "Cold Calls" } }, "teammate_by_pid": { "summary": "Update a teammate's queue by user_id", "value": { "name": "Cold Calls", "user_id": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220" } } } } } }, "responses": { "200": { "description": "Updated queue", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DialingQueue" } } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "description": "Assignee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "ASSIGNEE_NOT_FOUND", "message": "No team member found for the provided 'user_id' or 'email'.", "retryable": false, "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email." } } } } }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/dialing-queues/current/numbers": { "post": { "summary": "Append numbers to queue", "description": "Appends phone numbers to the Power Dialer queue assigned to the authenticated user. Creates the queue implicitly if none exists. Send `user_id` or `email` to append to a teammate's queue — if that teammate has no current queue, one is created with the API key owner as `creator_id` and the teammate as `assignee_id`. `user_id` wins when both are provided.", "operationId": "appendDialingQueueNumbers", "tags": [ "Power Dialer" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendQueueNumbersRequest" }, "examples": { "self": { "summary": "Append to your own queue", "value": { "numbers": [ { "number": "+1 (212) 555-0010", "name": "John", "last_name": "Doe", "company": "Acme Inc", "job_title": "Sales Manager", "emails": [ "john.doe@acme.com" ], "website": "https://acme.com" }, { "number": "+33 6 12 34 56 78", "name": "Marie", "last_name": "Dupont", "company": "Acme Inc" }, { "number": "+44 20 7946 0958" } ] } }, "teammate_by_pid": { "summary": "Append to a teammate's queue by user_id", "value": { "user_id": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220", "numbers": [ { "number": "+12125550010", "name": "John", "last_name": "Doe" } ] } }, "teammate_by_email": { "summary": "Append to a teammate's queue by email", "value": { "email": "teammate@acme.com", "numbers": [ { "number": "+12125550010", "name": "John", "last_name": "Doe" } ] } } } } } }, "responses": { "200": { "description": "Numbers appended", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppendQueueNumbersResponse" } } }, "example": { "data": { "added": [ { "number_to": "+12125550010", "position": 0, "created_at": "2026-04-30T10:00:00", "updated_at": "2026-04-30T10:00:00" }, { "number_to": "+33612345678", "position": 1, "created_at": "2026-04-30T10:00:00", "updated_at": "2026-04-30T10:00:00" } ], "skipped": [] } } } } }, "400": { "description": "Queue limit reached or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "type": "validation_error", "code": "DIALING_QUEUE_LIMIT_REACHED", "message": "The dialing queue cannot exceed 1,000 numbers.", "retryable": false } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "description": "Assignee not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "type": "not_found_error", "code": "ASSIGNEE_NOT_FOUND", "message": "No team member found for the provided 'user_id' or 'email'.", "retryable": false, "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email." } } } } }, "409": { "description": "Concurrent append conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "example": { "error": { "type": "conflict_error", "code": "DIALING_QUEUE_APPEND_CONFLICT", "message": "A concurrent append to this queue caused a position conflict.", "retryable": false, "suggestion": "Retry the request — the conflict resolves on the next attempt." } } } } }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "delete": { "summary": "Clear queue numbers", "description": "Removes numbers from the queue assigned to the authenticated user. Exactly one filter must be supplied via query string: `number` (E.164), `position` (0-based index), `number` + `position` together (delete a specific occurrence of a duplicate), or `unassigned=true` (remove every entry that has not been called yet). Combining `unassigned` with `number` or `position` is rejected. Pass `user_id` or `email` to clear a teammate's queue instead — `user_id` wins when both are provided.", "operationId": "clearDialingQueueNumbers", "tags": [ "Power Dialer" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "number", "in": "query", "required": false, "description": "Phone number to remove (any format — normalized to E.164). Removes every entry matching this number unless `position` is also supplied.", "schema": { "type": "string", "example": "+12125550010" } }, { "name": "position", "in": "query", "required": false, "description": "0-based position to remove. Combine with `number` to disambiguate when the same number appears more than once.", "schema": { "type": "integer", "minimum": 0, "example": 3 } }, { "name": "unassigned", "in": "query", "required": false, "description": "When `true`, removes every queue entry that has not been called yet. Cannot be combined with `number` or `position`.", "schema": { "type": "boolean", "example": true } }, { "name": "user_id", "in": "query", "required": false, "description": "ID of a teammate whose queue to clear. Resolve teammate ids via [GET /v2/api/users](/en/v2/api-reference/users/list-users). Wins over `email` when both are provided.", "schema": { "type": "string", "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220" } }, { "name": "email", "in": "query", "required": false, "description": "Email of a teammate whose queue to clear. Ignored when `user_id` is also supplied.", "schema": { "type": "string", "format": "email", "example": "teammate@acme.com" } } ], "responses": { "200": { "description": "Numbers removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ClearQueueNumbersResponse" } } }, "example": { "data": { "removed": 4 } } } } }, "400": { "description": "Filter missing or conflicting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "filter_required": { "summary": "No filter supplied", "value": { "error": { "type": "validation_error", "code": "DIALING_QUEUE_DELETE_FILTER_REQUIRED", "message": "Provide at least one of 'number', 'position', or 'unassigned=true' to clear queue numbers.", "retryable": false, "suggestion": "Add 'number', 'position', or 'unassigned=true' as a query parameter." } } }, "filter_conflict": { "summary": "unassigned combined with number/position", "value": { "error": { "type": "validation_error", "code": "DIALING_QUEUE_DELETE_FILTER_CONFLICT", "message": "'unassigned=true' cannot be combined with 'number' or 'position'.", "retryable": false, "suggestion": "Use 'unassigned=true' alone, or remove it and rely on 'number'/'position'." } } }, "invalid_phone_number": { "summary": "number is not a valid E.164 number", "value": { "error": { "type": "validation_error", "code": "INVALID_PHONE_NUMBER", "message": "The phone number '+1212' is not a valid E.164 number.", "retryable": false, "param": "number", "suggestion": "Provide a valid E.164 phone number (e.g., +33612345678)." } } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "description": "Queue or position not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "queue_not_found": { "summary": "User has no Power Dialer queue", "value": { "error": { "type": "not_found_error", "code": "DIALING_QUEUE_NOT_FOUND", "message": "No dialing queue found for the authenticated user.", "retryable": false, "suggestion": "Create a queue by appending numbers with POST /v2/api/dialing-queues/current/numbers." } } }, "position_not_found": { "summary": "No entry at the requested position", "value": { "error": { "type": "not_found_error", "code": "QUEUE_NUMBER_POSITION_NOT_FOUND", "message": "No queue number found at position 7.", "retryable": false, "param": "position", "suggestion": "Fetch the current queue with GET /v2/api/dialing-queues/current to see existing positions." } } }, "assignee_not_found": { "summary": "user_id or email does not match a teammate", "value": { "error": { "type": "not_found_error", "code": "ASSIGNEE_NOT_FOUND", "message": "No team member found for the provided 'user_id' or 'email'.", "retryable": false, "suggestion": "List your teammates with GET /v2/api/users and use one of their ids as 'user_id', or pass a team-member email." } } } } } } }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/analytics/overview": { "post": { "summary": "Team metrics", "description": "Returns team-wide KPIs with period-over-period comparison and a per-user breakdown. Covers all calls (inbound + outbound).", "operationId": "getTeamMetrics", "tags": [ "Analytics" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsBaseRequest" }, "example": { "date": { "from": "2026-03-25", "to": "2026-04-21" }, "compare_date": { "from": "2026-02-25", "to": "2026-03-24" }, "user_ids": [ "usr-abc123", "usr-def456" ] } } } }, "responses": { "200": { "description": "Team summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "date": { "$ref": "#/components/schemas/AnalyticsDateRange" }, "compare_date": { "$ref": "#/components/schemas/AnalyticsDateRange" }, "summary": { "type": "object", "properties": { "total_calls": { "$ref": "#/components/schemas/MetricValue" }, "talk_time_seconds": { "$ref": "#/components/schemas/MetricValue" }, "calls_over_1_min": { "$ref": "#/components/schemas/MetricValue" }, "answer_rate": { "$ref": "#/components/schemas/MetricValue" } } }, "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/UserBreakdown" } }, "last_updated": { "type": "string", "format": "date-time", "description": "When the metrics were last updated" } } } } }, "example": { "data": { "date": { "from": "2026-03-25", "to": "2026-04-21" }, "compare_date": { "from": "2026-02-25", "to": "2026-03-24" }, "summary": { "total_calls": { "value": 2899, "previous": 2512, "change": 0.15 }, "talk_time_seconds": { "value": 81720, "previous": 103380, "change": -0.21 }, "calls_over_1_min": { "value": 290, "previous": 310, "change": -0.06 }, "answer_rate": { "value": 0.503, "previous": 0.46, "change": 0.09 } }, "breakdown": [ { "user": { "id": "usr-abc123", "name": "Adrien Gaucher", "email": "adrien@company.com" }, "calls": { "value": 673, "change": -0.05 }, "talk_time_seconds": { "value": 38460, "change": -0.11 }, "calls_over_1_min": { "value": 141, "change": -0.1 }, "answer_rate": { "value": 0.645, "change": -0.03 } } ], "last_updated": "2026-04-21T19:07:00Z" } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/analytics/outbound": { "post": { "summary": "Outbound metrics", "description": "Returns outbound call metrics: dial funnel (dials → connected → conversations → conversions), time series, heatmap, leaderboard, and time spent metrics.", "operationId": "getAnalyticsOutbound", "tags": [ "Analytics" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundAnalyticsRequest" }, "example": { "date": { "from": "2026-03-25", "to": "2026-04-21" }, "compare_date": { "from": "2026-02-25", "to": "2026-03-24" }, "tags": [ "meeting_booked" ], "granularity": "DAY" } } } }, "responses": { "200": { "description": "Outbound analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "date": { "$ref": "#/components/schemas/AnalyticsDateRange" }, "compare_date": { "$ref": "#/components/schemas/AnalyticsDateRange" }, "funnel": { "type": "object", "properties": { "dials": { "$ref": "#/components/schemas/FunnelStage" }, "connected": { "$ref": "#/components/schemas/FunnelStage" }, "conversations": { "$ref": "#/components/schemas/FunnelStage" }, "conversions": { "$ref": "#/components/schemas/FunnelStage" } } }, "time_series": { "type": "object", "properties": { "dials": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" } }, "connected": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" } }, "connection_rate": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" } }, "conversions": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesPoint" } } } }, "heatmap": { "type": "object", "properties": { "dials": { "type": "array", "items": { "$ref": "#/components/schemas/HeatmapCell" } }, "connected": { "type": "array", "items": { "$ref": "#/components/schemas/HeatmapCell" } }, "connection_rate": { "type": "array", "items": { "$ref": "#/components/schemas/HeatmapCell" } } } }, "leaderboard": { "type": "array", "items": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UserRef" }, "connected": { "type": "integer" } } } }, "time_spent": { "type": "object", "properties": { "avg_ringing_time_seconds": { "$ref": "#/components/schemas/MetricValue" }, "avg_conversation_time_seconds": { "$ref": "#/components/schemas/MetricValue" }, "total_conversation_time_seconds": { "$ref": "#/components/schemas/MetricValue" } } }, "last_updated": { "type": "string", "format": "date-time", "description": "When the metrics were last updated" }, "items": { "type": "object", "nullable": true, "description": "Drilldown call list. Only present when extend=items is set.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundDrilldownItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } } } }, "400": { "$ref": "#/components/responses/ApiValidationError" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/conversations/{contact_number}/action": { "put": { "summary": "Execute conversation action", "description": "Execute an action on a conversation.", "operationId": "executeConversationAction", "tags": [ "Conversations" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "contact_number", "in": "path", "required": true, "description": "The external phone number in E.164 format. URL-encode the `+` as `%2B`.", "schema": { "type": "string", "example": "+14155551234" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "READ", "UNREAD", "ARCHIVE", "UNARCHIVE" ], "description": "The action to execute." }, "allo_number": { "type": "string", "description": "Scope the action to a specific Allo number (E.164). Without this, the action applies across all lines.", "example": "+14155550100" } }, "required": [ "action" ] }, "example": { "action": "READ", "allo_number": "+14155550100" } } } }, "responses": { "200": { "description": "Action executed successfully" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/people": { "post": { "summary": "Create person", "description": "Creates a new person in your CRM.", "operationId": "createPerson", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePersonRequest" }, "example": { "name": "John", "last_name": "Doe", "job_title": "CEO", "website": "https://example.com", "address": "123 Main St", "numbers": [ "+33612345678" ], "emails": [ "john@example.com" ], "company_id": "com-xyz789" } } } }, "responses": { "200": { "description": "Person created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmPerson" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "409": { "$ref": "#/components/responses/ApiConflict" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/people/{id}": { "get": { "summary": "Get person", "description": "Returns a single person by ID.", "operationId": "getPerson", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Person ID (e.g., \"per-abc123\")", "schema": { "type": "string", "example": "per-abc123" } } ], "responses": { "200": { "description": "Person details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmPerson" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "put": { "summary": "Update person", "description": "Updates an existing person. Only provided fields will be updated.", "operationId": "updatePerson", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Person ID (e.g., \"per-abc123\")", "schema": { "type": "string", "example": "per-abc123" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePersonRequest" }, "example": { "job_title": "CTO" } } } }, "responses": { "200": { "description": "Person updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmPerson" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/people/search": { "post": { "summary": "Search people", "description": "Search and filter people in your CRM with advanced filtering, sorting, and pagination.", "operationId": "searchPeople", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPeopleRequest" }, "example": { "filters": { "job_title": "engineer", "company": "Acme" }, "sort": "NAME_ASC", "page": 1, "size": 20 } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmPerson" } } } }, { "$ref": "#/components/schemas/PaginatedResponse" } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/companies": { "post": { "summary": "Create company", "description": "Creates a new company in your CRM.", "operationId": "createCompany", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompanyRequest" }, "example": { "name": "Acme Corp", "website": "https://acme.com", "industry": "Technology" } } } }, "responses": { "201": { "description": "Company created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmCompany" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/companies/{id}": { "get": { "summary": "Get company", "description": "Returns a single company by ID.", "operationId": "getCompany", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID (e.g., \"com-xyz789\")", "schema": { "type": "string", "example": "com-xyz789" } } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmCompany" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "put": { "summary": "Update company", "description": "Updates an existing company. Only provided fields will be updated.", "operationId": "updateCompany", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Company ID (e.g., \"com-xyz789\")", "schema": { "type": "string", "example": "com-xyz789" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyRequest" }, "example": { "industry": "SaaS" } } } }, "responses": { "200": { "description": "Company updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmCompany" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/companies/search": { "post": { "summary": "Search companies", "description": "Search and filter companies in your CRM.", "operationId": "searchCompanies", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCompaniesRequest" }, "example": { "filters": { "name": "Acme", "industry": "Technology" }, "sort": "NAME_ASC", "page": 1, "size": 20 } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmCompany" } } } }, { "$ref": "#/components/schemas/PaginatedResponse" } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/deals": { "post": { "summary": "Create deal", "description": "Creates a new deal in your CRM.", "operationId": "createDeal", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDealRequest" }, "example": { "name": "Enterprise Plan", "status": "negotiation", "amount": 50000, "currency": "USD", "company_id": "com-xyz789" } } } }, "responses": { "201": { "description": "Deal created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/deals/{id}": { "get": { "summary": "Get deal", "description": "Returns a single deal by ID.", "operationId": "getDeal", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Deal ID (e.g., \"dea-def456\")", "schema": { "type": "string", "example": "dea-def456" } } ], "responses": { "200": { "description": "Deal details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "patch": { "summary": "Update deal", "description": "Updates an existing deal. Only provided fields will be updated.", "operationId": "updateDeal", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Deal ID (e.g., \"dea-def456\")", "schema": { "type": "string", "example": "dea-def456" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDealRequest" }, "example": { "status": "won", "closed_at": "2026-04-28T12:00:00" } } } }, "responses": { "200": { "description": "Deal updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CrmDeal" } } } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } }, "delete": { "summary": "Delete deal", "description": "Deletes a deal from your CRM.", "operationId": "deleteDeal", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Deal ID (e.g., \"dea-def456\")", "schema": { "type": "string", "example": "dea-def456" } } ], "responses": { "204": { "description": "Deal deleted" }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "404": { "$ref": "#/components/responses/ApiNotFound" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } }, "/v2/api/crm/deals/search": { "post": { "summary": "Search deals", "description": "Search and filter deals in your CRM.", "operationId": "searchDeals", "tags": [ "CRM" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchDealsRequest" }, "example": { "search": "Enterprise", "page": 1, "size": 20 } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrmDeal" } } } }, { "$ref": "#/components/schemas/PaginatedResponse" } ] } } } }, "401": { "$ref": "#/components/responses/ApiUnauthorized" }, "422": { "$ref": "#/components/responses/ApiValidationError" }, "429": { "$ref": "#/components/responses/ApiRateLimited" } } } } }, "components": { "securitySchemes": { "CallsAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Scope needed: `CONVERSATIONS_READ`" }, "ContactsAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Scope needed: `CONTACTS_READ`" }, "ContactsWriteAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Scope needed: `CONTACTS_READ_WRITE`" }, "SmsAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Scope needed: `SMS_SEND`" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization" } }, "schemas": { "SummaryTemplate": { "type": "object", "properties": { "id": { "type": "string", "example": "tst-abc123" }, "name": { "type": "string", "example": "Sales call" }, "call_context": { "type": "string", "nullable": true, "example": "B2B SaaS sales calls" }, "icon": { "type": "string", "nullable": true, "example": "📞" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryTemplateSection" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SummaryTemplateSection": { "type": "object", "properties": { "title": { "type": "string", "example": "Pain points" }, "instructions": { "type": "string", "example": "List the prospect's pain points" }, "order": { "type": "integer", "description": "0-based position of the section in the summary.", "example": 0 } } }, "MeResponse": { "type": "object", "description": "Information about the authenticated API key and its capabilities", "properties": { "api_key_id": { "type": "string", "description": "Unique identifier of this API key" }, "scopes": { "type": "array", "description": "Scopes granted to this key. Determines which endpoints appear in the endpoints list", "items": { "type": "string" } }, "endpoints": { "type": "array", "description": "Endpoints this key can call, filtered by granted scopes", "items": { "type": "object", "properties": { "method": { "type": "string", "description": "HTTP method", "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "path": { "type": "string", "description": "Endpoint path with parameter placeholders" }, "description": { "type": "string", "description": "What the endpoint does" }, "scope": { "type": "string", "description": "The scope that grants access to this endpoint" } } } }, "team": { "type": "object", "nullable": true, "description": "The team this key belongs to. Null if the user has no team", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "rate_limits": { "type": "object", "description": "Request rate limits for this API key", "properties": { "read_per_second": { "type": "integer", "description": "Maximum GET requests per second" }, "write_per_second": { "type": "integer", "description": "Maximum POST/PUT/DELETE requests per second" } } } } }, "SearchCallsApiResponse": { "type": "object", "description": "Standard response wrapper for paginated call results", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CallApiResponse" } }, "metadata": { "$ref": "#/components/schemas/SearchMetadata" } } } } }, "CallApiResponse": { "type": "object", "description": "A call record with details about the conversation", "properties": { "id": { "type": "string", "description": "Unique call identifier", "example": "call_abc123" }, "from_number": { "type": "string", "description": "Phone number that initiated the call (E.164 format or 'anonymous')", "example": "+1234567890" }, "to_number": { "type": "string", "nullable": true, "description": "Phone number that received the call", "example": "+0987654321" }, "length_in_minutes": { "type": "number", "format": "double", "description": "Duration of the call in minutes", "example": 5.5 }, "type": { "type": "string", "nullable": true, "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direction of the call" }, "result": { "type": "string", "enum": [ "ANSWERED", "VOICEMAIL", "TRANSFERRED_AI", "TRANSFERRED_EXTERNAL", "BLOCKED", "FAILED", "FAILED_EXTERNAL", "RECEIVED", "CLOSED" ], "description": "The outcome of the call. For outbound calls that reached voicemail, this will be VOICEMAIL regardless of the routing result. Common values: ANSWERED (call was answered), VOICEMAIL (call went to voicemail), TRANSFERRED_AI (transferred to AI agent), BLOCKED (call was blocked)", "example": "ANSWERED" }, "summary": { "type": "string", "nullable": true, "description": "AI-generated summary of the call conversation", "example": "Customer inquired about order status" }, "tag": { "type": "string", "nullable": true, "description": "Tag/category assigned to the call", "example": "support" }, "recording_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL to access the call recording" }, "start_date": { "type": "string", "format": "date-time", "description": "When the call started (ISO 8601 format)", "example": "2024-01-15T10:30:00" }, "transcript": { "type": "array", "nullable": true, "description": "Transcript of the call conversation", "items": { "$ref": "#/components/schemas/TranscriptRow" } } } }, "TranscriptRow": { "type": "object", "description": "A single row in the call transcript", "properties": { "source": { "type": "string", "enum": [ "AGENT", "EXTERNAL", "USER" ], "description": "The source of this transcript entry (AGENT for AI assistant, EXTERNAL for the caller, USER for the Allo user)" }, "text": { "type": "string", "description": "The transcribed text content", "example": "Hello, how can I help you today?" }, "time": { "type": "string", "format": "date-time", "description": "When this transcript entry occurred (ISO 8601 format)", "example": "2024-01-15T10:30:15" }, "start_seconds": { "type": "number", "format": "double", "nullable": true, "description": "Start time of this segment in seconds from call start", "example": 15 }, "end_seconds": { "type": "number", "format": "double", "nullable": true, "description": "End time of this segment in seconds from call start", "example": 18.5 } } }, "SearchContactsApiResponse": { "type": "object", "description": "Standard response wrapper for paginated contact results", "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ContactWithEngagementApiResponse" } }, "metadata": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "ContactWithEngagementApiResponse": { "type": "object", "description": "A contact record with engagement information", "properties": { "id": { "type": "string", "description": "Unique contact identifier", "example": "cnt_abc123" }, "name": { "type": "string", "nullable": true, "description": "First name", "example": "John" }, "last_name": { "type": "string", "nullable": true, "description": "Last name", "example": "Doe" }, "company": { "type": "object", "nullable": true, "description": "Company information", "properties": { "name": { "type": "string", "nullable": true, "example": "Acme Corp" }, "id": { "type": "string", "nullable": true, "example": "com_xyz789" } } }, "job_title": { "type": "string", "nullable": true, "description": "Job title", "example": "Manager" }, "website": { "type": "string", "nullable": true, "description": "Website URL" }, "status": { "type": "string", "nullable": true, "description": "Contact status", "example": "active" }, "is_archived": { "type": "boolean", "description": "Whether the contact is archived" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the contact was created" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the contact was last updated" }, "numbers": { "type": "array", "items": { "type": "string" }, "description": "List of phone numbers", "example": [ "+1234567890" ] }, "is_whitelisted": { "type": "boolean", "description": "Whether the contact is whitelisted" }, "last_activity_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date of the last activity" }, "engagement": { "type": "string", "nullable": true, "enum": [ "ENGAGED", "COOLING", "COLD" ], "description": "Engagement level of the contact" } } }, "CreateContactRequest": { "type": "object", "description": "Request body for creating a new contact", "required": [ "numbers" ], "properties": { "name": { "type": "string", "nullable": true, "description": "First name", "example": "John" }, "last_name": { "type": "string", "nullable": true, "description": "Last name", "example": "Doe" }, "job_title": { "type": "string", "nullable": true, "description": "Job title", "example": "CEO" }, "website": { "type": "string", "nullable": true, "description": "Website URL", "example": "https://acme.com" }, "emails": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Email addresses", "example": [ "john@acme.com" ] }, "numbers": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers (at least one required, E.164 format)", "example": [ "+15551234567" ] } } }, "UpdateContactRequest": { "type": "object", "description": "Request body for updating an existing contact. Only provided fields will be updated.", "properties": { "name": { "type": "string", "nullable": true, "description": "First name" }, "last_name": { "type": "string", "nullable": true, "description": "Last name" }, "job_title": { "type": "string", "nullable": true, "description": "Job title" }, "website": { "type": "string", "nullable": true, "description": "Website URL" }, "emails": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Email addresses (replaces all existing emails)" }, "numbers": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Phone numbers (replaces all existing numbers)" } } }, "ContactApiResponse": { "type": "object", "description": "Standard response wrapper for a single contact", "properties": { "data": { "$ref": "#/components/schemas/ContactWithEngagementApiResponse" } } }, "SendSMSRequest": { "type": "object", "description": "Request body for sending an SMS message (US)", "required": [ "from", "to", "message" ], "properties": { "from": { "type": "string", "description": "Your Allo phone number (must be owned by your account)", "example": "+1234567890" }, "to": { "type": "string", "description": "Recipient phone number (E.164 format, same country as 'from')", "example": "+0987654321" }, "message": { "type": "string", "description": "Message content", "minLength": 1, "maxLength": 1000, "example": "Hello, this is a test message" } } }, "SendSMSFranceRequest": { "type": "object", "description": "Request body for sending an SMS message in France using a verified Sender ID", "required": [ "sender_id", "to", "message" ], "properties": { "sender_id": { "type": "string", "description": "Your verified Sender ID (must be verified by the Allo team). This is an alphanumeric identifier that will appear as the sender of the SMS.", "example": "MyCompany" }, "to": { "type": "string", "description": "Recipient phone number in France (E.164 format, must start with +33)", "example": "+33612345678" }, "message": { "type": "string", "description": "Message content", "minLength": 1, "maxLength": 1000, "example": "Bonjour, ceci est un message de test" } } }, "SendSMSResponse": { "type": "object", "description": "Standard response wrapper for sent SMS", "properties": { "data": { "$ref": "#/components/schemas/TextMessageApiResponse" } } }, "TextMessageApiResponse": { "type": "object", "description": "Sent SMS message details", "properties": { "from_number": { "type": "string", "nullable": true, "description": "Phone number that sent the message. Null when sender_id is used instead.", "example": "+1234567890" }, "sender_id": { "type": "string", "nullable": true, "description": "Sender ID used for the message (alphanumeric identifier). Only populated when sending with a verified Sender ID (e.g., for France SMS). Null when from_number is used.", "example": "MyCompany" }, "to_number": { "type": "string", "description": "Phone number that received the message", "example": "+0987654321" }, "type": { "type": "string", "enum": [ "OUTBOUND" ], "description": "Direction of the message (always OUTBOUND for sent messages)" }, "content": { "type": "string", "description": "Content of the SMS message", "example": "Hello, this is a test message" }, "start_date": { "type": "string", "format": "date-time", "description": "When the message was sent", "example": "2024-01-15T10:30:00" } } }, "SearchMetadata": { "type": "object", "description": "Pagination metadata for calls endpoint", "properties": { "total_pages": { "type": "integer", "example": 5 }, "current_page": { "type": "integer", "example": 0 } } }, "PaginationMeta": { "type": "object", "description": "Pagination metadata wrapper for contacts endpoint", "nullable": true, "properties": { "pagination": { "type": "object", "properties": { "total_pages": { "type": "integer", "example": 5 }, "current_page": { "type": "integer", "example": 0 } } } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code identifying the type of error" }, "details": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ErrorDetail" }, "description": "Additional error details, or null if not applicable" } } }, "ErrorDetail": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } }, "GetNumbersResponse": { "type": "object", "description": "Standard response wrapper containing list of phone numbers", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumberApiResponse" } } } }, "PhoneNumberApiResponse": { "type": "object", "description": "An Allo phone number with basic information", "properties": { "number": { "type": "string", "nullable": true, "description": "Phone number in E.164 format", "example": "+1234567890" }, "name": { "type": "string", "nullable": true, "description": "Display name for the phone number", "example": "Main Line" }, "country": { "type": "string", "nullable": true, "description": "Two-letter country code (ISO 3166-1 alpha-2)", "example": "US" }, "is_shared_number": { "type": "boolean", "description": "Whether this number is shared across team members" } } }, "GetContactContextResponse": { "type": "object", "description": "Standard response wrapper for contact context", "properties": { "data": { "$ref": "#/components/schemas/ContactContextApiResponse" } } }, "ContactContextApiResponse": { "type": "object", "description": "Comprehensive contact context including integration data and activity", "properties": { "id": { "type": "string", "description": "Unique contact identifier", "example": "cnt_abc123" }, "name": { "type": "string", "nullable": true, "description": "First name", "example": "John" }, "last_name": { "type": "string", "nullable": true, "description": "Last name", "example": "Doe" }, "numbers": { "type": "array", "items": { "type": "string" }, "description": "List of phone numbers", "example": [ "+1234567890" ] }, "emails": { "type": "array", "items": { "type": "string" }, "description": "List of email addresses", "example": [ "john@acme.com" ] }, "company": { "type": "object", "nullable": true, "description": "Company information", "properties": { "name": { "type": "string", "nullable": true, "example": "Acme Corp" }, "id": { "type": "string", "nullable": true, "example": "com_xyz789" } } }, "job_title": { "type": "string", "nullable": true, "description": "Job title", "example": "CEO" }, "website": { "type": "string", "nullable": true, "description": "Website URL", "example": "https://acme.com" }, "integration_data": { "type": "object", "description": "Data from connected CRM integrations, keyed by integration type (e.g., HUBSPOT, SALESFORCE, PIPEDRIVE)", "additionalProperties": { "type": "object", "additionalProperties": true }, "example": { "HUBSPOT": { "contact_id": "12345", "deal_stage": "Negotiation" } } }, "custom_properties": { "type": "object", "nullable": true, "description": "Custom properties defined for this contact", "additionalProperties": true, "example": { "preferred_language": "English", "vip_status": true } }, "engagement": { "type": "string", "nullable": true, "enum": [ "ENGAGED", "COOLING", "COLD" ], "description": "Engagement level of the contact. Only included when `extend=engagement` is specified." }, "activity": { "type": "array", "nullable": true, "description": "Recent communication activities with this contact (calls and SMS). Only included when `extend=activity` is specified.", "items": { "$ref": "#/components/schemas/ContactActivityApiResponse" } }, "conversation_url": { "type": "string", "description": "URL path to retrieve the full conversation history for this contact", "example": "/v1/api/contact/cnt_abc123/conversation" } } }, "ContactActivityApiResponse": { "type": "object", "description": "A communication activity (call or SMS) with a contact", "required": [ "type", "made_at" ], "properties": { "type": { "type": "string", "enum": [ "INBOUND_CALL", "OUTBOUND_CALL", "INBOUND_SMS", "OUTBOUND_SMS" ], "description": "Type of communication activity. Possible values:\n- `INBOUND_CALL`: An incoming call from the contact\n- `OUTBOUND_CALL`: An outgoing call to the contact\n- `INBOUND_SMS`: An incoming SMS from the contact\n- `OUTBOUND_SMS`: An outgoing SMS to the contact" }, "made_by": { "type": "string", "nullable": true, "description": "Name of the team member who handled the activity", "example": "John Doe" }, "made_at": { "type": "string", "format": "date-time", "description": "When the activity occurred (ISO 8601 format)", "example": "2024-01-15T10:30:00" }, "allo_number": { "type": "string", "nullable": true, "description": "The Allo phone number used for the call. Only present for call activities (INBOUND_CALL, OUTBOUND_CALL).", "example": "+1234567890" }, "content": { "type": "string", "nullable": true, "description": "The content/text of the SMS message. Only present for SMS activities (INBOUND_SMS, OUTBOUND_SMS).", "example": "Hello, this is a test message" } } }, "GetContactConversationResponse": { "type": "object", "description": "Standard response wrapper for contact conversation", "properties": { "data": { "$ref": "#/components/schemas/ConversationApiResponse" } } }, "ConversationApiResponse": { "type": "object", "description": "Paginated conversation history with calls and messages", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationItemApiResponse" }, "description": "List of conversation items (calls and messages)" }, "metadata": { "$ref": "#/components/schemas/PaginationMeta" } } }, "ConversationItemApiResponse": { "type": "object", "description": "A single item in the conversation (either a call or a message)", "properties": { "type": { "type": "string", "enum": [ "CALL", "TEXT_MESSAGE" ], "description": "Type of conversation item" }, "call": { "$ref": "#/components/schemas/CallApiResponse", "nullable": true, "description": "Call details (only present when type is CALL)" }, "message": { "$ref": "#/components/schemas/TextMessageApiResponse", "nullable": true, "description": "Message details (only present when type is TEXT_MESSAGE)" } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "size": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "PaginatedResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "example": "cnt-abc123" }, "name": { "type": "string", "example": "Sarah Johnson" }, "company": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "com-xyz789" }, "name": { "type": "string", "example": "Acme Corp" } } }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "dea-def456" }, "name": { "type": "string", "example": "Enterprise Plan" }, "status": { "type": "string", "enum": [ "OPEN", "WON", "LOST" ] } } } } } }, "UserRef": { "type": "object", "properties": { "id": { "type": "string", "example": "usr-abc123" }, "name": { "type": "string", "example": "John" }, "email": { "type": "string", "example": "john@acme.com" } } }, "TranscriptEntry": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "USER", "EXTERNAL" ] }, "time": { "type": "string", "format": "date-time" }, "text": { "type": "string" } } }, "ConversationItem": { "type": "object", "properties": { "id": { "type": "string", "example": "cll-abc123" }, "type": { "type": "string", "enum": [ "CALL", "SMS" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "allo_number": { "type": "string", "example": "+14155550100" }, "contact_number": { "type": "string", "example": "+14155551234" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "user": { "$ref": "#/components/schemas/UserRef" }, "date": { "type": "string", "format": "date-time" }, "duration": { "type": "integer", "nullable": true }, "result": { "type": "string", "nullable": true, "enum": [ "ANSWERED", "VOICEMAIL", "TRANSFERRED" ] }, "recording_url": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "transcript": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/TranscriptEntry" } }, "content": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "PENDING", "SENT", "DELIVERED", "FAILED" ] }, "message_type": { "type": "string", "nullable": true, "enum": [ "SMS", "MMS", "WHATSAPP" ] } } }, "ConversationSummary": { "type": "object", "properties": { "contact_number": { "type": "string", "example": "+14155551234" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "last_activity": { "type": "string", "format": "date-time" }, "last_item": { "$ref": "#/components/schemas/ConversationItem" } } }, "Conversation": { "type": "object", "properties": { "contact_number": { "type": "string", "example": "+14155551234" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "last_activity": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationItem" } } } }, "ItemSearchRequest": { "type": "object", "properties": { "allo_number": { "type": "string" }, "contact_number": { "type": "string" }, "user_id": { "type": "string" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "type": { "type": "string", "enum": [ "CALL", "SMS", "ALL" ], "default": "ALL" }, "result": { "type": "string", "enum": [ "ANSWERED", "VOICEMAIL", "TRANSFERRED" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "unread": { "type": "boolean" }, "unresponded": { "type": "boolean" }, "search": { "type": "string", "description": "Keyword search (not natural language). Extract keywords from the user's question. Terms are AND'd with prefix matching — 'billing refund' matches items containing both words, 'bill' matches 'billing'. Searches across call transcripts, summaries, and SMS content." }, "sort": { "type": "string", "enum": [ "DATE_DESC", "DATE_ASC", "RELEVANCE" ], "default": "DATE_DESC" }, "extend": { "type": "string" }, "page": { "type": "integer", "default": 1 }, "size": { "type": "integer", "default": 20, "maximum": 100 }, "date": { "$ref": "#/components/schemas/AnalyticsDateRange", "description": "Date range to filter by" } } }, "User": { "type": "object", "properties": { "id": { "type": "string", "example": "usr-abc123" }, "name": { "type": "string", "example": "Adrien" }, "email": { "type": "string", "example": "adrien@company.com" }, "role": { "type": "string", "enum": [ "ADMIN", "MANAGER", "MEMBER" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "BLOCKED" ] }, "image_url": { "type": "string", "nullable": true } } }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "example": "tag-abc123" }, "name": { "type": "string", "example": "qualified" }, "color": { "type": "string", "example": "#00AA00" } } }, "CallSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Call ID this summary belongs to", "example": "cll-abc123" }, "content": { "type": "string", "nullable": true, "description": "Markdown summary content" }, "version": { "type": "integer", "format": "int64", "description": "Optimistic-lock version. Increments on every successful update.", "example": 4 }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-05-12T14:32:11" }, "updated_by": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "usr-abc123" }, "name": { "type": "string", "nullable": true, "example": "Alex Kim" } } } } }, "PhoneNumber": { "type": "object", "properties": { "number": { "type": "string", "nullable": true, "description": "Phone number in E.164 format (null for sender IDs)", "example": "+14155550100" }, "name": { "type": "string", "nullable": true, "description": "Display label", "example": "Sales US" }, "country": { "type": "string", "nullable": true, "description": "ISO country code", "example": "US" }, "type": { "type": "string", "enum": [ "NUMBER", "SENDER_ID" ], "description": "Whether this is a phone number or a sender ID" }, "capabilities": { "type": "array", "description": "Supported capabilities for this number.", "items": { "type": "string", "enum": [ "VOICE", "SMS", "MMS" ] }, "example": [ "VOICE", "SMS", "MMS" ] }, "users": { "type": "array", "description": "Team members with access to this number", "items": { "$ref": "#/components/schemas/UserRef" } } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "request_id": { "type": "string" }, "retry_after_seconds": { "type": "integer", "nullable": true } } } } }, "MetricValue": { "type": "object", "properties": { "value": { "type": "number", "description": "Current period value" }, "previous": { "type": "number", "nullable": true, "description": "Previous period value" }, "change": { "type": "number", "nullable": true, "description": "Percentage change vs previous period (e.g. 0.15 = +15%)" } } }, "UserBreakdown": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UserRef" }, "calls": { "$ref": "#/components/schemas/MetricValue" }, "talk_time_seconds": { "$ref": "#/components/schemas/MetricValue" }, "calls_over_1_min": { "$ref": "#/components/schemas/MetricValue" }, "answer_rate": { "$ref": "#/components/schemas/MetricValue" } } }, "FunnelStage": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/MetricValue" }, "rate": { "type": "number", "nullable": true, "description": "Percentage of total dials (e.g. 0.29 = 29%)" } } }, "HeatmapCell": { "type": "object", "properties": { "day": { "type": "string", "enum": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ] }, "hour": { "type": "integer", "description": "Hour of day (0-23)" }, "value": { "type": "integer" } } }, "TimeSeriesPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "value": { "type": "number" } } }, "OutboundDrilldownItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Call ID", "example": "cll-abc123" }, "user": { "$ref": "#/components/schemas/UserRef" }, "allo_number": { "type": "string", "example": "+14155550100" }, "allo_number_label": { "type": "string", "example": "Sales US" }, "contact_number": { "type": "string", "example": "+14155551234" }, "stage": { "type": "string", "enum": [ "DIAL", "CONNECTED", "CONVERSATION", "CONVERSION" ] }, "voicemail": { "type": "boolean" }, "duration": { "type": "integer", "description": "Duration in seconds" }, "date": { "type": "string", "format": "date-time" } } }, "AnalyticsDateRange": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date", "description": "Start date", "example": "2026-03-25" }, "to": { "type": "string", "format": "date", "description": "End date", "example": "2026-04-21" } } }, "DialingQueue": { "type": "object", "description": "A user's Power Dialer queue with its configuration and numbers.", "properties": { "id": { "type": "string", "description": "Unique queue identifier (KSUID with `pdl` prefix)" }, "name": { "type": "string", "nullable": true, "description": "Display name of the queue" }, "creator_id": { "type": "string", "description": "User ID of the queue creator — the user (or API key owner) that created the queue." }, "assignee_id": { "type": "string", "nullable": true, "description": "User ID of the user expected to run the queue. `GET /current` returns the queue where this matches the authenticated user (or the user resolved from `user_id` / `email`). Defaults to the creator when none was specified at creation time." }, "voicemail_handling": { "type": "string", "enum": [ "SKIP", "NO_SKIP" ], "description": "How the Power Dialer reacts when the call lands in voicemail. `SKIP` advances to the next number; `NO_SKIP` keeps the user on the call." }, "do_not_disturb": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "When `ENABLED`, incoming calls are silenced while the queue is being run." }, "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/QueueNumber" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DialingQueueMeta": { "type": "object", "description": "Power Dialer queue metadata, without its numbers. Returned under the `queue` key of `GET /current`; the numbers themselves are the paginated `data`.", "properties": { "id": { "type": "string", "description": "Unique queue identifier (KSUID with `pdl` prefix)" }, "name": { "type": "string", "nullable": true, "description": "Display name of the queue" }, "creator_id": { "type": "string", "description": "User ID of the queue creator." }, "assignee_id": { "type": "string", "nullable": true, "description": "User ID of the user expected to run the queue." }, "voicemail_handling": { "type": "string", "enum": [ "SKIP", "NO_SKIP" ], "description": "How the Power Dialer reacts when the call lands in voicemail." }, "do_not_disturb": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "When `ENABLED`, incoming calls are silenced while the queue is being run." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "QueueNumber": { "type": "object", "description": "A phone number entry in a Power Dialer queue", "properties": { "number_to": { "type": "string", "description": "E.164 destination phone number" }, "position": { "type": "integer", "description": "Order within the queue (0-based)" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "call_start_date": { "type": "string", "format": "date-time", "nullable": true, "description": "When the user started calling this entry. `null` if the entry is still unassigned." }, "call_id": { "type": "string", "nullable": true, "description": "ID of the call placed for this entry (`cll-*`). `null` until a call is placed." }, "routing_result": { "type": "string", "nullable": true, "enum": [ "FAILED", "RECEIVED", "BLOCKED", "ANSWERED", "TRANSFERRED_BLAND", "TRANSFERRED_ELEVEN_LABS", "TRANSFERRED_EXTERNAL", "FAILED_EXTERNAL", "VOICEMAIL", "CLOSED" ], "description": "Final routing outcome of the call placed for this entry." }, "sync_status": { "type": "string", "enum": [ "NOT_SYNCED", "PROCESSING", "SYNCED" ], "description": "State of contact creation/sync for this entry." }, "detected_outbound_voicemail": { "type": "boolean", "nullable": true, "description": "Whether the call was detected as having reached a voicemail box." }, "not_reached_destination_reason": { "type": "string", "nullable": true, "enum": [ "BUSY", "CALLEE_TEMPORARILY_UNAVAILABLE", "RING_TIMEOUT", "NOT_IN_SERVICE", "DECLINED", "NETWORK_ERROR" ], "description": "Why the call did not reach the contact (only set when applicable)." }, "voicemail_left": { "type": "boolean", "nullable": true, "description": "Whether the user left a voicemail on this entry." } } }, "AppendQueueNumbersRequest": { "type": "object", "required": [ "numbers" ], "properties": { "numbers": { "type": "array", "description": "Numbers to append to the queue. Each entry requires a phone number; contact metadata is optional.", "minItems": 1, "items": { "type": "object", "required": [ "number" ], "properties": { "number": { "type": "string", "description": "Phone number in any format — will be normalized to E.164" }, "name": { "type": "string", "nullable": true, "description": "First name (optional — used to create or match a contact)" }, "last_name": { "type": "string", "nullable": true, "description": "Last name" }, "company": { "type": "string", "nullable": true, "description": "Company name — matched by name within the team (case-insensitive). If no matching company exists, one is created automatically." }, "website": { "type": "string", "nullable": true, "description": "Website URL" }, "job_title": { "type": "string", "nullable": true, "description": "Job title" }, "emails": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Email addresses" }, "addresses": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Physical addresses" } } } }, "user_id": { "type": "string", "nullable": true, "description": "Optional. ID of a teammate whose queue should receive the numbers. The teammate must belong to the same team as the API key owner. Wins over `email` when both are provided. Resolve teammate ids via [GET /v2/api/users](/en/v2/api-reference/users/list-users).", "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Optional. Email of a teammate whose queue should receive the numbers. Ignored when `user_id` is also supplied.", "example": "teammate@acme.com" } } }, "AppendQueueNumbersResponse": { "type": "object", "properties": { "added": { "type": "array", "description": "Numbers that were successfully appended", "items": { "$ref": "#/components/schemas/QueueNumber" } }, "skipped": { "type": "array", "description": "Numbers that were skipped (e.g. invalid format)", "items": { "type": "object", "properties": { "number": { "type": "string", "description": "The raw input number that was skipped" }, "reason": { "type": "string", "enum": [ "INVALID_PHONE_NUMBER" ], "description": "Why the number was skipped" } } } } } }, "UpsertDialingQueueRequest": { "type": "object", "description": "Creates or updates the queue config. All fields are optional — only the fields you supply are touched. Pass `user_id` or `email` to act on a teammate's queue instead.", "properties": { "name": { "type": "string", "nullable": true, "description": "New queue name (1–255 characters)", "minLength": 1, "maxLength": 255 }, "voicemail_handling": { "type": "string", "nullable": true, "enum": [ "SKIP", "NO_SKIP" ], "description": "How the Power Dialer reacts when the call hits voicemail." }, "do_not_disturb": { "type": "string", "nullable": true, "enum": [ "ENABLED", "DISABLED" ], "description": "Silence inbound calls while running the queue." }, "user_id": { "type": "string", "nullable": true, "description": "Optional. ID of a teammate whose queue config should be updated. The teammate must belong to the same team as the API key owner. Wins over `email` when both are provided.", "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Optional. Email of a teammate whose queue config should be updated. Ignored when `user_id` is also supplied.", "example": "teammate@acme.com" } } }, "ResetDialingQueueRequest": { "type": "object", "description": "Optional payload for resetting a queue. Send an empty body to reset your own queue without renaming.", "properties": { "name": { "type": "string", "nullable": true, "description": "Display name for the new queue (max 255 characters). Leave unset to create the queue without a name.", "maxLength": 255 }, "user_id": { "type": "string", "nullable": true, "description": "Optional. ID of a teammate the new queue should be assigned to. The API key owner is recorded as `creator_id`. The teammate must belong to the same team as the API key owner. Wins over `email` when both are provided.", "example": "usr-15BB68317A7F06F0C07A3BBD8F244102A6872220" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Optional. Email of a teammate the new queue should be assigned to. Ignored when `user_id` is also supplied.", "example": "teammate@acme.com" } } }, "ClearQueueNumbersResponse": { "type": "object", "description": "Result of clearing numbers from a Power Dialer queue.", "properties": { "removed": { "type": "integer", "description": "Number of queue entries that were removed.", "example": 4 } } }, "AnalyticsBaseRequest": { "type": "object", "required": [ "date" ], "properties": { "date": { "$ref": "#/components/schemas/AnalyticsDateRange" }, "compare_date": { "$ref": "#/components/schemas/AnalyticsDateRange", "description": "Comparison period. Metrics will include change vs this period." }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by user IDs. Cannot be combined with allo_numbers." }, "allo_numbers": { "type": "array", "items": { "type": "string" }, "description": "Filter by Allo numbers (E.164). Cannot be combined with user_ids." } } }, "OutboundAnalyticsRequest": { "allOf": [ { "$ref": "#/components/schemas/AnalyticsBaseRequest" }, { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag keys that define a conversion (e.g. ['meeting_booked', 'demo_scheduled'])" }, "granularity": { "type": "string", "enum": [ "DAY", "WEEK", "MONTH" ], "default": "DAY", "description": "Time series granularity" }, "extend": { "type": "string", "enum": [ "items" ], "description": "Include the list of outbound calls behind the funnel numbers. Requires `stage`." }, "stage": { "type": "string", "enum": [ "DIAL", "CONNECTED", "CONVERSATION", "CONVERSION" ], "description": "Filter drilldown items by funnel stage. Only used when `extend=items`." }, "page": { "type": "integer", "default": 1, "description": "Page number for drilldown items. Only used when `extend=items`." }, "size": { "type": "integer", "default": 20, "maximum": 100, "description": "Page size for drilldown items. Only used when `extend=items`." } } } ] }, "CrmCompanyRef": { "type": "object", "nullable": true, "description": "Embedded company reference", "properties": { "id": { "type": "string", "description": "Company ID", "example": "com-xyz789" }, "name": { "type": "string", "description": "Company name", "example": "Acme Corp" } } }, "CrmPerson": { "type": "object", "description": "A person in the CRM", "properties": { "id": { "type": "string", "description": "Unique person identifier", "example": "per-abc123" }, "name": { "type": "string", "nullable": true, "description": "First name", "example": "John" }, "last_name": { "type": "string", "nullable": true, "description": "Last name", "example": "Doe" }, "job_title": { "type": "string", "nullable": true, "description": "Job title", "example": "CEO" }, "website": { "type": "string", "nullable": true, "description": "Website URL", "example": "https://example.com" }, "address": { "type": "string", "nullable": true, "description": "Postal address", "example": "123 Main St" }, "numbers": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers in E.164 format", "example": [ "+33612345678" ] }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Email addresses", "example": [ "john@example.com" ] }, "company": { "$ref": "#/components/schemas/CrmCompanyRef" }, "interactions": { "type": "integer", "description": "Total number of interactions (calls + messages)", "example": 5 }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last activity", "example": "2026-04-28T10:30:00" }, "created_at": { "type": "string", "format": "date-time", "description": "When the person was created", "example": "2026-04-01T09:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the person was last updated", "example": "2026-04-28T10:30:00" } } }, "CrmCompany": { "type": "object", "description": "A company in the CRM", "properties": { "id": { "type": "string", "description": "Unique company identifier", "example": "com-xyz789" }, "name": { "type": "string", "description": "Company name", "example": "Acme Corp" }, "website": { "type": "string", "nullable": true, "description": "Company website URL", "example": "https://acme.com" }, "industry": { "type": "string", "nullable": true, "description": "Industry sector", "example": "Technology" }, "person_count": { "type": "integer", "description": "Number of people linked to this company", "example": 3 }, "interactions": { "type": "integer", "description": "Total number of interactions across all people in this company", "example": 12 }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last activity", "example": "2026-04-28T10:30:00" }, "created_at": { "type": "string", "format": "date-time", "description": "When the company was created", "example": "2026-04-01T09:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the company was last updated", "example": "2026-04-28T10:30:00" } } }, "CrmDeal": { "type": "object", "description": "A deal in the CRM", "properties": { "id": { "type": "string", "description": "Unique deal identifier", "example": "dea-def456" }, "name": { "type": "string", "description": "Deal name", "example": "Enterprise Plan" }, "status": { "type": "string", "nullable": true, "description": "Current deal status", "example": "negotiation" }, "amount": { "type": "number", "nullable": true, "description": "Deal monetary value", "example": 50000 }, "currency": { "type": "string", "nullable": true, "description": "Three-letter ISO 4217 currency code", "example": "USD", "minLength": 3, "maxLength": 3 }, "closed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the deal was closed (ISO 8601)", "example": null }, "company": { "$ref": "#/components/schemas/CrmCompanyRef" }, "created_at": { "type": "string", "format": "date-time", "description": "When the deal was created", "example": "2026-04-15T14:00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the deal was last updated", "example": "2026-04-28T10:30:00" } } }, "CreatePersonRequest": { "type": "object", "description": "Request body for creating a person", "required": [ "numbers" ], "properties": { "name": { "type": "string", "nullable": true, "description": "First name", "example": "John" }, "last_name": { "type": "string", "nullable": true, "description": "Last name", "example": "Doe" }, "job_title": { "type": "string", "nullable": true, "description": "Job title", "example": "CEO" }, "website": { "type": "string", "nullable": true, "description": "Website URL", "example": "https://example.com" }, "address": { "type": "string", "nullable": true, "description": "Postal address", "example": "123 Main St" }, "numbers": { "type": "array", "items": { "type": "string" }, "description": "Phone numbers in E.164 format. At least one number is required.", "minItems": 1, "example": [ "+33612345678" ] }, "emails": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Email addresses", "example": [ "john@example.com" ] }, "company_id": { "type": "string", "nullable": true, "description": "ID of the company to associate with", "example": "com-xyz789" }, "allow_duplicate_number": { "type": "boolean", "description": "When true, allows creating a person even if the phone numbers are already assigned to another person. Defaults to false.", "default": false } } }, "UpdatePersonRequest": { "type": "object", "description": "Request body for updating a person. Only provided fields will be updated.", "properties": { "name": { "type": "string", "nullable": true, "description": "First name" }, "last_name": { "type": "string", "nullable": true, "description": "Last name" }, "job_title": { "type": "string", "nullable": true, "description": "Job title" }, "website": { "type": "string", "nullable": true, "description": "Website URL" }, "address": { "type": "string", "nullable": true, "description": "Postal address" }, "numbers": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Phone numbers (replaces all existing numbers)" }, "emails": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Email addresses (replaces all existing emails)" }, "company_id": { "type": "string", "nullable": true, "description": "ID of the company to associate with" } } }, "SearchPeopleRequest": { "type": "object", "description": "Request body for searching people", "properties": { "filters": { "type": "object", "nullable": true, "description": "Named filters. All are combined with AND.", "properties": { "name": { "type": "string", "description": "Filter by first name (contains)" }, "last_name": { "type": "string", "description": "Filter by last name (contains)" }, "job_title": { "type": "string", "description": "Filter by job title (contains)" }, "website": { "type": "string", "description": "Filter by website (contains)" }, "company": { "type": "string", "description": "Filter by company name (contains)" }, "phone_number": { "type": "string", "description": "Filter by phone number (exact match)" }, "email": { "type": "string", "description": "Filter by email (contains)" }, "deal_status": { "type": "string", "description": "Filter by deal status (exact match)" } } }, "search": { "type": "string", "nullable": true, "description": "Free-text search across name, email, phone number, and company" }, "sort": { "type": "string", "nullable": true, "enum": [ "DATE_DESC", "DATE_ASC", "NAME_ASC", "NAME_DESC", "CREATED_DESC", "CREATED_ASC" ], "description": "Sort order (default: DATE_DESC)" }, "page": { "type": "integer", "default": 1, "description": "Page number (1-indexed)" }, "size": { "type": "integer", "default": 20, "maximum": 100, "description": "Results per page" } } }, "CreateCompanyRequest": { "type": "object", "description": "Request body for creating a company", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Company name", "example": "Acme Corp" }, "website": { "type": "string", "nullable": true, "description": "Company website URL", "example": "https://acme.com" }, "industry": { "type": "string", "nullable": true, "description": "Industry sector", "example": "Technology" } } }, "UpdateCompanyRequest": { "type": "object", "description": "Request body for updating a company. Only provided fields will be updated.", "properties": { "name": { "type": "string", "nullable": true, "description": "Company name" }, "website": { "type": "string", "nullable": true, "description": "Company website URL" }, "industry": { "type": "string", "nullable": true, "description": "Industry sector" } } }, "SearchCompaniesRequest": { "type": "object", "description": "Request body for searching companies", "properties": { "filters": { "type": "object", "nullable": true, "description": "Named filters. All are combined with AND.", "properties": { "name": { "type": "string", "description": "Filter by company name (contains)" }, "website": { "type": "string", "description": "Filter by website (contains)" }, "industry": { "type": "string", "description": "Filter by industry (contains)" } } }, "sort": { "type": "string", "nullable": true, "enum": [ "DATE_DESC", "DATE_ASC", "NAME_ASC", "NAME_DESC", "CREATED_DESC", "CREATED_ASC" ], "description": "Sort order (default: DATE_DESC)" }, "page": { "type": "integer", "default": 1, "description": "Page number (1-indexed)" }, "size": { "type": "integer", "default": 20, "maximum": 100, "description": "Results per page" } } }, "CreateDealRequest": { "type": "object", "description": "Request body for creating a deal", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Deal name", "example": "Enterprise Plan" }, "status": { "type": "string", "nullable": true, "description": "Deal status", "example": "negotiation" }, "amount": { "type": "number", "nullable": true, "description": "Deal monetary value", "example": 50000 }, "currency": { "type": "string", "nullable": true, "description": "Three-letter ISO 4217 currency code", "example": "USD", "minLength": 3, "maxLength": 3 }, "closed_at": { "type": "string", "nullable": true, "description": "When the deal was closed (ISO 8601)", "example": "2026-04-28T12:00:00" }, "company_id": { "type": "string", "nullable": true, "description": "ID of the company to associate with", "example": "com-xyz789" } } }, "UpdateDealRequest": { "type": "object", "description": "Request body for updating a deal. Only provided fields will be updated.", "properties": { "name": { "type": "string", "nullable": true, "description": "Deal name" }, "status": { "type": "string", "nullable": true, "description": "Deal status" }, "amount": { "type": "number", "nullable": true, "description": "Deal monetary value" }, "currency": { "type": "string", "nullable": true, "description": "Three-letter ISO 4217 currency code", "minLength": 3, "maxLength": 3 }, "closed_at": { "type": "string", "nullable": true, "description": "When the deal was closed (ISO 8601)" }, "company_id": { "type": "string", "nullable": true, "description": "ID of the company to associate with" } } }, "SearchDealsRequest": { "type": "object", "description": "Request body for searching deals", "properties": { "filters": { "type": "object", "nullable": true, "description": "Named filters. Combined with AND.", "properties": { "stage": { "type": "string", "description": "Filter by deal stage/status (exact match)" } } }, "search": { "type": "string", "nullable": true, "description": "Free-text search across deal name and company" }, "sort": { "type": "string", "nullable": true, "enum": [ "DATE_DESC", "DATE_ASC", "NAME_ASC", "NAME_DESC", "CREATED_DESC", "CREATED_ASC" ], "description": "Sort order (default: DATE_DESC)" }, "page": { "type": "integer", "default": 1, "description": "Page number (1-indexed)" }, "size": { "type": "integer", "default": 20, "maximum": 100, "description": "Results per page" } } }, "WebhookTopic": { "type": "string", "enum": [ "call.received", "call.triggered", "call.answered", "call.completed", "tag.added", "tag.removed", "sms.received", "sms.sent", "contact.created", "contact.updated", "summary.updated" ], "description": "An event topic. See the Event Catalog for payloads.", "example": "call.received" }, "WebhookApiResponse": { "type": "object", "description": "A webhook endpoint.", "properties": { "id": { "type": "string", "description": "Unique webhook endpoint ID.", "example": "ep_2NfDKEm9sF8xK3pQr1Zt" }, "url": { "type": "string", "format": "uri", "description": "HTTPS URL that receives event deliveries." }, "topics": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTopic" }, "description": "Event topics this endpoint is subscribed to." }, "description": { "type": "string", "nullable": true, "description": "Optional human-readable label." }, "enabled": { "type": "boolean", "description": "Whether the endpoint is active." }, "signing_secret": { "type": "string", "nullable": true, "description": "Secret used to verify delivery signatures. Returned only when the webhook is created or fetched by ID." }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the endpoint was created." } } }, "CreateWebhookApiRequest": { "type": "object", "required": [ "url", "topics" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS URL that will receive event deliveries." }, "topics": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTopic" }, "description": "Event topics to subscribe to (at least one)." }, "description": { "type": "string", "description": "Optional human-readable label." } } }, "UpdateWebhookApiRequest": { "type": "object", "description": "All fields optional. Only the fields you provide are changed.", "properties": { "url": { "type": "string", "format": "uri", "description": "New HTTPS delivery URL." }, "topics": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTopic" }, "description": "Replacement set of event topics." }, "description": { "type": "string", "description": "New label." }, "enabled": { "type": "boolean", "description": "Enable or disable the endpoint." } } }, "WebhookEventTypeApiResponse": { "type": "object", "properties": { "name": { "type": "string", "example": "call.received" }, "description": { "type": "string", "example": "Inbound call received" } } } }, "responses": { "Unauthorized": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "API_KEY_INVALID", "details": null } } } }, "Forbidden": { "description": "Forbidden - API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "API_KEY_INSUFFICIENT_SCOPE", "details": [ { "message": "required=CONTACTS_READ", "field": "scope" } ] } } } }, "TooManyRequests": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "API_KEY_QUOTA_EXCEEDED", "details": [ { "message": "limit=1000;type=DAILY;reset_in=3600", "field": "DAILY" } ] } } } }, "ApiUnauthorized": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ApiNotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ApiValidationError": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ApiConflict": { "description": "Conflict with existing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ApiRateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": { "Page": { "name": "page", "in": "query", "description": "Page number (1-indexed)", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, "Size": { "name": "size", "in": "query", "description": "Results per page", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, "Extend": { "name": "extend", "in": "query", "description": "Comma-separated optional fields. Supported: `transcript`", "schema": { "type": "string", "example": "transcript" } } } } }