aid: ringover name: Ringover description: Ringover provides a cloud‑based business phone system that unifies voice calling, messaging, and collaboration tools into a single platform. It offers features such as AI‑enhanced call handling, virtual numbers, call routing, analytics, and integrations with CRM and productivity applications, targeting enterprises and remote teams. The service is delivered via a web app and mobile apps, with a focus on scalability, security, and AI‑driven assistance for agents. url: https://artifacts.apis.io/ringover/apis.yml image: https://www.ringover.com/favicon.ico x-type: company x-source: harvest:new-submission x-tier: profiled x-tier-reason: enrichment pass 2026-10-28 (modular-v1; was harvest) specificationVersion: '0.20' created: '2026-10-28' modified: '2026-10-28' tags: - Communications - Cloud - VoIP - Collaboration - AI maintainers: - FN: Kin Lane email: kin@apievangelist.com - FN: APIs.json email: info@apis.io common: - type: CapabilityMap url: capabilities/ringover-capability-edges.yml name: Ringover Business Capability Map - type: AgenticAccess url: agentic-access/ringover-agentic-access.yml - type: RateLimits url: rate-limits/ringover-rate-limits.yml - type: Plans url: plans/ringover-plans-pricing.yml - type: Spectral url: rules/ringover-rules.yml - type: JSONLD url: json-ld/ringover-context.jsonld - type: Vocabulary url: vocabulary/ringover-vocabulary.yml - type: AgentSkill url: skills/_index.yml - type: Webhooks url: asyncapi/ringover-webhooks.yml - type: DataModel url: data-model/ringover-data-model.yml - type: Conventions url: conventions/ringover-conventions.yml - type: Authentication url: authentication/ringover-authentication.yml - type: Lifecycle url: lifecycle/ringover-lifecycle.yml - type: ErrorCatalog url: errors/ringover-problem-types.yml - type: Conformance url: conformance/ringover-conformance.yml - type: Overlay url: overlays/ringover-openapi-overlay.yaml - type: LLMsTxt url: llms/ringover-llms.txt - type: WellKnown url: well-known/ringover-well-known.yml - type: Hosts url: hosts/ringover-hosts.yml - type: Vendors url: vendors/ringover-vendors.yml - type: SDKs url: packages/ringover-packages.yml - type: Packages url: packages/ringover-packages.yml - type: Webhooks url: https://www.ringover.com/webhooks - type: Security url: https://www.ringover.com/security - type: APIReference url: https://developer.ringover.com/ - type: GitHubOrganization url: https://github.com/ringover - type: DomainSecurity url: security/ringover-domain-security.yml - type: Website url: https://ringover.com/ - type: Documentation url: https://www.ringover.com/features - type: Support url: https://www.ringover.com/contact - type: Blog url: https://www.ringover.com/news - type: Pricing url: https://www.ringover.com/pricing - type: SignUp url: https://www.ringover.com/free-trial - type: TermsOfService url: https://www.ringover.com/terms - type: PrivacyPolicy url: https://www.ringover.com/privacy - type: StatusPage url: https://www.ringover.com/status apis: - aid: ringover:ringover-blacklist-api name: Ringover Blacklist API description: >- Manage blacklisted phone numbers. There are two levels of blacklist: - **Team blacklist** (`/blacklists/numbers`): Blocks numbers for the entire team. Requires `Numbers R/W` + Monitoring ON. - **User blacklist** (`/users/{userId}/blacklists/numbers`): Blocks numbers for a specific user. Requires `Users R/W`. **Monitoring impact:** - *OFF*: Team blacklist routes are **blocked** (`401`). User blacklist routes work only for your own blacklist. - *ON*: Full team blacklist management. User blacklist routes can target any team member. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - blacklist properties: - type: OpenAPI url: openapi/ringover-blacklist-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-callbacks-api name: Ringover Callbacks API description: >- Initiate phone calls between a Ringover user and an external recipient. The system calls the user first on their chosen device, then connects them to the recipient. **Permissions required:** `Calls Write` required. **Monitoring impact:** - *OFF*: You can only initiate a callback from your own number. - *ON*: You can initiate a callback from any team member's number using the `from_number` parameter. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - callbacks properties: - type: OpenAPI url: openapi/ringover-callbacks-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-calls-api name: Ringover Calls API description: >- Manage your Ringover call history. Retrieve terminated and current calls, apply filters (by date, type, tags, users, IVRs…), archive calls, and access survey results. **Permissions required:** - **Read** (`Calls R`): List and retrieve calls, get current calls, get survey answers. - **Write** (`Calls W`): Archive calls, initiate callbacks, control live calls (mute, hold, transfer, hangup, record, DTMF). **Monitoring impact — Read operations (listing):** > **Important:** Call listing routes (`GET /calls`, `POST /calls`, `GET /calls/{callId}`) always return **all team calls** regardless of the Monitoring flag. The Monitoring setting is not applied to call listing — these routes behave identically whether Monitoring is ON or OFF. **Monitoring impact — Write operations:** - *OFF*: Archive operations apply only to **your own calls**. Live call controls (`/channels/*/events/*`) and call recording access are **blocked** (`401`). - *ON*: Archive operations can target **any team call**. Live call controls and call recording access are unlocked. **Limitations:** - Date range is limited to **15 days** maximum per request. - `limit_count` maximum is **1000**, `limit_offset` maximum is **9000**. - Multiple items in the call list may share the same `call_id` (occurs with transfers or IVR routing). **Summary and transcription:** `summary` is the Ringover summary stored for the call (plain text). `transcription` is the call transcription (speeches and words). These are not Empower recaps. Download URLs are never returned. A field is in one of three states: - **omitted** — not requested - **`null`** — requested, and the call has no summary or transcription row - **object** — the row exists. If the file cannot be downloaded, the HTTP status stays `200` and the object sets `error.code` (`unavailable` when the download fails, `error` or `invalid` when the provider status is not usable). `summary.text` is then `null`. Where they are included: - `GET /calls` and `POST /calls` — only when the query parameter `expand` is `summary` and/or `transcription`. Repeat it to ask for both (`expand=summary&expand=transcription`). Each value downloads a file and adds latency. `contact` is always returned and is not an `expand` value. - `GET /calls/{callId}` — `summary`, `transcription` and `contact` are included on every log. There is no `expand` parameter. - MCP `calls.search` and `calls.get` — only the values passed in `expand` (`summary`, `transcription`, `contact`). Nothing is included by default, including `contact`. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - calls properties: - type: OpenAPI url: openapi/ringover-calls-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-campaigns-api name: Ringover Campaigns API description: >- Manage your outbound call campaigns (Call Lists). This section provides a comprehensive overview of how to manage your campaign workflows: - Retrieve the list of campaigns, filterable by various parameters. - Assign Ringover users to specific campaigns. - Add or manage contacts associated with a campaign. - Start, stop, or reset campaigns dynamically. - Update campaign scripts to ensure consistent messaging. - Adjust the number of allowed call retries for specific campaigns. - Modify tags assigned to campaigns to enhance your tracking. - Manage numbers associated with campaigns, including: adding, updating, or removing them. - Extend the capabilities of your campaigns by adding custom columns (enriched data). **Permissions:** No specific permission required. A valid API key is sufficient to access all campaign routes. **Monitoring impact:** None. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - campaigns properties: - type: OpenAPI url: openapi/ringover-campaigns-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-cdn-api name: Ringover Cdn API description: >- Private CDN URLs (`transcription_url`, `recap_url`, `audio_url`, `video_url`, and other Ringover CDN download links) cannot be opened with a public API token. Use `POST /cdn/download` to proxy the file. Any authenticated token can call this route: the team id in the URL must match the token's team. Empower READ is not required. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - cdn properties: - type: OpenAPI url: openapi/ringover-cdn-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-channels-api name: Ringover Channels API description: >- Control live calls in real time. A channel represents an audio stream during a call. You can mute, hold, record, hangup, transfer, or send DTMF tones on active channels. **Permissions required:** `Calls Write` required for all channel operations. **Monitoring:** **Required** for all channel control routes. Returns `401` if Monitoring is OFF. Live call control is a supervisory feature. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - channels properties: - type: OpenAPI url: openapi/ringover-channels-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-conferences-api name: Ringover Conferences API description: >- Manage conference rooms. List conferences and update access PIN codes. **Permissions required:** No specific permission category, but **Monitoring must be ON** for all conference routes. Returns `401` if Monitoring is OFF. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - conferences properties: - type: OpenAPI url: openapi/ringover-conferences-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-contacts-api name: Ringover Contacts API description: >- Manage your Ringover contacts. Full CRUD operations on contacts and their phone numbers. **Permissions required:** - **Read** (`Contacts R`): List and get contacts. - **Write** (`Contacts W`): Create, update, delete contacts and their numbers, toggle sharing. **Monitoring impact:** None — contacts are always scoped to your own address book regardless of the Monitoring flag. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - contacts properties: - type: OpenAPI url: openapi/ringover-contacts-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-conversations-api name: Ringover Conversations API description: >- Manage SMS and Chat conversations. List conversations and their messages, archive/unarchive, rename, and manage conversation metadata. **Permissions required:** - **Read** (`Conversations R`): List conversations and messages. - **Write** (`Conversations W`): Archive/unarchive, rename, set purpose, send SMS. **Monitoring impact:** - *OFF*: Returns only **your own** conversations and non-archived messages. - *ON*: Returns **all team** conversations including archived messages. Enables level-2 archiving (permanent) and sending SMS on behalf of another user. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - conversations properties: - type: OpenAPI url: openapi/ringover-conversations-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-empower-api name: Ringover Empower API description: >- Access Ringover [Empower](https://www.ringover.com/sales-enablement-tool) AI features: call transcriptions, AI-generated summaries, key moments detection, mood analysis, and analytics. CDN URLs on a call (`transcription_url`, `recap_url`, `audio_url`, `video_url`) cannot be opened with a public API token. Download those files with `POST /cdn/download`. **Permissions required:** - **Read** (`Empower R`): Access call data, summaries, moments, analytics, flags, chat with AI. - **Write** (`Empower W`): Manage call tags, delete calls/media, manage flags. **Monitoring impact:** None — visibility is controlled by your **Empower role**: - *Empower Admin*: See all team calls. - *Empower Supervisor*: See calls from supervised users. - *Standard User*: See only your own calls. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - empower properties: - type: OpenAPI url: openapi/ringover-empower-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-groups-api name: Ringover Groups API description: >- Manage your Ringover groups. Groups organize users for call distribution (ring groups). You can list groups, manage members, configure ring duration, and toggle free access. **Permissions required:** - No specific permission is required to **list** groups. - `Users Write` is required to **add or remove** members. **Monitoring impact:** - *OFF*: Returns only groups you belong to. - *ON*: Returns all team groups. Unlocks group membership management, ring duration changes, and free-access toggling. > Some group management routes **require** Monitoring ON and will return `401` without it. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - groups properties: - type: OpenAPI url: openapi/ringover-groups-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-ivrs-api name: Ringover Ivrs API description: >- Retrieve your IVRs (Interactive Voice Response) and their scenarios. IVRs are the automated call routing systems configured on your Ringover account. **Permissions required:** - **Read** (`IVRs R`): List IVRs and scenarios. - **Write** (`IVRs W`): Create tags. **Monitoring impact:** - *OFF*: Returns only **your own** IVRs and scenarios. - *ON*: Returns **all team** IVRs and scenarios. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - ivrs properties: - type: OpenAPI url: openapi/ringover-ivrs-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-mcp-api name: Ringover MCP API description: >- ## Model Context Protocol The MCP endpoint exposes a **curated** set of Ringover operations to AI assistants (Claude, ChatGPT, Cursor, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io/). It is not a 1:1 copy of the REST API: tools that are hard for an agent to fill, rarely useful, or unsafe are omitted, and related mutations are grouped (for example `calls.archive`, `channels.control`, `users.update`). Source of truth for names, argument schemas and titles is `tools/list`. This page lists the frozen catalogue. ### Useful links - [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest) - [Lifecycle & initialization](https://modelcontextprotocol.io/specification/latest/basic/lifecycle) - [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) - [Streamable HTTP transport](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http) ### How it works MCP is JSON-RPC 2.0 over HTTP using the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http). All interactions use `POST /mcp` with a JSON-RPC body. The server is **stateless** — every request is independent. There is no session (`Mcp-Session-Id` is not used) and no `notifications/tools/list_changed`. ### Request headers Every `POST` must send: - `Content-Type: application/json` - `Accept: application/json, text/event-stream` — **both** media types are required (comma-separated, as MCP clients do). A request that omits `text/event-stream` is rejected with HTTP `400`. ### Response format Successful MCP calls return HTTP `200` with `Content-Type: application/json` and a **single JSON-RPC object** in the body. There is no SSE stream: the endpoint is stateless (one request, one response, no shared connection across tool calls), so Server-Sent Events would not add multiplexing here. ### JSON-RPC errors vs HTTP errors - **Supported methods** (`initialize`, `tools/list`, `tools/call`): invalid tool arguments, tool rate limits, and application failures on `tools/call` are returned with HTTP `200` (JSON-RPC `error` or a tool result with `isError: true`). - **HTTP transport rejections** (before the message is handled as MCP): invalid `Accept`, malformed JSON-RPC, unsupported method **name** (anything other than the three methods above), etc. → HTTP **`400`** with a **plain-text** body, not a JSON-RPC envelope. Example: `JSON RPC not handled: "monitor/unknown_method" unsupported`. - Missing or invalid credential → **`401`**. HTTP rate limit → **`429`**. ### Available JSON-RPC methods | Method | Purpose | |--------|---------| | `initialize` | Capability negotiation. Returns server info (`name: "ringover-public-api"`, `version: "v1.0.0"`) and capabilities. Optional — you can call `tools/list` or `tools/call` directly. | | `tools/list` | Returns the tools **this credential can use**, with `name`, `title`, `description`, `inputSchema` and `annotations`. | | `tools/call` | Execute a tool by `name` with `arguments`. | `tools/list` never returns a tool the caller cannot invoke. A write tool is listed only when the credential has the matching **write** grant. Calling a hidden name is refused (`forbidden`). ### Authentication The MCP endpoint accepts the same credentials as the rest of public-api: - a **Public API key** (raw, no `Bearer` prefix) - an **OAuth 2.0 access token** (`Authorization: Bearer `), when OAuth is enabled for the environment For API keys, three sources are tried in this **order** (first one set wins): | # | Source | Endpoint | Example | When to use | |---|--------|----------|---------|-------------| | 1 | URL path parameter | `POST /mcp/{token}` | `POST /mcp/abcd1234…` | Last resort for clients that cannot set headers or query strings. | | 2 | Query string `?token=` | `POST /mcp?token=…` | `POST /mcp?token=abcd1234…` | No-code / web tools that cannot set custom headers. | | 3 | `Authorization` header | `POST /mcp` | `Authorization: abcd1234…` | **Recommended** — same as REST. | The token is then normalized internally, so rate limiting, logging and permission checks behave the same regardless of source. > ⚠️ **Security note** — Tokens in the URL path or query string often appear in proxy logs, browser history and access logs. Prefer the `Authorization` header. If a token may have been exposed in a URL, **rotate it** from the Ringover Dashboard. ### Identifiers and JSON - MCP identifiers are **core IDs**. Do not apply the REST public offset (`+10000`). - Tool results use **snake_case** keys (`user_id`, `campaign_uuid`, `webhook_id`). - Write acknowledgements typically return `{"success": true}`. - `users.update`, `campaigns.update` and `conversations.update` may apply several upstream mutations in sequence. Validation runs first; an upstream error can still leave earlier fields updated. ### Cursor ```json { "mcpServers": { "ringover-public-api": { "url": "https://public-api.ringover.com/mcp", "headers": { "Authorization": "" } } } } ``` Use the US host `https://public-api-us.ringover.com/mcp` for US workspaces. ### Quick start Using the standard `Authorization` header (recommended): ``` POST /mcp Authorization: your-api-key-here Content-Type: application/json Accept: application/json, text/event-stream {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` Same call using the query string variant: ``` POST /mcp?token=your-api-key-here Content-Type: application/json Accept: application/json, text/event-stream {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` Same call using the URL path variant: ``` POST /mcp/your-api-key-here Content-Type: application/json Accept: application/json, text/event-stream {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` Example response: ```json {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}} ``` ### Rate limiting The MCP endpoint has its own rate limiting, separate from the REST API: - **HTTP rate limit** (per API key): 1 request/second with a burst of 10. Returns HTTP `429` when exceeded. - **Tool rate limit** (per team + tool name): ~1 call every 3 seconds with a burst of 5. Returns a JSON-RPC error in the response body (HTTP status remains `200`). ### Request timeout Each request has a **30-second timeout**. If a tool call exceeds this duration, the request is cancelled and an error is returned. ### Error handling Transport errors use HTTP status codes. Application errors on `tools/call` use a tool result with `isError: true` (HTTP still `200`): | Situation | Response | |-----------|----------| | Missing or invalid API key | HTTP `401` | | HTTP rate limit exceeded | HTTP `429` | | Tool rate limit exceeded | HTTP `200` + JSON-RPC error: `"rate limit exceeded for tool X"` | | Insufficient permission | HTTP `200` + tool result `isError`: `"forbidden"` | | Invalid arguments | HTTP `200` + tool result `isError` (validation message) | | Resource not found | HTTP `200` + tool result `isError` (for example `"user not found"`) | | Team feature not enabled (transcription) | HTTP `200` + JSON-RPC error: `"transcription feature not enabled for team"` | | Upstream / internal failure | HTTP `200` + tool result `isError` (generic message) | ### Permissions and Monitoring MCP tools follow the **same permission and Monitoring rules** as the matching REST operations. Read tools need the category **Read** grant; write tools need **Write**. `tools/list` already hides tools the token cannot use. The **Monitoring** flag still controls data **scope** (own data vs team), not which tools exist. `team.get` is visible to every authenticated caller. --- ## Available tools (111) Tool names follow `{resource}.{action}` (optional sub-resource: `campaigns.numbers.add`). `R` = read, `W` = write. ### Contacts **Permission:** Contacts. Monitoring does not widen the address book. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `contacts.search` | R | Search contacts by name, phone number, or company. | `query`, `limit` (0–500), `offset` | | `contacts.get` | R | Get a contact by core ID. | `contact_id` | | `contacts.create` | W | Create 1–50 contacts (numeric contract). | contacts payload | | `contacts.replace` | W | Replace a contact's full desired state. | `contact_id` + payload | | `contacts.delete` | W | Delete a contact. | `contact_id` | ### Calls and callbacks **Permission:** Calls. Call listing is team-wide regardless of Monitoring (same as REST). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `calls.search` | R | Search terminated calls. `summary`, `transcription` and `contact` are omitted unless `expand` asks for them. | `start_date`, `end_date`, `call_type`, `limit`, `offset`, `expand` | | `calls.get` | R | Get a terminated call. Unlike `GET /calls/{callId}`, summary, transcription and contact are omitted unless `expand` asks for them. | `call_id`, `expand` | | `calls.surveys.get` | R | Get post-call surveys. | `call_id` | | `calls.current.list` | R | List in-progress calls. | *(none / filters as advertised)* | | `calls.archive` | W | Archive a call, one channel, or logs. | `target` (`call` default, `channel`, `logs`), `call_id`, `channel_id`, `channel_ids`, `archive_cdr` | | `callbacks.create` | W | Create a callback. | user, destination number | | `callbacks.ivr.create` | W | Create a callback through an IVR. | IVR + destination | `expand` on `calls.search` and `calls.get` accepts `summary`, `transcription` and `contact`. Repeat values to combine them. The field states are the same as on REST (omitted, `null`, or object; a failed download stays a successful tool result and sets `error.code`). `contact` is included only when requested. Download URLs are not returned. ### Transcriptions **Permission:** Calls **and** the team transcription feature. Otherwise `"transcription feature not enabled for team"`. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `transcriptions.search` | R | List transcriptions, or semantic search when `query` is set. | `query`, `limit` (default 50), `offset`, `min_audio`, `max_audio` (`offset` / audio filters cannot be combined with `query`) | | `transcriptions.get` | R | Full transcript for a call. | `call_id` | ### Team **Permission:** none beyond a valid credential. Monitoring OFF returns a user-scoped view; ON returns the full team. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `team.get` | R | Team name, timezone, country, subscription. | *(none)* | ### Users, planning and snooze **Permission:** Users. Without Monitoring you only reach **your** user. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `users.list` | R | List team users. | *(none)* | | `users.get` | R | Get a user. | `user_id` | | `users.update` | W | Patch named identity fields. | `user_id` plus at least one of `email`, `first_name`, `last_name`, `job_title` | | `users.assign_profile` | W | Assign a permission profile. | `user_id`, `profile_id` | | `users.invite` | W | Invite users (per-item `created` / `failed`). | `users[]` (`email`, `number`, `plan_id`, names) | | `users.delete` | W | Delete or archive a user. | `user_id`, `type` (`DELETED` or `ARCHIVED`) | | `users.planning.get` | R | Weekly schedule. | `user_id` | | `users.planning.set` | W | Replace the weekly schedule. | `user_id`, slots | | `snoozes.list` | R | Available DND / snooze labels. | *(none)* | | `users.snooze.get_log` | R | Snooze history. | `user_id`, `limit`, `offset` | | `users.snooze.set` | W | Set or clear do-not-disturb. | `user_id`, label / duration | ### Groups **Permission:** Users. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `groups.list` | R | List ring groups. | *(none)* | | `groups.get` | R | Group with **all** members (not paginated). | `group_id` | | `groups.create` | W | Create a ring group. | name / members as advertised | | `groups.delete` | W | Delete a ring group. | `group_id` | | `groups.users.add` | W | Add members. | `group_id`, user IDs | | `groups.users.remove` | W | Remove members. | `group_id`, user IDs | ### Profiles **Permission:** Users. Profiles are team-wide. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `profiles.list` | R | List permission profiles. | *(none)* | | `profiles.get` | R | Get a profile. | `profile_id` | ### Numbers **Permission:** Numbers. Monitoring OFF returns numbers assigned to you. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `numbers.list` | R | List team numbers. | *(none)* | | `numbers.get` | R | Get a number. | `number` | | `numbers.reassign` | W | Reassign to a user, IVR or conference. | `number`, target | ### IVRs **Permission:** IVRs. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `ivrs.list` | R | List IVRs. | *(none)* | | `ivrs.get` | R | Get an IVR. | `ivr_id` | | `ivrs.scenarios.list` | R | Scenarios of one IVR. | `ivr_id` | | `ivrs.scenarios.get` | R | One scenario. | `ivr_id`, `scenario_id` | ### Conferences **Permission:** Calls (Monitoring typically required, same as REST). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `conferences.list` | R | List conference rooms. | *(none)* | | `conferences.get` | R | Get a conference. | `conf_id` | | `conferences.pincode.update` | W | Change the PIN. | conference id, pin | ### Tags **Permission:** Tags (API keys often include this with IVR-related grants). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `tags.list` | R | List tags. | *(none)* | | `tags.get` | R | Get a tag. | `tag_id` | | `tags.create` | W | Create a tag. | `name`, `color` | ### Presences **Mixed:** team presence typically requires Monitoring ON; user presence follows Users + Monitoring. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `presences.team.get` | R | Presence of all members. | *(none)* | | `presences.user.get` | R | Presence of one user. | `user_id` | ### Blacklist **Team list:** Numbers + Monitoring ON. **User list:** Users (own user without Monitoring). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `blacklist.team.list` | R | Team-blocked numbers. | `limit`, `offset` | | `blacklist.team.check` | R | Is this number blocked for the team? | `number` | | `blacklist.team.add` | W | Block for the team. | `number` | | `blacklist.team.delete` | W | Unblock for the team. | `number` | | `blacklist.user.list` | R | User blacklist. | `user_id`, `limit`, `offset` | | `blacklist.user.check` | R | Is this number blocked for a user? | `user_id`, `number` | | `blacklist.user.add` | W | Block for a user. | `user_id`, `number` | | `blacklist.user.delete` | W | Unblock for a user. | `user_id`, `number` | ### Channels (live call) **Permission:** Conversations write (same resource as live channel REST). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `channels.control` | W | Toggle mute, hold or recording, or hang up. | `channel_id`, `action` (`mute`, `hold`, `recording`, `hangup`) | | `channels.transfer` | W | Transfer to a number. | `channel_id`, `phone_number` | | `channels.dtmf.send` | W | Send one DTMF digit. | `channel_id`, `dtmf` (`0-9`, `#`, `*`) | ### Conversations and messages **Permission:** Conversations. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `conversations.list` | R | List SMS/chat conversations. | pagination / filters as advertised | | `conversations.get` | R | Get a conversation. | `conversation_id` | | `conversations.members.list` | R | List members. | `conversation_id` | | `conversations.messages.list` | R | List messages. | `conversation_id` | | `conversations.archive` | W | Archive (level 1). | `conversation_id` | | `conversations.unarchive` | W | Restore. | `conversation_id` | | `conversations.update` | W | Rename and/or set purpose. | `conversation_id`, `name` and/or `purpose` | | `conversations.messages.archive` | W | Archive a message. | conversation + message IDs | | `conversations.messages.unarchive` | W | Restore a message. | conversation + message IDs | ### SMS **Permission:** Conversations write. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `sms.send` | W | Send or schedule SMS. `mode=alphanumeric` uses the v1 sender contract. | `mode` (`standard` default, `alphanumeric`), `from_number` / `from_alphanum`, `to_number`, `content`, `user_id`, `user_id_forced`, `scheduled_at` | | `sms.opt_out.add` | W | Add a number to the team opt-out list. | `phone_number` | | `sms.opt_out.remove` | W | Remove a number from the opt-out list. | `phone_number` | ### WhatsApp **Permission:** Conversations. A valid key is enough on REST for some WhatsApp routes; MCP still lists only tools the credential can call. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `whatsapp.accounts.list` | R | List WhatsApp accounts. | *(none)* | | `whatsapp.templates.list` | R | List templates. | account as advertised | | `whatsapp.conversations.list` | R | List WhatsApp conversations. | filters as advertised | | `whatsapp.templates.send` | W | Send a template to a number. | template + destination | | `whatsapp.messages.send` | W | Send a message in a conversation. | conversation + body | ### Campaigns **Permission:** Campaigns (often granted on API keys by default). `campaigns.list` with `assigned_to_me=true` lists campaigns assigned to the caller; `ascending_order` and `is_running` cannot be combined with that flag. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `campaigns.list` | R | List calling campaigns. | `limit`, `offset`, `ascending_order`, `is_running`, `assigned_to_me` | | `campaigns.get` | R | Get a campaign. | `campaign_uuid` | | `campaigns.numbers.list` | R | Numbers in the campaign. | `campaign_uuid`, pagination | | `campaigns.groups.list` | R | Attached groups. | `campaign_uuid`, pagination | | `campaigns.users.list` | R | Attached users. | `campaign_uuid`, pagination | | `campaigns.logs.list` | R | Campaign logs. | `campaign_uuid` | | `campaigns.create` | W | Create a campaign. | `name`, `max_retry`, optional tags / IVR / dates | | `campaigns.start` | W | Start or schedule. | `campaign_uuid`, optional `start_date` | | `campaigns.stop` | W | Stop. | `campaign_uuid` | | `campaigns.reset` | W | Reset. | `campaign_uuid` | | `campaigns.update` | W | Patch name, retries, start date and/or script. Empty `script_uuid` unlinks the script. | `campaign_uuid` plus at least one of `name`, `max_retry`, `start_date`, `script_uuid` | | `campaigns.numbers.add` | W | Add numbers. | `campaign_uuid`, `to_numbers` | | `campaigns.numbers.delete` | W | Remove numbers. | `campaign_uuid`, `to_numbers` | | `campaigns.groups.add` | W | Attach groups. | `campaign_uuid`, `ids` | | `campaigns.groups.remove` | W | Detach groups. | `campaign_uuid`, `ids` | | `campaigns.users.add` | W | Attach users. | `campaign_uuid`, `ids` | | `campaigns.users.remove` | W | Detach users. | `campaign_uuid`, `ids` | | `campaigns.tags.add` | W | Add one tag without dropping existing tags. | `campaign_uuid`, `tag_id` | | `campaigns.tags.remove` | W | Remove one tag. | `campaign_uuid`, `tag_id` | CSV column editing is **not** exposed on MCP. ### Empower and tasks **Permission:** Empower. Visibility also follows Empower roles (admin / supervisor / user). | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `empower.calls.list` | R | Search analysed calls. | filters as advertised | | `empower.calls.get` | R | Get an analysed call. | call UUID | | `empower.calls.get_moments` | R | Call moments. | call UUID | | `empower.calls.get_summary` | R | Call summary. | call UUID | | `empower.flags.list` | R | List flags. | *(none)* | | `empower.calls.delete` | W | Delete calls or only their media. | call UUIDs / media flag | | `empower.flags.associate` | W | Attach a flag. | call + flag | | `empower.flags.disassociate` | W | Detach a flag. | call + flag | | `tasks.list` | R | List team tasks. | filters as advertised | | `tasks.create` | W | Create a batch of tasks. | task payload | ### Webhooks **Permission:** webhooks / integrations (`webhooks:manage` on OAuth). There is no separate read-only webhook scope: list/get appear with the same grant as mutations. | Tool | Access | Description | Main parameters | |------|--------|-------------|-----------------| | `webhooks.list` | R | List subscriptions with stable `webhook_id`. | *(none)* | | `webhooks.get` | R | Get one subscription. | `webhook_id` | | `webhooks.create` | W | Create or merge by target URL. | `target_url`, `events` | | `webhooks.events.add` | W | Union extra events onto a subscription. | `webhook_id`, `events` | | `webhooks.delete` | W | Delete a subscription. | `webhook_id` | Event names: `call.started`, `call.answered`, `call.ended`, `call.missed`, `call.voicemail`, `call.aftercall`, `sms.sent`, `sms.received`, `sms.delivery_receipt`, `fax.received`, `contact.call`, `contact.search`. `contact.call` and `contact.search` accept a single target URL each: attaching one to a second URL fails and nothing is saved. Their keys are returned in `event_signing_keys`. Replacing the whole event set is REST-only (`PUT`). humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - mcp properties: - type: OpenAPI url: openapi/ringover-mcp-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-messages-api name: Ringover Messages API description: >- Manage messages within conversations. List messages, archive and unarchive individual messages. **Permissions required:** - **Read** (`Conversations R`): List messages in a conversation. - **Write** (`Conversations W`): Archive/unarchive messages. **Monitoring impact:** - *OFF*: Returns non-archived messages from your own conversations. - *ON*: Returns all messages including archived ones. Enables level-2 archiving (permanent) for messages — requires Monitoring ON. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - messages properties: - type: OpenAPI url: openapi/ringover-messages-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-numbers-api name: Ringover Numbers API description: >- Retrieve information about phone numbers assigned to your Ringover account. **Permissions required:** - **Read** (`Numbers R`): List and get number details. - **Write** (`Numbers W`): Manage team blacklist. **Monitoring impact:** - *OFF*: Returns only **your assigned numbers**. Filter parameters are ignored. Team blacklist routes are blocked (`401`). - *ON*: Returns **all team numbers** with full filtering support (`is_ivr`, `is_user`, `is_conference`, `is_fax`, `is_available`). Team blacklist management is available. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - numbers properties: - type: OpenAPI url: openapi/ringover-numbers-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-presences-api name: Ringover Presences API description: >- Retrieve real-time presence information about users: planning status, snooze status, connected device, and whether they are currently in a call. **Permissions required:** - `Users Read` for individual user presence (`GET /users/{userId}/presences`). - No specific permission for team-wide presences (`GET /presences`), but **Monitoring must be ON**. **Monitoring impact:** - *OFF*: You can only retrieve **your own** presence. Team-wide presences route returns `401`. - *ON*: You can retrieve **any user's** presence and the team-wide presences endpoint is available. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - presences properties: - type: OpenAPI url: openapi/ringover-presences-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-profiles-api name: Ringover Profiles API description: >- Retrieve user profiles defined on your Ringover account. Each profile has an ID and a name. **Permissions required:** `Users Read` required. **Monitoring impact:** None — profiles are team-wide and always fully returned. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - profiles properties: - type: OpenAPI url: openapi/ringover-profiles-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-scim-api name: Ringover SCIM API description: >- Ringover exposes a **SCIM 2.0** server (RFC 7643 / RFC 7644) so your identity provider (Okta, Microsoft Entra ID, OneLogin, …) can automatically provision, update and deprovision Ringover users and groups. ### Base URL | Region | SCIM Base URL | |--------|---------------| | Europe | `https://public-api.ringover.com/v2/scim/v2` | | US | `https://public-api-us.ringover.com/v2/scim/v2` | ### Authentication SCIM uses the **same API key** as the REST API, passed **raw** in the `Authorization` header (no `Bearer ` prefix). Unauthenticated requests receive a `401` carrying a `WWW-Authenticate: Bearer` challenge. ``` Authorization: ``` ### Content type Request and response bodies use the SCIM media type `application/scim+json`. `application/json` is also accepted on input. ### Permissions & Monitoring | Operation | Permission required | |-----------|---------------------| | Read (Get, List, `.search`) | `Users Read` | | Write (Create, Replace, Patch, Delete) | `Users Write` | Because SCIM operates on the **whole team** (an IdP manages every user), the API key must have **Monitoring ON**. Without it, listings are restricted to your own data and most provisioning operations are refused. ### Integration steps Follow these steps to connect a user manager — an identity provider such as Okta / Microsoft Entra ID, or a custom provisioning system — to Ringover: 1. **Create an API key** in the Ringover Dashboard (**Developer > API Keys**) with **Users Read + Write** and **Monitoring ON**. This single key authenticates every SCIM request. 2. **Point your SCIM connector** at the base URL `https://public-api.ringover.com/v2/scim/v2`. For the credentials, use an **HTTP Header Token** auth type and paste the API key **raw** as the token — it must reach Ringover as `Authorization: `, without a `Bearer ` prefix. 3. **Verify connectivity** by calling `GET /ServiceProviderConfig` — it returns the supported features and confirms authentication. Most IdPs expose this as a "Test connection" button. 4. **Map attributes**: at minimum, map your directory's login / UPN to `userName` **as an email address** (a valid email is mandatory to provision). Optionally map `name`, `title` and group membership. To assign a Ringover profile, map `roles` and send the **numeric profile id** (discover it via `GET /profiles`) as `roles[].value`. 5. **Provision** users with `POST /Users` and groups with `POST /Groups`; store the returned `id` to address the resource later. 6. **Push updates** with `PATCH /Users/{id}` (or `PUT`), and **deprovision** by sending `active: false` via `PATCH` (or `DELETE /Users/{id}`) — in Ringover this **deletes** the user. 7. **Reconcile** by `userName` (or `id`) — not by `externalId` (see limitations). The **end-to-end example** below walks through the full lifecycle as raw HTTP calls. ### Resources | Resource | Endpoint | Description | |----------|----------|-------------| | User | `/Users` | Ringover team members | | Group | `/Groups` | Ring groups | Discovery endpoints (`/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`) describe the server's capabilities. ### User attribute mapping | SCIM attribute | Ringover field | Notes | |----------------|----------------|-------| | `id` | user id | Raw Ringover user id (string). | | `userName` | email / login | Required. Used as the unique identifier. | | `name.givenName` / `name.familyName` | firstname / lastname | Writable. | | `displayName` | — | **Read-only**, derived from the name. A value sent by the client is ignored. | | `title` | job title | Writable. | | `emails` | account email | **Immutable** after onboarding. The primary email is the account identifier. | | `roles` | Ringover profile | Single profile. On input, `roles[].value` **must be the numeric profile id** (discover it via `GET /profiles`). On output, `value` is the id and `display` the profile name. | | `active` | lifecycle | `false` deprovisions (deletes) the user; `true` (or absent) is a no-op. | | `externalId` | — | **Not persisted.** Echoed in the create response only; never returned on reads. | ### Group attribute mapping | SCIM attribute | Ringover field | Notes | |----------------|----------------|-------| | `id` | group id | Raw Ringover group id (string). | | `displayName` | group name | Set at creation. **Rename is not supported** and is ignored on update. | | `members` | group users | `members[].value` is a user id. | ### Querying: filter, sort, pagination, projection - **Filter** (`filter`): a single comparison `attribute op "value"`, with `op` one of `eq`, `sw` (starts-with), `ew` (ends-with), `co` (contains). Filterable attributes: Users `userName`, `externalId`, `emails`; Groups `displayName`, `externalId`. Any other operator returns `400 invalidFilter`. - **Sort** (`sortBy`, `sortOrder`): case-insensitive, default ascending. An unsupported `sortBy` is ignored. - **Pagination** (`startIndex` 1-based, `count`): `count` is capped at **100** per page. - **Projection** (`attributes` / `excludedAttributes`): comma-separated, **top-level attributes only**; `schemas`, `id` and `meta` are always returned. ### PATCH `PATCH` follows RFC 7644 §3.5.2 with `add` / `remove` / `replace` operations. On groups, membership operations are reconciled into a single upstream update. ### End-to-end example (provisioning from a user manager) A typical provisioning lifecycle, shown as raw HTTP calls (replace `$TOKEN` with your API key). All requests target the EU base URL `https://public-api.ringover.com/v2/scim/v2`. **1. Verify the connection** ```bash curl -s https://public-api.ringover.com/v2/scim/v2/ServiceProviderConfig \ -H "Authorization: $TOKEN" ``` **2. Create a user** — this is a real onboarding: it sends an invitation and consumes a license and a phone number. ```bash curl -s -X POST https://public-api.ringover.com/v2/scim/v2/Users \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "ada@example.com", "name": { "givenName": "Ada", "familyName": "Lovelace" }, "emails": [{ "value": "ada@example.com", "primary": true }], "active": true }' ``` Response (`201 Created`) — store the `id` for the next calls: ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "42", "userName": "ada@example.com", "active": true, "meta": { "resourceType": "User", "location": "/scim/v2/Users/42" } } ``` **3. Assign a role (Ringover profile)** — profile ids are discovered via the REST `GET /profiles` endpoint, then passed as `roles[].value`: ```bash # a) discover profile ids (REST API) curl -s https://public-api.ringover.com/v2/profiles -H "Authorization: $TOKEN" # b) assign profile id 12 to the user curl -s -X PATCH https://public-api.ringover.com/v2/scim/v2/Users/42 \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace", "path": "roles", "value": [{ "value": "12", "primary": true }] } ] }' ``` **4. Create a group and add the user as a member** ```bash curl -s -X POST https://public-api.ringover.com/v2/scim/v2/Groups \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Support", "members": [{ "value": "42" }] }' ``` **5. Update the user** (e.g. change the first name) ```bash curl -s -X PATCH https://public-api.ringover.com/v2/scim/v2/Users/42 \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace", "path": "name.givenName", "value": "Augusta" } ] }' ``` **6. Deprovision the user** — set `active: false` (soft delete) or issue a `DELETE`: ```bash curl -s -X PATCH https://public-api.ringover.com/v2/scim/v2/Users/42 \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace", "path": "active", "value": false }] }' ``` > Reconcile users by `userName` or `id`; `externalId` is not returned on reads, so do not rely on it for matching. ### Behavior & limitations - **Provisioning is a real onboarding operation.** Creating a user sends an invitation and consumes a **license and a phone number** from your team. A valid email is required: provide a primary `emails` value or an email-formatted `userName`, otherwise the request is rejected with `400 invalidValue`. - **`emails` is immutable**: it cannot be changed, removed or replaced via `PUT`/`PATCH`. - **`displayName` is read-only** and derived from the name. - **Group rename is not supported**: `displayName` is fixed after creation; updates only reconcile members. - **`active: false` deletes the user** (soft delete — the only deprovisioning lever). **`active: true` is a no-op** and there is **no reactivation** via SCIM. - **`roles[].value` must be a numeric profile id.** A non-numeric value (e.g. a role name) is **silently ignored** (no error), leaving the user with no profile assigned. Discover profile ids via `GET /profiles`. - **`externalId` is not persisted**: it is returned only in the create response, never on reads. Consequently `filter=externalId eq "..."` never matches, and reconciliation by `externalId` does not work — reconcile by `userName` or `id`. - **Multi-attribute `PUT`/`PATCH` on a user is not atomic**: each field is applied upstream independently, so a later failure can leave earlier fields already changed. - **`meta.created` / `meta.lastModified` are currently omitted** (they will be populated once available upstream). - **`Bulk` and custom resource types are not supported.** humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - scim properties: - type: OpenAPI url: openapi/ringover-scim-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-sms-api name: Ringover Sms API description: >- Send SMS messages to phone numbers. Phone numbers must be in E.164 format. **Permissions required:** `Conversations Write` required. **Monitoring impact:** - *OFF*: You can send SMS from your own number only. - *ON*: You can send SMS on behalf of another team member using the `user_id_forced` parameter. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - sms properties: - type: OpenAPI url: openapi/ringover-sms-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-snoozes-api name: Ringover Snoozes API description: >- Retrieve the list of available snooze statuses and manage user snooze settings. Snooze temporarily changes a user's availability status. **Permissions required:** - No specific permission to list snooze labels. - `Users Write` to modify a user's snooze status. **Monitoring impact:** None — snooze label listing is team-wide. Setting a user's snooze status requires only `Users Write` and works regardless of the Monitoring flag. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - snoozes properties: - type: OpenAPI url: openapi/ringover-snoozes-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-surveys-api name: Ringover Surveys API description: >- Retrieve survey answers associated with calls. Surveys are customer satisfaction questionnaires triggered after calls. **Permissions required:** `Calls Read` required. **Monitoring impact:** None — survey results are retrieved by call ID at the team level, regardless of the Monitoring flag. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - surveys properties: - type: OpenAPI url: openapi/ringover-surveys-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-tags-api name: Ringover Tags API description: >- Manage call tags. Tags are labels you can assign to calls for categorization and reporting. Each tag has an ID, name, color, description, and creation date. **Permissions required:** - **Read** (`IVRs R`): List tags. - **Write** (`IVRs W`): Create new tags. **Monitoring impact:** None — tags are always team-wide. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - tags properties: - type: OpenAPI url: openapi/ringover-tags-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-task-api name: Ringover Task API description: >- Manage team tasks. Create, list, and manage tasks associated with your team. **Permissions:** No specific permission required. A valid API key is sufficient. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - task properties: - type: OpenAPI url: openapi/ringover-task-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-teams-api name: Ringover Teams API description: >- The team object is a model of your Ringover team. It contains a list of related objects: - `numbers` and related information such as their type, country and prefix according to the country, - `users` and related information such as their user ID, team ID as well as personal data such as their first name, last name and email, - `ivrs` and related information such as their ID and the `numbers` objects associated, - `conferences` and related information such as their ID, name and tags (optional). **Permissions required:** No specific permission required. A valid API key is sufficient. **Monitoring impact:** - *OFF*: Returns a limited team object scoped to your own user data (your numbers, your IVRs, etc.). - *ON*: Returns the full team object including all numbers, users, IVRs, conferences, tags and groups. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - teams properties: - type: OpenAPI url: openapi/ringover-teams-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-transcriptions-api name: Ringover Transcriptions API description: >- Retrieve call transcriptions. Access is controlled by a team-level setting — your team must have the transcription feature enabled. **Permissions required:** Transcription access is based on a team-level setting, not on the API key permissions. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - transcriptions properties: - type: OpenAPI url: openapi/ringover-transcriptions-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-users-api name: Ringover Users API description: >- Manage your Ringover team members. Retrieve user information, manage plannings, check availability (presences/snooze), and organize user blacklists. **Permissions required:** - **Read** (`Users R`): Get user details, plannings, presences, user blacklists. - **Write** (`Users W`): Modify plannings, manage group members, manage user blacklists, modify snooze status. **Monitoring impact:** - *OFF*: GET requests return **only your own** user data, planning, and presence. Group listing returns only groups you belong to. - *ON*: GET requests return **all team** users, plannings, and presences. You can modify **any user's** planning. > Some write operations (plannings, group membership) **require** Monitoring ON and will return `401` without it. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - users properties: - type: OpenAPI url: openapi/ringover-users-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-webhook-api name: Ringover Webhook API description: >- Ringover uses webhooks to notify you any time that an event associated with your team occurs (ex: a new voicemail, the reception of a new message, a missed call...). A webhook is a URL that we call with a parameter that contains all the data about the event. It will allow you to create a **webhook handler** on your server in order to trigger specific actions in response to the event. You can configure your **webhooks** in the developer section of your Ringover dashboard. ## Securing your webhooks Every **call event** is signed with your **webhook key** (shown on the webhook configuration page of the Ringover dashboard, where you also configure your endpoint). Two signature versions exist; verify whichever your team is configured for. The raw webhook key is **never** sent as-is in a header — comparing a header to the key is not a valid check. ### V1 — current default (JWT, `Authorization` deprecated) The event is sent as a **JWT signed with `HS512`**, using your webhook key as the HMAC secret. The signed content is the concatenation of the **webhook URL** and the **JSON payload** (the request body). The same JWT is sent in two headers: - `X-Ringover-Webhook-Signature` — use this one. - `Authorization` — kept for backward compatibility only and **deprecated** (it will be removed; do not rely on it for new integrations). To verify, use any JWT library: `verify(token, , { algorithms: ["HS512"] })`. The decoded JWT exposes the `url` (your configured endpoint) and `payload` (the event body: `resource`, `event`, `timestamp`, `data`, `attempt`) claims. ### V3 — recommended (HMAC-SHA256, fixed size) V3 is currently enabled **on request** and will become the default for newly activated webhooks. Unlike the V1 JWT (whose size grows with the payload — problematic for large events such as transcriptions), V3 keeps a fixed-size signature. The signature is `Base64( HMAC-SHA256( , messageToSign ) )`, where `messageToSign` is the concatenation, **in this exact order**, of: 1. the HTTP method (`POST`) 2. the webhook URL 3. the JSON payload (the request body) 4. the timestamp Headers: - `X-Ringover-Webhook-Signature-V3` — the Base64 signature. - `X-Ringover-Request-Signature-V3-Timestamp` — the timestamp used to build `messageToSign`. Example: ``` HTTP method: POST Webhook URL: https://api.example.com/webhooks/call JSON payload: {"event":"ringing","resource":"call","timestamp":1554823493.762305,"data":{...}} Timestamp: 1554823493 messageToSign: POSThttps://api.example.com/webhooks/call{"event":"ringing","resource":"call","timestamp":1554823493.762305,"data":{...}}1554823493 ``` To verify, recompute `Base64(HMAC-SHA256(webhook key, messageToSign))` and compare it to `X-Ringover-Webhook-Signature-V3` (use a constant-time comparison). You can also reject requests whose `X-Ringover-Request-Signature-V3-Timestamp` is too old to mitigate replay attacks. > Warning: The `ivr_id` in the response body of webhook routes is offset by 10000 for legacy reasons (e.g. an ivr_id 22000 in the dashboard will be returned as 12000). ## Managing your webhooks from the API Webhooks can be configured from the developer section of the Ringover dashboard, or programmatically through the `/webhooks` endpoints. Both act on the same configuration — the one attached to the user who owns the API key you authenticate with. A webhook is a **subscription**: one `target_url` plus the set of `events` delivered to it. - The `uuid` of a webhook is **derived from its `target_url`** — an RFC 4122 **v5** UUID in the URL namespace. The same URL always yields the same id, that id never changes for the lifetime of the subscription, and you can compute it yourself instead of storing it: `uuidv5(target_url, URL namespace)`. - `target_url` is **immutable**. To deliver the same events to a different URL, create a new webhook and delete the old one. - Creating a webhook on a `target_url` that is already subscribed **merges** the event sets instead of creating a duplicate. - The same event can be delivered to **several** target URLs, except `contact.call` and `contact.search`: each of them accepts a **single** target URL. A request that would attach one of them to a second URL is rejected with `409` and nothing from that request is saved. Remove the event from the current URL first. - `signing_key` is the key used to sign the call, message and fax deliveries (see *Securing your webhooks* above). It is read-only and shared by every subscription of your configuration. - `contact.call` and `contact.search` each have their own key, returned in `event_signing_keys` on the webhook that holds the event. The key is generated on the first subscription and kept when the event is removed, so re-subscribing later reuses it. ### Event catalog These are the events you can subscribe to. The payload delivered to your `target_url` is described in the **Webhooks** section at the end of this page — the last column tells you which one to expect. | Event | Delivered when | Payload | |---|---|---| | `call.started` | An incoming call starts ringing | *Call ringing event* (`resource: call`, `event: ringing`) | | `call.answered` | A call is answered | *Call answered event* (`event: answered`) | | `call.ended` | A call is hung up | *Call hangup event* (`event: hangup`) | | `call.missed` | An incoming call is missed | *Call missed event* (`event: missed`) | | `call.voicemail` | A new voicemail is left | *Call voicemail event* (`event: voicemail`) | | `call.aftercall` | After-call data becomes available for a call | Several payloads with `resource: aftercall`. See *After-call events* below | | `sms.sent` | A message is sent | *Message event* (`resource: sms`, `event: sent`) | | `sms.received` | A message is received | *Message event* (`resource: sms`, `event: received`) | | `sms.delivery_receipt` | The carrier reports the delivery status of a sent message | *SMS delivery receipt event* (`resource: sms`, `event: sms.delivery_receipt`) | | `fax.received` | A fax is received | Not documented in this reference yet | | `contact.call` | A call starts, so you can return notes about the contact to the agent | *Contact event*. The `x-ringover-webhook-signature` JWT is signed with `event_signing_keys["contact.call"]` | | `contact.search` | A user searches contacts in the Ringover app, so you can return matching contacts from your API | *Contact Search event*. The `Authorization` header equals `event_signing_keys["contact.search"]` | ### After-call events Subscribing to `call.aftercall` delivers several requests for the same call, as each piece of data becomes available. Every payload has `resource: aftercall`. The `event` field says which piece just arrived. | `event` | Delivered when | Payload | |---|---|---| | `voicemail_available` | The voicemail audio file is ready | *Voicemail available event* | | `record_available` | The call recording is ready | *Record available event* | | `transcription_available` | The transcription is ready | *Transcription available event* | | `summary_available` | The Ringover summary is ready | *Summary available event* | | `empower` | Empower after-call data is ready | *Empower event* | | `comments_updated` | The call comment changes | *Comment updated event* | | `tags_updated` | The call tags change | *Tag updated event* | `call.voicemail` (`resource: call`, `event: voicemail`) reports that a voicemail was left. `voicemail_available` follows once the audio file is ready. Public CDN links in these payloads are deprecated. `record_link`, `voicemail_link`, and `transcription_link` are v1 URLs: anyone who has the link can download the file. Retrieve the file from the private field on the same event: - `record_available` — `private_record_link` - `voicemail_available` — `private_voicemail_link` - `transcription_available` — `private_transcription_link` To download a `private_*_link`, request that URL with your public API key in the `Authorization` header. Do not add a `Bearer` prefix: `Authorization: your-api-key-here`. For Ringover users, the summary is sent through `summary_available`. For Empower users, the summary, the transcription, and the follow-up actions are sent together through `empower`. **Permissions:** No specific permission required. A valid API key is sufficient, both to receive events and to manage subscriptions through the `/webhooks` endpoints. **Monitoring impact:** None. Your webhook configuration is resolved from the API key itself, so the Monitoring flag does not change what you can read or write. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - webhook properties: - type: OpenAPI url: openapi/ringover-webhook-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json - aid: ringover:ringover-whatsapp-api name: Ringover WhatsApp API description: >- Manage WhatsApp Business messaging. Send template messages, manage templates, and handle WhatsApp conversations. **Permissions:** No specific permission required. A valid API key is sufficient. humanURL: https://developer.ringover.com/ baseURL: https://public-api.ringover.com/v2 tags: - whatsapp properties: - type: OpenAPI url: openapi/ringover-whatsapp-api-openapi.yml - type: JSONSchema url: json-schema/ringover-calls-filter-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-response-schema.json - type: JSONSchema url: json-schema/ringover-empower-logs-calls-request-schema.json - type: JSONSchema url: json-schema/ringover-call-empower-schema.json - type: JSONSchema url: json-schema/ringover-conversation-light-schema.json - type: JSONSchema url: json-schema/ringover-get-call-empower-res-body-schema.json x-submission-probe: 301 (-> https://www.ringover.com/) 2026-10-26 x-enrichment: date: '2026-10-28' status: enriched artifacts_added: 48 pass: modular-v1 engine: identity=oss,contract=oss,surfaces=oss,docs=oss,regulatory=oss