{ "openapi": "3.1.0", "info": { "title": "RevDesk v1 API", "version": "1.0.0", "description": "Connect RevDesk calls, SMS, phone numbers, caller IDs, caller trust, agents, contacts, tasks, webhooks, and usage to the rest of your revenue workflow with organization-scoped permissions.", "contact": { "name": "RevDesk", "email": "support@revdesk.com" } }, "externalDocs": { "description": "RevDesk API versioning and deprecation policy", "url": "https://docs.revdesk.com/api-reference/versioning-and-deprecation" }, "x-versioning-policy": { "strategy": "URL path versioning", "currentVersion": "v1", "deprecationSignals": [ "Deprecation response header", "Sunset response header", "Link rel=sunset" ], "policyUrl": "https://docs.revdesk.com/api-reference/versioning-and-deprecation" }, "servers": [ { "url": "https://api.revdesk.com" } ], "tags": [ { "name": "Phone Numbers" }, { "name": "Caller IDs" }, { "name": "Enterprise Registration" }, { "name": "Branded Calling" }, { "name": "Calls" }, { "name": "SMS" }, { "name": "WebRTC" }, { "name": "Reputation" }, { "name": "Usage" }, { "name": "Account" }, { "name": "Agents" }, { "name": "Appointments" }, { "name": "Contacts" }, { "name": "Documents" }, { "name": "Notifications" }, { "name": "Number Health" }, { "name": "Number Registration" }, { "name": "Optimize" }, { "name": "Sandbox" }, { "name": "Sub-entities" }, { "name": "Tasks" }, { "name": "Webhooks" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "RevDesk API key", "description": "Organization-scoped RevDesk API key. Each operation declares its required permissions in x-required-scopes.", "x-scopes-supported": [ "account:read", "agents:read", "agents:write", "bookings:read", "brand:read", "brand:write", "caller_trust:read", "caller_trust:write", "calls:read", "calls:write", "contacts:read", "contacts:write", "jobs:read", "jobs:write", "notifications:write", "phone_numbers:read", "phone_numbers:write", "optimize:read", "optimize:write", "sms:read", "sms:write", "sub_entities:read", "sub_entities:write", "tokens:mint", "transcripts:read", "usage:read", "voice:read", "voice:webrtc", "voice:write", "webhooks:read", "webhooks:write" ] } }, "headers": { "XRateLimitLimit": { "description": "Maximum requests allowed in the current one-minute window.", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "XRateLimitReset": { "description": "Unix timestamp in milliseconds when the current window resets.", "schema": { "type": "integer" } }, "RateLimit": { "description": "Current quota remaining and seconds until reset, using the IETF RateLimit structured-field syntax.", "schema": { "type": "string", "example": "\"default\";r=599;t=60" } }, "RateLimitPolicy": { "description": "Named quota policy and one-minute window.", "schema": { "type": "string", "example": "\"default\";q=600;w=60" } }, "RetryAfter": { "description": "Seconds to wait before retrying a rate-limited request.", "schema": { "type": "integer", "minimum": 0 } }, "WWWAuthenticate": { "description": "Bearer challenge with RFC 9728 protected-resource metadata and, on scope failures, the required scope.", "schema": { "type": "string" } } }, "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "resolution_hint": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } }, "doc_url": { "type": "string", "format": "uri" } } } } } } }, "x-scope-descriptions": { "account:read": "Read the authenticated account and workspace identity.", "agents:read": "Read voice-agent configuration.", "agents:write": "Create or change voice-agent configuration and start web calls.", "bookings:read": "Read appointments and bookings.", "brand:read": "Read branded-calling configuration and status.", "brand:write": "Create or change branded-calling configuration.", "caller_trust:read": "Read caller-trust registrations, reputation, and remediation status.", "caller_trust:write": "Create or change caller-trust registrations and remediation requests.", "calls:read": "Read call history and call details.", "calls:write": "Place, control, or end calls.", "contacts:read": "Read contacts.", "contacts:write": "Create or change contacts.", "jobs:read": "Read long-horizon tasks and outcomes. The scope name is retained for compatibility.", "jobs:write": "Create or change long-horizon tasks. The scope name is retained for compatibility.", "notifications:write": "Register or revoke this user's native notification devices.", "phone_numbers:read": "Read owned and available phone numbers.", "phone_numbers:write": "Purchase, configure, or release phone numbers.", "optimize:read": "Read website tests, results, conversions, and site properties.", "optimize:write": "Create, start, pause, ship, or archive website tests and record conversions.", "sms:read": "Read messages and SMS configuration.", "sms:write": "Send messages or change SMS configuration.", "sub_entities:read": "Read bounded sub-entities.", "sub_entities:write": "Create or change bounded sub-entities.", "tokens:mint": "Mint short-lived, bounded client tokens from an API key.", "transcripts:read": "Read call transcripts.", "usage:read": "Read usage and spend summaries.", "voice:read": "Read caller IDs and voice configuration.", "voice:webrtc": "Create short-lived WebRTC room tokens.", "voice:write": "Create, verify, change, or remove caller IDs.", "webhooks:read": "Read webhook subscriptions.", "webhooks:write": "Create, change, or remove webhook subscriptions." }, "paths": { "/v1/account": { "get": { "operationId": "v1_account_get", "tags": [ "Account" ], "summary": "Account snapshot", "description": "The organization's account snapshot: plan tier and phone-number + caller-trust footprint counts. For the authenticated user and the key's scopes, use GET /v1/me.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "api_key_id": { "type": "string" }, "plan": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, { "type": "null" } ] }, "footprint": { "type": "object", "properties": { "phone_numbers": { "type": "number" }, "enrolled_reputation_numbers": { "type": "number" }, "own_brand_enterprise": { "type": "boolean" } }, "required": [ "phone_numbers", "enrolled_reputation_numbers", "own_brand_enterprise" ], "additionalProperties": false }, "is_demo": { "type": "boolean" } }, "required": [ "api_key_id", "plan", "user", "organization", "footprint", "is_demo" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "account:read" ], "x-required-scopes": [ "account:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/agents": { "get": { "operationId": "v1_agents_get", "tags": [ "Agents" ], "summary": "List AI agents", "description": "Returns every AI agent in the caller's active organization — the agents that answer inbound calls and lead outbound jobs. Use an agent's `id` as `agent_id` on POST /v1/calls or POST /v1/room-token.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "agent_type": { "type": "string", "enum": [ "inbound", "outbound", "both", "unassigned" ] }, "greeting": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "voice_id": { "type": [ "string", "null" ] }, "business_name": { "type": [ "string", "null" ] }, "business_description": { "type": [ "string", "null" ] }, "phone_number": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "provider": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "id", "phone_number", "provider", "is_active" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "enabled", "agent_type", "greeting", "language", "voice_id", "business_name", "business_description", "phone_number", "created_at", "updated_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": [ "page_size" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "agents:read" ], "x-required-scopes": [ "agents:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/agents/{id}": { "get": { "operationId": "v1_agents_id_get", "tags": [ "Agents" ], "summary": "Get an AI agent", "description": "Fetch a single AI agent by id, including its system prompt.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "agent_type": { "type": "string", "enum": [ "inbound", "outbound", "both", "unassigned" ] }, "greeting": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "voice_id": { "type": [ "string", "null" ] }, "business_name": { "type": [ "string", "null" ] }, "business_description": { "type": [ "string", "null" ] }, "system_prompt": { "type": [ "string", "null" ] }, "phone_number": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "provider": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "id", "phone_number", "provider", "is_active" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "enabled", "agent_type", "greeting", "language", "voice_id", "business_name", "business_description", "system_prompt", "phone_number", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "agents:read" ], "x-required-scopes": [ "agents:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_agents_id_patch", "tags": [ "Agents" ], "summary": "Configure an AI agent", "description": "Update an agent's name, greeting, system prompt, voice, language, or enabled state. Changes are synced to the voice runtime so the next call uses them. Send only the fields you want to change.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "enabled": { "type": "boolean" }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "system_prompt": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] }, "voice_id": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 2, "maxLength": 10 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "agent_type": { "type": "string", "enum": [ "inbound", "outbound", "both", "unassigned" ] }, "greeting": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "voice_id": { "type": [ "string", "null" ] }, "business_name": { "type": [ "string", "null" ] }, "business_description": { "type": [ "string", "null" ] }, "system_prompt": { "type": [ "string", "null" ] }, "phone_number": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "provider": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "id", "phone_number", "provider", "is_active" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "enabled", "agent_type", "greeting", "language", "voice_id", "business_name", "business_description", "system_prompt", "phone_number", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "agents:write" ], "x-required-scopes": [ "agents:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/agents/{id}/web-call": { "post": { "operationId": "v1_agents_id_web_call_post", "tags": [ "Agents" ], "summary": "Start a browser call with an AI agent", "description": "Dispatches the agent into a room and returns a browser join token. Hand the token and room_url to @revdesk/webrtc (RevDeskRoom) and talk to the agent in the browser — no phone number needed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } }, { "name": "X-Revdesk-Caller-IP", "in": "header", "required": false, "description": "Optional end-user IPv4 or IPv6 address reported by your server for the browser caller. Stored as client-reported diagnostics, separately from the API request IP; never used for authentication. Raw IPs expire after 30 days.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "room_url": { "type": "string" }, "room_name": { "type": "string" }, "expires_in": { "type": "number" }, "agent_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ice_servers": { "type": "array", "items": {} } }, "required": [ "token", "room_url", "room_name", "expires_in", "agent_id", "ice_servers" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "agents:write" ], "x-required-scopes": [ "agents:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/appointments": { "get": { "operationId": "v1_appointments_get", "tags": [ "Appointments" ], "summary": "List appointments", "description": "Returns recent appointments (bookings) for the authenticated organization, newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "start_time": { "type": "string" }, "end_time": { "type": "string" }, "timezone": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "event_type": { "type": "string" }, "scheduling_option": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "title", "description", "contact_name", "contact_email", "start_time", "end_time", "timezone", "status", "event_type", "scheduling_option", "notes", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "bookings:read" ], "x-required-scopes": [ "bookings:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-ids/{id}": { "patch": { "operationId": "v1_caller_ids_id_patch", "tags": [ "Caller IDs" ], "summary": "Update CNAM display name", "description": "Sets the CNAM display name for a verified caller ID. If the caller ID's phone number is also a carrier-provisioned phone, the CNAM update is pushed to the carrier.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cnam_display_name": { "type": "string", "minLength": 1, "maxLength": 15 } }, "required": [ "cnam_display_name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "caller_id_id": { "type": "string" }, "phone_number": { "type": "string" }, "status": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "certification_method": { "type": [ "string", "null" ] }, "cnam_display_name": { "type": [ "string", "null" ] }, "cnam_status": { "type": [ "string", "null" ] }, "rcd_display_name": { "type": [ "string", "null" ] }, "rcd_status": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "caller_id_id", "phone_number", "status", "verified_at", "certification_method", "cnam_display_name", "cnam_status", "rcd_display_name", "rcd_status", "active", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:write" ], "x-required-scopes": [ "voice:write" ], "x-rate-limit": { "requestsPerMinute": 600 } }, "delete": { "operationId": "v1_caller_ids_id_delete", "tags": [ "Caller IDs" ], "summary": "Revoke a caller ID", "description": "Revokes a verified caller ID so it can no longer be used as an outbound caller ID. The record is kept (status REVOKED, active false) so historical calls stay attributed; it still appears in GET /v1/caller-ids with active=false. Re-verify the number to use it again.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "caller_id_id": { "type": "string" }, "phone_number": { "type": "string" }, "status": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "certification_method": { "type": [ "string", "null" ] }, "cnam_display_name": { "type": [ "string", "null" ] }, "cnam_status": { "type": [ "string", "null" ] }, "rcd_display_name": { "type": [ "string", "null" ] }, "rcd_status": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "caller_id_id", "phone_number", "status", "verified_at", "certification_method", "cnam_display_name", "cnam_status", "rcd_display_name", "rcd_status", "active", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:write" ], "x-required-scopes": [ "voice:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-ids/{id}/verify": { "post": { "operationId": "v1_caller_ids_id_verify_post", "tags": [ "Caller IDs" ], "summary": "Submit verification code", "description": "Submits the verification code received during the caller ID verification call. On success the caller ID status changes to VERIFIED.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verification_code": { "type": "string", "minLength": 1 } }, "required": [ "verification_code" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "verified", "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:write" ], "x-required-scopes": [ "voice:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-ids": { "post": { "operationId": "v1_caller_ids_post", "tags": [ "Caller IDs" ], "summary": "Start caller ID verification", "description": "Initiates a call-based verification for the given phone number. The carrier calls the number and reads a verification code aloud to whoever answers. The code is held by the carrier and is never returned by this API — proving possession of the number is the point. Submit the code the owner heard via POST /v1/caller-ids/{id}/verify.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "minLength": 1 } }, "required": [ "phone_number" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "caller_id_id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "caller_id_id", "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:write" ], "x-required-scopes": [ "voice:write" ], "x-rate-limit": { "requestsPerMinute": 600 } }, "get": { "operationId": "v1_caller_ids_get", "tags": [ "Caller IDs" ], "summary": "List caller IDs", "description": "Returns all caller IDs for the authenticated team, including verification status and CNAM details.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "caller_id_id": { "type": "string" }, "phone_number": { "type": "string" }, "status": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "certification_method": { "type": [ "string", "null" ] }, "cnam_display_name": { "type": [ "string", "null" ] }, "cnam_status": { "type": [ "string", "null" ] }, "rcd_display_name": { "type": [ "string", "null" ] }, "rcd_status": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "caller_id_id", "phone_number", "status", "verified_at", "certification_method", "cnam_display_name", "cnam_status", "rcd_display_name", "rcd_status", "active", "created_at", "updated_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:read" ], "x-required-scopes": [ "voice:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/brand": { "get": { "operationId": "v1_caller_trust_brand_get", "tags": [ "Branded Calling" ], "summary": "Retrieve the caller's Display Identity Record (brand)", "description": "Returns the display name, logo, call reasons, and vetting state shown on branded calls.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "call_reasons": { "type": "array", "items": { "type": "string" } }, "authorizer_name": { "type": [ "string", "null" ] }, "authorizer_email": { "type": [ "string", "null" ] }, "authorizer_email_verified": { "type": "boolean" }, "logo_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "telnyx_status": { "type": [ "string", "null" ] }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "submitted_at": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ] } }, "required": [ "id", "display_name", "call_reasons", "authorizer_name", "authorizer_email", "authorizer_email_verified", "logo_url", "status", "telnyx_status", "rejection_reasons", "submitted_at", "approved_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read", "brand:read" ], "x-required-scopes": [ "caller_trust:read", "brand:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "put": { "operationId": "v1_caller_trust_brand_put", "tags": [ "Branded Calling" ], "summary": "Save (or update) the Display Identity Record draft", "description": "Persists the brand (display name, call reasons, authorizer) against the caller's enterprise and mirrors it to the carrier while the DIR is editable. Requires the Branded Calling add-on. Submit for vetting via `POST /v1/caller-trust/brand/submit`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 35 }, "call_reasons": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "authorizer_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "authorizer_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "display_name", "call_reasons", "authorizer_name", "authorizer_email" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "call_reasons": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } }, "required": [ "id", "display_name", "call_reasons", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "brand:write", "caller_trust:write" ], "x-required-scopes": [ "brand:write", "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/brand/submit": { "post": { "operationId": "v1_caller_trust_brand_submit_post", "tags": [ "Branded Calling" ], "summary": "Submit the brand profile for vetting", "description": "Submits the Display Identity Record to the carrier for vetting. Requires the Branded Calling add-on, a complete brand (display name, call reasons, logo), and a verified authorizer email.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "telnyx_status": { "type": [ "string", "null" ] }, "submitted_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "telnyx_status", "submitted_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "brand:write" ], "x-required-scopes": [ "brand:write" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/documents/{id}": { "get": { "operationId": "v1_caller_trust_documents_id_get", "tags": [ "Documents" ], "summary": "Get document status", "description": "Returns metadata for a previously uploaded document, including its verification status and antivirus scan status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "document_id": { "type": "string" }, "filename": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "av_scan_status": { "type": [ "string", "null" ] }, "sha256": { "type": [ "string", "null" ] } }, "required": [ "document_id", "filename", "content_type", "status", "av_scan_status", "sha256" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/documents": { "post": { "operationId": "v1_caller_trust_documents_post", "tags": [ "Documents" ], "summary": "Upload a document (e.g. signed LOA)", "description": "Uploads a base64-encoded PDF to the carrier's document API. Returns a document ID that can be passed to the reputation enable endpoint. Documents expire after 30 minutes if not linked to a service — upload immediately before enabling reputation.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_base64": { "type": "string", "minLength": 1 }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "customer_reference": { "type": "string", "maxLength": 255 } }, "required": [ "file_base64", "filename" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "document_id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "document_id", "filename", "content_type", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/{id}/generate-loa": { "post": { "operationId": "v1_caller_trust_enterprise_id_generate_loa_post", "tags": [ "Enterprise Registration" ], "summary": "Generate LOA PDF for hand-signing (by ID)", "description": "Generates a Letter of Authorization PDF pre-filled with enterprise data and a blank hand-signature line. Enterprise must have been submitted to the carrier first (has carrier_enterprise_id). Addresses a specific registration by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "signer_full_name", "signer_email", "signer_title" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pdf_base64": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "pdf_base64", "filename" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/{id}/resign": { "post": { "operationId": "v1_caller_trust_enterprise_id_resign_post", "tags": [ "Enterprise Registration" ], "summary": "Re-sign the LOA for an enterprise (by ID)", "description": "Use when the on-file LOA needs to be replaced. Replaces the LOA with the carrier; the old LoaSignature row is preserved for audit. Status resets to PENDING_VETTING. Addresses a specific registration by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": [ "string", "null" ] }, "loa_document_id": { "type": [ "string", "null" ] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/{id}": { "get": { "operationId": "v1_caller_trust_enterprise_id_get", "tags": [ "Enterprise Registration" ], "summary": "Get an enterprise registration by ID", "description": "Returns a specific enterprise registration by its ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "role_type": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": [ "string", "null" ] }, "loa_document_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "read_only": { "type": "boolean" } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "role_type", "status", "rejection_reasons", "synced_at", "loa_document_id", "created_at", "read_only" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_caller_trust_enterprise_id_patch", "tags": [ "Enterprise Registration" ], "summary": "Update a DRAFT enterprise registration", "description": "Updates fields on a DRAFT enterprise. Rejects updates to enterprises that have left DRAFT status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 3, "maxLength": 64 }, "dba": { "type": "string", "minLength": 1, "maxLength": 255 }, "organization_type": { "type": "string", "enum": [ "COMMERCIAL", "GOVERNMENT", "NON_PROFIT" ] }, "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "website": { "type": "string", "minLength": 1, "maxLength": 255 }, "fein": { "type": "string", "minLength": 9, "maxLength": 20 }, "industry": { "type": "string", "enum": [ "accounting", "finance", "billing", "collections", "business", "charity", "nonprofit", "communications", "telecom", "customer service", "support", "delivery", "shipping", "logistics", "education", "financial", "banking", "government", "public", "healthcare", "health", "pharmacy", "medical", "insurance", "legal", "law", "notifications", "scheduling", "real estate", "property", "retail", "ecommerce", "sales", "marketing", "software", "technology", "tech", "media", "surveys", "market research", "travel", "hospitality", "hotel" ] }, "jurisdiction_of_incorporation": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "GU", "MP", "PR", "VI" ] }, "number_of_employees": { "type": "string", "enum": [ "SIZE_1_10", "SIZE_11_50", "SIZE_51_200", "SIZE_201_500", "SIZE_501_2000", "SIZE_2001_10000", "SIZE_10001_PLUS" ] }, "organization_legal_type": { "type": "string", "enum": [ "CORPORATION", "LLC", "PARTNERSHIP", "NONPROFIT", "OTHER" ] }, "organization_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "job_title": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 } }, "required": [ "first_name", "last_name", "email", "job_title", "phone" ], "additionalProperties": false }, "billing_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone_number": { "type": "string", "minLength": 1 } }, "required": [ "first_name", "last_name", "email", "phone_number" ], "additionalProperties": false }, "organization_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": [ "string", "null" ] } }, "required": [ "country", "administrative_area", "city", "postal_code", "street_address" ], "additionalProperties": false }, "billing_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": [ "string", "null" ] } }, "required": [ "country", "administrative_area", "city", "postal_code", "street_address" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "role_type": { "type": "string" } }, "required": [ "id", "legal_name", "dba", "status", "role_type" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_caller_trust_enterprise_id_delete", "tags": [ "Enterprise Registration" ], "summary": "Delete an enterprise registration by ID", "description": "Deletes a specific enterprise registration. DRAFT records that were never submitted to the carrier are removed directly. Active records are torn down with the carrier and marked DELETED locally.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/{id}/sign-and-submit": { "post": { "operationId": "v1_caller_trust_enterprise_id_sign_and_submit_post", "tags": [ "Enterprise Registration" ], "summary": "Sign LOA + submit enterprise to carrier (by ID)", "description": "DRAFT -> PENDING_VETTING in one call. Generates + signs the LOA PDF, uploads it to the carrier, creates the carrier enterprise record, and enables Number Reputation for it. Addresses a specific registration by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": [ "string", "null" ] }, "loa_document_id": { "type": [ "string", "null" ] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/{id}/submit": { "post": { "operationId": "v1_caller_trust_enterprise_id_submit_post", "tags": [ "Enterprise Registration" ], "summary": "Submit enterprise to the carrier (by ID)", "description": "Accepts Number Reputation Terms of Service and creates the enterprise with the carrier. Does NOT sign an LOA or enable reputation — those are separate steps. Addresses a specific registration by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/generate-loa": { "post": { "operationId": "v1_caller_trust_enterprise_generate_loa_post", "tags": [ "Enterprise Registration" ], "summary": "Generate LOA PDF for hand-signing", "description": "Generates a Letter of Authorization PDF pre-filled with enterprise data and a blank hand-signature line. Enterprise must have been submitted to the carrier first (has carrier_enterprise_id).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "signer_full_name", "signer_email", "signer_title" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pdf_base64": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "pdf_base64", "filename" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/resign": { "post": { "operationId": "v1_caller_trust_enterprise_resign_post", "tags": [ "Enterprise Registration" ], "summary": "Re-sign the LOA for an enterprise", "description": "Use when the on-file LOA needs to be replaced. Replaces the LOA with the carrier; the old LoaSignature row is preserved for audit. Status resets to PENDING_VETTING.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": [ "string", "null" ] }, "loa_document_id": { "type": [ "string", "null" ] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise": { "get": { "operationId": "v1_caller_trust_enterprise_get", "tags": [ "Enterprise Registration" ], "summary": "Get the caller's enterprise registration", "description": "Returns the own-brand enterprise record if one has been registered, or null otherwise.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "role_type": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": [ "string", "null" ] }, "loa_document_id": { "type": [ "string", "null" ] }, "read_only": { "type": "boolean" } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "role_type", "status", "rejection_reasons", "synced_at", "loa_document_id", "read_only" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_caller_trust_enterprise_post", "tags": [ "Enterprise Registration" ], "summary": "Create or update the caller's enterprise registration draft", "description": "Idempotent upsert of the own-brand enterprise registration as DRAFT. No carrier-side calls are made here — submission to the carrier happens in a separate sign-and-submit step.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 3, "maxLength": 64 }, "dba": { "type": "string", "minLength": 1, "maxLength": 255 }, "organization_type": { "type": "string", "enum": [ "COMMERCIAL", "GOVERNMENT", "NON_PROFIT" ] }, "country_code": { "default": "US", "type": "string", "minLength": 2, "maxLength": 2 }, "website": { "type": "string", "minLength": 1, "maxLength": 255 }, "fein": { "type": "string", "minLength": 9, "maxLength": 20 }, "industry": { "type": "string", "enum": [ "accounting", "finance", "billing", "collections", "business", "charity", "nonprofit", "communications", "telecom", "customer service", "support", "delivery", "shipping", "logistics", "education", "financial", "banking", "government", "public", "healthcare", "health", "pharmacy", "medical", "insurance", "legal", "law", "notifications", "scheduling", "real estate", "property", "retail", "ecommerce", "sales", "marketing", "software", "technology", "tech", "media", "surveys", "market research", "travel", "hospitality", "hotel" ] }, "jurisdiction_of_incorporation": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "GU", "MP", "PR", "VI" ] }, "number_of_employees": { "type": "string", "enum": [ "SIZE_1_10", "SIZE_11_50", "SIZE_51_200", "SIZE_201_500", "SIZE_501_2000", "SIZE_2001_10000", "SIZE_10001_PLUS" ] }, "organization_legal_type": { "type": "string", "enum": [ "CORPORATION", "LLC", "PARTNERSHIP", "NONPROFIT", "OTHER" ] }, "organization_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "job_title": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 } }, "required": [ "first_name", "last_name", "email", "job_title", "phone" ], "additionalProperties": false }, "billing_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone_number": { "type": "string", "minLength": 1 } }, "required": [ "first_name", "last_name", "email", "phone_number" ], "additionalProperties": false }, "organization_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": [ "string", "null" ] } }, "required": [ "country", "administrative_area", "city", "postal_code", "street_address" ], "additionalProperties": false }, "billing_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": [ "string", "null" ] } }, "required": [ "country", "administrative_area", "city", "postal_code", "street_address" ], "additionalProperties": false } }, "required": [ "legal_name", "dba", "organization_type", "country_code", "website", "fein", "industry", "jurisdiction_of_incorporation", "number_of_employees", "organization_legal_type", "organization_contact", "billing_contact", "organization_address", "billing_address" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "role_type": { "type": "string" } }, "required": [ "id", "legal_name", "dba", "status", "role_type" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_caller_trust_enterprise_delete", "tags": [ "Enterprise Registration" ], "summary": "Delete the caller's enterprise registration", "description": "Deletes the own-brand enterprise registration. DRAFT records that were never submitted to the carrier are removed directly. Active records are torn down with the carrier (enterprise + reputation) and marked DELETED locally.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/sign-and-submit": { "post": { "operationId": "v1_caller_trust_enterprise_sign_and_submit_post", "tags": [ "Enterprise Registration" ], "summary": "Sign LOA + submit enterprise to carrier", "description": "DRAFT -> PENDING_VETTING in one call. Generates + signs the LOA PDF, uploads it to the carrier, creates the carrier enterprise record, and enables Number Reputation for it.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": [ "string", "null" ] }, "loa_document_id": { "type": [ "string", "null" ] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/submit": { "post": { "operationId": "v1_caller_trust_enterprise_submit_post", "tags": [ "Enterprise Registration" ], "summary": "Submit enterprise to the carrier", "description": "Accepts Number Reputation Terms of Service and creates the enterprise with the carrier. Does NOT sign an LOA or enable reputation — those are separate steps.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "carrier_enterprise_id": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "carrier_enterprise_id", "legal_name", "dba", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/registration-profile": { "get": { "operationId": "v1_caller_trust_registration_profile_get", "tags": [ "Number Registration" ], "summary": "Get the workspace's Free Caller Registry registration profile", "description": "Returns the workspace's default call purpose and monthly call-volume bracket submitted to the Free Caller Registry, the effective values in use today, and the full lists of valid options.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_purpose": { "anyOf": [ { "type": "string", "enum": [ "attorney_legal", "financial_service", "first_responder", "government", "health", "informational", "pharmacy", "political", "real_estate", "school_college", "survey", "telemarketing" ] }, { "type": "null" } ] }, "monthly_call_volume": { "anyOf": [ { "type": "string", "enum": [ "1", "101", "501", "1001", "5001", "10001", "50001", "dontknow" ] }, { "type": "null" } ] }, "effective_call_purpose": { "type": "string", "enum": [ "attorney_legal", "financial_service", "first_responder", "government", "health", "informational", "pharmacy", "political", "real_estate", "school_college", "survey", "telemarketing" ] }, "effective_monthly_call_volume": { "type": "string", "enum": [ "1", "101", "501", "1001", "5001", "10001", "50001", "dontknow" ] }, "call_purpose_options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "monthly_call_volume_options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "call_purpose", "monthly_call_volume", "effective_call_purpose", "effective_monthly_call_volume", "call_purpose_options", "monthly_call_volume_options" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "put": { "operationId": "v1_caller_trust_registration_profile_put", "tags": [ "Number Registration" ], "summary": "Set the workspace's Free Caller Registry registration profile", "description": "Sets the default call purpose and monthly call-volume bracket for Free Caller Registry submissions. call_purpose and monthly_call_volume must be option values from GET (call_purpose_options / monthly_call_volume_options).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "call_purpose": { "type": "string", "enum": [ "attorney_legal", "financial_service", "first_responder", "government", "health", "informational", "pharmacy", "political", "real_estate", "school_college", "survey", "telemarketing" ] }, "monthly_call_volume": { "type": "string", "enum": [ "1", "101", "501", "1001", "5001", "10001", "50001", "dontknow" ] } }, "required": [ "call_purpose", "monthly_call_volume" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_purpose": { "anyOf": [ { "type": "string", "enum": [ "attorney_legal", "financial_service", "first_responder", "government", "health", "informational", "pharmacy", "political", "real_estate", "school_college", "survey", "telemarketing" ] }, { "type": "null" } ] }, "monthly_call_volume": { "anyOf": [ { "type": "string", "enum": [ "1", "101", "501", "1001", "5001", "10001", "50001", "dontknow" ] }, { "type": "null" } ] }, "effective_call_purpose": { "type": "string", "enum": [ "attorney_legal", "financial_service", "first_responder", "government", "health", "informational", "pharmacy", "political", "real_estate", "school_college", "survey", "telemarketing" ] }, "effective_monthly_call_volume": { "type": "string", "enum": [ "1", "101", "501", "1001", "5001", "10001", "50001", "dontknow" ] }, "call_purpose_options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "monthly_call_volume_options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "call_purpose", "monthly_call_volume", "effective_call_purpose", "effective_monthly_call_volume", "call_purpose_options", "monthly_call_volume_options" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/reputation/numbers/{phone}": { "get": { "operationId": "v1_caller_trust_reputation_numbers_phone_get", "tags": [ "Reputation" ], "summary": "Get reputation scores for a phone number", "description": "Returns Hiya-sourced spam risk + 0-100 component scores. Passing `fresh=true` forces a live carrier query billed at $0.25 to your wallet (rate-limited to 1/day/number). Cached reads are free — the weekly scheduled check keeps them warm.", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": true, "schema": {} } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_number": { "type": "string" }, "enterprise_id": { "type": [ "string", "null" ] }, "spam_risk": { "type": [ "string", "null" ] }, "spam_category": { "type": [ "string", "null" ] }, "maturity_score": { "type": [ "number", "null" ] }, "connection_score": { "type": [ "number", "null" ] }, "engagement_score": { "type": [ "number", "null" ] }, "sentiment_score": { "type": [ "number", "null" ] }, "last_refreshed_at": { "type": [ "string", "null" ] } }, "required": [ "phone_number", "enterprise_id", "spam_risk", "spam_category", "maturity_score", "connection_score", "engagement_score", "sentiment_score", "last_refreshed_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_caller_trust_reputation_numbers_phone_delete", "tags": [ "Reputation" ], "summary": "Disenroll a phone number from reputation monitoring", "description": "Removes a phone number from carrier number-reputation monitoring. The number must be currently enrolled. Cached reputation scores are deleted.", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_number": { "type": "string" }, "disenrolled": { "type": "boolean", "const": true } }, "required": [ "phone_number", "disenrolled" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/reputation/numbers": { "get": { "operationId": "v1_caller_trust_reputation_numbers_get", "tags": [ "Reputation" ], "summary": "List reputation scores for every enrolled number", "description": "Returns per-phone spam risk + component scores for every number the caller owns that's enrolled under an enterprise (either umbrella or own-brand).", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string" }, "enterprise_id": { "type": "string" }, "spam_risk": { "type": [ "string", "null" ] }, "spam_category": { "type": [ "string", "null" ] }, "maturity_score": { "type": [ "number", "null" ] }, "connection_score": { "type": [ "number", "null" ] }, "engagement_score": { "type": [ "number", "null" ] }, "sentiment_score": { "type": [ "number", "null" ] }, "last_refreshed_at": { "type": [ "string", "null" ] } }, "required": [ "phone_number", "enterprise_id", "spam_risk", "spam_category", "maturity_score", "connection_score", "engagement_score", "sentiment_score", "last_refreshed_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": [ "page_size" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_caller_trust_reputation_numbers_post", "tags": [ "Reputation" ], "summary": "Enroll phone numbers in reputation monitoring", "description": "Enrolls one or more phone numbers in carrier number-reputation monitoring. Numbers must belong to the caller and be in US E.164 format. Enrollment is idempotent — re-enrolling an already-enrolled number is a no-op.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_numbers": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^\\+1\\d{10}$" } } }, "required": [ "phone_numbers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enrolled": { "type": "number" }, "phone_numbers": { "type": "array", "items": { "type": "string" } } }, "required": [ "enrolled", "phone_numbers" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/reputation/remediations/{id}": { "get": { "operationId": "v1_caller_trust_reputation_remediations_id_get", "tags": [ "Reputation" ], "summary": "Get a remediation request", "description": "Status and per-number outcomes for one remediation request. Outcomes are null until processing completes (usually a few days). Possible outcomes: remediated, not_flagged, requires_review, ineligible, refused.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "submitted_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "numbers": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "billed_amount_dc": { "type": "number" } }, "required": [ "phone_number", "outcome", "billed_amount_dc" ], "additionalProperties": false } } }, "required": [ "request_id", "status", "source", "submitted_at", "completed_at", "numbers" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/reputation/remediations": { "post": { "operationId": "v1_caller_trust_reputation_remediations_post", "tags": [ "Reputation" ], "summary": "Submit numbers for spam-label remediation", "description": "Asks the carrier analytics providers to clear spam/scam-likely labels on the given numbers. Billed $2 per number to your wallet once accepted, regardless of outcome. Limit: one remediation per number per 14 days. Numbers must be enrolled in reputation monitoring. Async — poll GET /remediations/{id} or subscribe to the reputation.remediation_completed webhook.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_numbers": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^\\+1\\d{10}$" } } }, "required": [ "phone_numbers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "submitted_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "numbers": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "billed_amount_dc": { "type": "number" } }, "required": [ "phone_number", "outcome", "billed_amount_dc" ], "additionalProperties": false } } }, "required": [ "request_id", "status", "source", "submitted_at", "completed_at", "numbers" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } }, "get": { "operationId": "v1_caller_trust_reputation_remediations_get", "tags": [ "Reputation" ], "summary": "List remediation requests", "description": "Every remediation request that includes at least one of your numbers, newest first. Use GET /remediations/{id} for per-number outcomes.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "submitted_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "numbers_count": { "type": "number" } }, "required": [ "request_id", "status", "source", "submitted_at", "completed_at", "numbers_count" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": [ "page_size" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/reputation": { "get": { "operationId": "v1_caller_trust_reputation_get", "tags": [ "Reputation" ], "summary": "Get Number Reputation enrollment settings", "description": "Number reputation monitoring is included for every number under RevDesk's shared umbrella. This returns per-enterprise settings (status + check frequency) only for own-brand registrations; it returns null when the caller's numbers are on the shared umbrella (the default), which is not an error.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "enterprise_id", "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_caller_trust_reputation_post", "tags": [ "Reputation" ], "summary": "Enable Number Reputation monitoring", "description": "Enables (or re-enables) enterprise-level reputation monitoring via the carrier's reputation provider. Requires an enterprise that has been submitted to the carrier (has a carrier_enterprise_id) and has an LOA document on file. Idempotent on REJECTED status — calling this after rejection replaces the rejected record with a fresh PENDING one.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "check_frequency": { "type": "string", "enum": [ "weekly", "biweekly", "monthly", "never" ] }, "loa_document_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "enterprise_id", "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } }, "delete": { "operationId": "v1_caller_trust_reputation_delete", "tags": [ "Reputation" ], "summary": "Disable Number Reputation monitoring", "description": "Disables reputation monitoring for the caller's enterprise. Only works when the current status is APPROVED. All enrolled numbers will stop being monitored.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "disabled": { "type": "boolean", "const": true } }, "required": [ "enterprise_id", "disabled" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } }, "patch": { "operationId": "v1_caller_trust_reputation_patch", "tags": [ "Reputation" ], "summary": "Update reputation check frequency", "description": "Changes how often the carrier refreshes spam scores for enrolled numbers. Each refresh is billed per number, so this is a cost lever. Only works when reputation status is APPROVED.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "check_frequency": { "type": "string", "enum": [ "weekly", "biweekly", "monthly", "never" ] } }, "required": [ "check_frequency" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "status": { "type": "string" }, "check_frequency": { "type": "string" } }, "required": [ "enterprise_id", "status", "check_frequency" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/calls/{id}/hangup": { "post": { "operationId": "v1_calls_id_hangup_post", "tags": [ "Calls" ], "summary": "Hang up a call", "description": "Ends a call or cancels an unused browser calling ticket. Idempotent for terminal calls. mode=setup_failed records a browser setup error and cancels only unused tickets; mode=cancel_setup cancels only unused tickets. Both setup modes leave originated calls untouched. With no mode, active calls are hung up normally.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": true, "schema": { "default": "hangup", "type": "string", "enum": [ "hangup", "cancel_setup", "setup_failed" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "call_id", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "calls:write" ], "x-required-scopes": [ "calls:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/calls/{id}": { "get": { "operationId": "v1_calls_id_get", "tags": [ "Calls" ], "summary": "Retrieve a single call", "description": "Returns metadata for the call. `has_recording` reflects whether a recording exists, but the actual `recording_url` is only populated when the key also holds the `recordings:read` scope (recording audio is sensitive and gated separately from call metadata).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "direction": { "type": [ "string", "null" ] }, "from_number": { "type": [ "string", "null" ] }, "to_number": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ] }, "ended_at": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "number", "null" ] }, "phone_number_id": { "type": [ "number", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "user_id": { "type": [ "string", "null" ] }, "has_recording": { "type": "boolean" }, "recording_url": { "type": [ "string", "null" ] }, "has_transcript": { "type": "boolean" }, "source": { "type": [ "string", "null" ] }, "client_name": { "type": [ "string", "null" ] }, "client_label": { "type": [ "string", "null" ] }, "credential_type": { "type": [ "string", "null" ] }, "test_result": { "anyOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "BUSINESS_NAME", "LOCATION", "NUMBER_ONLY", "SPAM", "NO_CALL" ] }, "observed_label": { "type": "string" }, "recorded_at": { "type": "string" }, "callback_verified": { "type": "boolean" } }, "required": [ "outcome", "observed_label", "recorded_at", "callback_verified" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "type": "string" }, "failure_code": { "type": [ "string", "null" ] }, "failure_category": { "type": [ "string", "null" ] }, "disconnection_reason": { "type": [ "string", "null" ] }, "network": { "anyOf": [ { "type": "object", "properties": { "capturedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "caller": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "phone", "agent", "unknown" ] }, "ip": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] }, { "type": "null" } ] }, "ipSource": { "type": "string", "enum": [ "request", "client_reported", "unavailable", "expired" ] }, "userId": { "type": [ "string", "null" ] } }, "required": [ "kind", "ip", "ipSource", "userId" ], "additionalProperties": false }, "callee": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "phone", "agent", "unknown" ] }, "ip": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] }, { "type": "null" } ] }, "ipSource": { "type": "string", "enum": [ "request", "client_reported", "unavailable", "expired" ] }, "userId": { "type": [ "string", "null" ] } }, "required": [ "kind", "ip", "ipSource", "userId" ], "additionalProperties": false }, "requester": { "anyOf": [ { "type": "object", "properties": { "ip": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "app", "api" ] }, "userId": { "type": [ "string", "null" ] } }, "required": [ "ip", "kind", "userId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "capturedAt", "caller", "callee", "requester" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "direction", "from_number", "to_number", "started_at", "ended_at", "duration_seconds", "phone_number_id", "organization_id", "user_id", "has_recording", "recording_url", "has_transcript", "source", "client_name", "client_label", "credential_type", "test_result", "created_at", "failure_code", "failure_category", "disconnection_reason", "network" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "calls:read" ], "x-required-scopes": [ "calls:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/calls/{id}/test-result": { "patch": { "operationId": "v1_calls_id_test_result_patch", "tags": [ "Calls", "Phone Numbers" ], "summary": "Record a spam-label test result", "description": "Records what a recipient handset displayed for a call placed through the spam-label test endpoint. Only calls already marked as spam-label tests can be annotated.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "BUSINESS_NAME", "LOCATION", "NUMBER_ONLY", "SPAM", "NO_CALL" ] }, "observed_label": { "default": "", "type": "string", "maxLength": 160 }, "callback_verified": { "default": false, "type": "boolean" } }, "required": [ "outcome", "observed_label", "callback_verified" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "BUSINESS_NAME", "LOCATION", "NUMBER_ONLY", "SPAM", "NO_CALL" ] }, "observed_label": { "type": "string" }, "recorded_at": { "type": "string" }, "callback_verified": { "type": "boolean" } }, "required": [ "call_id", "outcome", "observed_label", "recorded_at", "callback_verified" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "calls:write" ], "x-required-scopes": [ "calls:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/calls/{id}/transcript": { "get": { "operationId": "v1_calls_id_transcript_get", "tags": [ "Calls" ], "summary": "Retrieve a call transcript", "description": "Returns the flat transcript text plus the speaker-diarized `structured_transcript` turns. Requires the `transcripts:read` scope (transcript content is sensitive and gated separately from call metadata). Organizations whose call-content policy pins content to a compliance (HIPAA) boundary receive `403 content_policy_forbidden`. A call with no stored transcript returns `404 not_found`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "transcript": { "type": [ "string", "null" ] }, "structured_transcript": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "text": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] }, "interrupted": { "type": "boolean" }, "language": { "type": "string" } }, "required": [ "role", "text" ], "additionalProperties": {} } }, { "type": "null" } ] }, "transcript_provider": { "type": [ "string", "null" ] } }, "required": [ "call_id", "transcript", "structured_transcript", "transcript_provider" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "transcripts:read" ], "x-required-scopes": [ "transcripts:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/calls/dial": { "post": { "operationId": "v1_calls_dial_post", "tags": [ "Calls" ], "summary": "Bridge two phone numbers (from_number ↔ destination)", "description": "Bridges two phone numbers into one call — your from_number and the destination. Because it rings two phones, it uses TWO concurrent channels. Pass connect_number to ring a separate phone for the human leg (e.g. an agent's own cell) while the destination still sees from_number; the connect_number is never shown to the destination. Supply from_number or number_set_id; exact from_number always wins when both are present. Number Sets use recipient-sticky selection among the healthiest eligible members. High-risk caller IDs return a health_warning without reputation-based blocking; inactive or technically unroutable exact numbers fail without fallback. Billing, wallet, concurrency, and contractual protections still apply. For 1-channel calls, use POST /v1/calls (AI outbound — the agent joins over the network) or the WebRTC token flow (a human joins in the browser). Returns immediately with call_id, resolved from_number, selection_source, evidence_state, health_warning, and recommended_action; poll GET /v1/calls/{id} or subscribe to webhooks for status. Demo keys must target an allowlisted destination.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_number": { "description": "Exact owned caller ID in E.164. Wins when number_set_id is also supplied; never silently substituted.", "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "number_set_id": { "description": "Resolve an outbound-enabled Number Set member when from_number is omitted. Supply at least one of from_number or number_set_id.", "type": "string", "minLength": 1 }, "to_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "connect_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "record": { "default": true, "type": "boolean" }, "amd": { "default": false, "type": "boolean" }, "client_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "client_label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "to_number", "record", "amd" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted for asynchronous processing", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Location": { "description": "Canonical URL to poll for the queued call's current status.", "schema": { "type": "string", "format": "uri-reference" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "provider_call_sid": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" }, "status": { "type": "string" }, "selection_source": { "type": "string", "enum": [ "exact_from_number", "number_set_sticky_health" ] }, "evidence_state": { "type": "string" }, "health_warning": { "type": [ "string", "null" ] }, "recommended_action": { "type": "string" } }, "required": [ "call_id", "provider_call_sid", "from_number", "to_number", "status", "selection_source", "evidence_state", "health_warning", "recommended_action" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "calls:write" ], "x-required-scopes": [ "calls:write" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/calls": { "get": { "operationId": "v1_calls_get", "tags": [ "Calls" ], "summary": "List calls", "description": "Returns recent calls for the authenticated organization, newest first. Every call reports has_recording, but the actual recording_url is only populated when the key also holds the recordings:read scope; without it the field is null.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "spam_label_test" ] } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "direction": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" }, "started_at": { "type": [ "string", "null" ] }, "ended_at": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "number", "null" ] }, "phone_number_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "has_recording": { "type": "boolean" }, "recording_url": { "type": [ "string", "null" ] }, "has_transcript": { "type": "boolean" }, "source": { "type": [ "string", "null" ] }, "client_name": { "type": [ "string", "null" ] }, "client_label": { "type": [ "string", "null" ] }, "credential_type": { "type": [ "string", "null" ] }, "test_result": { "anyOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "BUSINESS_NAME", "LOCATION", "NUMBER_ONLY", "SPAM", "NO_CALL" ] }, "observed_label": { "type": "string" }, "recorded_at": { "type": "string" }, "callback_verified": { "type": "boolean" } }, "required": [ "outcome", "observed_label", "recorded_at", "callback_verified" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "type": "string" }, "user_id": { "type": [ "string", "null" ] }, "failure_code": { "type": [ "string", "null" ] }, "failure_category": { "type": [ "string", "null" ] }, "disconnection_reason": { "type": [ "string", "null" ] }, "network": { "anyOf": [ { "type": "object", "properties": { "capturedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "caller": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "phone", "agent", "unknown" ] }, "ip": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] }, { "type": "null" } ] }, "ipSource": { "type": "string", "enum": [ "request", "client_reported", "unavailable", "expired" ] }, "userId": { "type": [ "string", "null" ] } }, "required": [ "kind", "ip", "ipSource", "userId" ], "additionalProperties": false }, "callee": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "browser", "phone", "agent", "unknown" ] }, "ip": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] }, { "type": "null" } ] }, "ipSource": { "type": "string", "enum": [ "request", "client_reported", "unavailable", "expired" ] }, "userId": { "type": [ "string", "null" ] } }, "required": [ "kind", "ip", "ipSource", "userId" ], "additionalProperties": false }, "requester": { "anyOf": [ { "type": "object", "properties": { "ip": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "app", "api" ] }, "userId": { "type": [ "string", "null" ] } }, "required": [ "ip", "kind", "userId" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "capturedAt", "caller", "callee", "requester" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "direction", "from_number", "to_number", "started_at", "ended_at", "duration_seconds", "phone_number_id", "has_recording", "recording_url", "has_transcript", "source", "client_name", "client_label", "credential_type", "test_result", "created_at", "user_id", "failure_code", "failure_category", "disconnection_reason", "network" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "calls:read" ], "x-required-scopes": [ "calls:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_calls_post", "tags": [ "Calls" ], "summary": "Place an outbound AI call", "description": "Dispatches a single-leg outbound AI call to the destination. The agent (assistantId, or your most recently created agent) joins over the network and speaks, so the call uses one channel. For a human dial-bridge call from a specific number, use POST /v1/calls/dial.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "minLength": 1 }, "assistantId": { "type": "string" }, "script": { "type": "string" }, "name": { "type": "string" } }, "required": [ "phoneNumber" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted for asynchronous processing", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Location": { "description": "Canonical URL to poll for the queued call's current status.", "schema": { "type": "string", "format": "uri-reference" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "contact_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "call_id", "contact_id", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "calls:write" ], "x-required-scopes": [ "calls:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/client-tokens": { "post": { "operationId": "v1_client_tokens_post", "tags": [ "WebRTC" ], "summary": "Mint a bounded client token", "description": "Issues a short-lived, downscoped token (rdc_…) that is safe to ship into an untrusted client app. The token is restricted to the from_numbers (caller IDs) and to_numbers (destinations) you specify, so it can only place calls within those bounds — never from any number to any number. Present it on the same Authorization: Bearer header in place of your API key; the WebRTC SDK accepts it directly. The token's bounds must fall within this key's own number allowlist and its scopes; it is stateless and revoked by expiry. This endpoint requires a real API key — a minted token cannot mint further tokens. Regardless of the parent key's scopes, a client token may only carry the browser-calling scope (voice:webrtc) — it can never make durable account changes or mint further tokens. An explicit, non-empty to_numbers (destination allowlist) is required so the token can never dial an arbitrary number.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_numbers": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } }, "to_numbers": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "voice:webrtc" ] } }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 3600 } }, "required": [ "from_numbers", "to_numbers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "expires_in": { "type": "number" }, "from_numbers": { "type": "array", "items": { "type": "string" } }, "to_numbers": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "token", "expires_in", "from_numbers", "to_numbers", "scopes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "tokens:mint" ], "x-required-scopes": [ "tokens:mint" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/contacts/{id}": { "get": { "operationId": "v1_contacts_id_get", "tags": [ "Contacts" ], "summary": "Get a contact", "description": "Returns a single contact by id.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone_number": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "source": { "type": "string" }, "metadata": { "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "phone_number", "email", "status", "source", "metadata", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "contacts:read" ], "x-required-scopes": [ "contacts:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_contacts_id_patch", "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Updates a contact's name, email, company, or metadata. Fields omitted from the body are left unchanged; pass null to clear a nullable field. The phone number is immutable — create a new contact instead.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone_number": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "source": { "type": "string" }, "metadata": { "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "phone_number", "email", "status", "source", "metadata", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "contacts:write" ], "x-required-scopes": [ "contacts:write" ], "x-rate-limit": { "requestsPerMinute": 600 } }, "delete": { "operationId": "v1_contacts_id_delete", "tags": [ "Contacts" ], "summary": "Delete a contact", "description": "Permanently deletes a contact. Related records (messages, calls) are removed by database cascade. This cannot be undone.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "contacts:write" ], "x-required-scopes": [ "contacts:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/contacts": { "get": { "operationId": "v1_contacts_get", "tags": [ "Contacts" ], "summary": "List contacts", "description": "Returns recent contacts for the authenticated organization, newest first.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone_number": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "source": { "type": "string" }, "metadata": { "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "phone_number", "email", "status", "source", "metadata", "created_at", "updated_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "contacts:read" ], "x-required-scopes": [ "contacts:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_contacts_post", "tags": [ "Contacts" ], "summary": "Create or update a contact", "description": "Upserts a contact by phone number: creates it when no contact with that number exists in the organization, otherwise updates the existing contact's name/email/metadata. The `created` flag in the response tells you which happened (201 on create, 200 on update).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "sms_consent": { "type": "boolean" }, "sms_consent_source": { "type": "string" } }, "required": [ "phone_number" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone_number": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "source": { "type": "string" }, "metadata": { "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created": { "type": "boolean" } }, "required": [ "id", "name", "phone_number", "email", "status", "source", "metadata", "created_at", "updated_at", "created" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "contacts:write" ], "x-required-scopes": [ "contacts:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/jobs/{jobId}": { "get": { "operationId": "v1_jobs_jobId_get", "tags": [ "Tasks" ], "summary": "Retrieve a task (legacy path)", "deprecated": true, "description": "Deprecated compatibility alias for `GET /v1/tasks/{taskId}`. Returns the task, its provenance timeline, and recorded outcomes with evidence.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "objective": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "number" }, "occurred_at": { "type": "string" }, "row_type": { "type": "string" }, "actor": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "system": { "type": [ "string", "null" ] }, "body": { "type": "string" } }, "required": [ "seq", "occurred_at", "row_type", "actor", "channel", "system", "body" ], "additionalProperties": false } }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "occurred_at": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "billable": { "type": "boolean" }, "billed_at": { "type": [ "string", "null" ] }, "billed_amount": { "type": [ "number", "null" ] }, "attribution_mode": { "type": "string" }, "disputed_at": { "type": [ "string", "null" ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "interaction_type": { "type": "string" }, "interaction_id": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "interaction_type", "interaction_id", "note" ], "additionalProperties": false } } }, "required": [ "id", "kind", "occurred_at", "value", "billable", "billed_at", "billed_amount", "attribution_mode", "disputed_at", "evidence" ], "additionalProperties": false } } }, "required": [ "id", "type", "status", "objective", "contact_id", "deadline", "created_at", "closed_at", "events", "outcomes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "jobs:read" ], "x-required-scopes": [ "jobs:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/jobs": { "get": { "operationId": "v1_jobs_get", "tags": [ "Tasks" ], "summary": "List tasks (legacy path)", "deprecated": true, "description": "Deprecated compatibility alias for `GET /v1/tasks`. Tasks are returned newest first and may be filtered with `status` (OPEN, PAUSED, ACHIEVED, ABANDONED, EXPIRED).", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "objective": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "opportunity_id": { "type": [ "string", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "status", "objective", "contact_id", "opportunity_id", "deadline", "created_at", "closed_at" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "jobs:read" ], "x-required-scopes": [ "jobs:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_jobs_post", "tags": [ "Tasks" ], "summary": "Create a task (legacy path)", "deprecated": true, "description": "Deprecated compatibility alias for `POST /v1/tasks`. Hand RevDesk an outcome to pursue; progress and the terminal outcome arrive through task webhooks.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "objective": { "type": "string", "minLength": 1 }, "contact_id": { "type": "string" }, "opportunity_id": { "type": "string" }, "deadline": {}, "success_criteria": { "type": "object", "properties": { "outcome_kinds": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "guardrails": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "string" } }, "quiet_hours": { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "time_zone": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false }, "max_touches": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "max_touches_since_reply": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "min_hours_between_touches": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "type", "objective" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "objective": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "opportunity_id": { "type": [ "string", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "status", "objective", "contact_id", "opportunity_id", "deadline", "created_at", "closed_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "jobs:write" ], "x-required-scopes": [ "jobs:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/me": { "get": { "operationId": "v1_me_get", "tags": [ "Account" ], "summary": "Current identity", "description": "The identity behind the API key: the user, their organization, and the scopes the key carries. For the organization's plan and footprint, use GET /v1/account.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "api_key_id": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "is_demo": { "type": "boolean" }, "demo_expires_at": { "type": [ "string", "null" ] } }, "required": [ "api_key_id", "user", "organization", "scopes", "is_demo", "demo_expires_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/messages/{id}": { "get": { "operationId": "v1_messages_id_get", "tags": [ "SMS" ], "summary": "Get an SMS message", "description": "Returns a single SMS message by id (the id returned from list and send responses).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "phone_number": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "content": { "type": "string" }, "status": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_token": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "direction", "content", "status", "contact_name", "contact_email", "contact_token", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:read" ], "x-required-scopes": [ "sms:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/messages": { "get": { "operationId": "v1_messages_get", "tags": [ "SMS" ], "summary": "List SMS messages", "description": "Returns recent SMS messages for the authenticated organization, newest first. Direction is derived per message: inbound messages came from the contact's number, outbound messages were sent from one of your numbers.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 50 } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phone_number": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "content": { "type": "string" }, "status": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_token": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "direction", "content", "status", "contact_name", "contact_email", "contact_token", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:read" ], "x-required-scopes": [ "sms:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_messages_post", "tags": [ "SMS" ], "summary": "Send an SMS to a contact", "deprecated": true, "description": "Sends an outbound SMS to the given number from your organization's default sending number, creating the contact if it does not exist. Superseded by POST /v1/sms/send, which lets you pick the sending number explicitly.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "name": { "type": "string" } }, "required": [ "phone_number", "message" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "boolean" }, "message_id": { "type": "string" }, "contact_token": { "type": "string" }, "phone_number": { "type": "string" } }, "required": [ "sent", "message_id", "contact_token", "phone_number" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:write" ], "x-required-scopes": [ "sms:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/mobile/devices/{installationId}": { "delete": { "operationId": "v1_mobile_devices_installationId_delete", "tags": [ "Notifications" ], "summary": "Revoke a native notification device", "description": "Stops native push delivery for one installation owned by the authenticated user and organization.", "parameters": [ { "name": "installationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "notifications:write" ], "x-required-scopes": [ "notifications:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/mobile/devices": { "put": { "operationId": "v1_mobile_devices_put", "tags": [ "Notifications" ], "summary": "Register a native notification device", "description": "Registers or refreshes one authenticated user's native RevDesk installation for Expo push delivery. The installation is bound to the OAuth actor and active organization; repeated calls are idempotent.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "installation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expo_push_token": { "type": "string", "pattern": "^(?:ExponentPushToken|ExpoPushToken)\\[[A-Za-z0-9_-]+\\]$" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "environment": { "type": "string", "enum": [ "development", "preview", "production" ] }, "app_version": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "installation_id", "expo_push_token", "platform", "environment", "app_version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "installation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "platform": { "type": "string" }, "environment": { "type": "string" }, "app_version": { "type": "string" }, "last_registered_at": { "type": "string" } }, "required": [ "installation_id", "platform", "environment", "app_version", "last_registered_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "notifications:write" ], "x-required-scopes": [ "notifications:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-health/attempts/{id}/observation": { "post": { "operationId": "v1_number_health_attempts_id_observation_post", "tags": [ "Number Health" ], "summary": "Record or revise a carrier/handset observation", "description": "Stores the exact handset display with server-measured call evidence and an audit snapshot.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "CLEAN", "NUMBER_ONLY", "LOCATION", "WRONG_NAME", "SPAM", "SCAM", "BLOCKED", "NO_RING", "UNKNOWN" ] }, "observed_label": { "type": "string", "maxLength": 120 }, "callback_verified": { "type": "boolean" }, "handset": { "type": "object", "properties": { "manufacturer": { "type": "string", "maxLength": 80 }, "model": { "type": "string", "maxLength": 80 }, "os": { "type": "string", "maxLength": 80 } }, "additionalProperties": false } }, "required": [ "outcome" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "program_id": { "type": "string" } }, "required": [ "id", "program_id" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-health/numbers": { "get": { "operationId": "v1_number_health_numbers_get", "tags": [ "Number Health" ], "summary": "List authoritative number-health evidence", "description": "Returns every phone number in the workspace with Number Set membership, provider scores, carrier-specific handset observations, evidence freshness, and the next recommended action.", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CLEAN_OBSERVED", "NEEDS_DATA", "WATCH", "FLAGGED", "SETUP_INCOMPLETE", "RETIRED" ] } }, { "name": "team_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "number_set_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "area_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{3}$" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "phone_number": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "team_id": { "type": [ "string", "null" ] }, "team_name": { "type": [ "string", "null" ] }, "area_code": { "type": "string" }, "cnam_display_name": { "type": [ "string", "null" ] }, "cnam_status": { "type": [ "string", "null" ] }, "caller_registry_status": { "type": [ "string", "null" ] }, "reputation_enrolled_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "number_set_id": { "type": [ "string", "null" ] }, "number_set_name": { "type": [ "string", "null" ] }, "number_set_use_case": { "type": [ "string", "null" ] }, "member_role": { "anyOf": [ { "type": "string", "enum": [ "PRIMARY", "ALTERNATE" ] }, { "type": "null" } ] }, "member_state": { "anyOf": [ { "type": "string", "enum": [ "PREPARING", "ACTIVE", "STANDBY", "RETIRED" ] }, { "type": "null" } ] }, "evidence_state": { "type": "string", "enum": [ "CLEAN_OBSERVED", "NEEDS_DATA", "WATCH", "FLAGGED", "SETUP_INCOMPLETE", "RETIRED" ] }, "health_warning": { "type": [ "string", "null" ] }, "recommended_action": { "type": "string" }, "has_alternate": { "type": "boolean" }, "spam_risk": { "anyOf": [ { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, { "type": "null" } ] }, "spam_category": { "type": [ "string", "null" ] }, "maturity_score": { "type": [ "number", "null" ] }, "connection_score": { "type": [ "number", "null" ] }, "engagement_score": { "type": [ "number", "null" ] }, "sentiment_score": { "type": [ "number", "null" ] }, "reputation_refreshed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "qualifying_calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "callback_verified": { "type": "boolean" }, "observations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "carrier": { "type": "string", "enum": [ "ATT", "TMOBILE", "VERIZON", "OTHER", "UNKNOWN" ] }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "CLEAN", "NUMBER_ONLY", "LOCATION", "SPAM", "SCAM", "BLOCKED", "WRONG_NAME", "NO_RING", "UNKNOWN" ] }, { "type": "null" } ] }, "observed_label": { "type": [ "string", "null" ] }, "observed_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "duration_seconds": { "type": [ "number", "null" ] }, "callback_verified": { "type": "boolean" } }, "required": [ "id", "carrier", "outcome", "observed_label", "observed_at", "duration_seconds", "callback_verified" ], "additionalProperties": false } } }, "required": [ "id", "phone_number", "name", "is_active", "team_id", "team_name", "area_code", "cnam_display_name", "cnam_status", "caller_registry_status", "reputation_enrolled_at", "number_set_id", "number_set_name", "number_set_use_case", "member_role", "member_state", "evidence_state", "health_warning", "recommended_action", "has_alternate", "spam_risk", "spam_category", "maturity_score", "connection_score", "engagement_score", "sentiment_score", "reputation_refreshed_at", "qualifying_calls", "callback_verified", "observations" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "total_results": { "type": "number" } }, "required": [ "total_results" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/number-health/policy": { "get": { "operationId": "v1_number_health_policy_get", "tags": [ "Number Health" ], "summary": "Get the canonical Number Health evidence policy", "description": "Returns readiness criteria and current wallet prices for explicit fresh-check/remediation previews.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "version": { "type": "string" }, "qualifying_calls": { "type": "number" }, "consented_testers": { "type": "number" }, "active_days": { "type": "number" }, "duration_target_seconds": { "type": "number" }, "history_window_days": { "type": "number" }, "readiness_interactions_per_tester_day": { "type": "number" }, "calendar_timezone": { "type": "string", "const": "UTC" }, "fresh_check_price_usd": { "type": "number" }, "remediation_price_usd": { "type": "number" }, "synthetic_counts": { "type": "boolean", "const": false } }, "required": [ "version", "qualifying_calls", "consented_testers", "active_days", "duration_target_seconds", "history_window_days", "readiness_interactions_per_tester_day", "calendar_timezone", "fresh_check_price_usd", "remediation_price_usd", "synthetic_counts" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/number-health/sessions/{id}/attempts": { "post": { "operationId": "v1_number_health_sessions_id_attempts_post", "tags": [ "Number Health" ], "summary": "Attach a real call to a Number Health session", "description": "Creates an audited attempt from an existing human WebRTC call. Server call events remain authoritative for answer state and duration.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "call_id": { "type": "string", "minLength": 1 } }, "required": [ "phone_id", "call_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-health/sessions/{id}/inbound": { "get": { "operationId": "v1_number_health_sessions_id_inbound_get", "tags": [ "Number Health" ], "summary": "Read carrier-confirmed inbound test progress", "description": "Only returns calls from the session's consented tester to a number in its saved queue, after the session began.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "phone_id", "in": "query", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "answered_at": { "type": [ "string", "null" ] }, "ended_at": { "type": [ "string", "null" ] }, "duration_seconds": { "type": "number" }, "callback_verified": { "type": "boolean" }, "human": { "type": "boolean" } }, "required": [ "call_id", "status", "answered_at", "ended_at", "duration_seconds", "callback_verified", "human" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/number-health/sessions/{id}": { "get": { "operationId": "v1_number_health_sessions_id_get", "tags": [ "Number Health" ], "summary": "Resume a Number Health test session", "description": "Returns the saved session scope, tester, queue, and server-backed attempts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "participant_id": { "type": [ "string", "null" ] }, "tester_alias": { "type": [ "string", "null" ] }, "tester_phone": { "type": [ "string", "null" ] }, "tester_carrier": { "anyOf": [ { "type": "string", "enum": [ "ATT", "TMOBILE", "VERIZON", "OTHER", "UNKNOWN" ] }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "RAPID_AUDIT", "HUMAN_READINESS", "CONNECTIVITY_QA" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "COMPLETED", "CANCELLED" ] }, "scope": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ALL", "TEAM", "NUMBER_SET", "AREA_CODE", "FLAGGED", "NEEDS_DATA" ] }, "value": { "type": "string" }, "phoneIds": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "kind", "phoneIds" ], "additionalProperties": false }, "compare_alternates": { "type": "boolean" }, "current_phone_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "phone_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "started_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phone_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "phone_number": { "type": "string" }, "status": { "type": "string", "enum": [ "TICKETED", "RINGING", "CONNECTED", "COMPLETED", "FAILED", "CANCELED" ] }, "mode": { "type": "string", "enum": [ "RAPID_AUDIT", "HUMAN_READINESS", "CONNECTIVITY_QA" ] }, "evidence_eligible": { "type": "boolean" }, "evidence_exclusion_reason": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "number", "null" ] }, "inbound_duration_seconds": { "type": [ "number", "null" ] }, "outbound_duration_seconds": { "type": [ "number", "null" ] }, "display_outcome": { "anyOf": [ { "type": "string", "enum": [ "CLEAN", "NUMBER_ONLY", "LOCATION", "SPAM", "SCAM", "BLOCKED", "WRONG_NAME", "NO_RING", "UNKNOWN" ] }, { "type": "null" } ] }, "observed_label": { "type": [ "string", "null" ] }, "callback_verified": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "phone_id", "phone_number", "status", "mode", "evidence_eligible", "evidence_exclusion_reason", "duration_seconds", "inbound_duration_seconds", "outbound_duration_seconds", "display_outcome", "observed_label", "callback_verified", "created_at" ], "additionalProperties": false } } }, "required": [ "id", "participant_id", "tester_alias", "tester_phone", "tester_carrier", "mode", "status", "scope", "compare_alternates", "current_phone_id", "phone_ids", "started_at", "completed_at", "attempts" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_number_health_sessions_id_patch", "tags": [ "Number Health" ], "summary": "Pause, resume, or close a Number Health session", "description": "Updates session lifecycle without deleting its saved observations or call evidence.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "COMPLETED", "CANCELLED" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-health/sessions": { "post": { "operationId": "v1_number_health_sessions_post", "tags": [ "Number Health" ], "summary": "Start a resumable Number Health test session", "description": "Saves a consented tester, test mode, and immutable selected-number queue for a workspace.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tester": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 2, "maxLength": 80 }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "carrier": { "type": "string", "enum": [ "ATT", "TMOBILE", "VERIZON", "OTHER", "UNKNOWN" ] }, "consented": { "type": "boolean", "const": true } }, "required": [ "alias", "phone_number", "carrier", "consented" ], "additionalProperties": false }, "mode": { "type": "string", "enum": [ "RAPID_AUDIT", "HUMAN_READINESS", "CONNECTIVITY_QA" ] }, "scope": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ALL", "TEAM", "NUMBER_SET", "AREA_CODE", "FLAGGED", "NEEDS_DATA" ] }, "value": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": false }, "compare_alternates": { "default": true, "type": "boolean" } }, "required": [ "tester", "mode", "scope", "compare_alternates" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:write" ], "x-required-scopes": [ "caller_trust:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-health/sets/{id}/resolve": { "post": { "operationId": "v1_number_health_sets_id_resolve_post", "tags": [ "Number Health" ], "summary": "Resolve a Number Set caller ID", "description": "Chooses a recipient-sticky outbound member from the healthiest available tier, with warnings.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } }, "required": [ "destination_number" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "number_set_id": { "type": "string" }, "phone_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "from_number": { "type": "string" }, "evidence_state": { "type": "string", "enum": [ "CLEAN_OBSERVED", "NEEDS_DATA", "WATCH", "FLAGGED", "SETUP_INCOMPLETE", "RETIRED" ] }, "health_warning": { "type": [ "string", "null" ] }, "identification_guidance": { "type": [ "string", "null" ] }, "selection_source": { "type": "string", "const": "number_set_sticky_health" } }, "required": [ "number_set_id", "phone_id", "from_number", "evidence_state", "health_warning", "identification_guidance", "selection_source" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-health/sets/{id}": { "patch": { "operationId": "v1_number_health_sets_id_patch", "tags": [ "Number Health" ], "summary": "Update a Number Set and its member roles", "description": "Updates explicit clinic membership, roles, and outbound eligibility. This changes outbound selection only; it does not disable inbound service or alter billing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "use_case": { "type": "string", "minLength": 3, "maxLength": 240 }, "identification_guidance": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "members": { "type": "array", "items": { "type": "object", "properties": { "phone_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "role": { "type": "string", "enum": [ "PRIMARY", "ALTERNATE" ] }, "state": { "type": "string", "enum": [ "PREPARING", "ACTIVE", "STANDBY", "RETIRED" ] }, "outbound_enabled": { "type": "boolean" }, "priority": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "phone_id", "role", "state", "outbound_enabled", "priority" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:write" ], "x-required-scopes": [ "phone_numbers:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-health/sets": { "get": { "operationId": "v1_number_health_sets_get", "tags": [ "Number Health" ], "summary": "List Number Sets", "description": "Lists explicit clinic/purpose caller-ID sets and their current and alternate members.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "team_id": { "type": [ "string", "null" ] }, "team_name": { "type": [ "string", "null" ] }, "use_case": { "type": "string" }, "expected_daily_calls": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "identification_guidance": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phone_id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "phone_number": { "type": "string" }, "phone_name": { "type": [ "string", "null" ] }, "phone_active": { "type": "boolean" }, "role": { "type": "string", "enum": [ "PRIMARY", "ALTERNATE" ] }, "state": { "type": "string", "enum": [ "PREPARING", "ACTIVE", "STANDBY", "RETIRED" ] }, "outbound_enabled": { "type": "boolean" }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "phone_id", "phone_number", "phone_name", "phone_active", "role", "state", "outbound_enabled", "priority" ], "additionalProperties": false } } }, "required": [ "id", "name", "team_id", "team_name", "use_case", "expected_daily_calls", "identification_guidance", "status", "created_at", "updated_at", "members" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "total_results": { "type": "number" } }, "required": [ "total_results" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_number_health_sets_post", "tags": [ "Number Health" ], "summary": "Create a Number Set", "description": "Creates an organization-scoped clinic/purpose set from owned phone numbers.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "team_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "use_case": { "default": "Expected customer communications", "type": "string", "minLength": 3, "maxLength": 240 }, "expected_daily_calls": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "identification_guidance": { "type": "string", "maxLength": 500 }, "members": { "default": [], "type": "array", "items": { "type": "object", "properties": { "phone_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "role": { "type": "string", "enum": [ "PRIMARY", "ALTERNATE" ] }, "state": { "default": "ACTIVE", "type": "string", "enum": [ "PREPARING", "ACTIVE", "STANDBY" ] }, "outbound_enabled": { "default": true, "type": "boolean" }, "priority": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "phone_id", "role", "state", "outbound_enabled", "priority" ], "additionalProperties": false } } }, "required": [ "name", "use_case", "members" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:write" ], "x-required-scopes": [ "phone_numbers:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/number-registrations/{id}": { "get": { "operationId": "v1_number_registrations_id_get", "tags": [ "Number Registration" ], "summary": "Get a number registration", "description": "One registration with its latest submission state and per-engine acknowledgments (hiya, tns, first_orion). A registration is `submitted` once the registry accepts it and `active` after the first engine acknowledges — propagation to carrier spam labeling typically completes within 24–48 hours.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "registration_id": { "type": "string" }, "phone_number": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "hosted": { "type": "boolean" }, "registered_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "submission": { "anyOf": [ { "type": "object", "properties": { "submission_id": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": [ "string", "null" ] }, "vendor_acks": { "type": "object", "properties": { "hiya": { "type": [ "string", "null" ] }, "tns": { "type": [ "string", "null" ] }, "first_orion": { "type": [ "string", "null" ] } }, "required": [ "hiya", "tns", "first_orion" ], "additionalProperties": false }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "submission_id", "status", "submitted_at", "vendor_acks", "last_error" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "registration_id", "phone_number", "status", "source", "hosted", "registered_at", "cancelled_at", "created_at", "submission" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/number-registrations": { "get": { "operationId": "v1_number_registrations_get", "tags": [ "Number Registration" ], "summary": "List number registrations", "description": "RevDesk-managed Free Caller Registry status for hosted numbers in your workspace, oldest first and cursor-paged. Filter by status or an exact phone_number.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "submitted", "active", "failed", "cancelled" ] } }, { "name": "phone_number", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "registration_id": { "type": "string" }, "phone_number": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "hosted": { "type": "boolean" }, "registered_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "registration_id", "phone_number", "status", "source", "hosted", "registered_at", "cancelled_at", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": [ "page_size" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "caller_trust:read" ], "x-required-scopes": [ "caller_trust:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/phone-numbers/{id}/cnam-status": { "get": { "operationId": "v1_phone_numbers_id_cnam_status_get", "tags": [ "Phone Numbers" ], "summary": "Check live CNAM status", "description": "Queries the carrier for the current CNAM status. A pending name is promoted to APPROVED only when the carrier reports that same name as enabled.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "cnam_display_name": { "type": [ "string", "null" ] }, "cnam_status": { "type": "string" }, "live_status": { "type": "string", "enum": [ "active", "inactive", "provisioning" ] }, "live_enabled": { "type": "boolean" }, "live_display_name": { "type": [ "string", "null" ] } }, "required": [ "id", "phone_number", "cnam_display_name", "cnam_status", "live_status", "live_enabled", "live_display_name" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:read" ], "x-required-scopes": [ "phone_numbers:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/phone-numbers/{id}": { "get": { "operationId": "v1_phone_numbers_id_get", "tags": [ "Phone Numbers" ], "summary": "Retrieve a phone number", "description": "Polls for status. While provisioning is in flight, `is_active=false` and `phone_number` is a `pending:…` placeholder. Once the workflow completes, both fields update atomically.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "provider": { "type": "string" }, "is_active": { "type": "boolean" }, "subscription_status": { "type": [ "string", "null" ] }, "iso_country": { "type": "string" }, "reputation_enrolled_at": { "type": [ "string", "null" ] }, "agent_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "name", "organization_id", "user_id", "provider", "is_active", "subscription_status", "iso_country", "reputation_enrolled_at", "agent_id", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:read" ], "x-required-scopes": [ "phone_numbers:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_phone_numbers_id_patch", "tags": [ "Phone Numbers" ], "summary": "Update a phone number's settings", "description": "Mutates name + recording flags + CNAM display name. CNAM is the caller-ID name shown on outbound calls (max 15 chars, US local numbers only). Setting `cnam_display_name` updates the carrier on the spot — propagation to carriers takes 24-72h.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "cnam_display_name": { "type": "string", "minLength": 1, "maxLength": 15 }, "cnam_enabled": { "type": "boolean" }, "recording_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" }, "agent_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "cnam_display_name": { "type": [ "string", "null" ] }, "cnam_status": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "recording_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" }, "agent_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "id", "cnam_display_name", "cnam_status", "name", "recording_enabled", "transcription_enabled", "agent_id" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:write" ], "x-required-scopes": [ "phone_numbers:write" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_phone_numbers_id_delete", "tags": [ "Phone Numbers" ], "summary": "Release a phone number", "description": "Releases the phone number from the carrier, cancels the Stripe subscription line item, deletes associated call data and recordings, and removes the database record.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:write" ], "x-required-scopes": [ "phone_numbers:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/phone-numbers/{id}/sms-config": { "get": { "operationId": "v1_phone_numbers_id_sms_config_get", "tags": [ "SMS" ], "summary": "Get a number's SMS auto-reply override", "description": "Returns the per-number SMS auto-reply override, if any. When `has_override` is false the number inherits the workspace setting (GET /v1/sms/config).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_number_id": { "type": "number" }, "has_override": { "type": "boolean" }, "auto_reply_enabled": { "type": [ "boolean", "null" ] }, "reply_delay_seconds": { "type": [ "number", "null" ] }, "default_prompt": { "type": [ "string", "null" ] } }, "required": [ "phone_number_id", "has_override", "auto_reply_enabled", "reply_delay_seconds", "default_prompt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:read" ], "x-required-scopes": [ "sms:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_phone_numbers_id_sms_config_patch", "tags": [ "SMS" ], "summary": "Set a number's SMS auto-reply override", "description": "Creates or updates a per-number SMS auto-reply override, taking precedence over the workspace setting. Set `auto_reply_enabled: false` for one-way SMS on this number only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_reply_enabled": { "type": "boolean" }, "reply_delay_seconds": { "type": "integer", "minimum": 0, "maximum": 300 }, "default_prompt": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_number_id": { "type": "number" }, "has_override": { "type": "boolean" }, "auto_reply_enabled": { "type": [ "boolean", "null" ] }, "reply_delay_seconds": { "type": [ "number", "null" ] }, "default_prompt": { "type": [ "string", "null" ] } }, "required": [ "phone_number_id", "has_override", "auto_reply_enabled", "reply_delay_seconds", "default_prompt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:write" ], "x-required-scopes": [ "sms:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/phone-numbers/{id}/test-call": { "post": { "operationId": "v1_phone_numbers_id_test_call_post", "tags": [ "Phone Numbers", "Calls" ], "summary": "Place a spam-label test call", "description": "Calls a US or Canadian mobile phone from one specific owned number so the recipient can record the carrier label shown on screen. The number must be active and assigned to an AI agent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_number": { "type": "string", "pattern": "^\\+1\\d{10}$" }, "client_name": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "destination_number" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted for asynchronous processing", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "status": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" } }, "required": [ "call_id", "status", "from_number", "to_number" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:read", "calls:write" ], "x-required-scopes": [ "phone_numbers:read", "calls:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/phone-numbers": { "get": { "operationId": "v1_phone_numbers_get", "tags": [ "Phone Numbers" ], "summary": "List owned phone numbers", "description": "Returns every Phone row owned by the caller's active organization.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "provider": { "type": "string" }, "is_active": { "type": "boolean" }, "iso_country": { "type": "string" }, "reputation_enrolled_at": { "type": [ "string", "null" ] }, "cnam_display_name": { "type": [ "string", "null" ] }, "cnam_status": { "type": "string" }, "agent_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "texting_enabled": { "type": "boolean" }, "texting_status": { "type": "string", "enum": [ "approved", "pending", "rejected", "not_registered" ] }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "name", "organization_id", "user_id", "provider", "is_active", "iso_country", "reputation_enrolled_at", "cnam_display_name", "cnam_status", "agent_id", "texting_enabled", "texting_status", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": [ "page_size" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:read" ], "x-required-scopes": [ "phone_numbers:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_phone_numbers_post", "tags": [ "Phone Numbers" ], "summary": "Purchase a new phone number", "description": "Initiates the durable provisioning workflow. Returns 202 with a workflow run id — poll `/v1/phone-numbers/{phone_record_id}` to see when the number goes active. The new number attaches to the caller's active organization.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string" }, "area_code": { "type": "string", "pattern": "^\\d{3}$" }, "name": { "type": "string", "maxLength": 120 } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted for asynchronous processing", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Location": { "description": "Canonical URL to poll for provisioning status.", "schema": { "type": "string", "format": "uri-reference" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_record_id": { "type": "number" }, "workflow_run_id": { "type": "string" }, "status_url": { "type": "string" } }, "required": [ "phone_record_id", "workflow_run_id", "status_url" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:write" ], "x-required-scopes": [ "phone_numbers:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/phone-numbers/search": { "get": { "operationId": "v1_phone_numbers_search_get", "tags": [ "Phone Numbers" ], "summary": "Search available phone numbers", "description": "Query carrier inventory for numbers matching the given filters. Returns up to 50 results per call.", "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "default": "US", "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "area_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{3}$" } }, { "name": "contains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "in_region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "number_type", "in": "query", "required": true, "schema": { "default": "local", "type": "string", "enum": [ "local", "tollFree", "mobile", "national" ] } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string" }, "locality": { "type": "string" }, "region": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } } }, "required": [ "phone_number", "locality", "region", "features" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": [ "page_size" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "phone_numbers:read" ], "x-required-scopes": [ "phone_numbers:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/room-token": { "post": { "operationId": "v1_room_token_post", "tags": [ "WebRTC" ], "summary": "Issue a room-join token for private browser calling", "description": "Issues a single-call token for browser calling where RevDesk places the call and your browser joins it. You provide a caller ID (from_number, which must be a number you own) and a destination (to_number); RevDesk dials the destination and returns a token your browser uses to join the live call and talk through the mic. Nothing about the underlying network is exposed to the browser. The connection runs entirely on RevDesk's own infrastructure. Pass the returned token and room_url to the RevDesk browser SDK (@revdesk/webrtc) to join.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } }, { "name": "X-Revdesk-Caller-IP", "in": "header", "required": false, "description": "Optional end-user IPv4 or IPv6 address reported by your server for the browser caller. Stored as client-reported diagnostics, separately from the API request IP; never used for authentication. Raw IPs expire after 30 days.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "to_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "ttl_seconds": { "type": "integer", "minimum": 30, "maximum": 600 }, "client_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "client_label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "from_number", "to_number" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "room_url": { "type": "string" }, "room_name": { "type": "string" }, "call_id": { "type": "string" }, "expires_in": { "type": "number" }, "from_number": { "type": "string" }, "to_number": { "type": "string" } }, "required": [ "token", "room_url", "room_name", "call_id", "expires_in", "from_number", "to_number" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:webrtc" ], "x-required-scopes": [ "voice:webrtc" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/sandbox": { "get": { "operationId": "v1_sandbox_get", "tags": [ "Sandbox" ], "summary": "Inspect the zero-auth synthetic sandbox", "security": [], "description": "Returns supported sample operations for a non-production environment. This endpoint never reads tenant data or performs external side effects.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string", "const": "sandbox" }, "production_data": { "type": "boolean", "const": false }, "authentication_required": { "type": "boolean", "const": false }, "operations": { "type": "array", "items": { "type": "string", "enum": [ "list_calls", "create_contact", "send_sms", "place_call" ] } } }, "required": [ "environment", "production_data", "authentication_required", "operations" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit": { "requestsPerMinute": 60 } }, "post": { "operationId": "v1_sandbox_post", "tags": [ "Sandbox" ], "summary": "Exercise a synthetic RevDesk operation", "security": [], "description": "Accepts a representative operation and returns deterministic sample output. Calls, messages, contacts, billing, and tenant records are never created or changed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "list_calls", "create_contact", "send_sms", "place_call" ] }, "input": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "operation", "input" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string", "const": "sandbox" }, "production_data": { "type": "boolean", "const": false }, "performed": { "type": "boolean", "const": false }, "operation": { "type": "string", "enum": [ "list_calls", "create_contact", "send_sms", "place_call" ] }, "synthetic_result": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "environment", "production_data", "performed", "operation", "synthetic_result" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit": { "requestsPerMinute": 60 } } }, "/v1/optimize/conversions": { "get": { "operationId": "v1_optimize_conversions_get", "tags": [ "Optimize" ], "summary": "List conversions for a website test", "description": "Returns the conversions recorded for a test, newest first: those the tag observed on the page and those sent to POST /v1/optimize/conversions.", "parameters": [ { "name": "test_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "test_id": { "type": [ "string", "null" ] }, "variant_id": { "type": [ "string", "null" ] }, "visitor_id": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } }, "required": [ "id", "test_id", "variant_id", "visitor_id", "value", "currency", "occurred_at", "url", "source" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:read" ], "x-required-scopes": [ "optimize:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_optimize_conversions_post", "tags": [ "Optimize" ], "summary": "Record a conversion", "description": "Records a conversion for a test from your own systems (a closed order, a booked appointment, a signed contract) so the results reflect outcomes the tag cannot see. Send the tag's `visitor_id` so the conversion is credited to the arm that visitor saw; a conversion with neither `variant_id` nor a known `visitor_id` is stored but cannot count toward an arm. Repeat sends with the same `metadata.order_id` are ignored.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "test_id": { "type": "string", "minLength": 1 }, "variant_id": { "type": "string", "minLength": 1 }, "visitor_id": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "occurred_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "test_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recorded": { "type": "boolean" }, "test_id": { "type": "string" }, "variant_id": { "type": [ "string", "null" ] } }, "required": [ "recorded", "test_id", "variant_id" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:write" ], "x-required-scopes": [ "optimize:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/optimize/properties": { "get": { "operationId": "v1_optimize_properties_get", "tags": [ "Optimize" ], "summary": "List site properties", "description": "Returns the websites registered to the workspace with their public tag key and whether the tag has been seen on the site. A workspace has one website today.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "public_key": { "type": "string" }, "verified_at": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" } }, "required": [ "id", "domain", "public_key", "verified_at", "enabled" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "total_results": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:read" ], "x-required-scopes": [ "optimize:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/optimize/snippet": { "get": { "operationId": "v1_optimize_snippet_get", "tags": [ "Optimize" ], "summary": "Get the site tag", "description": "Returns the script tag for the workspace's website. Install it in the head of every page; the property is verified the first time the tag loads from the registered domain.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "property_id": { "type": "string" }, "public_key": { "type": "string" }, "script_tag": { "type": "string" } }, "required": [ "property_id", "public_key", "script_tag" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:read" ], "x-required-scopes": [ "optimize:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/optimize/tests/{id}/results": { "get": { "operationId": "v1_optimize_tests_id_results_get", "tags": [ "Optimize" ], "summary": "Get website test results", "description": "Per-variant impressions, conversions, lift, significance, and conversion value, with the current decision and a daily series. Results are recomputed when the stored rollup is more than five minutes old.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 7, "maximum": 90 } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "test": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hypothesis": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "shipped", "archived" ] }, "kind": { "type": "string", "enum": [ "variation", "split_url" ] }, "page_url": { "type": "string" }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "goal": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "form_submit", "tel_click", "cta_click", "url_visit", "selector_click" ] }, "selector": { "type": [ "string", "null" ] }, "url_pattern": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "selector", "url_pattern" ], "additionalProperties": false }, { "type": "null" } ] }, "traffic_split": { "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "weight": { "type": "number" }, "ops": { "maxItems": 40, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setText" }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setAttribute" }, "name": { "type": "string", "pattern": "^(?!on)(?!src$)(?!srcdoc$)(?!style$)(?!href$)[a-z][a-z0-9-]*$" }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "selector", "op", "name", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "addClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "removeClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setStyle" }, "styles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "selector", "op", "styles" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "hide" } }, "required": [ "selector", "op" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "replaceHref" }, "value": { "type": "string", "maxLength": 2000, "pattern": "^(https?:\\/\\/|tel:|mailto:|sms:|\\/(?!\\/)|#|\\?)" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false } ] } }, "redirect_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_control", "weight", "ops", "redirect_url" ], "additionalProperties": false } }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "winner_variant_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hypothesis", "status", "kind", "page_url", "url_match_type", "goal", "traffic_split", "variants", "started_at", "completed_at", "shipped_at", "winner_variant_id", "created_at" ], "additionalProperties": false }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "impressions": { "type": "number" }, "conversions": { "type": "number" }, "conversion_rate": { "type": [ "number", "null" ] }, "lift": { "type": [ "number", "null" ] }, "p_value": { "type": [ "number", "null" ] }, "probability_to_beat_control": { "type": [ "number", "null" ] }, "revenue_cents": { "type": "number" } }, "required": [ "id", "name", "is_control", "impressions", "conversions", "conversion_rate", "lift", "p_value", "probability_to_beat_control", "revenue_cents" ], "additionalProperties": false } }, "decision": { "type": "object", "properties": { "winner_variant_id": { "type": [ "string", "null" ] }, "reason": { "type": "string", "enum": [ "winner", "collecting", "no_difference", "inconclusive" ] } }, "required": [ "winner_variant_id", "reason" ], "additionalProperties": false }, "computed_at": { "type": "string" }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "variant_id": { "type": "string" }, "impressions": { "type": "number" }, "conversions": { "type": "number" } }, "required": [ "day", "variant_id", "impressions", "conversions" ], "additionalProperties": false } } }, "required": [ "test", "variants", "decision", "computed_at", "daily" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:read" ], "x-required-scopes": [ "optimize:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/optimize/tests/{id}": { "get": { "operationId": "v1_optimize_tests_id_get", "tags": [ "Optimize" ], "summary": "Get a website test", "description": "Returns a single website test with its goal and variants.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hypothesis": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "shipped", "archived" ] }, "kind": { "type": "string", "enum": [ "variation", "split_url" ] }, "page_url": { "type": "string" }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "goal": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "form_submit", "tel_click", "cta_click", "url_visit", "selector_click" ] }, "selector": { "type": [ "string", "null" ] }, "url_pattern": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "selector", "url_pattern" ], "additionalProperties": false }, { "type": "null" } ] }, "traffic_split": { "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "weight": { "type": "number" }, "ops": { "maxItems": 40, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setText" }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setAttribute" }, "name": { "type": "string", "pattern": "^(?!on)(?!src$)(?!srcdoc$)(?!style$)(?!href$)[a-z][a-z0-9-]*$" }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "selector", "op", "name", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "addClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "removeClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setStyle" }, "styles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "selector", "op", "styles" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "hide" } }, "required": [ "selector", "op" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "replaceHref" }, "value": { "type": "string", "maxLength": 2000, "pattern": "^(https?:\\/\\/|tel:|mailto:|sms:|\\/(?!\\/)|#|\\?)" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false } ] } }, "redirect_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_control", "weight", "ops", "redirect_url" ], "additionalProperties": false } }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "winner_variant_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hypothesis", "status", "kind", "page_url", "url_match_type", "goal", "traffic_split", "variants", "started_at", "completed_at", "shipped_at", "winner_variant_id", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:read" ], "x-required-scopes": [ "optimize:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_optimize_tests_id_patch", "tags": [ "Optimize" ], "summary": "Update a website test", "description": "Changes a test's name, hypothesis, page, or traffic split, and starts or pauses it through `status`. Fields left out are unchanged. Shipped and archived tests cannot be edited.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "hypothesis": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "page_url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "traffic_split": { "type": "number", "minimum": 0.05, "maximum": 1 }, "status": { "type": "string", "enum": [ "active", "paused" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hypothesis": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "shipped", "archived" ] }, "kind": { "type": "string", "enum": [ "variation", "split_url" ] }, "page_url": { "type": "string" }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "goal": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "form_submit", "tel_click", "cta_click", "url_visit", "selector_click" ] }, "selector": { "type": [ "string", "null" ] }, "url_pattern": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "selector", "url_pattern" ], "additionalProperties": false }, { "type": "null" } ] }, "traffic_split": { "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "weight": { "type": "number" }, "ops": { "maxItems": 40, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setText" }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setAttribute" }, "name": { "type": "string", "pattern": "^(?!on)(?!src$)(?!srcdoc$)(?!style$)(?!href$)[a-z][a-z0-9-]*$" }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "selector", "op", "name", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "addClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "removeClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setStyle" }, "styles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "selector", "op", "styles" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "hide" } }, "required": [ "selector", "op" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "replaceHref" }, "value": { "type": "string", "maxLength": 2000, "pattern": "^(https?:\\/\\/|tel:|mailto:|sms:|\\/(?!\\/)|#|\\?)" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false } ] } }, "redirect_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_control", "weight", "ops", "redirect_url" ], "additionalProperties": false } }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "winner_variant_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hypothesis", "status", "kind", "page_url", "url_match_type", "goal", "traffic_split", "variants", "started_at", "completed_at", "shipped_at", "winner_variant_id", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:write" ], "x-required-scopes": [ "optimize:write" ], "x-rate-limit": { "requestsPerMinute": 600 } }, "delete": { "operationId": "v1_optimize_tests_id_delete", "tags": [ "Optimize" ], "summary": "Archive a website test", "description": "Archives a test. A running test stops serving its variants; results and shipped changes are kept. Tests are never hard deleted.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "archived": { "type": "boolean" } }, "required": [ "id", "archived" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:write" ], "x-required-scopes": [ "optimize:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/optimize/tests/{id}/ship": { "post": { "operationId": "v1_optimize_tests_id_ship_post", "tags": [ "Optimize" ], "summary": "Ship a website test", "description": "Makes a variant permanent for every visitor of the page and retires the test. Send `{}` to ship the recorded winner, or `variant_id` to choose. A running test is completed first.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hypothesis": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "shipped", "archived" ] }, "kind": { "type": "string", "enum": [ "variation", "split_url" ] }, "page_url": { "type": "string" }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "goal": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "form_submit", "tel_click", "cta_click", "url_visit", "selector_click" ] }, "selector": { "type": [ "string", "null" ] }, "url_pattern": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "selector", "url_pattern" ], "additionalProperties": false }, { "type": "null" } ] }, "traffic_split": { "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "weight": { "type": "number" }, "ops": { "maxItems": 40, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setText" }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setAttribute" }, "name": { "type": "string", "pattern": "^(?!on)(?!src$)(?!srcdoc$)(?!style$)(?!href$)[a-z][a-z0-9-]*$" }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "selector", "op", "name", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "addClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "removeClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setStyle" }, "styles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "selector", "op", "styles" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "hide" } }, "required": [ "selector", "op" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "replaceHref" }, "value": { "type": "string", "maxLength": 2000, "pattern": "^(https?:\\/\\/|tel:|mailto:|sms:|\\/(?!\\/)|#|\\?)" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false } ] } }, "redirect_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_control", "weight", "ops", "redirect_url" ], "additionalProperties": false } }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "winner_variant_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hypothesis", "status", "kind", "page_url", "url_match_type", "goal", "traffic_split", "variants", "started_at", "completed_at", "shipped_at", "winner_variant_id", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:write" ], "x-required-scopes": [ "optimize:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/optimize/tests": { "get": { "operationId": "v1_optimize_tests_get", "tags": [ "Optimize" ], "summary": "List website tests", "description": "Returns the workspace's website tests, newest first. Filter by `status` and page with `limit` and `offset`. `property_id` is optional while a workspace has one website.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "shipped", "archived" ] } }, { "name": "property_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hypothesis": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "shipped", "archived" ] }, "kind": { "type": "string", "enum": [ "variation", "split_url" ] }, "page_url": { "type": "string" }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "goal": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "form_submit", "tel_click", "cta_click", "url_visit", "selector_click" ] }, "selector": { "type": [ "string", "null" ] }, "url_pattern": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "selector", "url_pattern" ], "additionalProperties": false }, { "type": "null" } ] }, "traffic_split": { "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "weight": { "type": "number" }, "ops": { "maxItems": 40, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setText" }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setAttribute" }, "name": { "type": "string", "pattern": "^(?!on)(?!src$)(?!srcdoc$)(?!style$)(?!href$)[a-z][a-z0-9-]*$" }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "selector", "op", "name", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "addClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "removeClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setStyle" }, "styles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "selector", "op", "styles" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "hide" } }, "required": [ "selector", "op" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "replaceHref" }, "value": { "type": "string", "maxLength": 2000, "pattern": "^(https?:\\/\\/|tel:|mailto:|sms:|\\/(?!\\/)|#|\\?)" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false } ] } }, "redirect_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_control", "weight", "ops", "redirect_url" ], "additionalProperties": false } }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "winner_variant_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hypothesis", "status", "kind", "page_url", "url_match_type", "goal", "traffic_split", "variants", "started_at", "completed_at", "shipped_at", "winner_variant_id", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:read" ], "x-required-scopes": [ "optimize:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_optimize_tests_post", "tags": [ "Optimize" ], "summary": "Create a website test", "description": "Creates a test on one page with a control plus the variants you send. Each variant is a list of DOM operations (text, attributes, classes, inline style, hide, link targets) applied by the tag. Pass a `goal` to create one or `goal_id` to reuse one. With `start: true` the test begins immediately; otherwise it is saved as a draft.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "property_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "page_url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "goal": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "form_submit", "tel_click", "cta_click", "url_visit", "selector_click" ] }, "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "url_pattern": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "type" ], "additionalProperties": false }, "goal_id": { "type": "string", "minLength": 1 }, "hypothesis": { "type": "string", "maxLength": 400 }, "traffic_split": { "type": "number", "minimum": 0.05, "maximum": 1 }, "variants": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "hypothesis": { "type": "string", "maxLength": 400 }, "ops": { "maxItems": 40, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setText" }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setAttribute" }, "name": { "type": "string", "pattern": "^(?!on)(?!src$)(?!srcdoc$)(?!style$)(?!href$)[a-z][a-z0-9-]*$" }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "selector", "op", "name", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "addClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "removeClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setStyle" }, "styles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "selector", "op", "styles" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "hide" } }, "required": [ "selector", "op" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "replaceHref" }, "value": { "type": "string", "maxLength": 2000, "pattern": "^(https?:\\/\\/|tel:|mailto:|sms:|\\/(?!\\/)|#|\\?)" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false } ] } }, "weight": { "type": "number", "minimum": 0, "maximum": 10 } }, "required": [ "name", "ops" ], "additionalProperties": false } }, "start": { "type": "boolean" } }, "required": [ "name", "page_url", "variants" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hypothesis": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "running", "paused", "completed", "shipped", "archived" ] }, "kind": { "type": "string", "enum": [ "variation", "split_url" ] }, "page_url": { "type": "string" }, "url_match_type": { "type": "string", "enum": [ "exact", "prefix", "regex" ] }, "goal": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "form_submit", "tel_click", "cta_click", "url_visit", "selector_click" ] }, "selector": { "type": [ "string", "null" ] }, "url_pattern": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "selector", "url_pattern" ], "additionalProperties": false }, { "type": "null" } ] }, "traffic_split": { "type": "number" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_control": { "type": "boolean" }, "weight": { "type": "number" }, "ops": { "maxItems": 40, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setText" }, "value": { "type": "string", "maxLength": 5000 } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setAttribute" }, "name": { "type": "string", "pattern": "^(?!on)(?!src$)(?!srcdoc$)(?!style$)(?!href$)[a-z][a-z0-9-]*$" }, "value": { "type": "string", "maxLength": 2000 } }, "required": [ "selector", "op", "name", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "addClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "removeClass" }, "value": { "type": "string", "maxLength": 200, "pattern": "^[\\w-]+(\\s+[\\w-]+)*$" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "setStyle" }, "styles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "selector", "op", "styles" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "hide" } }, "required": [ "selector", "op" ], "additionalProperties": false }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 500 }, "nth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "op": { "type": "string", "const": "replaceHref" }, "value": { "type": "string", "maxLength": 2000, "pattern": "^(https?:\\/\\/|tel:|mailto:|sms:|\\/(?!\\/)|#|\\?)" } }, "required": [ "selector", "op", "value" ], "additionalProperties": false } ] } }, "redirect_url": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_control", "weight", "ops", "redirect_url" ], "additionalProperties": false } }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "winner_variant_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "hypothesis", "status", "kind", "page_url", "url_match_type", "goal", "traffic_split", "variants", "started_at", "completed_at", "shipped_at", "winner_variant_id", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "optimize:write" ], "x-required-scopes": [ "optimize:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/sms/config": { "get": { "operationId": "v1_sms_config_get", "tags": [ "SMS" ], "summary": "Get workspace SMS auto-reply settings", "description": "Returns the workspace-wide SMS auto-reply configuration. `auto_reply_enabled: false` is one-way SMS — inbound texts are still received, the AI just doesn't auto-respond. Per-number overrides are managed on /v1/phone-numbers/{id}/sms-config.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "auto_reply_enabled": { "type": "boolean" }, "reply_delay_seconds": { "type": "number" }, "default_prompt": { "type": [ "string", "null" ] } }, "required": [ "auto_reply_enabled", "reply_delay_seconds", "default_prompt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:read" ], "x-required-scopes": [ "sms:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_sms_config_patch", "tags": [ "SMS" ], "summary": "Update workspace SMS auto-reply settings", "description": "Updates the workspace-wide SMS auto-reply configuration. Set `auto_reply_enabled: false` for one-way SMS (the AI stops auto-responding to inbound texts).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_reply_enabled": { "type": "boolean" }, "reply_delay_seconds": { "type": "integer", "minimum": 0, "maximum": 300 }, "default_prompt": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "auto_reply_enabled": { "type": "boolean" }, "reply_delay_seconds": { "type": "number" }, "default_prompt": { "type": [ "string", "null" ] } }, "required": [ "auto_reply_enabled", "reply_delay_seconds", "default_prompt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:write" ], "x-required-scopes": [ "sms:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/sms/send": { "post": { "operationId": "v1_sms_send_post", "tags": [ "SMS" ], "summary": "Send an SMS message", "description": "Sends an outbound SMS from the specified phone number. The 'from' number must be an active phone number owned by the authenticated organization.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "to", "from", "message" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message_id": { "type": "string" }, "to": { "type": "string" }, "from": { "type": "string" }, "status": { "type": "string" } }, "required": [ "message_id", "to", "from", "status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sms:write" ], "x-required-scopes": [ "sms:write" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/sub-entities/{id}": { "get": { "operationId": "v1_sub_entities_id_get", "tags": [ "Sub-entities" ], "summary": "Retrieve a sub-entity", "description": "Retrieve one child organization that the authenticated umbrella organization can administer, including its HIPAA posture and current member and phone-number counts.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sub_entities:read" ], "x-required-scopes": [ "sub_entities:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_sub_entities_id_patch", "tags": [ "Sub-entities" ], "summary": "Update a sub-entity", "description": "Rename or flip the `hipaa_enabled` flag. Changing `hipaa_enabled` requires the `compliance:write` scope IN ADDITION to `sub_entities:write`. HIPAA is fail-closed and non-downgradeable: `hipaa_enabled=false` is REJECTED while the umbrella organization is HIPAA-enabled. Enabling HIPAA defaults the sub-entity's call-recording retention to 30 days (adjustable per number afterward).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "hipaa_enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sub_entities:write" ], "x-required-scopes": [ "sub_entities:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/sub-entities": { "get": { "operationId": "v1_sub_entities_get", "tags": [ "Sub-entities" ], "summary": "List sub-entities under the caller's umbrella organization", "description": "Every managed child organization (sub-entity) of the authenticated org. Each entry includes member + phone-number counts so the caller can tell which sub-entities are live.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": [ "page_size" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sub_entities:read" ], "x-required-scopes": [ "sub_entities:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_sub_entities_post", "tags": [ "Sub-entities" ], "summary": "Create a sub-entity under the caller's umbrella organization", "description": "Creates a new managed child organization. When the key carries a user, that user becomes the owner. HIPAA posture is INHERITED from the umbrella (fail-closed): if the umbrella is HIPAA-enabled the new sub-entity starts HIPAA-enabled.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "slug": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "sub_entities:write" ], "x-required-scopes": [ "sub_entities:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/tasks/{taskId}": { "get": { "operationId": "v1_tasks_taskId_get", "tags": [ "Tasks" ], "summary": "Retrieve a task", "description": "The task, every band of its provenance timeline in order, and each recorded outcome with the interactions that produced it.", "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "objective": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "number" }, "occurred_at": { "type": "string" }, "row_type": { "type": "string" }, "actor": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "system": { "type": [ "string", "null" ] }, "body": { "type": "string" } }, "required": [ "seq", "occurred_at", "row_type", "actor", "channel", "system", "body" ], "additionalProperties": false } }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "occurred_at": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "billable": { "type": "boolean" }, "billed_at": { "type": [ "string", "null" ] }, "billed_amount": { "type": [ "number", "null" ] }, "attribution_mode": { "type": "string" }, "disputed_at": { "type": [ "string", "null" ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "interaction_type": { "type": "string" }, "interaction_id": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "interaction_type", "interaction_id", "note" ], "additionalProperties": false } } }, "required": [ "id", "kind", "occurred_at", "value", "billable", "billed_at", "billed_amount", "attribution_mode", "disputed_at", "evidence" ], "additionalProperties": false } } }, "required": [ "id", "type", "status", "objective", "contact_id", "deadline", "created_at", "closed_at", "events", "outcomes" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "jobs:read" ], "x-required-scopes": [ "jobs:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/tasks": { "get": { "operationId": "v1_tasks_get", "tags": [ "Tasks" ], "summary": "List tasks", "description": "Tasks the organization has open or has completed, newest first. Filter with `status` (OPEN, PAUSED, ACHIEVED, ABANDONED, EXPIRED).", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "objective": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "opportunity_id": { "type": [ "string", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "status", "objective", "contact_id", "opportunity_id", "deadline", "created_at", "closed_at" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "jobs:read" ], "x-required-scopes": [ "jobs:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_tasks_post", "tags": [ "Tasks" ], "summary": "Create a task", "description": "Hand RevDesk an outcome to pursue. The agent plans and executes across channels until the success criteria are met, the deadline passes, or the guardrails stop it.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "objective": { "type": "string", "minLength": 1 }, "contact_id": { "type": "string" }, "opportunity_id": { "type": "string" }, "deadline": {}, "success_criteria": { "type": "object", "properties": { "outcome_kinds": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "guardrails": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "string" } }, "quiet_hours": { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "time_zone": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false }, "max_touches": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "max_touches_since_reply": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "min_hours_between_touches": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "type", "objective" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "objective": { "type": "string" }, "contact_id": { "type": [ "string", "null" ] }, "opportunity_id": { "type": [ "string", "null" ] }, "deadline": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "status", "objective", "contact_id", "opportunity_id", "deadline", "created_at", "closed_at" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "jobs:write" ], "x-required-scopes": [ "jobs:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/usage/{phoneId}": { "get": { "operationId": "v1_usage_phoneId_get", "tags": [ "Usage" ], "summary": "Per-phone usage", "description": "Returns voice usage for a specific phone number in the current calendar month. The phone must belong to the authenticated user or team.", "parameters": [ { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_id": { "type": "number" }, "phone_number": { "type": "string" }, "period_start": { "type": "string" }, "period_end": { "type": "string" }, "calls_placed": { "type": "number" }, "minutes_used": { "type": "number" }, "duration_seconds": { "type": "number" }, "calls_by_status": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": [ "phone_id", "phone_number", "period_start", "period_end", "calls_placed", "minutes_used", "duration_seconds", "calls_by_status" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:read" ], "x-required-scopes": [ "voice:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/usage": { "get": { "operationId": "v1_usage_get", "tags": [ "Usage" ], "summary": "Current-month usage rollup", "description": "Aggregated counts across all numbers the key can see: outbound calls, minutes used, and spam-risk distribution across enrolled numbers.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "period_start": { "type": "string" }, "period_end": { "type": "string" }, "calls_placed": { "type": "number" }, "minutes_used": { "type": "number" }, "phone_numbers_active": { "type": "number" }, "spam_risk_distribution": { "type": "object", "properties": { "low": { "type": "number" }, "medium": { "type": "number" }, "high": { "type": "number" }, "unknown": { "type": "number" } }, "required": [ "low", "medium", "high", "unknown" ], "additionalProperties": false } }, "required": [ "period_start", "period_end", "calls_placed", "minutes_used", "phone_numbers_active", "spam_risk_distribution" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "usage:read" ], "x-required-scopes": [ "usage:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/webhook_subscriptions/{id}": { "delete": { "operationId": "v1_webhook_subscriptions_id_delete", "tags": [ "Webhooks" ], "summary": "Delete a webhook subscription", "description": "Deletes a webhook subscription. Pending deliveries for it are cancelled.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "id", "deleted" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "webhooks:write" ], "x-required-scopes": [ "webhooks:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/webhook_subscriptions": { "get": { "operationId": "v1_webhook_subscriptions_get", "tags": [ "Webhooks" ], "summary": "List webhook subscriptions", "description": "Returns the webhook subscriptions created through this API for the authenticated organization. Signing secrets are shown once at creation and are never returned here.", "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "webhook_url": { "type": "string" }, "event_type": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "webhook_url", "event_type", "active", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "webhooks:read" ], "x-required-scopes": [ "webhooks:read" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_webhook_subscriptions_post", "tags": [ "Webhooks" ], "summary": "Create a webhook subscription", "description": "Subscribes an https URL to an event type (one of: new_call, call_completed, contact_replied, contact_created, new_appointment, number_purchased, number_released, number_updated, call_no_answer, call_voicemail, call_busy, call_failed, sms_sent, sms_delivered, sms_failed, texting_registration_status_changed, registration_submitted, registration_confirmed, registration_failed, job_started, job_progressed, job_outcome_recorded, job_completed, optimize.test.created, optimize.test.started, optimize.test.completed, optimize.test.winner, optimize.test.shipped, optimize.conversion.created). The response includes the HMAC signing secret used for X-RevDesk-Signature — it is shown once, here, and is not retrievable afterwards.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "minLength": 1 }, "event_type": { "type": "string", "minLength": 1 } }, "required": [ "webhook_url", "event_type" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "secret" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "webhooks:write" ], "x-required-scopes": [ "webhooks:write" ], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/webrtc-token": { "post": { "operationId": "v1_webrtc_token_post", "tags": [ "WebRTC" ], "summary": "Issue a scoped WebRTC calling token", "description": "Issues a single-use WebRTC token for the RevDesk WebRTC SDK, pinned to one caller ID (from_number, which must be a number you own) and one destination (to_number). The token is an opaque RevDesk token — pass it to the @revdesk/webrtc SDK to place exactly that one call. It is valid only for that single call and is invalidated when the call ends; it cannot be reused. (Token lifetime covers the platform max call duration so it never cuts an active call.)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID — when present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } }, { "name": "X-Revdesk-Caller-IP", "in": "header", "required": false, "description": "Optional end-user IPv4 or IPv6 address reported by your server for the browser caller. Stored as client-reported diagnostics, separately from the API request IP; never used for authentication. Raw IPs expire after 30 days.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "to_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "client_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "client_label": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "from_number", "to_number" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "string" }, "expires_in": { "type": "number" }, "call_id": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" } }, "required": [ "token", "expires_in", "call_id", "from_number", "to_number" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": [ "voice:webrtc" ], "x-required-scopes": [ "voice:webrtc" ], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } } } }