{ "components": { "securitySchemes": { "ApiKeyAuth": { "description": "API key (sk_phones_* prefix) for programmatic access", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "description": "Approved customer operations authenticated with an X-API-Key header.", "title": "Steer Phones Customer API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/customer/phone-systems": { "get": { "description": "Returns every phone system the API key currently covers, resolved live from the key's grant: a single-system key lists its one system, a group key lists the group's current members, and an organization key lists the organization's directly-attached systems. Membership changes apply to existing keys without reissue, so call this operation to discover the `{phoneSystemId}` values usable in resource paths. Requires only a valid tenant API key — no resource scope.", "operationId": "listAccessiblePhoneSystems", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "Every phone system the API key currently covers, ordered by name.", "items": { "additionalProperties": false, "properties": { "id": { "description": "Phone system identifier — use it as the {phoneSystemId} path segment.", "format": "uuid", "type": "string" }, "name": { "description": "Display name of the phone system.", "type": "string" } }, "required": ["id", "name"], "type": "object" }, "type": "array" } }, "required": ["data"], "type": "object" } } }, "description": "Phone systems covered by the key, ordered by name." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The credential is not a tenant API key: an interactive session token or a platform API key was presented." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List accessible phone systems", "tags": ["Phone Systems"] } }, "/customer/phone-systems/{phoneSystemId}/agent-configs": { "get": { "description": "Returns a deterministic page of Call Assistant routing identities, with exact status and agent-number filters.", "operationId": "listAgentConfigs", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exact lifecycle status.", "in": "query", "name": "status", "schema": { "enum": ["active", "inactive", "paused", "archived", "testing"], "type": "string" } }, { "description": "Exact agent routing number from 1 through 9.", "in": "query", "name": "agentNumber", "schema": { "maximum": 9, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "agentNumber": { "anyOf": [ { "maximum": 9, "minimum": 1, "type": "integer" }, { "type": "null" } ] }, "createdAt": { "description": "When the agent configuration was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive", "paused", "archived", "testing"], "type": "string" }, "updatedAt": { "description": "When the agent configuration record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "agentNumber", "status", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "A deterministic page of AI-agent routing identities." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The query or phone-system identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the agent-configs:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is outside the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List agent configs", "tags": ["Agent Configs"] } }, "/customer/phone-systems/{phoneSystemId}/agent-configs/{agentConfigId}": { "get": { "description": "Returns one Call Assistant routing identity without prompt, model, or credential configuration.", "operationId": "getAgentConfig", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Agent-config identifier from a list response or typed reference.", "in": "path", "name": "agentConfigId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "agentNumber": { "anyOf": [ { "maximum": 9, "minimum": 1, "type": "integer" }, { "type": "null" } ] }, "createdAt": { "description": "When the agent configuration was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive", "paused", "archived", "testing"], "type": "string" }, "updatedAt": { "description": "When the agent configuration record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "agentNumber", "status", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "AI-agent routing identity without prompt or model configuration." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "A path identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the agent-configs:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The agent config or phone system does not exist within the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get an agent config", "tags": ["Agent Configs"] } }, "/customer/phone-systems/{phoneSystemId}/call-analyses": { "get": { "description": "Returns the phone system’s call analyses, newest first (ordered by createdAt descending with id as the tiebreak, so paging is deterministic). A call.analysis.completed webhook carries both callSid and callLogId — filter by either identifier to fetch that call’s analysis, or bound the list with an inclusive createdAt window (dateFrom/dateTo). Requires the calls:read scope.", "operationId": "listCallAnalyses", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Inclusive lower bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateFrom", "schema": { "format": "date-time", "type": "string" } }, { "description": "Inclusive upper bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateTo", "schema": { "format": "date-time", "type": "string" } }, { "description": "Exact-match filter on the call identifier from a webhook payload.", "in": "query", "name": "callSid", "schema": { "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Filter on the call log identifier from a webhook payload.", "in": "query", "name": "callLogId", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "analyzedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the analysis completed." }, "callLogId": { "description": "Analyzed call log — the callLogId carried by webhook payloads.", "format": "uuid", "type": "string" }, "callSid": { "description": "Call identifier of the analyzed call, as delivered in webhook payloads.", "type": "string" }, "coachingTips": { "description": "Actionable coaching suggestions from the analysis.", "items": { "type": "string" }, "type": "array" }, "createdAt": { "description": "When the row was created; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "id": { "description": "Call analysis identifier.", "format": "uuid", "type": "string" }, "overallScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Overall score (0-100); null until the analysis completes." }, "phoneSystemId": { "description": "Phone system the analyzed call belongs to.", "format": "uuid", "type": "string" }, "status": { "description": "Analysis lifecycle status.", "enum": ["pending", "processing", "completed", "failed"], "type": "string" } }, "required": [ "id", "phoneSystemId", "callLogId", "callSid", "status", "overallScore", "coachingTips", "analyzedAt", "createdAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "One page of call analyses with the total row count for the filter." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: an unknown query parameter, a malformed date or UUID, or a pageSize above 100. Field problems are itemized in errors[]." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the calls:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List call analyses", "tags": ["Call Logs"] } }, "/customer/phone-systems/{phoneSystemId}/call-analyses/{id}": { "get": { "description": "Returns one call analysis by its id from a list response. status tracks the analysis lifecycle; overallScore and analyzedAt stay null until it completes. Requires the calls:read scope.", "operationId": "getCallAnalysis", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Call analysis identifier from a list response.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "analyzedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the analysis completed." }, "callLogId": { "description": "Analyzed call log — the callLogId carried by webhook payloads.", "format": "uuid", "type": "string" }, "callSid": { "description": "Call identifier of the analyzed call, as delivered in webhook payloads.", "type": "string" }, "coachingTips": { "description": "Actionable coaching suggestions from the analysis.", "items": { "type": "string" }, "type": "array" }, "createdAt": { "description": "When the row was created; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "id": { "description": "Call analysis identifier.", "format": "uuid", "type": "string" }, "overallScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Overall score (0-100); null until the analysis completes." }, "phoneSystemId": { "description": "Phone system the analyzed call belongs to.", "format": "uuid", "type": "string" }, "status": { "description": "Analysis lifecycle status.", "enum": ["pending", "processing", "completed", "failed"], "type": "string" } }, "required": [ "id", "phoneSystemId", "callLogId", "callSid", "status", "overallScore", "coachingTips", "analyzedAt", "createdAt" ], "type": "object" } } }, "description": "The call analysis." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: id is not a UUID." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the calls:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "No such call analysis in this phone system — a nonexistent id and an id belonging to another phone system are indistinguishable — or the phone system itself is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a call analysis", "tags": ["Call Logs"] } }, "/customer/phone-systems/{phoneSystemId}/call-groups": { "get": { "description": "Returns a deterministic page of call groups, with exact status and group-number filters.", "operationId": "listCallGroups", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exact lifecycle status.", "in": "query", "name": "status", "schema": { "enum": ["active", "inactive"], "type": "string" } }, { "description": "Exact call-group number.", "in": "query", "name": "number", "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the call group was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive"], "type": "string" }, "updatedAt": { "description": "When the call group record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "number", "status", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "A deterministic page of call-group routing identities." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The query or phone-system identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the call-groups:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is outside the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List call groups", "tags": ["Call Groups"] } }, "/customer/phone-systems/{phoneSystemId}/call-groups/{callGroupId}": { "get": { "description": "Returns ordered membership and directly configured unanswered routing for one call group.", "operationId": "getCallGroup", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Call-group identifier from a list response or typed reference.", "in": "path", "name": "callGroupId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the call group was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "members": { "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "const": "extension", "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, "type": "array" }, "name": { "type": "string" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phoneSystemId": { "format": "uuid", "type": "string" }, "ringPattern": { "enum": ["simultaneous", "ring_around"], "type": "string" }, "status": { "enum": ["active", "inactive"], "type": "string" }, "unansweredCallBehavior": { "additionalProperties": false, "properties": { "businessHours": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": [ "extension", "agent-config", "call-group", "call-menu" ], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": ["extension-voicemail", "call-group-voicemail"], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "anyOf": [ { "additionalProperties": false, "properties": { "playbackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "type": { "const": "play-audio", "type": "string" } }, "required": ["type", "playbackUrl"], "type": "object" }, { "additionalProperties": false, "properties": { "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "type": { "const": "forward", "type": "string" } }, "required": ["type", "phoneNumber"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "company-voicemail", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "voicemail-management", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "directory", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "initial-call-menu", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "send-sms", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "hangup", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "dynamic-routing", "type": "string" } }, "required": ["type"], "type": "object" } ] } ] }, { "type": "null" } ] }, "offHours": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": [ "extension", "agent-config", "call-group", "call-menu" ], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": ["extension-voicemail", "call-group-voicemail"], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "anyOf": [ { "additionalProperties": false, "properties": { "playbackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "type": { "const": "play-audio", "type": "string" } }, "required": ["type", "playbackUrl"], "type": "object" }, { "additionalProperties": false, "properties": { "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "type": { "const": "forward", "type": "string" } }, "required": ["type", "phoneNumber"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "company-voicemail", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "voicemail-management", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "directory", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "initial-call-menu", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "send-sms", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "hangup", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "dynamic-routing", "type": "string" } }, "required": ["type"], "type": "object" } ] } ] }, { "type": "null" } ] }, "timeoutSeconds": { "minimum": 0, "type": "integer" } }, "required": ["timeoutSeconds", "businessHours", "offHours"], "type": "object" }, "updatedAt": { "description": "When the call group record was last updated.", "format": "date-time", "type": "string" }, "voicemailGreetingPlaybackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "phoneSystemId", "name", "number", "status", "createdAt", "updatedAt", "members", "ringPattern", "unansweredCallBehavior", "voicemailGreetingPlaybackUrl" ], "type": "object" } } }, "description": "Call-group membership and directly configured unanswered routing." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "A path identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the call-groups:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The call group or phone system does not exist within the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a call group", "tags": ["Call Groups"] } }, "/customer/phone-systems/{phoneSystemId}/call-log-reports": { "get": { "description": "Returns the enriched reporting representation of the phone system’s calls across one bounded time window — the values a recurring export needs, without a detail request per call. Select the window with timeField (createdAt for historical extraction, updatedAt to pick up changed rows) plus the required half-open [dateFrom, dateTo) bounds. Rows are ordered ascending by the selected timestamp then by id; traverse by sending nextCursor back unchanged until hasMore is false. The cursor is opaque, is valid only for the same phone system, time field, and window, and carries no authorization — every page is reauthorized. limit and includeTranscripts are per-request delivery controls and may change on a continuation. Rows carry stable IDs and codes alongside the display values they currently resolve to; refresh renamed values through the dimensions operation. Recording audio and signed media URLs are not included — they remain governed by recordings:read. Requires a tenant-wide calls:read grant.", "operationId": "listCallLogReports", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Which timestamp the window filters and orders by: createdAt for historical extraction, updatedAt to pick up changed rows.", "in": "query", "name": "timeField", "schema": { "default": "createdAt", "enum": ["createdAt", "updatedAt"], "type": "string" } }, { "description": "Inclusive lower bound of the window (ISO 8601 UTC). Required.", "in": "query", "name": "dateFrom", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Exclusive upper bound of the window (ISO 8601 UTC). Required.", "in": "query", "name": "dateTo", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "Rows to return: at most 100, or 25 when transcripts are included.", "in": "query", "name": "limit", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Include transcript text and turns. Omitted entirely when false, so a metadata page never reads a transcript body.", "in": "query", "name": "includeTranscripts", "schema": { "default": "false", "enum": ["true", "false"], "type": "string" } }, { "description": "Continuation token from a previous response’s nextCursor.", "in": "query", "name": "cursor", "schema": { "maxLength": 512, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "description": "One page of report rows.", "items": { "additionalProperties": false, "properties": { "answeredByExtension": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "description": "Stable identifier; join report rows on this, not on the name.", "format": "uuid", "type": "string" }, "name": { "description": "Current display name, as of this response.", "type": "string" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dialable number, when the resource has one." } }, "required": ["id", "name", "number"], "type": "object" }, { "type": "null" } ], "description": "Extension that answered the call." }, "callGroup": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "description": "Stable identifier; join report rows on this, not on the name.", "format": "uuid", "type": "string" }, "name": { "description": "Current display name, as of this response.", "type": "string" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dialable number, when the resource has one." } }, "required": ["id", "name", "number"], "type": "object" }, { "type": "null" } ], "description": "Call group the call was routed through." }, "callOutcomeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable business outcome code, when recorded." }, "callSid": { "description": "Call identifier, as delivered in webhook payloads.", "type": "string" }, "category": { "additionalProperties": false, "description": "Call category code and its current label.", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable category code; null when the call was not analyzed." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current display label for the code, resolved for this phone system." } }, "required": ["code", "label"], "type": "object" }, "conversionValue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conversion amount as an exact decimal string, so no precision is lost in JSON." }, "createdAt": { "description": "When the call log row was created.", "format": "date-time", "type": "string" }, "customerSentiment": { "additionalProperties": false, "description": "Customer sentiment code, label, and score.", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable sentiment code; null when the call was not analyzed." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current display label for the code, resolved for this phone system." }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Score recorded when the call was analyzed." } }, "required": ["code", "label", "score"], "type": "object" }, "direction": { "description": "Call direction.", "enum": ["inbound", "outbound", "internal"], "type": "string" }, "durationSeconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Call duration in seconds." }, "employeeSentiment": { "additionalProperties": false, "description": "Employee sentiment code, label, and score.", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable sentiment code; null when the call was not analyzed." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current display label for the code, resolved for this phone system." }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Score recorded when the call was analyzed." } }, "required": ["code", "label", "score"], "type": "object" }, "endTime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the call ended." }, "forwardedFrom": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Number the call was forwarded from, when known." }, "from": { "description": "Calling party.", "type": "string" }, "fromDisplay": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored display form of the calling party." }, "fromExtension": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "description": "Stable identifier; join report rows on this, not on the name.", "format": "uuid", "type": "string" }, "name": { "description": "Current display name, as of this response.", "type": "string" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dialable number, when the resource has one." } }, "required": ["id", "name", "number"], "type": "object" }, { "type": "null" } ], "description": "Extension the call originated from." }, "fromName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller name, when known." }, "fromNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored dialable form of the calling party." }, "hasRecording": { "description": "Whether a recording exists for this call.", "type": "boolean" }, "id": { "description": "Call log identifier — the callLogId carried by webhook payloads.", "format": "uuid", "type": "string" }, "isConverted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the call was marked converted." }, "isEdited": { "description": "Whether the call log has been edited.", "type": "boolean" }, "isEmergency": { "description": "Whether the call was an emergency call.", "type": "boolean" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Call outcome (answered, missed, abandoned, voicemail, transferred, …)." }, "outcomeSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What recorded the outcome." }, "overallSentiment": { "additionalProperties": false, "description": "Overall sentiment code, label, and score.", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable sentiment code; null when the call was not analyzed." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current display label for the code, resolved for this phone system." }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Score recorded when the call was analyzed." } }, "required": ["code", "label", "score"], "type": "object" }, "parentCallSid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent call identifier when this row is a transferred or forwarded leg." }, "phoneSystemId": { "description": "Phone system this call belongs to.", "format": "uuid", "type": "string" }, "recordingDurationSeconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Recording duration in seconds." }, "recordingSid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recording identifier — audio is fetched through the recordings operations." }, "representative": { "additionalProperties": false, "description": "Representative attribution for the call.", "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Attribution confidence, when attribution ran." }, "id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Attributed representative, when one was identified." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current display name of the attributed representative." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What produced the attribution." }, "state": { "description": "identified when a representative was attributed, unknown when attribution ran and matched no one, not_analyzed when attribution never ran.", "enum": ["identified", "unknown", "not_analyzed"], "type": "string" } }, "required": ["id", "name", "state", "confidence", "source"], "type": "object" }, "routeSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored summary of the path the call took." }, "scorecardScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Scorecard score, when the call was scored." }, "sentimentSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What produced the sentiment values." }, "startTime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the call started." }, "status": { "description": "Call status (completed, no-answer, busy, failed, canceled).", "type": "string" }, "tags": { "description": "Tags as they were applied to this call.", "items": { "additionalProperties": false, "properties": { "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tag color as it was when the tag was applied." }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Confidence, for an automatically applied tag." }, "group": { "description": "Tag group as it was when the tag was applied.", "type": "string" }, "id": { "description": "Stable tag identifier; join on this rather than on the name.", "format": "uuid", "type": "string" }, "name": { "description": "Tag name as it was when the tag was applied.", "type": "string" }, "source": { "description": "What applied the tag.", "type": "string" } }, "required": ["id", "name", "group", "color", "source", "confidence"], "type": "object" }, "type": "array" }, "to": { "description": "Called party.", "type": "string" }, "toDisplay": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored display form of the called party." }, "toNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stored dialable form of the called party." }, "transcript": { "anyOf": [ { "additionalProperties": false, "properties": { "text": { "description": "Canonical transcript text.", "type": "string" }, "turns": { "description": "Diarized turns. Empty when the call has canonical text but no usable structured detail.", "items": { "additionalProperties": false, "properties": { "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Recognition confidence, when the provider reported one." }, "endSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Offset from the start of the call, in seconds, when the provider reported one." }, "speaker": { "description": "Vendor-neutral speaker identity.", "oneOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "role", "type": "string" }, "role": { "description": "The party this speaker was resolved to.", "enum": ["agent", "customer"], "type": "string" } }, "required": ["kind", "role"], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "numbered", "type": "string" }, "ordinal": { "description": "1-based position in the transcript’s order of first appearance.", "minimum": 1, "type": "integer" } }, "required": ["kind", "ordinal"], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "unattributed", "type": "string" } }, "required": ["kind"], "type": "object" } ], "type": "object" }, "startSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Offset from the start of the call, in seconds, when the provider reported one." }, "text": { "description": "What was said in this turn.", "type": "string" } }, "required": [ "text", "speaker", "startSeconds", "endSeconds", "confidence" ], "type": "object" }, "type": "array" } }, "required": ["text", "turns"], "type": "object" }, { "type": "null" } ], "description": "Present only when includeTranscripts=true, and null there when no transcript text is currently stored." }, "transcriptionStatus": { "description": "Whether transcript text is retrievable right now: completed, processing (keep polling), failed, or unavailable.", "enum": ["completed", "processing", "failed", "unavailable"], "type": "string" }, "updatedAt": { "description": "When the call log row last changed; the watermark an update-time window selects on.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "callSid", "parentCallSid", "direction", "startTime", "endTime", "durationSeconds", "createdAt", "updatedAt", "from", "fromName", "fromDisplay", "fromNumber", "to", "toDisplay", "toNumber", "forwardedFrom", "status", "outcome", "callOutcomeCode", "isConverted", "conversionValue", "outcomeSource", "category", "overallSentiment", "employeeSentiment", "customerSentiment", "sentimentSource", "scorecardScore", "representative", "hasRecording", "recordingSid", "recordingDurationSeconds", "transcriptionStatus", "callGroup", "answeredByExtension", "fromExtension", "isEmergency", "isEdited", "tags", "routeSummary" ], "type": "object" }, "type": "array" }, "hasMore": { "description": "Whether more rows remain in the requested window.", "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque continuation token, or null at the end of the window. Send it back unchanged; its contents are not a supported contract and it is valid only for the same phone system, time field, and window." } }, "required": ["data", "nextCursor", "hasMore"], "type": "object" } } }, "description": "One page of report rows plus the continuation token for the rest of the window." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: a missing or malformed window bound, dateTo at or before dateFrom, a limit above the applicable ceiling, an unknown query parameter, or a cursor that does not continue this request. Field problems are itemized in errors[]." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the calls:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is not covered by the key." }, "413": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The page is too large to deliver. params carries the measured response size as actualBytes and maxBytes, or — when a transcript page was refused before its bodies were read — the stored measurement as guard, storedBytes, limitBytes, and rowCount. No rows are truncated in either case: retry with a smaller limit, or with includeTranscripts=false. A single transcript that overflows on its own cannot be delivered here, but retrying the same cursor without transcripts continues the traversal." }, "429": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The per-key reporting request budget for this operation is exhausted, or the limiter could not be consulted. Retry after the interval in retry_after." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List call log reports", "tags": ["Call Log Reports"] } }, "/customer/phone-systems/{phoneSystemId}/call-log-reports/dimensions": { "get": { "description": "Returns current display values for exactly the call groups, extensions, representatives, and category and sentiment definitions that retained report rows still reference. Report rows keep stable IDs and codes forever, so this is how a rename reaches a client without rewriting history. Membership is derived from retained calls, never from tenant configuration, so unused inventory is neither queried nor published, and nothing describing how the phone system is configured appears at all. Semantics are replace-all for that membership: an item missing from a later snapshot was deleted or is no longer referenced and should be dropped from your lookup, while a referenced but deactivated item stays and carries its status. This is a reporting projection, not the separately scoped Call Group or Extension resources. Requires a tenant-wide calls:read grant.", "operationId": "getCallLogReportDimensions", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "callGroups": { "description": "Call groups referenced by retained report rows, ordered by id.", "items": { "additionalProperties": false, "properties": { "id": { "description": "Stable identifier report rows reference.", "format": "uuid", "type": "string" }, "name": { "description": "Current display name.", "type": "string" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dialable number, when the resource has one." }, "status": { "description": "Lifecycle state (active, inactive).", "type": "string" }, "updatedAt": { "description": "When the underlying record last changed.", "format": "date-time", "type": "string" } }, "required": ["id", "name", "status", "updatedAt", "number"], "type": "object" }, "type": "array" }, "categories": { "description": "Call category definitions referenced by retained report rows, ordered by code.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Stable code report rows reference.", "type": "string" }, "label": { "description": "Current effective label for the code.", "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Aggregation score, for taxonomies that carry one; null otherwise." }, "source": { "description": "Which definition won: this phone system’s override, the global default, or the deterministic fallback derived from the code itself.", "enum": ["phone_system_override", "global_default", "fallback"], "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lifecycle state of the winning definition; null for a fallback, which owns no row." }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the winning definition last changed; null for a fallback." } }, "required": ["code", "label", "source", "status", "score", "updatedAt"], "type": "object" }, "type": "array" }, "customerSentiments": { "description": "Customer sentiment definitions referenced by retained report rows, ordered by code.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Stable code report rows reference.", "type": "string" }, "label": { "description": "Current effective label for the code.", "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Aggregation score, for taxonomies that carry one; null otherwise." }, "source": { "description": "Which definition won: this phone system’s override, the global default, or the deterministic fallback derived from the code itself.", "enum": ["phone_system_override", "global_default", "fallback"], "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lifecycle state of the winning definition; null for a fallback, which owns no row." }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the winning definition last changed; null for a fallback." } }, "required": ["code", "label", "source", "status", "score", "updatedAt"], "type": "object" }, "type": "array" }, "employeeSentiments": { "description": "Employee sentiment definitions referenced by retained report rows, ordered by code.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Stable code report rows reference.", "type": "string" }, "label": { "description": "Current effective label for the code.", "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Aggregation score, for taxonomies that carry one; null otherwise." }, "source": { "description": "Which definition won: this phone system’s override, the global default, or the deterministic fallback derived from the code itself.", "enum": ["phone_system_override", "global_default", "fallback"], "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lifecycle state of the winning definition; null for a fallback, which owns no row." }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the winning definition last changed; null for a fallback." } }, "required": ["code", "label", "source", "status", "score", "updatedAt"], "type": "object" }, "type": "array" }, "extensions": { "description": "Extensions referenced by retained report rows, ordered by id.", "items": { "additionalProperties": false, "properties": { "id": { "description": "Stable identifier report rows reference.", "format": "uuid", "type": "string" }, "name": { "description": "Current display name.", "type": "string" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Dialable number, when the resource has one." }, "status": { "description": "Lifecycle state (active, inactive).", "type": "string" }, "updatedAt": { "description": "When the underlying record last changed.", "format": "date-time", "type": "string" } }, "required": ["id", "name", "status", "updatedAt", "number"], "type": "object" }, "type": "array" }, "generatedAt": { "description": "When this snapshot was taken. Membership and display values are read in immediate succession rather than from one database instant, so a change landing mid-request may appear in the next refresh instead. Report rows carry each reference name inline, so a row always renders either way.", "format": "date-time", "type": "string" }, "handlerEntries": { "description": "Representatives referenced by retained report rows, ordered by id.", "items": { "additionalProperties": false, "properties": { "id": { "description": "Stable identifier report rows reference.", "format": "uuid", "type": "string" }, "name": { "description": "Current display name.", "type": "string" }, "status": { "description": "Lifecycle state (active, inactive).", "type": "string" }, "updatedAt": { "description": "When the underlying record last changed.", "format": "date-time", "type": "string" } }, "required": ["id", "name", "status", "updatedAt"], "type": "object" }, "type": "array" }, "overallSentiments": { "description": "Overall sentiment definitions referenced by retained report rows, ordered by code.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Stable code report rows reference.", "type": "string" }, "label": { "description": "Current effective label for the code.", "type": "string" }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Aggregation score, for taxonomies that carry one; null otherwise." }, "source": { "description": "Which definition won: this phone system’s override, the global default, or the deterministic fallback derived from the code itself.", "enum": ["phone_system_override", "global_default", "fallback"], "type": "string" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lifecycle state of the winning definition; null for a fallback, which owns no row." }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the winning definition last changed; null for a fallback." } }, "required": ["code", "label", "source", "status", "score", "updatedAt"], "type": "object" }, "type": "array" } }, "required": [ "generatedAt", "callGroups", "extensions", "handlerEntries", "categories", "overallSentiments", "employeeSentiments", "customerSentiments" ], "type": "object" } } }, "description": "The report-scoped dimensions snapshot taken at generatedAt." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: phoneSystemId is not a UUID." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the calls:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is not covered by the key." }, "413": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The snapshot exceeds the transport size limit. params carries actualBytes and maxBytes. This operation returns one complete replace-all snapshot and takes no limit, so the request cannot be narrowed; report rows already carry the IDs, names, and labels they reference." }, "429": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The per-key reporting request budget for this operation is exhausted, or the limiter could not be consulted. Retry after the interval in retry_after." }, "503": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The membership query exceeded its statement timeout, so no snapshot was built. No partial snapshot is ever returned. Retry the request." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get call log report dimensions", "tags": ["Call Log Reports"] } }, "/customer/phone-systems/{phoneSystemId}/call-logs": { "get": { "description": "Returns the phone system’s call logs, newest first (ordered by createdAt descending with id as the tiebreak, so paging is deterministic). Filter by an inclusive createdAt window (dateFrom/dateTo) or by the exact callSid delivered in a call webhook — the follow-up fetch for webhook consumers. Requires the calls:read scope.", "operationId": "listCallLogs", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Inclusive lower bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateFrom", "schema": { "format": "date-time", "type": "string" } }, { "description": "Inclusive upper bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateTo", "schema": { "format": "date-time", "type": "string" } }, { "description": "Exact-match filter on the call identifier from a webhook payload.", "in": "query", "name": "callSid", "schema": { "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "callSid": { "description": "Call identifier, as delivered in webhook payloads.", "type": "string" }, "createdAt": { "description": "When the row was created; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "direction": { "description": "Call direction.", "enum": ["inbound", "outbound", "internal"], "type": "string" }, "duration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Call duration in seconds." }, "endTime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the call ended." }, "from": { "description": "Calling party.", "type": "string" }, "fromName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller name, when known." }, "id": { "description": "Call log identifier — the callLogId carried by webhook payloads.", "format": "uuid", "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Call outcome (answered, missed, abandoned, voicemail, transferred, …)." }, "parentCallSid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent call identifier when this row is a transferred or forwarded leg." }, "phoneSystemId": { "description": "Phone system this call belongs to.", "format": "uuid", "type": "string" }, "recordingDuration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Recording duration in seconds." }, "recordingSid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recording identifier when the call was recorded — fetch via the recordings operations." }, "startTime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the call started." }, "status": { "description": "Call status (completed, no-answer, busy, failed, canceled).", "type": "string" }, "to": { "description": "Called party.", "type": "string" } }, "required": [ "id", "phoneSystemId", "callSid", "parentCallSid", "direction", "from", "fromName", "to", "status", "startTime", "endTime", "duration", "outcome", "recordingSid", "recordingDuration", "createdAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "One page of call logs with the total row count for the filter." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: an unknown query parameter, a malformed date, or a pageSize above 100. Field problems are itemized in errors[]." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the calls:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List call logs", "tags": ["Call Logs"] } }, "/customer/phone-systems/{phoneSystemId}/call-logs/{callLogId}": { "get": { "description": "Returns one call log by the callLogId carried in webhook payloads and list responses, including the transcript when one is currently stored. transcriptionStatus reports whether transcript text is retrievable right now: a transcript removed by retention or explicit deletion reads unavailable even though the transcription itself once finished. Requires the calls:read scope.", "operationId": "getCallLog", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Call log identifier from a webhook payload or a list response.", "in": "path", "name": "callLogId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "callSid": { "description": "Call identifier, as delivered in webhook payloads.", "type": "string" }, "createdAt": { "description": "When the row was created; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "direction": { "description": "Call direction.", "enum": ["inbound", "outbound", "internal"], "type": "string" }, "duration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Call duration in seconds." }, "endTime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the call ended." }, "from": { "description": "Calling party.", "type": "string" }, "fromName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller name, when known." }, "id": { "description": "Call log identifier — the callLogId carried by webhook payloads.", "format": "uuid", "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Call outcome (answered, missed, abandoned, voicemail, transferred, …)." }, "parentCallSid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent call identifier when this row is a transferred or forwarded leg." }, "phoneSystemId": { "description": "Phone system this call belongs to.", "format": "uuid", "type": "string" }, "recordingDuration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Recording duration in seconds." }, "recordingSid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Recording identifier when the call was recorded — fetch via the recordings operations." }, "startTime": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the call started." }, "status": { "description": "Call status (completed, no-answer, busy, failed, canceled).", "type": "string" }, "to": { "description": "Called party.", "type": "string" }, "transcribedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Call transcript text, or null when no transcript is currently stored." }, "transcriptionStatus": { "description": "Whether transcript text is retrievable right now: completed, processing (keep polling), failed, or unavailable. A transcript removed by retention or explicit deletion reads unavailable even though the transcription itself once finished.", "enum": ["completed", "processing", "failed", "unavailable"], "type": "string" } }, "required": [ "id", "phoneSystemId", "callSid", "parentCallSid", "direction", "from", "fromName", "to", "status", "startTime", "endTime", "duration", "outcome", "recordingSid", "recordingDuration", "createdAt", "transcribedText", "transcriptionStatus" ], "type": "object" } } }, "description": "The call log, with its transcript when transcription completed." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: callLogId is not a UUID." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the calls:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "No such call log in this phone system — a nonexistent id and an id belonging to another phone system are indistinguishable — or the phone system itself is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a call log", "tags": ["Call Logs"] } }, "/customer/phone-systems/{phoneSystemId}/call-menus": { "get": { "description": "Returns a deterministic page of customer-facing call menus with exact status filtering.", "operationId": "listCallMenus", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exact lifecycle status.", "in": "query", "name": "status", "schema": { "enum": ["active", "inactive"], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the call menu was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive"], "type": "string" }, "updatedAt": { "description": "When the call menu record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "status", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "A deterministic page of call-menu routing identities." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The query or phone-system identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the call-menus:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is outside the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List call menus", "tags": ["Call Menus"] } }, "/customer/phone-systems/{phoneSystemId}/call-menus/{callMenuId}": { "get": { "description": "Returns prompts, ordered choices, and directly configured fallback routing for one call menu.", "operationId": "getCallMenu", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Call-menu identifier from a list response or typed reference.", "in": "path", "name": "callMenuId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "allowDirectExtensionDial": { "type": "boolean" }, "choices": { "items": { "additionalProperties": false, "properties": { "actions": { "items": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": [ "extension", "agent-config", "call-group", "call-menu" ], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": ["extension-voicemail", "call-group-voicemail"], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "anyOf": [ { "additionalProperties": false, "properties": { "playbackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "type": { "const": "play-audio", "type": "string" } }, "required": ["type", "playbackUrl"], "type": "object" }, { "additionalProperties": false, "properties": { "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "type": { "const": "forward", "type": "string" } }, "required": ["type", "phoneNumber"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "company-voicemail", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "voicemail-management", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "directory", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "initial-call-menu", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "send-sms", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "hangup", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "dynamic-routing", "type": "string" } }, "required": ["type"], "type": "object" } ] } ] }, "minItems": 1, "type": "array" }, "digit": { "enum": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*"], "type": "string" } }, "required": ["digit", "actions"], "type": "object" }, "type": "array" }, "createdAt": { "description": "When the call menu was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "maxRepeats": { "minimum": 1, "type": "integer" }, "name": { "type": "string" }, "noInputAction": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": ["extension", "agent-config", "call-group", "call-menu"], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": ["extension-voicemail", "call-group-voicemail"], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "anyOf": [ { "additionalProperties": false, "properties": { "playbackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "type": { "const": "play-audio", "type": "string" } }, "required": ["type", "playbackUrl"], "type": "object" }, { "additionalProperties": false, "properties": { "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "type": { "const": "forward", "type": "string" } }, "required": ["type", "phoneNumber"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "company-voicemail", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "voicemail-management", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "directory", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "initial-call-menu", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "send-sms", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "hangup", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "dynamic-routing", "type": "string" } }, "required": ["type"], "type": "object" } ] } ] }, "phoneSystemId": { "format": "uuid", "type": "string" }, "promptPlaybackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "status": { "enum": ["active", "inactive"], "type": "string" }, "updatedAt": { "description": "When the call menu record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "status", "createdAt", "updatedAt", "promptPlaybackUrl", "maxRepeats", "allowDirectExtensionDial", "choices", "noInputAction" ], "type": "object" } } }, "description": "Call-menu choices and directly configured fallback routing." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "A path identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the call-menus:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The call menu or phone system does not exist within the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a call menu", "tags": ["Call Menus"] } }, "/customer/phone-systems/{phoneSystemId}/extensions": { "get": { "description": "Returns a deterministic page of extensions, with exact status and extension-number filters.", "operationId": "listExtensions", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exact lifecycle status.", "in": "query", "name": "status", "schema": { "enum": ["active", "inactive"], "type": "string" } }, { "description": "Exact extension number.", "in": "query", "name": "number", "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the extension was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "number": { "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive"], "type": "string" }, "updatedAt": { "description": "When the extension record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "number", "status", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "A deterministic page of extension routing identities." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The query or phone-system identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the extensions:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is outside the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List extensions", "tags": ["Extensions"] } }, "/customer/phone-systems/{phoneSystemId}/extensions/{extensionId}": { "get": { "description": "Returns phone assignments and directly configured unanswered routing for one extension.", "operationId": "getExtension", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Extension identifier from a list response or typed reference.", "in": "path", "name": "extensionId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the extension was created.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "number": { "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "phones": { "items": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "const": "phone", "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, "type": "array" }, "status": { "enum": ["active", "inactive"], "type": "string" }, "unansweredCallBehavior": { "additionalProperties": false, "properties": { "businessHours": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": [ "extension", "agent-config", "call-group", "call-menu" ], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": ["extension-voicemail", "call-group-voicemail"], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "anyOf": [ { "additionalProperties": false, "properties": { "playbackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "type": { "const": "play-audio", "type": "string" } }, "required": ["type", "playbackUrl"], "type": "object" }, { "additionalProperties": false, "properties": { "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "type": { "const": "forward", "type": "string" } }, "required": ["type", "phoneNumber"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "company-voicemail", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "voicemail-management", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "directory", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "initial-call-menu", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "send-sms", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "hangup", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "dynamic-routing", "type": "string" } }, "required": ["type"], "type": "object" } ] } ] }, { "type": "null" } ] }, "offHours": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": [ "extension", "agent-config", "call-group", "call-menu" ], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "enum": ["extension-voicemail", "call-group-voicemail"], "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "anyOf": [ { "additionalProperties": false, "properties": { "playbackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "type": { "const": "play-audio", "type": "string" } }, "required": ["type", "playbackUrl"], "type": "object" }, { "additionalProperties": false, "properties": { "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "type": { "const": "forward", "type": "string" } }, "required": ["type", "phoneNumber"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "company-voicemail", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "voicemail-management", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "directory", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "initial-call-menu", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "send-sms", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "hangup", "type": "string" } }, "required": ["type"], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "const": "dynamic-routing", "type": "string" } }, "required": ["type"], "type": "object" } ] } ] }, { "type": "null" } ] }, "timeoutSeconds": { "minimum": 0, "type": "integer" } }, "required": ["timeoutSeconds", "businessHours", "offHours"], "type": "object" }, "updatedAt": { "description": "When the extension record was last updated.", "format": "date-time", "type": "string" }, "voicemailGreetingPlaybackUrl": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "phoneSystemId", "name", "number", "status", "createdAt", "updatedAt", "phones", "unansweredCallBehavior", "voicemailGreetingPlaybackUrl" ], "type": "object" } } }, "description": "Extension assignments and directly configured unanswered routing." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "A path identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the extensions:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The extension or phone system does not exist within the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get an extension", "tags": ["Extensions"] } }, "/customer/phone-systems/{phoneSystemId}/phone-numbers": { "get": { "description": "Returns a deterministic page of phone numbers, with exact status and phone-number filters.", "operationId": "listPhoneNumbers", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exact lifecycle status.", "in": "query", "name": "status", "schema": { "enum": ["active", "inactive", "released"], "type": "string" } }, { "description": "Exact E.164 phone number.", "in": "query", "name": "phoneNumber", "schema": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the phone number was created.", "format": "date-time", "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive", "released"], "type": "string" }, "updatedAt": { "description": "When the phone number record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "phoneNumber", "displayName", "status", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "A deterministic page of phone-number inventory." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The query or phone-system identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the phone-numbers:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is outside the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List phone numbers", "tags": ["Phone Numbers"] } }, "/customer/phone-systems/{phoneSystemId}/phone-numbers/{phoneNumberId}": { "get": { "description": "Returns customer-safe origin, country, and primary-number detail by id.", "operationId": "getPhoneNumber", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Phone-number identifier from a list response.", "in": "path", "name": "phoneNumberId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the phone number was created.", "format": "date-time", "type": "string" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "isPrimary": { "type": "boolean" }, "isoCountry": { "enum": ["US", "CA"], "type": "string" }, "origin": { "enum": ["managed", "carrier_hosted"], "type": "string" }, "phoneNumber": { "description": "E.164 phone number, including the leading + and international country code.", "example": "+14155551212", "format": "phone-number", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive", "released"], "type": "string" }, "updatedAt": { "description": "When the phone number record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "phoneNumber", "displayName", "status", "createdAt", "updatedAt", "origin", "isoCountry", "isPrimary" ], "type": "object" } } }, "description": "Customer-safe phone-number detail." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "A path identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the phone-numbers:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone number or phone system does not exist within the key grant." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a phone number", "tags": ["Phone Numbers"] } }, "/customer/phone-systems/{phoneSystemId}/phones": { "get": { "description": "Returns a deterministic page of phones in the phone system, with exact status and extension filters.", "operationId": "listPhones", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exact lifecycle status.", "in": "query", "name": "status", "schema": { "enum": ["active", "inactive"], "type": "string" } }, { "description": "Exact assigned extension identifier.", "in": "query", "name": "extensionId", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "description": "When the phone was created.", "format": "date-time", "type": "string" }, "extension": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "const": "extension", "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "status": { "enum": ["active", "inactive"], "type": "string" }, "updatedAt": { "description": "When the phone record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "status", "extension", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "A deterministic page of customer-safe phone inventory." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The query or phone-system identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the phones:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is outside the key grant." }, "501": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Phone inventory is unavailable because encryption is not configured." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List phones", "tags": ["Phones"] } }, "/customer/phone-systems/{phoneSystemId}/phones/{phoneId}": { "get": { "description": "Returns customer-safe hardware and extension-assignment detail for one phone.", "operationId": "getPhone", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Phone identifier from a list response.", "in": "path", "name": "phoneId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "When the phone was created.", "format": "date-time", "type": "string" }, "deviceRole": { "enum": [ "desk", "dect_base", "dect_handset", "speaker_base", "speaker_ringer" ], "type": "string" }, "extension": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "const": "extension", "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "type": "null" } ] }, "firmwareVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "type": "string" }, "macAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "parentPhone": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "phoneSystemId": { "format": "uuid", "type": "string" }, "type": { "const": "phone", "type": "string" } }, "required": ["type", "id", "phoneSystemId"], "type": "object" }, { "type": "null" } ] }, "phoneSystemId": { "format": "uuid", "type": "string" }, "slot": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "enum": ["active", "inactive"], "type": "string" }, "updatedAt": { "description": "When the phone record was last updated.", "format": "date-time", "type": "string" } }, "required": [ "id", "phoneSystemId", "name", "status", "extension", "createdAt", "updatedAt", "brand", "model", "deviceRole", "parentPhone", "slot", "macAddress", "firmwareVersion" ], "type": "object" } } }, "description": "Customer-safe phone hardware and assignment detail." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "A path identifier is invalid." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the phones:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone or phone system does not exist within the key grant." }, "501": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Phone inventory is unavailable because encryption is not configured." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a phone", "tags": ["Phones"] } }, "/customer/phone-systems/{phoneSystemId}/recordings": { "get": { "description": "Returns the phone system’s call recordings, newest first (ordered by createdAt descending with id as the tiebreak, so paging is deterministic), optionally bounded by an inclusive createdAt window (dateFrom/dateTo). Each row carries status: ready means the audio is fetchable through the signed-URL operation now; processing means it is still landing after the call — retry shortly. Voicemail audio is not listed here; follow a voicemail’s recordingSid to the signed-URL operation instead. Requires the recordings:read scope.", "operationId": "listRecordings", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Inclusive lower bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateFrom", "schema": { "format": "date-time", "type": "string" } }, { "description": "Inclusive upper bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateTo", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "callSid": { "description": "Call identifier of the recorded call, as delivered in webhook payloads.", "type": "string" }, "createdAt": { "description": "When the recording was created; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "duration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Recording duration in seconds, or null while the recording is still processing and its length is not yet known." }, "from": { "description": "Calling party.", "type": "string" }, "phoneSystemId": { "description": "Phone system this recording belongs to.", "format": "uuid", "type": "string" }, "recordingSid": { "description": "Recording identifier, as delivered in webhook payloads.", "type": "string" }, "status": { "description": "Whether the audio is fetchable yet via the signed-URL operation.", "enum": ["ready", "processing"], "type": "string" }, "to": { "description": "Called party.", "type": "string" } }, "required": [ "recordingSid", "phoneSystemId", "callSid", "status", "duration", "from", "to", "createdAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "One page of call recordings with the total row count for the filter." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: an unknown query parameter, a malformed date, or a pageSize above 100. Field problems are itemized in errors[]." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the recordings:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List call recordings", "tags": ["Recordings"] } }, "/customer/phone-systems/{phoneSystemId}/recordings/{recordingSid}": { "get": { "description": "Returns one call recording by the recordingSid carried in webhook payloads and list responses. status: ready means the audio is fetchable through the signed-URL operation now; processing means it is still landing after the call — retry shortly. A voicemail’s recordingSid does not resolve here (the voicemail operations represent it); its audio still flows through the signed-URL operation. Requires the recordings:read scope.", "operationId": "getRecording", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Recording identifier from a webhook payload or a list response.", "in": "path", "name": "recordingSid", "required": true, "schema": { "pattern": "^RE[0-9a-fA-F]{32}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "callSid": { "description": "Call identifier of the recorded call, as delivered in webhook payloads.", "type": "string" }, "createdAt": { "description": "When the recording was created; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "duration": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Recording duration in seconds, or null while the recording is still processing and its length is not yet known." }, "from": { "description": "Calling party.", "type": "string" }, "phoneSystemId": { "description": "Phone system this recording belongs to.", "format": "uuid", "type": "string" }, "recordingSid": { "description": "Recording identifier, as delivered in webhook payloads.", "type": "string" }, "status": { "description": "Whether the audio is fetchable yet via the signed-URL operation.", "enum": ["ready", "processing"], "type": "string" }, "to": { "description": "Called party.", "type": "string" } }, "required": [ "recordingSid", "phoneSystemId", "callSid", "status", "duration", "from", "to", "createdAt" ], "type": "object" } } }, "description": "The call recording, including its readiness status." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: recordingSid is not a valid recording identifier." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the recordings:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "No such call recording in this phone system — a nonexistent identifier, permanently unavailable audio, and an identifier belonging to another phone system are indistinguishable — or the phone system itself is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a call recording", "tags": ["Recordings"] } }, "/customer/phone-systems/{phoneSystemId}/recordings/{recordingSid}/url": { "get": { "description": "Returns a short-lived signed URL for streaming the audio of a recording — call recordings AND voicemail audio both resolve here by recordingSid, so voicemail integrations need this scope alongside voicemails:read. The URL stops working at expiresAt (15 minutes after issue); request a fresh one rather than storing it. While the audio is still processing the response is a retryable RECORDING_NOT_READY problem — retry after a short delay. Requires the recordings:read scope.", "operationId": "getRecordingUrl", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Recording identifier from a webhook payload or a list response.", "in": "path", "name": "recordingSid", "required": true, "schema": { "pattern": "^RE[0-9a-fA-F]{32}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expiresAt": { "description": "When the signed URL stops working.", "format": "date-time", "type": "string" }, "url": { "description": "Short-lived signed URL for streaming the audio.", "format": "uri", "type": "string" } }, "required": ["url", "expiresAt"], "type": "object" } } }, "description": "The signed audio URL and the instant it expires." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: recordingSid is not a valid recording identifier." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the recordings:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "No such recording in this phone system — a nonexistent identifier, permanently unavailable audio, and an identifier belonging to another phone system are indistinguishable — or the phone system itself is not covered by the key." }, "409": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The recording exists but its audio is still processing (code RECORDING_NOT_READY, retryable: true) — retry after a short delay." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a signed recording audio URL", "tags": ["Recordings"] } }, "/customer/phone-systems/{phoneSystemId}/voicemails": { "get": { "description": "Returns the phone system’s voicemails, newest first (ordered by createdAt descending with id as the tiebreak, so paging is deterministic). Filter by an inclusive createdAt window (dateFrom/dateTo). Each row carries the recordingSid of its audio; fetch the audio through the recording signed-URL operation, which requires the recordings:read scope. Requires the voicemails:read scope.", "operationId": "listVoicemails", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "1-indexed page number.", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Rows per page; at most 100.", "in": "query", "name": "pageSize", "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Inclusive lower bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateFrom", "schema": { "format": "date-time", "type": "string" } }, { "description": "Inclusive upper bound (ISO 8601 UTC) on the row creation time.", "in": "query", "name": "dateTo", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "archived": { "description": "Whether the voicemail has been archived.", "type": "boolean" }, "callGroupId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Call group mailbox that received the voicemail, when group-addressed." }, "callSid": { "description": "Call identifier of the call that left the voicemail, as delivered in webhook payloads.", "type": "string" }, "createdAt": { "description": "When the voicemail was left; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "duration": { "description": "Voicemail duration in seconds.", "type": "integer" }, "extensionId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Extension mailbox that received the voicemail, when extension-addressed." }, "from": { "description": "Calling party.", "type": "string" }, "fromName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller name, when known." }, "id": { "description": "Voicemail identifier — the voicemailId carried by webhook payloads.", "format": "uuid", "type": "string" }, "listened": { "description": "Whether the voicemail has been listened to.", "type": "boolean" }, "phoneSystemId": { "description": "Phone system this voicemail belongs to.", "format": "uuid", "type": "string" }, "recordingSid": { "description": "Recording identifier of the voicemail audio — fetch via the signed-URL operation.", "type": "string" } }, "required": [ "id", "phoneSystemId", "callSid", "recordingSid", "extensionId", "callGroupId", "from", "fromName", "duration", "listened", "archived", "createdAt" ], "type": "object" }, "type": "array" }, "page": { "minimum": 1, "type": "integer" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "totalPages": { "minimum": 0, "type": "integer" } }, "required": ["data", "total", "page", "pageSize", "totalPages"], "type": "object" } } }, "description": "One page of voicemails with the total row count for the filter." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: an unknown query parameter, a malformed date, or a pageSize above 100. Field problems are itemized in errors[]." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the voicemails:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The phone system does not exist or is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List voicemails", "tags": ["Voicemails"] } }, "/customer/phone-systems/{phoneSystemId}/voicemails/{voicemailId}": { "get": { "description": "Returns one voicemail by the voicemailId carried in webhook payloads and list responses, including the transcript when one is currently stored. transcriptionStatus reports whether transcript text is retrievable right now: a transcript removed by retention or explicit deletion reads unavailable even though the transcription itself once finished. The voicemail audio itself is fetched through the recording signed-URL operation using this row’s recordingSid (requires the recordings:read scope). Requires the voicemails:read scope.", "operationId": "getVoicemail", "parameters": [ { "description": "Phone system identifier, discoverable via the accessible phone systems operation.", "in": "path", "name": "phoneSystemId", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Voicemail identifier from a webhook payload or a list response.", "in": "path", "name": "voicemailId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "archived": { "description": "Whether the voicemail has been archived.", "type": "boolean" }, "callGroupId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Call group mailbox that received the voicemail, when group-addressed." }, "callSid": { "description": "Call identifier of the call that left the voicemail, as delivered in webhook payloads.", "type": "string" }, "createdAt": { "description": "When the voicemail was left; lists are ordered by this, descending.", "format": "date-time", "type": "string" }, "duration": { "description": "Voicemail duration in seconds.", "type": "integer" }, "extensionId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Extension mailbox that received the voicemail, when extension-addressed." }, "from": { "description": "Calling party.", "type": "string" }, "fromName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller name, when known." }, "id": { "description": "Voicemail identifier — the voicemailId carried by webhook payloads.", "format": "uuid", "type": "string" }, "listened": { "description": "Whether the voicemail has been listened to.", "type": "boolean" }, "phoneSystemId": { "description": "Phone system this voicemail belongs to.", "format": "uuid", "type": "string" }, "recordingSid": { "description": "Recording identifier of the voicemail audio — fetch via the signed-URL operation.", "type": "string" }, "transcribedText": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Voicemail transcript text, or null when no transcript is currently stored." }, "transcriptionStatus": { "description": "Whether transcript text is retrievable right now: completed, processing (keep polling), failed, or unavailable. A transcript removed by retention or explicit deletion reads unavailable even though the transcription itself once finished.", "enum": ["completed", "processing", "failed", "unavailable"], "type": "string" } }, "required": [ "id", "phoneSystemId", "callSid", "recordingSid", "extensionId", "callGroupId", "from", "fromName", "duration", "listened", "archived", "createdAt", "transcribedText", "transcriptionStatus" ], "type": "object" } } }, "description": "The voicemail, with its transcript when one is currently stored." }, "400": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "Validation failure: voicemailId is not a UUID." }, "401": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The API key is missing, malformed, expired, or revoked." }, "403": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "The key lacks the voicemails:read scope, or is not a tenant API key." }, "404": { "content": { "application/problem+json": { "schema": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine identifier to branch on.", "type": "string" }, "correlationId": { "description": "Request identifier to quote to support.", "type": "string" }, "detail": { "description": "User-safe explanation. Display it if you must; never match on it.", "type": "string" }, "errors": { "description": "Field-level validation problems. Present on validation failures.", "items": { "additionalProperties": false, "properties": { "code": { "description": "Per-field machine code (REQUIRED, TOO_SMALL, …).", "type": "string" }, "detail": { "description": "Human-readable description of the field problem.", "type": "string" }, "pointer": { "description": "JSON Pointer to the offending request field.", "type": "string" } }, "required": ["pointer", "code", "detail"], "type": "object" }, "type": "array" }, "params": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "description": "Extra primitive detail about the condition, such as a limit that was hit.", "propertyNames": { "type": "string" }, "type": "object" }, "retry_after": { "description": "Seconds to wait before retrying, when a meaningful delay exists.", "type": "integer" }, "retryable": { "description": "Whether this condition is transient. Derived from code.", "type": "boolean" }, "status": { "description": "Mirrors the HTTP status code.", "type": "integer" }, "title": { "description": "Short human summary of the problem type.", "type": "string" }, "type": { "description": "URL identifying the problem type. An identifier to match, not a link.", "type": "string" } }, "required": [ "type", "title", "status", "code", "detail", "correlationId", "retryable" ], "type": "object" } } }, "description": "No such voicemail in this phone system — a nonexistent id, a deleted voicemail, and an id belonging to another phone system are indistinguishable — or the phone system itself is not covered by the key." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a voicemail", "tags": ["Voicemails"] } } }, "servers": [ { "url": "https://api.steerphones.com/v1" } ], "tags": [ { "description": "AI voice agent configuration", "name": "Agent Configs" }, { "description": "Call group (ring group) management", "name": "Call Groups" }, { "description": "Bulk call reporting: cursor-paginated enriched call rows over one bounded time window, and the replace-all snapshot of the display values those rows reference", "name": "Call Log Reports" }, { "description": "Call log search and detail", "name": "Call Logs" }, { "description": "Interactive call-menu routing", "name": "Call Menus" }, { "description": "Extension CRUD", "name": "Extensions" }, { "description": "Phone number management", "name": "Phone Numbers" }, { "description": "Phone system management", "name": "Phone Systems" }, { "description": "Phone inventory and management", "name": "Phones" }, { "description": "Call and voicemail recording audio access", "name": "Recordings" }, { "description": "Voicemail management", "name": "Voicemails" } ] }