# Build on Vocenya Build on Vocenya: a REST API with organization API keys and scopes, signed webhooks for leads, calls and bookings, and MCP servers for AI assistants like Claude and Cursor. - API reference: https://vocenya.com/docs/api - OpenAPI specification: https://vocenya.com/docs/api.json - Base URL: https://vocenya.com/api/public/v1 - Create an API key: https://vocenya.com/app/developers ## Authentication API keys belong to your organization, not to a person. Send the key as a Bearer token: `Authorization: Bearer vk_live_...`. The full key is shown once, when it is created. Each key carries scopes: - `calls:read`: Read calls - `leads:read`: Read leads - `leads:write`: Create leads - `bookings:read`: Read bookings - `outbound:write`: Queue outbound AI calls and check their status - `dnc:read`: Read the Do Not Call list - `dnc:write`: Add to and remove from the Do Not Call list - `chats:read`: Read website chats - `webhooks:manage`: Manage webhooks Lists are cursor paginated: pass `meta.next_cursor` as `?cursor=` for the next page. A lead `callback` (an AI call back) also needs `outbound:write`. Errors use one shape: `{"message": "...", "code": "..."}`, with `errors` added for validation failures. A missing or invalid key gets 401; a key without a needed scope gets 403 `missing_scope`. ## Webhooks Events: - `lead.created`: A lead was captured - `call.completed`: An inbound call ended - `booking.created`: An appointment was booked - `chat.handed_off`: A website chat was handed to a person - `outbound_call.completed`: An outbound call ended Every delivery is signed with HMAC-SHA256 in the `Vocenya-Signature: t=,v1=` header, computed over `.` with your endpoint secret. Reject signatures older than 300 seconds. Respond with a 2xx within 10 seconds; failed deliveries are retried with exponential backoff, up to 8 attempts. Each event has a unique id (the body `id` and the `Vocenya-Delivery` header) for ignoring duplicates. Endpoints must use https and are added in the app or with the API; subscribing to an event also needs that record's read scope (`lead.created` needs `leads:read`, `call.completed` `calls:read`, `booking.created` `bookings:read`, `chat.handed_off` `chats:read`, `outbound_call.completed` `outbound:write`). ## MCP servers - Platform: https://vocenya.com/mcp/platform (requires an API key as a Bearer token; each tool checks the key's scopes) - Site: https://vocenya.com/mcp/site (public, read-only, no key) ## Rate limits 120 requests per minute per API key by default, shared between the REST API and the platform MCP server. Over the limit the API answers 429 with a Retry-After header. Repeated requests with a missing or invalid key are also limited per IP address. ## HIPAA mode For organizations in HIPAA mode, the API and MCP server leave out transcripts, summaries, chat message text and the reason and details of a lead, and webhooks carry ids only. Call recordings are never available through the API. ## Frequently asked questions ### Who owns an API key? Your business does. Keys belong to your Vocenya organization, not to the person who created them, so they keep working when a teammate leaves. An account owner creates and revokes keys in the app, under Developers. ### Can I see an API key again after I create it? No. The full key is shown once, when you create it. Vocenya stores only a hash of it, so if you lose a key, revoke it and create a new one. ### Can the API call anyone I send it? No. Outbound calls queued through the API or the MCP server go through the same checks as calls started in the app: consent, the Do Not Call list and local calling hours. A blocked call is refused with a reason code, and a call outside calling hours waits until it is allowed to ring. ### What is the difference between the two MCP servers? The platform server works with your own account data (calls, leads, bookings, outbound calls, the Do Not Call list and chats) and needs an API key. The site server is public and read-only: it answers questions about Vocenya itself, such as pricing, industries and guides, and needs no key. ### Is there an OpenAPI specification? Yes. The OpenAPI document is published at /docs/api.json and the interactive reference at /docs/api. You can use the JSON to generate a client in your language. ### What happens when I go over the rate limit? Each key can make 120 requests a minute by default. Past that the API answers 429 Too Many Requests with a Retry-After header telling you how many seconds to wait. ### Does the API work for practices in HIPAA mode? Yes, with less detail. For organizations in HIPAA mode the API and MCP server leave out transcripts, summaries, chat message text and the reason and details of a lead, and webhooks carry ids only. Call recordings are never available through the API. --- Source: https://vocenya.com/developers