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 Blacklist 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: Blacklist
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.'
paths:
/blacklists/numbers:
get:
operationId: getBlacklistsNumbers
tags:
- Blacklist
x-permissions:
required: Numbers R
monitoring: required
summary: List team-wide blacklisted numbers
description: 'Retrieves the phone numbers on your team''s shared blacklist. The team blacklist applies to all users — calls from blacklisted numbers are blocked for the entire team. This is distinct from per-user blacklists (`GET /users/{userId}/blacklists/numbers`). Results are paginated using `limit_count` and `limit_offset`.
**Permission:** `Numbers Read` required.
**Monitoring:** **Required.** The team blacklist is a supervisory feature. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: limit_count
in: query
description: 'The number of results (default: 100).'
schema:
type: integer
format: int64
- name: limit_offset
in: query
description: 'Number of elements that will be ignored (default: 0).'
schema:
type: integer
format: int64
responses:
'200':
description: Successful operation — returns the blacklisted numbers.
content:
application/json:
schema:
$ref: '#/components/schemas/blacklist_list'
'204':
description: No blacklisted numbers found.
'401':
description: Unauthorized — invalid or missing API token, missing `Numbers Read` permission, or Monitoring is OFF.
'500':
description: Internal server error.
post:
operationId: postBlacklistsNumbers
tags:
- Blacklist
x-permissions:
required: Numbers W
monitoring: required
summary: Add a number to the team blacklist
description: 'Adds a phone number to your team''s shared blacklist. Once added, calls from this number are blocked for **all users** in the team. An optional comment can explain the reason (e.g., "spam", "harassment"). If the number is already blacklisted, the request returns `304 Not Modified`.
**Permission:** `Numbers Write` required.
**Monitoring:** **Required.** Team blacklist management is a supervisory feature. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/request_new_blacklist'
required: true
responses:
'200':
description: Successful operation — number added to blacklist.
'304':
description: Number already blacklisted (not modified).
'401':
description: Unauthorized — invalid or missing API token, missing `Numbers Write` permission, or Monitoring is OFF.
'500':
description: Internal server error.
/blacklists/numbers/{phoneNumber}:
get:
operationId: getBlacklistsNumbersPhonenumber
tags:
- Blacklist
x-permissions:
required: Numbers R
monitoring: required
summary: Check if a number is in the team blacklist
description: 'Checks whether a specific phone number is present in your team''s shared blacklist. Returns `200` with the blacklist entry details (including comment) if the number is found, or `404` if it is not blacklisted. Use this for quick lookups before deciding to add or remove a number.
**Permission:** `Numbers Read` required.
**Monitoring:** **Required.** Team blacklist access is a supervisory feature. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: phoneNumber
in: path
description: Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
required: true
schema:
type: integer
format: int64
example: 33612345678
responses:
'200':
description: The number is blacklisted — returns blacklist entry details.
content:
application/json:
schema:
$ref: '#/components/schemas/blacklist'
'401':
description: Unauthorized — invalid or missing API token, missing `Numbers Read` permission, or Monitoring is OFF.
'404':
description: Phone number is not in the blacklist.
'500':
description: Internal server error.
delete:
operationId: deleteBlacklistsNumbersPhonenumber
tags:
- Blacklist
x-permissions:
required: Numbers W
monitoring: required
summary: Remove a number from the team blacklist
description: 'Removes a phone number from your team''s shared blacklist, allowing calls from this number to reach all team members again. If the number was not in the blacklist, the request returns `304 Not Modified`.
**Permission:** `Numbers Write` required.
**Monitoring:** **Required.** Team blacklist management is a supervisory feature. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: phoneNumber
in: path
description: Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
required: true
schema:
type: integer
format: int64
example: 33612345678
responses:
'200':
description: Successful operation — number removed from blacklist.
'304':
description: Number was not in the blacklist (not modified).
'401':
description: Unauthorized — invalid or missing API token, missing `Numbers Write` permission, or Monitoring is OFF.
'500':
description: Internal server error.
/blacklists/numbers/{phoneNumber}/comment/{newComment}:
patch:
operationId: patchBlacklistsNumbersPhonenumberCommentNewcomment
tags:
- Blacklist
x-permissions:
required: Numbers W
monitoring: required
summary: Update the comment on a team blacklisted number
description: 'Updates the comment (reason) associated with a blacklisted phone number in your team''s shared blacklist. The new comment is passed directly in the URL path. Use this to add or modify the reason why a number was blocked without removing and re-adding the entry. If the new comment is identical to the current one, the request returns `304 Not Modified`.
**Permission:** `Numbers Write` required.
**Monitoring:** **Required.** Team blacklist management is a supervisory feature. Returns `401 Unauthorized` if Monitoring is OFF on your API key.'
parameters:
- name: phoneNumber
in: path
description: Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
required: true
schema:
type: integer
format: int64
example: 33612345678
- name: newComment
in: path
description: The new comment text to associate with the blacklisted number (e.g., reason for blocking).
required: true
schema:
type: string
example: new_comment
responses:
'200':
description: Successful operation — comment updated.
'304':
description: Comment unchanged (same as current).
'401':
description: Unauthorized — invalid or missing API token, missing `Numbers Write` permission, or Monitoring is OFF.
'404':
description: Phone number is not in the blacklist.
'500':
description: Internal server error.
/users/{userId}/blacklists/numbers:
get:
operationId: getUsersUseridBlacklistsNumbers
tags:
- Blacklist
x-permissions:
required: Users R
monitoring: optional
monitoring-off: Returns the blacklist only if the userId matches your own
monitoring-on: Returns any user's blacklist
summary: Get a user's personal blacklist
description: 'Retrieves the phone numbers blacklisted by a specific user. A user''s personal blacklist contains numbers that are blocked from calling or being called by this user specifically. This is distinct from the team-level blacklist (`GET /blacklists/numbers`). Results are paginated using `limit_count` and `limit_offset`.
**Permission:** `Users Read` required.
**Monitoring impact:**
- **OFF:** Returns the blacklist only if `userId` matches **your own** user ID. Requesting another user''s blacklist returns `401`.
- **ON:** Returns **any user''s** personal blacklist.'
parameters:
- name: limit_count
in: query
description: 'The number of results (default: 100).'
schema:
type: integer
format: int64
- name: limit_offset
in: query
description: 'Number of elements that will be ignored (default: 0).'
schema:
type: integer
format: int64
- name: userId
in: path
description: The identifier of the user
required: true
schema:
type: integer
format: int64
example: 123456
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/blacklist_list'
'204':
description: The user's blacklist is empty
'400':
description: The provided user ID is invalid
'401':
description: Authentication token is missing, invalid, expired, or Users Read permission is missing
'500':
description: Internal server error
post:
operationId: postUsersUseridBlacklistsNumbers
tags:
- Blacklist
x-permissions:
required: Users W
monitoring: optional
monitoring-off: Can only add to your own blacklist
monitoring-on: Can add to any user's blacklist
summary: Add a number to a user's blacklist
description: 'Adds a phone number to a user''s personal blacklist. Once blacklisted, calls from this number to the user are blocked. An optional comment can be attached to explain why the number was blocked (e.g., "spam caller", "wrong number"). If the number is already blacklisted, the request returns `304 Not Modified`.
**Permission:** `Users Write` required.
**Monitoring impact:**
- **OFF:** Can only add to **your own** blacklist.
- **ON:** Can add to **any user''s** blacklist.'
parameters:
- name: userId
in: path
description: The identifier of the user
required: true
schema:
type: integer
format: int64
example: 123456
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/request_new_blacklist'
required: true
responses:
'200':
description: Successful operation
'304':
description: The number is already in this user's blacklist
'400':
description: The provided user ID or request body is invalid
'401':
description: Authentication token is missing, invalid, expired, or Users Write permission is missing
'500':
description: Internal server error
/users/{userId}/blacklists/numbers/{phoneNumber}:
get:
operationId: getUsersUseridBlacklistsNumbersPhonenumber
tags:
- Blacklist
x-permissions:
required: Users R
monitoring: optional
monitoring-off: Can only check your own blacklist
monitoring-on: Can check any user's blacklist
summary: Check if a number is in a user's blacklist
description: 'Checks whether a specific phone number is present in a user''s personal blacklist. Returns `200` with the blacklist entry (including comment) if the number is found, or `404` if it is not blacklisted. Use this for quick lookups before deciding to add or remove a number.
**Permission:** `Users Read` required.
**Monitoring impact:**
- **OFF:** Can only check **your own** blacklist. Requesting another user''s blacklist returns `401`.
- **ON:** Can check **any user''s** blacklist.'
parameters:
- name: userId
in: path
description: The identifier of the user
required: true
schema:
type: integer
format: int64
example: 123456
- name: phoneNumber
in: path
description: Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
required: true
schema:
type: integer
format: int64
example: 33612345678
responses:
'200':
description: The phone number is blacklisted by this user
content:
application/json:
schema:
$ref: '#/components/schemas/blacklist'
'400':
description: The provided user ID or phone number is invalid
'401':
description: Authentication token is missing, invalid, expired, or Users Read permission is missing
'404':
description: The phone number is not in the user's blacklist
'500':
description: Internal server error
delete:
operationId: deleteUsersUseridBlacklistsNumbersPhonenumber
tags:
- Blacklist
x-permissions:
required: Users W
monitoring: optional
monitoring-off: Can only remove from your own blacklist
monitoring-on: Can remove from any user's blacklist
summary: Remove a number from a user's blacklist
description: 'Removes a phone number from a user''s personal blacklist, allowing calls from this number to reach the user again. If the number was not in the blacklist, the request returns `304 Not Modified`.
**Permission:** `Users Write` required.
**Monitoring impact:**
- **OFF:** Can only remove from **your own** blacklist.
- **ON:** Can remove from **any user''s** blacklist.'
parameters:
- name: userId
in: path
description: The identifier of the user
required: true
schema:
type: integer
format: int64
example: 123456
- name: phoneNumber
in: path
description: Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
required: true
schema:
type: integer
format: int64
example: 33612345678
responses:
'200':
description: Successful operation
'304':
description: The number was not in the blacklist (nothing changed)
'401':
description: Authentication token is missing, invalid, expired, or Users Write permission is missing
'500':
description: Internal server error
/users/{userId}/blacklists/numbers/{phoneNumber}/comment/{newComment}:
patch:
operationId: patchUsersUseridBlacklistsNumbersPhonenumberCommentNewcomment
tags:
- Blacklist
x-permissions:
required: Users W
monitoring: optional
monitoring-off: Can only update comments on your own blacklist
monitoring-on: Can update comments on any user's blacklist
summary: Update the comment on a user's blacklisted number
description: 'Updates the comment (reason) associated with a blacklisted phone number in a user''s personal blacklist. The new comment is passed directly in the URL path. Use this to add or modify the reason why a number was blocked without removing and re-adding the entry.
**Permission:** `Users Write` required.
**Monitoring impact:**
- **OFF:** Can only update comments on **your own** blacklist entries.
- **ON:** Can update comments on **any user''s** blacklist entries.'
parameters:
- name: userId
in: path
description: The identifier of the user
required: true
schema:
type: integer
format: int64
example: 123456
- name: phoneNumber
in: path
description: Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
required: true
schema:
type: integer
format: int64
example: 33612345678
- name: newComment
in: path
description: The new comment
required: true
schema:
type: string
example: new_comment
responses:
'200':
description: Successful operation
'304':
description: The comment is unchanged (same as the current value)
'401':
description: Authentication token is missing, invalid, expired, or Users Write permission is missing
'404':
description: The phone number is not in the user's blacklist
'500':
description: Internal server error
components:
schemas:
blacklist:
type: object
properties:
user_id:
type: integer
format: int64
description: Your user identifier
example: 12345
team_id:
type: integer
format: int64
description: Your team identifier
example: 123456
number:
type: integer
format: int64
description: A blacklisted number
example: 33184800000
comment:
type:
- string
- 'null'
description: The comment about this blacklisted number, can be null.
example: Unfriendly
direction:
type: string
description: IN or OUT for blacklisted numbers (direction of the call)
example: IN
request_new_blacklist:
type: object
properties:
number:
type: integer
format: int64
description: Phone number (E.164 format) (mandatory)
example: 33184800000
comment:
type:
- string
- 'null'
description: A comment about this blacklisted number
example: null
direction:
type: string
description: IN (default value) or OUT for blacklisted numbers
example: IN
blacklist_list:
type: object
properties:
team_id:
type: integer
format: int64
description: Your team identifier
example: 123456
limit_offset_setted:
type: integer
format: int64
description: 'Number of elements that will be ignored (default: 0).'
example: 1
limit_count_setted:
type: integer
format: int64
description: 'The number of results (default: 100).'
example: 10
total_blacklist_count:
type: integer
format: int64
description: The total number of blacklisted phone numbers
example: 37
blacklist_list_count:
type: integer
format: int64
description: The size of the array <em>blacklist_list</em>, corresponds to the number of blacklisted phone numbers retrieved.
example: 1
blacklist_list:
type: array
items:
$ref: '#/components/schemas/blacklist'
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