Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
license:
name: Proprietary – Contact us for usage terms
url: https://www.ringover.com/contact
description: '# Ringover Public API
Welcome to the Ringover Public API. This RESTful API lets you integrate Ringover telephony, messaging, contacts, and AI analytics into your applications. ## Base URL
| Region | Base URL |
|--------|----------|
| Europe | `https://public-api.ringover.com/v2` |
| United States | `https://public-api-us.ringover.com/v2` |
## Authentication
All requests must include your API key in the `Authorization` header:
```
Authorization: your-api-key-here
```
To create an API key:
1. Open the Ringover Dashboard. 2. Navigate to **Developer > API Keys**. 3. Click **Create an API key**, select a user, and set a label. 4. Configure the permissions for this key (see Permissions below). ## Permissions
Each API key is associated with **7 permission categories**, each configurable as **None**, **Read**, **Write**, or **Read+Write**:
| Category | Controls access to |
|----------|-------------------|
| **Calls** | Call history, archives, live call controls, callbacks |
| **Contacts** | Contact CRUD and phone number management |
| **Users** | User listing, plannings, presences, groups, user blacklists |
| **Numbers** | Phone number listing, team blacklist |
| **IVRs** | IVR/scenario listing, tag management |
| **Conversations** | SMS/Chat conversations, messages, SMS sending |
| **Empower** | AI call analysis, summaries, moments, analytics |
### The Monitoring flag (Supervision)
In addition to R/W permissions, each API key has a **Monitoring** toggle that controls the **scope** of data returned:
| Monitoring | Effect |
|------------|--------|
| **OFF** | Your permissions give access to **your own data only** (your calls, your numbers, your conversations…) |
| **ON** | Your permissions give access to **the entire team''s data** (all users, all calls, all conversations…) |
Monitoring does **not** grant additional permissions — it widens the scope of existing ones. Some routes **require** Monitoring to be enabled and will return `401` without it. Conversely, some routes may ignore the Monitoring flag entirely or apply it differently — unless stated otherwise in the endpoint documentation, the default behavior described above applies. > Each endpoint in this documentation specifies its exact permission and monitoring requirements. ### Special cases
- **Campaigns, Tasks, WhatsApp**: These routes do not require specific token permissions. A valid API key is sufficient. - **Empower**: Uses its own role system (Admin / Supervisor / User) in addition to the Empower R/W permission. - **Transcriptions**: Access is controlled by a team-level setting, not by the token permissions. - **Conferences**: All conference routes require Monitoring enabled. ## Rate Limiting
A **2-request-per-second** rate limit is applied per API key. Exceeding this limit returns `429 Too Many Requests`. ## Pagination
List endpoints support offset-based pagination with two parameters:
- `limit_count`: Maximum number of items to return (default: 100, max varies by endpoint). - `limit_offset`: Number of items to skip (default: 0). Some call-related endpoints also support cursor-based pagination via `last_id_returned`. ## Error Responses
| HTTP Code | Meaning |
|-----------|---------|
| `400` | Bad request — invalid parameters or body |
| `401` | Unauthorized — invalid/expired API key, or access denied by permission/monitoring checks on most endpoints |
| `403` | Forbidden — authenticated request refused by specific endpoint logic (notably some Empower routes) or upstream forwarded services |
| `402` | Payment required — feature not available on your plan |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
## SCIM 2.0 Provisioning
Ringover exposes a **SCIM 2.0** server (RFC 7643 / RFC 7644) for automated user and group provisioning from your identity provider (Okta, Microsoft Entra ID, …). It reuses the **same API key** as the REST API (`Authorization` header).'
version: 2.1.0
title: Ringover Public Channels API
x-logo:
url: https://webcdn.ringover.com/app/img/misc/logo_app_redoc.png
backgroundColor: '#FAFAFA'
altText: Ringover Logo
termsOfService: https://ringover.com/terms/
contact:
email: support@ringover.com
servers:
- url: https://public-api.ringover.com/v2
description: Production server (Europe)
- url: https://public-api-us.ringover.com/v2
description: Production server (United States)
security:
- Authorization: []
tags:
- name: Channels
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.'
paths:
/channels/{channelId}/events/mute/toggle:
post:
operationId: postChannelsChannelidEventsMuteToggle
tags:
- Channels
x-permissions:
required: Calls W
monitoring: required
summary: Toggle mute on a live call channel
description: 'Toggles the mute state on a live call channel. If the channel is currently unmuted, the participant will be muted (their audio is no longer transmitted to the other party). If already muted, they will be unmuted. This is a real-time telephony control — the effect is immediate and applies to the ongoing call.
The `channelId` identifies a specific participant''s leg in the call. Use `POST /calls/current` to discover active channel IDs.
**Permission:** `Calls Write` required.
**Monitoring:** **Required.** This is a live call supervisory control. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: channelId
in: path
description: The unique identifier of the call channel. Use `POST /calls/current` to discover active channel IDs.
required: true
schema:
type: string
responses:
'201':
description: Successfully processed — the mute toggle event has been applied to the channel.
'400':
description: Invalid channel ID format.
'401':
description: Unauthorized — missing or invalid token, or Monitoring is not enabled on your API key.
'404':
description: Channel not found — no active call channel matches the provided ID.
'500':
description: Internal server error.
'502':
description: Service temporarily unavailable — please retry later.
/channels/{channelId}/events/hold/toggle:
post:
operationId: postChannelsChannelidEventsHoldToggle
tags:
- Channels
x-permissions:
required: Calls W
monitoring: required
summary: Toggle hold on a live call channel
description: 'Toggles the hold state on a live call channel. If the channel is currently active, the participant will be placed on hold (they hear hold music, their audio is paused). If already on hold, the call is resumed. This is a real-time telephony control — the effect is immediate.
The `channelId` identifies a specific participant''s leg in the call. Use `POST /calls/current` to discover active channel IDs.
**Permission:** `Calls Write` required.
**Monitoring:** **Required.** This is a live call supervisory control. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: channelId
in: path
description: The unique identifier of the call channel. Use `POST /calls/current` to discover active channel IDs.
required: true
schema:
type: string
responses:
'201':
description: Successfully processed — the hold toggle event has been applied to the channel.
'400':
description: Invalid channel ID format.
'401':
description: Unauthorized — missing or invalid token, or Monitoring is not enabled on your API key.
'404':
description: Channel not found — no active call channel matches the provided ID.
'500':
description: Internal server error.
'502':
description: Service temporarily unavailable — please retry later.
/channels/{channelId}/events/record/toggle:
post:
operationId: postChannelsChannelidEventsRecordToggle
tags:
- Channels
x-permissions:
required: Calls W
monitoring: required
summary: Toggle recording on a live call channel
description: 'Toggles call recording on a live call channel. If the call is not being recorded, recording starts — the audio is captured and stored for later retrieval via `GET /calls/{callId}/channels/{channelId}`. If already recording, it stops. This is a real-time telephony control — the effect is immediate.
The `channelId` identifies a specific participant''s leg in the call. Use `POST /calls/current` to discover active channel IDs. Recording availability also depends on the team''s recording policy configuration.
**Permission:** `Calls Write` required.
**Monitoring:** **Required.** This is a live call supervisory control. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: channelId
in: path
description: The unique identifier of the call channel. Use `POST /calls/current` to discover active channel IDs.
required: true
schema:
type: string
responses:
'201':
description: Successfully processed — the recording toggle event has been applied to the channel.
'400':
description: Invalid channel ID format.
'401':
description: Unauthorized — missing or invalid token, or Monitoring is not enabled on your API key.
'404':
description: Channel not found — no active call channel matches the provided ID.
'500':
description: Internal server error.
'502':
description: Service temporarily unavailable — please retry later.
/channels/{channelId}/events/hangup:
post:
operationId: postChannelsChannelidEventsHangup
tags:
- Channels
x-permissions:
required: Calls W
monitoring: required
summary: Hang up a live call channel
description: 'Terminates (hangs up) a live call on the specified channel. The call is immediately disconnected for the participant identified by this channel. If the call has only two participants, the entire call ends. If the call involves multiple participants (e.g., conference or transfer), only the specified participant is disconnected.
The `channelId` identifies a specific participant''s leg in the call. Use `POST /calls/current` to discover active channel IDs.
**Permission:** `Calls Write` required.
**Monitoring:** **Required.** This is a live call supervisory control. Returns `401 Unauthorized` if Monitoring is OFF on your API key.
> **Warning:** This action is immediate and irreversible — the call cannot be resumed after hangup.'
parameters:
- name: channelId
in: path
description: The unique identifier of the call channel. Use `POST /calls/current` to discover active channel IDs.
required: true
schema:
type: string
responses:
'201':
description: Successfully processed — the call on the channel has been hung up.
'400':
description: Invalid channel ID format.
'401':
description: Unauthorized — missing or invalid token, or Monitoring is not enabled on your API key.
'404':
description: Channel not found — no active call channel matches the provided ID.
'500':
description: Internal server error.
'502':
description: Service temporarily unavailable — please retry later.
/channels/{channelId}/events/transfer:
post:
operationId: postChannelsChannelidEventsTransfer
tags:
- Channels
x-permissions:
required: Calls W
monitoring: required
summary: Transfer a live call to another number or user
description: 'Transfers the live call on the specified channel to another phone number or user. The current participant is disconnected and the call is redirected to the transfer destination. This is a blind (cold) transfer — the call is forwarded immediately without announcing the transfer to the destination.
The `channelId` identifies a specific participant''s leg in the call. Use `POST /calls/current` to discover active channel IDs. The transfer destination is specified in the request body.
**Permission:** `Calls Write` required.
**Monitoring:** **Required.** This is a live call supervisory control. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: channelId
in: path
description: The unique identifier of the call channel. Use `POST /calls/current` to discover active channel IDs.
required: true
schema:
type: string
requestBody:
description: event_transfer object must be set
content:
application/json:
schema:
$ref: '#/components/schemas/event_transfer'
required: true
responses:
'201':
description: Successfully processed — the call transfer has been initiated.
'400':
description: Invalid request body or channel ID format.
'401':
description: Unauthorized — missing or invalid token, or Monitoring is not enabled on your API key.
'404':
description: Channel not found — no active call channel matches the provided ID.
'500':
description: Internal server error.
'502':
description: Service temporarily unavailable — please retry later.
/channels/{channelId}/events/dtmf:
post:
operationId: postChannelsChannelidEventsDtmf
tags:
- Channels
x-permissions:
required: Calls W
monitoring: required
summary: Send DTMF tones during a live call
description: 'Sends DTMF (Dual-Tone Multi-Frequency) tones on the specified live call channel. DTMF tones are the signals produced by phone keypads (digits 0-9, *, #). Use this to interact with external IVR menus, automated phone systems, or voicemail boxes during a live call.
The `channelId` identifies a specific participant''s leg in the call. Use `POST /calls/current` to discover active channel IDs. The DTMF digits to send are specified in the request body.
**Permission:** `Calls Write` required.
**Monitoring:** **Required.** This is a live call supervisory control. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: channelId
in: path
description: The unique identifier of the call channel. Use `POST /calls/current` to discover active channel IDs.
required: true
schema:
type: string
requestBody:
description: event_dtmf object must be set
content:
application/json:
schema:
$ref: '#/components/schemas/event_dtmf'
required: true
responses:
'201':
description: Successfully processed — the DTMF tones have been sent on the channel.
'400':
description: Invalid request body or channel ID format.
'401':
description: Unauthorized — missing or invalid token, or Monitoring is not enabled on your API key.
'404':
description: Channel not found — no active call channel matches the provided ID.
'500':
description: Internal server error.
'502':
description: Service temporarily unavailable — please retry later.
components:
schemas:
event_dtmf:
type: object
properties:
dtmf:
description: possible value [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, \#, *]
type: string
example: '0'
event_transfer:
type: object
properties:
phone_number:
type: integer
format: int64
example: 33123456789
securitySchemes:
Authorization:
description: "We use API keys for authentication to authorize API requests. First, you need to create a public access token (API key) and select the appropriate rights for each user. To do so:\n 1. Open the Ringover Dashboard.\n 2. Go to the **Developer** section.\n 3. Click the **Create an API key** button.\n 4. Select a user in the drop-down menu and enter a label for the key and click the **Create** button.\n 5. Click the **Edit** button corresponding to the API key and select the appropriate rights.\n\nOnce you've created a public access token, you can use it in the `Authorization` header to authenticate your HTTP request.\n\n```\nAuthorization: <your-public-token>\n```\n\nThis is the **recommended authentication method** and the only one supported by the REST and SCIM endpoints.\n"
type: apiKey
name: Authorization
in: header
AuthorizationQuery:
description: '**Alternative authentication method, only available on the MCP endpoint (`/mcp`).**
Pass your Public API token via the `token` query string parameter:
```
POST /mcp?token=<your-public-token>
```
Useful for clients (no-code platforms, browser tools, etc.) that cannot set custom HTTP headers.
See the **mcp** tag for details on the three accepted authentication sources and their precedence.
'
type: apiKey
name: token
in: query
AuthorizationPath:
description: '**Alternative authentication method, only available on the MCP endpoint (`/mcp/{token}`).**
Pass your Public API token directly inside the URL path:
```
POST /mcp/<your-public-token>
```
Most permissive variant — works with any HTTP client, including those that strip custom headers and query strings.
> ⚠️ The token appears in URLs and is therefore likely to be logged by proxies, browsers and access logs. Prefer the `Authorization` header whenever your client supports it, and rotate any token that may have leaked.
OpenAPI 3.0 does not support `apiKey` in `path`, so this scheme is declared in `query` for tooling compatibility — the actual transport is the URL path. See the **mcp** tag for details.
'
type: apiKey
name: token
in: query
x-tagGroups:
- name: Ringover Public API
tags:
- How to paginate?
- teams
- groups
- users
- numbers
- ivrs
- tags
- conferences
- calls
- campaigns
- channels
- contacts
- conversations
- messages
- sms
- profiles
- presences
- blacklist
- webhook
- callbacks
- surveys
- snoozes
- transcriptions
- cdn
- empower
- whatsapp
- task
- mcp
- name: SCIM 2.0 Provisioning
tags:
- scim