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 Groups 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: Groups
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.'
paths:
/groups:
get:
operationId: getGroups
tags:
- Groups
x-permissions:
required: none
monitoring: optional
monitoring-off: Returns only groups you belong to
monitoring-on: Returns all groups in the team
summary: List groups
description: 'Retrieves call groups (ring groups) configured for your team. Groups define how incoming calls are distributed among a set of users (simultaneous ring, round-robin, etc.). Each group includes its member list, ring strategy, and configuration.
**Permission:** No specific permission required. A valid API key is sufficient.
**Monitoring impact:**
- **OFF:** Returns only the groups **you belong to** as a member.
- **ON:** Returns **all groups** in the team, regardless of your membership.
**Pagination:** Results are returned in a **stable order** (by group id), so the same offset always yields the same page. To read every group, keep `limit_count` fixed and increase `limit_offset` by that amount on each request — this avoids the duplicates and gaps you would get from an unordered list.'
parameters:
- name: limit_count
in: query
description: 'Maximum number of groups to return. Default: 100.'
schema:
type: integer
format: int64
default: 100
maximum: 1000
example: 100
- name: limit_offset
in: query
description: 'Number of groups to skip for pagination. Default: 0.'
schema:
type: integer
format: int64
default: 0
example: 0
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/group_list'
'400':
description: A request parameter is malformed or missing
'401':
description: Authentication token is missing, invalid, or expired
'500':
description: Internal server error
/groups/{groupId}:
get:
operationId: getGroupsGroupid
tags:
- Groups
x-permissions:
required: none
monitoring: optional
monitoring-off: Returns the group only if you belong to it
monitoring-on: Returns any group in the team
summary: Get a group by ID
description: 'Retrieves detailed information about a specific call group, including its members, ring strategy, ring durations, and IVR assignments. Use this to inspect a group''s configuration before making changes (e.g., adding/removing members, modifying ring duration).
**Permission:** No specific permission required. A valid API key is sufficient.
**Monitoring impact:**
- **OFF:** Returns the group only if **you are a member** of it. Returns `404` otherwise.
- **ON:** Returns **any group** in the team regardless of your membership.
**Member pagination:** `limit_count` and `limit_offset` paginate **only the `users` sub-array** (group members) of the response — they do not affect the group object itself. The response does not include a total member count: keep incrementing `limit_offset` until an empty `users` array is returned.'
parameters:
- in: path
name: groupId
description: The identifier of the group
required: true
schema:
type: integer
format: int64
- name: limit_count
in: query
description: 'Maximum number of group members to include in the `users` array. Default: 100.'
schema:
type: integer
format: int64
default: 100
maximum: 1000
example: 100
- name: limit_offset
in: query
description: 'Number of group members to skip in the `users` array for pagination. Default: 0.'
schema:
type: integer
format: int64
default: 0
example: 0
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/group_full'
'400':
description: The provided group ID is invalid
'401':
description: Authentication token is missing, invalid, or expired
'404':
description: No group found with the specified ID (or you do not have access to it without monitoring)
'500':
description: Internal server error
/groups/{groupId}/isjumper/toggle:
patch:
operationId: patchGroupsGroupidIsjumperToggle
tags:
- Groups
x-permissions:
required: none
monitoring: required
summary: Toggle free access on a group
description: 'Toggles the `is_jumper` flag on a specific group. When enabled (`is_jumper = true`), users can freely join and leave this group without requiring an administrator action. When disabled, group membership is managed exclusively by administrators. This corresponds to the "Free access" switch in the Ringover dashboard.
**Permission:** No specific permission required. A valid API key is sufficient.
**Monitoring:** **Required.** This is a team-level configuration change. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- in: path
name: groupId
description: The identifier of the group
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Successful operation
'400':
description: The provided group ID is invalid
'401':
description: Authentication token is missing, invalid, expired, or monitoring is not enabled on the API key
'404':
description: No group found with the specified ID
'500':
description: Internal server error
/groups/{groupId}/users:
post:
operationId: postGroupsGroupidUsers
tags:
- Groups
x-permissions:
required: Users W
monitoring: required
summary: Add a user to a group
description: 'Adds a user to a call group. Once added, the user will receive calls routed to this group according to the group''s ring strategy (simultaneous, round-robin, etc.). The user must exist in the team. If the user is already a member of the group, the request has no effect.
**Permission:** `Users Write` required.
**Monitoring:** **Required.** Group membership management is a supervisory operation. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- in: path
name: groupId
description: The identifier of the group
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/add_user_group'
responses:
'200':
description: Successful operation
'400':
description: The provided group ID or request body is invalid
'401':
description: Authentication token is missing, invalid, expired, Users Write permission is missing, or monitoring is not enabled
'404':
description: No group found with the specified ID
'500':
description: Internal server error
delete:
operationId: deleteGroupsGroupidUsers
tags:
- Groups
x-permissions:
required: Users W
monitoring: required
summary: Remove users from a group
description: 'Removes one or more users from a call group. The request body is an array of user IDs to remove. Once removed, these users will no longer receive calls routed to this group. If a user ID is not a member of the group, it is silently ignored.
**Permission:** `Users Write` required.
**Monitoring:** **Required.** Group membership management is a supervisory operation. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- in: path
name: groupId
description: The identifier of the group
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
type: array
items:
type: integer
responses:
'200':
description: Successful operation
'400':
description: The provided group ID or request body is invalid
'401':
description: Authentication token is missing, invalid, expired, Users Write permission is missing, or monitoring is not enabled
'404':
description: No group found with the specified ID
'500':
description: Internal server error
/groups/{groupId}/users/{userId}/ring_duration/{ringDuration}:
patch:
operationId: patchGroupsGroupidUsersUseridRing_durationRingduration
tags:
- Groups
x-permissions:
required: none
monitoring: required
summary: Update ring duration for a user in a group
description: 'Sets how long (in seconds) the phone rings for a specific user within a call group before the call is forwarded to the next member or dropped. This is a per-user, per-group setting — a user can have different ring durations in different groups. The value should be between 5 and 60 seconds.
**Permission:** No specific permission required. A valid API key is sufficient.
**Monitoring:** **Required.** Group configuration changes are supervisory operations. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- in: path
name: groupId
description: The identifier of the group
required: true
schema:
type: integer
format: int64
- in: path
name: userId
description: The identifier of the user
required: true
schema:
type: integer
format: int64
- in: path
name: ringDuration
description: 'Ring duration in seconds (how long the phone rings before the call is forwarded). Typical values: 5–60.'
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Successful operation
'400':
description: One or more path parameters are invalid
'401':
description: Authentication token is missing, invalid, expired, or monitoring is not enabled on the API key
'404':
description: No group found with the specified ID, or the user is not a member of the group
'500':
description: Internal server error
components:
schemas:
group_user:
allOf:
- $ref: '#/components/schemas/user_light'
- type: object
properties:
ring_duration:
type: integer
format: int64
description: Ring duration when an IVR incoming call append
example: 0
order:
type: integer
format: int64
description: The order in the ivr queue
example: 0
group_light:
type: object
properties:
group_id:
type: integer
format: int64
description: The identifier of the group
example: 999999
name:
type: string
description: The name of the group
example: myIVR
total_users_count:
type: integer
format: int64
description: The number of users in the group
example: 0
color:
type: string
example: FFD54F
is_jumper:
type: boolean
description: Allow users to jump into
example: false
add_user_group:
type: array
example:
- 12345
items:
type: integer
format: int64
example: 12345
group_full:
allOf:
- $ref: '#/components/schemas/group_light'
- type: object
properties:
users:
type:
- array
- 'null'
description: The list of campaign sms
items:
$ref: '#/components/schemas/group_user'
user_light:
type: object
properties:
user_id:
type: integer
format: int64
description: The user identifier
example: 123456
team_id:
type: integer
format: int64
description: The team identifier of the user
example: 123456
initial:
type: string
description: The initials of the user
example: PM
color:
type: string
example: 3CC8C8
firstname:
type: string
description: The firstname of the user
example: Pauline
lastname:
type: string
description: The lastname of the user
example: Martin
company:
type: string
description: The company of the user
example: Ringover
email:
type: string
description: The email of the user
example: pauline.martin@ringover.com
picture:
type: string
description: The picture of the user
example: https://cdn77.ringover.com/img/users/default.jpg
concat_name:
type: string
example: Pauline Martin
group_list:
type: object
properties:
list_count:
type: integer
format: int64
description: The size of the list
example: 1
list:
type: array
items:
$ref: '#/components/schemas/group_light'
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