{ "openapi": "3.0.0", "info": { "title": "Nedzo API", "version": "1.0.0", "description": "RESTful API for Nedzo AI communications platform. Provides programmatic access to workspaces, agents, contacts, and contact lists." }, "servers": [ { "url": "https://api.nedzo.ai/v1", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key authentication using Bearer token format. Obtain your API key from the Nedzo dashboard." } }, "schemas": { "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique workspace identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "accountId": { "type": "string", "format": "uuid", "description": "Account ID that owns this workspace", "example": "789e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace name", "example": "My Workspace" }, "description": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Optional workspace description", "example": "Main workspace for customer campaigns" }, "timezone": { "type": "string", "description": "Workspace timezone (IANA format)", "example": "America/New_York" }, "contactEmail": { "type": "string", "nullable": true, "format": "email", "description": "Contact email for workspace", "example": "contact@example.com" }, "contactPhone": { "type": "string", "nullable": true, "description": "Contact phone for workspace", "example": "+1234567890" }, "createdAt": { "type": "string", "format": "date-time", "description": "Workspace creation timestamp", "example": "2025-12-11T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Workspace last update timestamp", "example": "2025-12-11T12:00:00Z" } }, "required": [ "id", "accountId", "name", "description", "timezone", "contactEmail", "contactPhone", "createdAt", "updatedAt" ] }, "Error": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "URI reference identifying the problem type", "example": "https://api.nedzo.ai/errors/not-found" }, "title": { "type": "string", "description": "Short, human-readable summary of the problem", "example": "Not Found" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code", "example": 404 }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence", "example": "Workspace with ID 123e4567-e89b-12d3-a456-426614174000 not found" }, "instance": { "type": "string", "description": "URI reference identifying the specific occurrence", "example": "/v1/workspaces/123e4567-e89b-12d3-a456-426614174000" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field name that failed validation", "example": "name" }, "message": { "type": "string", "description": "Validation error message", "example": "Name is required" } }, "required": [ "field", "message" ] }, "description": "Validation errors (present for 400 Validation Error)", "example": [ { "field": "name", "message": "Name is required" } ] } }, "required": [ "type", "title", "status", "detail" ] }, "CreateWorkspace": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace name (required)", "example": "My New Workspace" }, "description": { "type": "string", "maxLength": 1000, "description": "Optional workspace description", "example": "Workspace for Q1 campaigns" }, "timezone": { "type": "string", "description": "Workspace timezone (IANA format). Defaults to UTC.", "example": "America/Los_Angeles" }, "contactEmail": { "type": "string", "format": "email", "description": "Contact email for workspace", "example": "admin@example.com" }, "contactPhone": { "type": "string", "description": "Contact phone for workspace", "example": "+1987654321" } }, "required": [ "name" ] }, "UpdateWorkspace": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Workspace name", "example": "Updated Workspace Name" }, "description": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Workspace description (can be set to null)", "example": "Updated description" }, "timezone": { "type": "string", "description": "Workspace timezone (IANA format)", "example": "Europe/London" }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email" }, { "nullable": true }, { "nullable": true } ], "description": "Contact email (can be set to null)", "example": "newemail@example.com" }, "contactPhone": { "type": "string", "nullable": true, "description": "Contact phone (can be set to null)", "example": "+44123456789" } } }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique agent identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID that owns this agent", "example": "789e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Agent name", "example": "Customer Support Agent" }, "prompt": { "type": "string", "nullable": true, "description": "System prompt for the agent", "example": "You are a helpful customer support assistant..." }, "voiceConfig": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Voice configuration settings (JSON)", "example": { "provider": "elevenlabs", "voiceId": "voice_123" } }, "widgetConfig": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Widget appearance settings (JSON)", "example": { "primaryColor": "#007bff", "position": "bottom-right" } }, "language": { "type": "string", "nullable": true, "description": "Agent language code", "example": "en" }, "createdAt": { "type": "string", "format": "date-time", "description": "Agent creation timestamp", "example": "2025-12-11T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Agent last update timestamp", "example": "2025-12-11T12:00:00Z" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft delete timestamp (null if active)", "example": null } }, "required": [ "id", "workspaceId", "name", "prompt", "voiceConfig", "widgetConfig", "language", "createdAt", "updatedAt", "deletedAt" ] }, "CreateAgent": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID to create agent in (required)", "example": "789e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Agent name (required)", "example": "My New Agent" }, "prompt": { "type": "string", "description": "System prompt for the agent", "example": "You are a helpful assistant for our e-commerce platform." }, "voiceConfig": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Voice configuration settings (JSON)", "example": { "provider": "elevenlabs", "voiceId": "voice_456" } }, "widgetConfig": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Widget appearance settings (JSON)", "example": { "theme": "dark" } }, "language": { "type": "string", "description": "Agent language code", "example": "en" } }, "required": [ "workspaceId", "name" ] }, "UpdateAgent": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Agent name", "example": "Updated Agent Name" }, "prompt": { "type": "string", "nullable": true, "description": "System prompt (can be set to null)", "example": "Updated system prompt..." }, "voiceConfig": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "nullable": true }, { "nullable": true } ], "description": "Voice configuration (can be set to null)", "example": { "provider": "elevenlabs", "voiceId": "new_voice" } }, "widgetConfig": { "anyOf": [ { "type": "object", "additionalProperties": { "nullable": true } }, { "nullable": true }, { "nullable": true } ], "description": "Widget configuration (can be set to null)", "example": { "theme": "light", "position": "top-right" } }, "language": { "type": "string", "nullable": true, "description": "Agent language code (can be set to null)", "example": "es" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique contact identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID that owns this contact", "example": "789e4567-e89b-12d3-a456-426614174000" }, "contactListId": { "type": "string", "nullable": true, "format": "uuid", "description": "Contact list ID (null if not in a list)", "example": "456e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "nullable": true, "description": "Contact first name", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "Contact last name", "example": "Doe" }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Contact email address", "example": "john.doe@example.com" }, "phone": { "type": "string", "nullable": true, "description": "Contact phone number", "example": "+1-555-123-4567" }, "createdAt": { "type": "string", "format": "date-time", "description": "Contact creation timestamp", "example": "2025-12-11T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Contact last update timestamp", "example": "2025-12-11T12:00:00Z" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft delete timestamp (null if active)", "example": null } }, "required": [ "id", "workspaceId", "contactListId", "firstName", "lastName", "email", "phone", "createdAt", "updatedAt", "deletedAt" ] }, "CreateContact": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID to create contact in (required)", "example": "789e4567-e89b-12d3-a456-426614174000" }, "contactListId": { "type": "string", "format": "uuid", "description": "Contact list ID to assign contact to", "example": "456e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "maxLength": 255, "description": "Contact first name", "example": "John" }, "lastName": { "type": "string", "maxLength": 255, "description": "Contact last name", "example": "Doe" }, "email": { "type": "string", "format": "email", "description": "Contact email address", "example": "john.doe@example.com" }, "phone": { "type": "string", "maxLength": 50, "description": "Contact phone number", "example": "+1-555-123-4567" } }, "required": [ "workspaceId" ] }, "UpdateContact": { "type": "object", "properties": { "contactListId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "nullable": true }, { "nullable": true } ], "description": "Contact list ID (set to null to remove from list)", "example": "456e4567-e89b-12d3-a456-426614174000" }, "firstName": { "type": "string", "nullable": true, "maxLength": 255, "description": "Contact first name (can be set to null)", "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "maxLength": 255, "description": "Contact last name (can be set to null)", "example": "Smith" }, "email": { "type": "string", "nullable": true, "format": "email", "description": "Contact email (can be set to null)", "example": "jane.smith@example.com" }, "phone": { "type": "string", "nullable": true, "maxLength": 50, "description": "Contact phone (can be set to null)", "example": "+1-555-987-6543" } } }, "CallResponse": { "type": "object", "properties": { "callId": { "type": "string", "description": "Call identifier for tracking. Use this ID to query call status and results.", "example": "vapi-call-abc123" } }, "required": [ "callId" ] }, "CreateCallRequest": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid", "description": "UUID of the agent to use for the call", "example": "123e4567-e89b-12d3-a456-426614174000" }, "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Phone number to call in E.164 format", "example": "+14155551234" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom variables to pass to the assistant. These override contact field values.", "example": { "customerName": "John Doe", "appointmentTime": "3pm" } } }, "required": [ "agentId", "phoneNumber" ] }, "PhoneNumber": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID", "example": "789e4567-e89b-12d3-a456-426614174000" }, "number": { "type": "string", "description": "Phone number in E.164 format", "example": "+14155551234" }, "countryDial": { "type": "string", "nullable": true, "description": "Country dialing code", "example": "+1" }, "status": { "type": "string", "enum": [ "pending", "active", "payment_failed", "activation_failed" ], "description": "Phone number status", "example": "active" }, "type": { "type": "string", "enum": [ "inbound_outbound", "outbound_only" ], "description": "Phone number type", "example": "outbound_only" }, "engineId": { "type": "string", "nullable": true, "description": "Voice engine ID", "example": "asst_abc123" }, "telephonyId": { "type": "string", "nullable": true, "description": "Provider phone number ID", "example": "1234567890" }, "price": { "type": "number", "nullable": true, "description": "Monthly price in USD", "example": 1.5 }, "purchasedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Purchase timestamp", "example": "2025-12-11T12:00:00Z" }, "renewalAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Next renewal timestamp", "example": "2026-01-11T12:00:00Z" }, "dialsToday": { "type": "number", "description": "Dials today", "example": 0 }, "dialsTotal": { "type": "number", "description": "Total dials", "example": 0 }, "available": { "type": "boolean", "description": "Available for use", "example": true }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Soft delete timestamp", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp", "example": "2025-12-11T12:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2025-12-11T12:00:00Z" } }, "required": [ "id", "workspaceId", "number", "countryDial", "status", "type", "engineId", "telephonyId", "price", "purchasedAt", "renewalAt", "dialsToday", "dialsTotal", "available", "deletedAt", "createdAt", "updatedAt" ] }, "AvailablePhoneNumber": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "Phone number", "example": "+14155551234" }, "nationalFormat": { "type": "string", "nullable": true, "description": "National format", "example": "(415) 555-1234" }, "phoneNumberType": { "type": "string", "description": "Type", "example": "local" }, "regionInformation": { "nullable": true }, "cost": { "nullable": true }, "features": { "nullable": true } }, "required": [ "phoneNumber", "nationalFormat", "phoneNumberType" ] }, "SearchPhoneNumbers": { "type": "object", "properties": { "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "default": "US", "description": "ISO country code", "example": "US" }, "areaCode": { "type": "string", "maxLength": 10, "description": "Area code", "example": "415" }, "contains": { "type": "string", "maxLength": 20, "description": "Number pattern", "example": "555" }, "numberType": { "type": "string", "enum": [ "local", "toll_free", "mobile", "national" ], "default": "local", "description": "Number type", "example": "local" }, "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 10, "description": "Max results", "example": 10 } } }, "BuyPhoneNumber": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID", "example": "789e4567-e89b-12d3-a456-426614174000" }, "number": { "type": "string", "minLength": 10, "maxLength": 20, "description": "Phone number to purchase", "example": "+14155551234" }, "countryDial": { "type": "string", "maxLength": 5, "description": "Country dial code", "example": "+1" }, "type": { "type": "string", "enum": [ "inbound_outbound", "outbound_only" ], "default": "outbound_only", "description": "Phone number type", "example": "outbound_only" }, "addressBundleId": { "type": "string", "format": "uuid", "description": "Address bundle for compliance" }, "messagingProfileId": { "type": "string", "description": "Messaging profile ID" } }, "required": [ "workspaceId", "number" ] }, "ImportPhoneNumber": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID", "example": "789e4567-e89b-12d3-a456-426614174000" }, "number": { "type": "string", "minLength": 10, "maxLength": 20, "description": "Phone number", "example": "+14155551234" }, "countryDial": { "type": "string", "maxLength": 5 }, "telephonyId": { "type": "string" }, "engineId": { "type": "string" }, "type": { "type": "string", "enum": [ "inbound_outbound", "outbound_only" ], "default": "outbound_only", "description": "Phone number type", "example": "outbound_only" }, "status": { "type": "string", "enum": [ "pending", "active", "payment_failed", "activation_failed" ], "default": "pending", "description": "Phone number status", "example": "active" }, "price": { "type": "number" } }, "required": [ "workspaceId", "number" ] }, "UpdatePhoneNumber": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "active", "payment_failed", "activation_failed" ], "description": "Phone number status", "example": "active" }, "type": { "type": "string", "enum": [ "inbound_outbound", "outbound_only" ], "description": "Phone number type", "example": "outbound_only" }, "telephonyId": { "type": "string", "nullable": true }, "engineId": { "type": "string", "nullable": true }, "available": { "type": "boolean" } } }, "AddressBundle": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "providerId": { "type": "string", "nullable": true, "description": "Provider bundle ID" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "Bundle status", "example": "approved" }, "countryCode": { "type": "string", "enum": [ "US", "GB", "MX", "CO" ], "description": "Country code", "example": "US" }, "businessName": { "type": "string", "description": "Business name", "example": "Acme Corp" }, "streetAddress": { "type": "string", "description": "Street address", "example": "123 Main St" }, "city": { "type": "string", "description": "City", "example": "New York" }, "state": { "type": "string", "description": "State/Province", "example": "NY" }, "zip": { "type": "string", "description": "Postal code", "example": "10001" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "workspaceId", "providerId", "status", "countryCode", "businessName", "streetAddress", "city", "state", "zip", "createdAt", "updatedAt" ] }, "CreateAddressBundle": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "businessName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Business name", "example": "Acme Corp" }, "streetAddress": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Street address", "example": "123 Main St" }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "City", "example": "New York" }, "state": { "type": "string", "minLength": 1, "maxLength": 100, "description": "State", "example": "NY" }, "zip": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Postal code", "example": "10001" }, "countryCode": { "type": "string", "enum": [ "US", "GB", "MX", "CO" ], "default": "US", "description": "Country code", "example": "US" } }, "required": [ "workspaceId", "businessName", "streetAddress", "city", "state", "zip" ] }, "A2PBrand": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "providerId": { "type": "string", "nullable": true, "description": "Provider brand ID" }, "status": { "type": "string", "enum": [ "pending", "approved", "failed" ], "description": "Brand status", "example": "approved" }, "businessName": { "type": "string", "description": "Business name", "example": "Acme Corp" }, "ein": { "type": "string", "nullable": true, "description": "EIN number", "example": "12-3456789" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "workspaceId", "providerId", "status", "businessName", "ein", "createdAt", "updatedAt" ] }, "CreateA2PBrand": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "businessName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Business name", "example": "Acme Corp" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name", "example": "Acme" }, "entityType": { "type": "string", "enum": [ "PRIVATE_PROFIT", "PUBLIC_PROFIT", "NON_PROFIT", "SOLE_PROPRIETOR", "GOVERNMENT" ], "description": "Business entity type", "example": "PRIVATE_PROFIT" }, "vertical": { "type": "string", "enum": [ "AGRICULTURE", "COMMUNICATION", "CONSTRUCTION", "EDUCATION", "ENERGY", "ENTERTAINMENT", "FINANCIAL", "GAMBLING", "GOVERNMENT", "HEALTHCARE", "HOSPITALITY", "HUMAN_RESOURCES", "INSURANCE", "LEGAL", "MANUFACTURING", "NGO", "POLITICAL", "POSTAL", "PROFESSIONAL", "REAL_ESTATE", "RETAIL", "TECHNOLOGY", "TRANSPORTATION" ], "description": "Business vertical", "example": "TECHNOLOGY" }, "ein": { "type": "string", "maxLength": 20, "description": "EIN", "example": "12-3456789" }, "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 20 }, "email": { "type": "string", "maxLength": 255, "format": "email" }, "street": { "type": "string", "maxLength": 100 }, "city": { "type": "string", "maxLength": 100 }, "state": { "type": "string", "maxLength": 20 }, "postalCode": { "type": "string", "maxLength": 10 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "US" }, "website": { "type": "string", "format": "uri" }, "isReseller": { "type": "boolean", "default": false } }, "required": [ "workspaceId", "businessName", "displayName", "entityType", "vertical" ] }, "A2PCampaign": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier" }, "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "brandId": { "type": "string", "format": "uuid", "description": "A2P Brand ID" }, "providerId": { "type": "string", "nullable": true, "description": "Provider campaign ID" }, "status": { "type": "string", "enum": [ "pending", "approved", "failed" ], "description": "Campaign status", "example": "approved" }, "useCase": { "type": "string", "enum": [ "ACCOUNT_NOTIFICATION", "AGENTS_FRANCHISES", "CARRIER_EXEMPT", "CHARITY", "CONVERSATIONAL", "CUSTOMER_CARE", "DELIVERY_NOTIFICATION", "EMERGENCY", "FRAUD_ALERT", "HIGHER_EDUCATION", "K12_EDUCATION", "LOW_VOLUME", "MARKETING", "MIXED", "POLITICAL", "POLLING_VOTING", "PUBLIC_SERVICE_ANNOUNCEMENT", "SECURITY_ALERT", "SOCIAL", "SWEEPSTAKES", "TWO_FACTOR_AUTH" ], "description": "Campaign use case", "example": "CUSTOMER_CARE" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "id", "workspaceId", "brandId", "providerId", "status", "useCase", "createdAt", "updatedAt" ] }, "CreateA2PCampaign": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "brandId": { "type": "string", "format": "uuid", "description": "A2P Brand ID" }, "useCase": { "type": "string", "enum": [ "ACCOUNT_NOTIFICATION", "AGENTS_FRANCHISES", "CARRIER_EXEMPT", "CHARITY", "CONVERSATIONAL", "CUSTOMER_CARE", "DELIVERY_NOTIFICATION", "EMERGENCY", "FRAUD_ALERT", "HIGHER_EDUCATION", "K12_EDUCATION", "LOW_VOLUME", "MARKETING", "MIXED", "POLITICAL", "POLLING_VOTING", "PUBLIC_SERVICE_ANNOUNCEMENT", "SECURITY_ALERT", "SOCIAL", "SWEEPSTAKES", "TWO_FACTOR_AUTH" ], "description": "Campaign use case", "example": "CUSTOMER_CARE" }, "description": { "type": "string", "minLength": 40, "maxLength": 4096, "description": "Campaign description" }, "sample1": { "type": "string", "minLength": 20, "maxLength": 1024 }, "sample2": { "type": "string", "minLength": 20, "maxLength": 1024 }, "messageFlow": { "type": "string", "minLength": 40, "maxLength": 2048 }, "helpMessage": { "type": "string", "minLength": 20, "maxLength": 255 }, "helpKeywords": { "type": "string", "maxLength": 255 }, "optinMessage": { "type": "string", "minLength": 20, "maxLength": 255 }, "optinKeywords": { "type": "string", "maxLength": 255 }, "optoutMessage": { "type": "string", "minLength": 20, "maxLength": 255 }, "optoutKeywords": { "type": "string", "maxLength": 255 }, "subscriberOptin": { "type": "boolean", "default": true }, "subscriberOptout": { "type": "boolean", "default": true }, "subscriberHelp": { "type": "boolean", "default": true }, "embeddedLink": { "type": "boolean", "default": false }, "embeddedPhone": { "type": "boolean", "default": false }, "numberPool": { "type": "boolean", "default": false }, "ageGated": { "type": "boolean", "default": false }, "directLending": { "type": "boolean", "default": false }, "autoRenewal": { "type": "boolean", "default": true } }, "required": [ "workspaceId", "brandId", "useCase", "description" ] } }, "parameters": {} }, "paths": { "/v1/workspaces": { "get": { "summary": "List workspaces", "description": "List all workspaces accessible to the API key. Account-scoped keys see all workspaces in account. Workspace-scoped keys see only their workspace.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Array of workspaces accessible to the API key", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create workspace", "description": "Create a new workspace within the account. Requires account-scoped API key (workspace-scoped keys cannot create workspaces).", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspace" } } } }, "responses": { "201": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Validation error - invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - workspace-scoped keys cannot create workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{id}": { "get": { "summary": "Get workspace by ID", "description": "Retrieves a specific workspace by its UUID. Requires valid API key with access to the workspace.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Workspace UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Workspace retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Invalid workspace ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update workspace", "description": "Updates workspace details. All fields are optional - only provided fields will be updated. Requires API key with access to the workspace.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Workspace UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspace" } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "description": "Validation error - invalid request body or workspace ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete workspace", "description": "Permanently deletes a workspace. Requires API key with access to the workspace. Workspace-scoped keys cannot delete their own workspace.", "tags": [ "Workspaces" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Workspace UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Workspace deleted successfully (no content)" }, "400": { "description": "Invalid workspace ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this workspace or cannot delete own scoped workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents": { "get": { "summary": "List agents", "description": "List all agents in a workspace. Soft-deleted agents are excluded by default. Use includeDeleted=true to include them. Returns 404 for unauthorized workspace access.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Filter agents by workspace ID (required)", "example": "789e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "workspaceId", "in": "query" }, { "schema": { "type": "string", "description": "Include soft-deleted agents (default: false)", "example": "false" }, "required": false, "name": "includeDeleted", "in": "query" } ], "responses": { "200": { "description": "Array of agents in the workspace", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } } } }, "400": { "description": "Validation error - missing or invalid workspaceId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found (includes unauthorized access for security)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create agent", "description": "Create a new agent within a workspace. Requires workspaceId and name. Optional fields include prompt, voiceConfig, widgetConfig, and language.", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgent" } } } }, "responses": { "201": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Validation error - invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents/{id}": { "get": { "summary": "Get agent by ID", "description": "Retrieves a specific agent by its UUID. Returns the agent even if soft-deleted (deletedAt will be populated).", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Agent UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Agent retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Invalid agent ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update agent", "description": "Updates agent details. All fields are optional - only provided fields will be updated. Cannot update soft-deleted agents (returns 404).", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Agent UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgent" } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Validation error - invalid request body or agent ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found or soft-deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete agent (soft delete)", "description": "Soft-deletes an agent by setting deletedAt timestamp. The agent is NOT permanently removed. Returns 204 even if already soft-deleted (idempotent).", "tags": [ "Agents" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Agent UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Agent soft-deleted successfully (no content)" }, "400": { "description": "Invalid agent ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts": { "get": { "summary": "List contacts", "description": "List all contacts in a workspace. Optionally filter by contact list. Soft-deleted contacts are excluded by default. Use includeDeleted=true to include them. Returns 404 for unauthorized workspace access.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Filter contacts by workspace ID (required)", "example": "789e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "workspaceId", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Filter contacts by contact list ID", "example": "456e4567-e89b-12d3-a456-426614174000" }, "required": false, "name": "contactListId", "in": "query" }, { "schema": { "type": "string", "description": "Include soft-deleted contacts (default: false)", "example": "false" }, "required": false, "name": "includeDeleted", "in": "query" } ], "responses": { "200": { "description": "Array of contacts in the workspace", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } }, "400": { "description": "Validation error - missing or invalid workspaceId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found (includes unauthorized access for security)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create contact", "description": "Create a new contact within a workspace. Only workspaceId is required. Optional fields include contactListId, firstName, lastName, email, and phone.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContact" } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Validation error - invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts/{id}": { "get": { "summary": "Get contact by ID", "description": "Retrieves a specific contact by its UUID. Returns the contact even if soft-deleted (deletedAt will be populated).", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Contact UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Contact retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid contact ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update contact", "description": "Updates contact details. All fields are optional - only provided fields will be updated. Cannot update soft-deleted contacts (returns 404).", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Contact UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContact" } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Validation error - invalid request body or contact ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found or soft-deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete contact (soft delete)", "description": "Soft-deletes a contact by setting deletedAt timestamp. The contact is NOT permanently removed. Returns 204 even if already soft-deleted (idempotent).", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Contact UUID", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Contact soft-deleted successfully (no content)" }, "400": { "description": "Invalid contact ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "API key does not have access to this contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/call": { "post": { "summary": "Initiate outbound call", "description": "Initiate an outbound voice call to the specified phone number using the configured agent. Returns a call ID immediately for tracking. The call is placed asynchronously - use the conversations endpoint to retrieve call results once the call completes. Rate limited to 10 requests per minute.", "tags": [ "Calls" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCallRequest" } } } }, "responses": { "200": { "description": "Call initiated successfully. Returns call ID for tracking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } } }, "400": { "description": "Validation error - invalid phone number format, invalid agent ID, agent not active, or no phone number available for the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent not found (includes unauthorized access for security)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (10 requests per minute). Retry-After header included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Call could not be initiated. Please try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/phone-numbers": { "get": { "summary": "List phone numbers", "description": "List all phone numbers in a workspace.", "tags": [ "Telephony - Phone Numbers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Workspace ID" }, "required": true, "name": "workspaceId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "includeDeleted", "in": "query" } ], "responses": { "200": { "description": "Phone numbers list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/phone-numbers/search": { "post": { "summary": "Search available phone numbers", "description": "Search for available phone numbers to purchase.", "tags": [ "Telephony - Phone Numbers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPhoneNumbers" } } } }, "responses": { "200": { "description": "Available numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/AvailablePhoneNumber" } }, "total": { "type": "number" } }, "required": [ "numbers", "total" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/phone-numbers/buy": { "post": { "summary": "Buy a phone number", "description": "Purchase a phone number.", "tags": [ "Telephony - Phone Numbers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyPhoneNumber" } } } }, "responses": { "201": { "description": "Phone number purchased", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/phone-numbers/import": { "post": { "summary": "Import a phone number", "description": "Import an existing phone number to the workspace.", "tags": [ "Telephony - Phone Numbers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPhoneNumber" } } } }, "responses": { "201": { "description": "Phone number imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/phone-numbers/{id}": { "get": { "summary": "Get phone number by ID", "description": "Retrieve a specific phone number.", "tags": [ "Telephony - Phone Numbers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Phone number UUID" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Phone number details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update phone number", "description": "Update phone number details.", "tags": [ "Telephony - Phone Numbers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhoneNumber" } } } }, "responses": { "200": { "description": "Phone number updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete phone number", "description": "Soft-delete and release a phone number.", "tags": [ "Telephony - Phone Numbers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Phone number deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/address-bundles": { "get": { "summary": "List address bundles", "description": "List all address bundles in a workspace.", "tags": [ "Telephony - Address Bundles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "workspaceId", "in": "query" } ], "responses": { "200": { "description": "Address bundles list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AddressBundle" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create address bundle", "description": "Create a new address bundle for regulatory compliance.", "tags": [ "Telephony - Address Bundles" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAddressBundle" } } } }, "responses": { "201": { "description": "Address bundle created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBundle" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/address-bundles/{id}": { "get": { "summary": "Get address bundle by ID", "description": "Retrieve a specific address bundle.", "tags": [ "Telephony - Address Bundles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Address bundle details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBundle" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete address bundle", "description": "Delete an address bundle.", "tags": [ "Telephony - Address Bundles" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Address bundle deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/a2p-brands": { "get": { "summary": "List A2P brands", "description": "List all A2P brands (10DLC) in a workspace.", "tags": [ "Telephony - A2P Brands" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "workspaceId", "in": "query" } ], "responses": { "200": { "description": "A2P brands list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/A2PBrand" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create A2P brand", "description": "Register a new A2P brand for 10DLC messaging.", "tags": [ "Telephony - A2P Brands" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateA2PBrand" } } } }, "responses": { "201": { "description": "A2P brand created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2PBrand" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/a2p-brands/{id}": { "get": { "summary": "Get A2P brand by ID", "description": "Retrieve a specific A2P brand.", "tags": [ "Telephony - A2P Brands" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "A2P brand details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2PBrand" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete A2P brand", "description": "Delete an A2P brand.", "tags": [ "Telephony - A2P Brands" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "A2P brand deleted" }, "400": { "description": "Brand has active campaigns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/a2p-campaigns": { "get": { "summary": "List A2P campaigns", "description": "List all A2P campaigns in a workspace.", "tags": [ "Telephony - A2P Campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "workspaceId", "in": "query" }, { "schema": { "type": "string", "format": "uuid" }, "required": false, "name": "brandId", "in": "query" } ], "responses": { "200": { "description": "A2P campaigns list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/A2PCampaign" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create A2P campaign", "description": "Register a new A2P campaign for 10DLC messaging.", "tags": [ "Telephony - A2P Campaigns" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateA2PCampaign" } } } }, "responses": { "201": { "description": "A2P campaign created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2PCampaign" } } } }, "400": { "description": "Validation error or brand not approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/internal/telephony/a2p-campaigns/{id}": { "get": { "summary": "Get A2P campaign by ID", "description": "Retrieve a specific A2P campaign.", "tags": [ "Telephony - A2P Campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "A2P campaign details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2PCampaign" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete A2P campaign", "description": "Delete an A2P campaign.", "tags": [ "Telephony - A2P Campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "A2P campaign deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }