{ "components": { "schemas": { "CallList": { "properties": { "data": { "description": "The page of call resources.", "items": { "$ref": "#/components/schemas/CallResource" }, "title": "Data", "type": "array" }, "has_more": { "description": "Whether more results exist after this page.", "title": "Has More", "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass back as `cursor` to fetch the next page; null on the last page.", "title": "Next Cursor" }, "object": { "const": "list", "default": "list", "description": "Always `list` for a paginated collection.", "title": "Object", "type": "string" } }, "required": [ "data", "has_more", "next_cursor" ], "title": "CallList", "type": "object" }, "CallResource": { "properties": { "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the agent that handled the call (agt_...).", "title": "Agent Id" }, "direction": { "description": "`inbound` or `outbound`.", "enum": [ "inbound", "outbound" ], "title": "Direction", "type": "string" }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total call duration in seconds.", "title": "Duration Seconds" }, "ended_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the call ended; null while in progress.", "title": "Ended At" }, "from_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller phone number in E.164 format.", "title": "From Number" }, "has_recording": { "description": "Whether recording audio is available at `/v1/calls/{id}/recording`.", "title": "Has Recording", "type": "boolean" }, "id": { "description": "Unique call ID.", "examples": [ "call_9f8e7d6c5b4a3f2e1d0c9b8a" ], "title": "Id", "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Detected outcome, e.g. `booked`, `lead`, `transferred` (lowercased).", "title": "Outcome" }, "sentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Overall caller sentiment: `positive`, `neutral`, or `negative`.", "title": "Sentiment" }, "started_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the call started (UTC, ISO-8601).", "title": "Started At" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Call lifecycle status, e.g. `completed`.", "title": "Status" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One-paragraph AI summary of the call.", "title": "Summary" }, "to_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Receiving phone number in E.164 format; null in v1.", "title": "To Number" } }, "required": [ "id", "agent_id", "direction", "status", "started_at", "ended_at", "duration_seconds", "from_number", "to_number", "summary", "sentiment", "outcome", "has_recording" ], "title": "CallResource", "type": "object" }, "ContactCreate": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact email address.", "title": "Email" }, "external_id": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Your CRM's stable id. When set, upsert matches it FIRST (before phone).", "title": "External Id" }, "fields": { "additionalProperties": true, "description": "Custom key/value fields surfaced to the agent as caller context.", "title": "Fields", "type": "object" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact name; used by the agent as returning-caller context.", "title": "Name" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Operator-facing notes; never spoken by the agent.", "title": "Notes" }, "phone": { "description": "E.164, e.g. +35799123456. Upsert key (fallback).", "title": "Phone", "type": "string" } }, "required": [ "phone" ], "title": "ContactCreate", "type": "object" }, "ContactUpdate": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New contact email address.", "title": "Email" }, "external_id": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "New CRM stable id for this contact.", "title": "External Id" }, "fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "description": "Custom fields to shallow-merge; a key set to null is removed.", "title": "Fields" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New contact name.", "title": "Name" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New operator-facing notes.", "title": "Notes" } }, "title": "ContactUpdate", "type": "object" }, "InsightsResponse": { "properties": { "call_id": { "description": "ID of the call these insights belong to.", "title": "Call Id", "type": "string" }, "extracted": { "additionalProperties": true, "description": "Structured lead/intent fields captured on the call.", "title": "Extracted", "type": "object" }, "lead_captured": { "description": "Whether a lead was captured on this call.", "title": "Lead Captured", "type": "boolean" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Detected call outcome, e.g. `booked`, `lead`, `transferred`.", "title": "Outcome" }, "sentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Overall caller sentiment: `positive`, `neutral`, or `negative`.", "title": "Sentiment" } }, "required": [ "call_id", "sentiment", "outcome", "lead_captured", "extracted" ], "title": "InsightsResponse", "type": "object" }, "TranscriptResponse": { "properties": { "call_id": { "description": "ID of the call this transcript belongs to.", "title": "Call Id", "type": "string" }, "turns": { "description": "Ordered conversation turns, earliest first.", "items": { "$ref": "#/components/schemas/TranscriptTurn" }, "title": "Turns", "type": "array" } }, "required": [ "call_id", "turns" ], "title": "TranscriptResponse", "type": "object" }, "TranscriptTurn": { "properties": { "role": { "description": "Who spoke this turn: `agent` or `caller`.", "enum": [ "agent", "caller" ], "title": "Role", "type": "string" }, "text": { "description": "The text of this turn.", "title": "Text", "type": "string" } }, "required": [ "role", "text" ], "title": "TranscriptTurn", "type": "object" }, "UsageMinutes": { "properties": { "included": { "description": "Minutes included in the plan", "title": "Included", "type": "number" }, "topup_remaining": { "description": "Top-up minutes still available", "title": "Topup Remaining", "type": "number" }, "topup_used": { "description": "Top-up minutes used this period", "title": "Topup Used", "type": "number" }, "total_allowance": { "description": "Everything available this period", "title": "Total Allowance", "type": "number" }, "total_used": { "description": "used + topup_used", "title": "Total Used", "type": "number" }, "used": { "description": "Plan minutes used this period", "title": "Used", "type": "number" } }, "required": [ "used", "included", "topup_used", "topup_remaining", "total_used", "total_allowance" ], "title": "UsageMinutes", "type": "object" }, "UsageResource": { "properties": { "call_count": { "description": "Number of calls in the current billing period.", "title": "Call Count", "type": "integer" }, "minutes": { "$ref": "#/components/schemas/UsageMinutes", "description": "Minute usage breakdown for the current period." }, "period_end": { "description": "End of the current billing period (UTC, ISO-8601).", "title": "Period End", "type": "string" }, "period_start": { "description": "Start of the current billing period (UTC, ISO-8601).", "title": "Period Start", "type": "string" }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current plan tier", "title": "Plan" } }, "required": [ "plan", "period_start", "period_end", "minutes", "call_count" ], "title": "UsageResource", "type": "object" }, "WebhookEndpointCreate": { "properties": { "description": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "Optional label for this endpoint.", "title": "Description" }, "events": { "description": "Event types to subscribe to; an empty list subscribes to all event types.", "items": { "type": "string" }, "title": "Events", "type": "array" }, "url": { "description": "Public HTTPS URL to deliver events to.", "maxLength": 500, "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "WebhookEndpointCreate", "type": "object" }, "WebhookEndpointUpdate": { "properties": { "description": { "anyOf": [ { "maxLength": 200, "type": "string" }, { "type": "null" } ], "description": "New label for this endpoint.", "title": "Description" }, "events": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "New list of subscribed event types.", "title": "Events" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set to `enabled` or `disabled` to pause or resume deliveries.", "title": "Status" }, "url": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "description": "New public HTTPS delivery URL.", "title": "Url" } }, "title": "WebhookEndpointUpdate", "type": "object" } } }, "info": { "description": "The Essere Voice API gives you programmatic access to your AI voice agents:\ncalls, transcripts, insights, appointments, contacts, phone numbers, usage,\nand outbound webhooks.\n\n## Base URL\n\n```\nhttps://voice-public-api.essere.ai/v1\n```\n\n## Authentication\n\nSend your API key on every request (from an environment variable or\nsecret store — never hard-code it):\n\n```\nAuthorization: Bearer $ESSERE_API_KEY\n```\n\nKeys are created in the Essere dashboard under **Developers**\n(paid plan required). Staging keys start with `vk_test_`. Keys are shown once\nat creation — store them securely and never commit them.\n\nScopes: `read` (all GET endpoints) and `read_write` (also POST/PATCH/DELETE,\nincluding webhook-endpoint management).\n\n## Rate limits\n\n120 requests per minute per account (shared across all your API keys),\nenforced as a fixed one-minute window —\nbursts straddling a window boundary can briefly exceed the nominal rate, so\nsize your client-side throttling to the limit, not to the boundary behavior.\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and\n`X-RateLimit-Reset`; `429` responses add `Retry-After`.\n\n## Pagination\n\nList endpoints are cursor-based: pass `limit` (default 25, max 100) and\n`cursor`. Responses are a list envelope:\n\n```json\n{\"object\": \"list\", \"data\": [], \"has_more\": true, \"next_cursor\": \"...\"}\n```\n\nIterate by passing `next_cursor` back as `cursor` until `has_more` is `false`.\n\n## Idempotency\n\nPOST/PATCH endpoints honor an `Idempotency-Key` header (any unique string,\n24h window). Retried requests with the same key return the stored response\nwith `Idempotent-Replayed: true`.\n\n## Errors\n\nErrors are JSON with a stable machine-readable code:\n\n```json\n{\"error\": {\"type\": \"authentication_error\", \"code\": \"invalid_api_key\", \"message\": \"...\"}}\n```\n\n| HTTP | `type` | `code` | Meaning |\n|------|--------|--------|---------|\n| 400 | `invalid_request_error` | `invalid_request` | Malformed parameters or body (`param` names the field). |\n| 400 | `invalid_request_error` | `invalid_cursor` | The pagination cursor is not valid. |\n| 400 | `invalid_request_error` | `invalid_phone` | The phone number is not valid E.164. |\n| 401 | `authentication_error` | `invalid_api_key` | Missing, malformed, or revoked API key. |\n| 403 | `permission_error` | `plan_required` | The account is not on a paid plan. Upgrade in the dashboard. |\n| 403 | `permission_error` | `insufficient_scope` | The key is `read`-scoped but the endpoint needs `read_write`. |\n| 403 | `permission_error` | `account_inactive` | The account is not active. Reactivate it in the dashboard. |\n| 404 | `not_found_error` | `resource_not_found` | No such resource on this account. |\n| 409 | `idempotency_error` | `idempotency_conflict` | `Idempotency-Key` reused with a different request body. |\n| 413 | `invalid_request_error` | `request_too_large` | The request body exceeds the 1 MB limit. |\n| 429 | `rate_limit_error` | `rate_limit_exceeded` | Too many requests — honor `Retry-After`. |\n| 5xx | `api_error` | `internal_error` | Something went wrong on our side. Safe to retry with backoff. |\n| 503 | `api_error` | `service_unavailable` | A dependent service is temporarily unavailable — retry. |\n\n## Webhooks\n\nSubscribe to events (`call.completed`, `call.transferred`,\n`appointment.booked`, `appointment.cancelled`, `lead.captured`,\n`usage.threshold_reached`) via the Webhook Endpoints resource. Payloads are\nsigned with `X-Essere-Signature` — see the\n[webhooks guide](https://voice-developers.essere.ai/webhooks).\n\n## More\n\nGuides, recipes, and an AI-ready `llms.txt` live at\n[voice-developers.essere.ai](https://voice-developers.essere.ai). An MCP\nserver is available at `https://voice-public-api.essere.ai/mcp` (same API keys).\n", "title": "Essere Voice API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/agents": { "get": { "description": "List the account's AI voice agents with status, language, and default-agent flag. Archived agents are hidden unless `include_archived=true`.", "operationId": "list_agents_v1_agents_get", "parameters": [ { "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "title": "Include Archived", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-06-01T09:12:00Z", "id": "agt_1a2b3c4d5e6f7a8b9c0d1e2f", "is_default": true, "language": "en", "name": "Reception Agent", "status": "active" } ], "has_more": false, "object": "list" }, "schema": {} } }, "description": "A list of agents." } }, "summary": "List agents", "tags": [ "Agents" ] } }, "/v1/agents/{agent_id}": { "get": { "description": "Fetch one agent by ID, including archived agents.", "operationId": "get_agent_v1_agents__agent_id__get", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "title": "Agent Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-06-01T09:12:00Z", "id": "agt_1a2b3c4d5e6f7a8b9c0d1e2f", "is_default": true, "language": "en", "name": "Reception Agent", "status": "active" }, "schema": {} } }, "description": "The agent." } }, "summary": "Retrieve an agent", "tags": [ "Agents" ] } }, "/v1/appointments": { "get": { "description": "List appointments booked by the account's agents (booked or cancelled), timezone-aware, with attendee details. Filter by date range (`from`/`to`), `status`, or `agent_id`. Cursor-paginated.", "operationId": "list_appointments_v1_appointments_get", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "in": "query", "name": "agent_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "agent_id": "agt_1a2b3c4d5e6f7a8b9c0d1e2f", "attendee": { "email": "maria@example.com", "name": "Maria Georgiou", "phone": "+35799123456" }, "end_time": "2026-07-20T10:30:00Z", "id": "apt_2b3c4d5e6f7a8b9c0d1e2f3a", "location": "Makarios Avenue 12", "start_time": "2026-07-20T10:00:00Z", "status": "booked", "title": "Apartment viewing" } ], "has_more": false, "object": "list" }, "schema": {} } }, "description": "A page of appointments." } }, "summary": "List appointments", "tags": [ "Appointments" ] } }, "/v1/calls": { "get": { "description": "Returns your calls, newest first. Filter by ISO-8601 date range (`from`/`to`), `agent`, `direction`, or `status`. Summary and insight fields are included inline when available; fetch `/v1/calls/{id}/transcript` for full turns. Cursor-paginated.", "operationId": "list_calls_v1_calls_get", "parameters": [ { "description": "Only calls started at/after this ISO 8601 timestamp", "in": "query", "name": "from", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only calls started at/after this ISO 8601 timestamp", "title": "From" } }, { "description": "Only calls started at/before this ISO 8601 timestamp", "in": "query", "name": "to", "required": false, "schema": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Only calls started at/before this ISO 8601 timestamp", "title": "To" } }, { "description": "Filter by agent id (agt_...)", "in": "query", "name": "agent", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by agent id (agt_...)", "title": "Agent" } }, { "description": "Filter by call status", "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by call status", "title": "Status" } }, { "description": "Filter by call direction", "in": "query", "name": "direction", "required": false, "schema": { "anyOf": [ { "enum": [ "inbound", "outbound" ], "type": "string" }, { "type": "null" } ], "description": "Filter by call direction", "title": "Direction" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "description": "Opaque cursor from next_cursor", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from next_cursor", "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "agent_id": "agt_1a2b3c4d5e6f7a8b9c0d1e2f", "direction": "inbound", "duration_seconds": 263, "ended_at": "2026-07-17T14:07:45Z", "from_number": "+35799123456", "has_recording": true, "id": "call_9f8e7d6c5b4a3f2e1d0c9b8a", "outcome": "booked", "sentiment": "positive", "started_at": "2026-07-17T14:03:22Z", "status": "completed", "summary": "Caller asked about availability for a 2-bedroom apartment; agent booked a viewing." } ], "has_more": false, "object": "list" }, "schema": { "$ref": "#/components/schemas/CallList" } } }, "description": "A page of calls." } }, "summary": "List calls", "tags": [ "Calls" ] } }, "/v1/calls/{call_id}": { "get": { "description": "Fetch one call by ID, including summary, sentiment, outcome, duration, and numbers.", "operationId": "get_call_v1_calls__call_id__get", "parameters": [ { "in": "path", "name": "call_id", "required": true, "schema": { "title": "Call Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "agent_id": "agt_1a2b3c4d5e6f7a8b9c0d1e2f", "direction": "inbound", "duration_seconds": 263, "ended_at": "2026-07-17T14:07:45Z", "from_number": "+35799123456", "has_recording": true, "id": "call_9f8e7d6c5b4a3f2e1d0c9b8a", "outcome": "booked", "sentiment": "positive", "started_at": "2026-07-17T14:03:22Z", "status": "completed", "summary": "Caller asked about availability for a 2-bedroom apartment; agent booked a viewing." }, "schema": { "$ref": "#/components/schemas/CallResource" } } }, "description": "The call." } }, "summary": "Retrieve a call", "tags": [ "Calls" ] } }, "/v1/calls/{call_id}/insights": { "get": { "description": "Fetch extracted insights for a call: sentiment, outcome, whether a lead was captured, and structured extracted fields.", "operationId": "get_insights_v1_calls__call_id__insights_get", "parameters": [ { "in": "path", "name": "call_id", "required": true, "schema": { "title": "Call Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "call_id": "call_9f8e7d6c5b4a3f2e1d0c9b8a", "extracted": { "bedrooms": "2", "budget": "250000" }, "lead_captured": true, "outcome": "booked", "sentiment": "positive" }, "schema": { "$ref": "#/components/schemas/InsightsResponse" } } }, "description": "The insights." } }, "summary": "Retrieve call insights", "tags": [ "Calls" ] } }, "/v1/calls/{call_id}/recording": { "get": { "description": "Streams the call recording audio. The response body is the audio file itself (no URL indirection).", "operationId": "get_call_recording_v1_calls__call_id__recording_get", "parameters": [ { "in": "path", "name": "call_id", "required": true, "schema": { "title": "Call Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} }, "audio/mpeg": {} }, "description": "The recording audio stream." } }, "summary": "Stream the call recording", "tags": [ "Calls" ] } }, "/v1/calls/{call_id}/transcript": { "get": { "description": "Fetch the structured transcript of a call: ordered turns with role (`agent` or `caller`) and text.", "operationId": "get_transcript_v1_calls__call_id__transcript_get", "parameters": [ { "in": "path", "name": "call_id", "required": true, "schema": { "title": "Call Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "call_id": "call_9f8e7d6c5b4a3f2e1d0c9b8a", "turns": [ { "role": "agent", "text": "Hi, you've reached Horizon Estates. How can I help?" }, { "role": "caller", "text": "I'm calling about the two-bedroom on Makarios Avenue." } ] }, "schema": { "$ref": "#/components/schemas/TranscriptResponse" } } }, "description": "The transcript." } }, "summary": "Retrieve a call transcript", "tags": [ "Calls" ] } }, "/v1/contacts": { "get": { "description": "List contact records, ordered by most-recently-updated. Filter by exact `phone` (E.164), `external_id`, or `updated_since` for incremental CRM sync. Cursor-paginated.", "operationId": "list_contacts_v1_contacts_get", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "in": "query", "name": "phone", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" } }, { "description": "Filter by your CRM's stable id", "in": "query", "name": "external_id", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by your CRM's stable id", "title": "External Id" } }, { "description": "ISO 8601 — only contacts updated at/after this instant (incremental sync)", "in": "query", "name": "updated_since", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 — only contacts updated at/after this instant (incremental sync)", "title": "Updated Since" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-07-01T09:12:00Z", "email": "maria@example.com", "external_id": "crm-8842", "fields": { "source": "website-form" }, "id": "ctc_4d5e6f7a8b9c0d1e2f3a4b5c", "name": "Maria Georgiou", "notes": "Interested in 2-bedroom apartments, budget EUR 250k.", "phone": "+35799123456", "updated_at": "2026-07-15T11:30:00Z" } ], "has_more": false, "object": "list" }, "schema": {} } }, "description": "A page of contacts." } }, "summary": "List contacts", "tags": [ "Contacts" ] }, "post": { "description": "Create a contact, or upsert an existing one (matched by `external_id` first, then `phone`). The agent uses it as returning-caller context on the next call from that number. Requires the `read_write` scope; honors `Idempotency-Key`.", "operationId": "create_contact_v1_contacts_post", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "created_at": "2026-07-01T09:12:00Z", "email": "maria@example.com", "external_id": "crm-8842", "fields": { "source": "website-form" }, "id": "ctc_4d5e6f7a8b9c0d1e2f3a4b5c", "name": "Maria Georgiou", "notes": "Interested in 2-bedroom apartments, budget EUR 250k.", "phone": "+35799123456", "updated_at": "2026-07-15T11:30:00Z" }, "schema": {} } }, "description": "The created or updated contact." } }, "summary": "Create or update a contact", "tags": [ "Contacts" ] } }, "/v1/contacts/{contact_id}": { "get": { "description": "Fetch one contact by ID.", "operationId": "get_contact_v1_contacts__contact_id__get", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-07-01T09:12:00Z", "email": "maria@example.com", "external_id": "crm-8842", "fields": { "source": "website-form" }, "id": "ctc_4d5e6f7a8b9c0d1e2f3a4b5c", "name": "Maria Georgiou", "notes": "Interested in 2-bedroom apartments, budget EUR 250k.", "phone": "+35799123456", "updated_at": "2026-07-15T11:30:00Z" }, "schema": {} } }, "description": "The contact." } }, "summary": "Retrieve a contact", "tags": [ "Contacts" ] }, "patch": { "description": "Update an existing contact by ID. Only provided fields change; a `fields` key set to null is removed. Requires the `read_write` scope; honors `Idempotency-Key`.", "operationId": "update_contact_v1_contacts__contact_id__patch", "parameters": [ { "in": "path", "name": "contact_id", "required": true, "schema": { "title": "Contact Id", "type": "string" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "created_at": "2026-07-01T09:12:00Z", "email": "maria@example.com", "external_id": "crm-8842", "fields": { "source": "website-form" }, "id": "ctc_4d5e6f7a8b9c0d1e2f3a4b5c", "name": "Maria Georgiou", "notes": "Interested in 2-bedroom apartments, budget EUR 250k.", "phone": "+35799123456", "updated_at": "2026-07-15T11:30:00Z" }, "schema": {} } }, "description": "The updated contact." } }, "summary": "Update a contact", "tags": [ "Contacts" ] } }, "/v1/numbers": { "get": { "description": "List the account's phone numbers with `kind` (platform, purchased, or external), verification `status`, and assigned agent.", "operationId": "list_numbers_v1_numbers_get", "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "agent_id": "agt_1a2b3c4d5e6f7a8b9c0d1e2f", "country": "CY", "id": "num_3c4d5e6f7a8b9c0d1e2f3a4b", "kind": "purchased", "phone_number": "+35722123456", "status": "active" } ], "has_more": false, "object": "list" }, "schema": {} } }, "description": "A list of phone numbers." } }, "summary": "List phone numbers", "tags": [ "Numbers" ] } }, "/v1/usage": { "get": { "description": "Minutes used vs. allowance (plan + top-ups) and call count for the current billing period.", "operationId": "get_usage_v1_usage_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResource" } } }, "description": "Successful Response" } }, "summary": "Retrieve current-period usage", "tags": [ "Usage" ] } }, "/v1/webhook-endpoints": { "get": { "description": "List your outbound webhook endpoints with their subscribed events and status.", "operationId": "list_webhook_endpoints_v1_webhook_endpoints_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "List webhook endpoints", "tags": [ "Webhook Endpoints" ] }, "post": { "description": "Register an outbound webhook endpoint (HTTPS URL). The signing `secret` (`whsec_...`) is returned once, on creation only — store it securely. An empty `events` array subscribes to all event types. Requires the `read_write` scope.", "operationId": "create_webhook_endpoint_v1_webhook_endpoints_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Create a webhook endpoint", "tags": [ "Webhook Endpoints" ] } }, "/v1/webhook-endpoints/{endpoint_id}": { "delete": { "description": "Delete a webhook endpoint. No further events are delivered to it. Requires the `read_write` scope.", "operationId": "delete_webhook_endpoint_v1_webhook_endpoints__endpoint_id__delete", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Delete a webhook endpoint", "tags": [ "Webhook Endpoints" ] }, "get": { "description": "Fetch one webhook endpoint by ID (the signing secret is never returned).", "operationId": "get_webhook_endpoint_v1_webhook_endpoints__endpoint_id__get", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Retrieve a webhook endpoint", "tags": [ "Webhook Endpoints" ] }, "patch": { "description": "Update a webhook endpoint's URL, subscribed events, description, or status (`enabled`/`disabled`). Requires the `read_write` scope.", "operationId": "update_webhook_endpoint_v1_webhook_endpoints__endpoint_id__patch", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Update a webhook endpoint", "tags": [ "Webhook Endpoints" ] } }, "/v1/webhook-endpoints/{endpoint_id}/deliveries": { "get": { "description": "List recent delivery attempts for an endpoint (metadata only — event payloads are not echoed back). Cursor-paginated.", "operationId": "list_webhook_deliveries_v1_webhook_endpoints__endpoint_id__deliveries_get", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "List webhook deliveries", "tags": [ "Webhook Endpoints" ] } }, "/v1/webhook-endpoints/{endpoint_id}/ping": { "post": { "description": "Enqueue a `ping` test event to the endpoint through the normal delivery pipeline. Rate-limited per client. Requires the `read_write` scope.", "operationId": "ping_webhook_endpoint_v1_webhook_endpoints__endpoint_id__ping_post", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Send a test event", "tags": [ "Webhook Endpoints" ] } }, "/v1/webhook-endpoints/{endpoint_id}/rotate-secret": { "post": { "description": "Rotate the endpoint's signing secret. The new `whsec_` secret is shown once; the previous secret keeps verifying for 24 hours (deliveries carry two signatures during the overlap). Requires the `read_write` scope.", "operationId": "rotate_webhook_endpoint_secret_v1_webhook_endpoints__endpoint_id__rotate_secret_post", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "title": "Endpoint Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Rotate a webhook signing secret", "tags": [ "Webhook Endpoints" ] } } }, "servers": [ { "url": "https://voice-public-api.essere.ai" } ], "tags": [ { "description": "Completed and in-progress calls handled by your agents, with transcripts, insights, and recording audio.", "name": "Calls" }, { "description": "Appointments booked (or cancelled) by your agents, timezone-aware, with agent attribution.", "name": "Appointments" }, { "description": "Your AI voice agents (read-only in v1).", "name": "Agents" }, { "description": "Phone numbers connected to your agents and their verification status.", "name": "Numbers" }, { "description": "Contact records you push to us. The agent uses them as returning-caller context on the next call from that phone number.", "name": "Contacts" }, { "description": "Plan minutes, top-ups, and call counts for the current billing period.", "name": "Usage" }, { "description": "Manage outbound webhook endpoints: subscriptions, delivery log, ping test-sends. Requires read_write scope.", "name": "Webhook Endpoints" } ] }