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 Numbers 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: Numbers
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.'
paths:
/numbers:
get:
operationId: getNumbers
tags:
- Numbers
x-permissions:
required: Numbers R
monitoring: optional
monitoring-off: Returns only your own numbers. Filter parameters are ignored.
monitoring-on: Returns all team numbers with full filter support (is_ivr, is_user, is_conference, is_fax, is_available).
summary: List team phone numbers
description: 'Retrieves the list of phone numbers provisioned for your team. Each number includes its assignment (user, IVR, conference, fax, or unassigned), country, and configuration. The total count is in the `list_count` field.
Five boolean filters allow you to select numbers by assignment type. By default, `is_available` is `true` and all others are `false`. Set a filter to `true` to include that category. If `is_available` is `false`, at least one other filter must be `true`.
**Permission:** `Numbers Read` required.
**Monitoring impact:**
- **OFF:** Returns only **your own** numbers (numbers assigned to your user). All filter parameters are **ignored** — the response always contains your numbers regardless of filters.
- **ON:** Returns **all team numbers** with full filter support (`is_ivr`, `is_user`, `is_conference`, `is_fax`, `is_available`).'
parameters:
- name: is_user
in: query
description: 'Include numbers assigned to users. Default: `false`. Only effective when Monitoring is ON.'
schema:
type: boolean
default: false
example: false
- name: is_ivr
in: query
description: 'Include numbers assigned to IVRs (Interactive Voice Response). Default: `false`. Only effective when Monitoring is ON.'
schema:
type: boolean
default: false
example: false
- name: is_fax
in: query
description: 'Include numbers used for fax. Default: `false`. Only effective when Monitoring is ON.'
schema:
type: boolean
default: false
example: false
- name: is_conference
in: query
description: 'Include numbers assigned to conference rooms. Default: `false`. Only effective when Monitoring is ON.'
schema:
type: boolean
default: false
example: false
- name: is_available
in: query
description: 'Include unassigned (available) numbers. Default: `true`. If set to `false`, at least one other filter must be `true`. Only effective when Monitoring is ON.'
schema:
type: boolean
default: true
example: false
responses:
'200':
description: Successful operation — returns the list of numbers.
content:
application/json:
schema:
$ref: '#/components/schemas/number_list'
'204':
description: No numbers found matching the given filters.
'400':
description: Invalid query parameter value.
'401':
description: Unauthorized — invalid or missing API token, or missing `Numbers Read` permission.
'500':
description: Internal server error.
/numbers/{number}:
get:
operationId: getNumbersNumber
tags:
- Numbers
x-permissions:
required: Numbers R
monitoring: optional
monitoring-off: Returns number details only if the number belongs to you.
monitoring-on: Returns details for any number in the team.
summary: Get a specific phone number's details
description: 'Retrieves detailed information about a specific phone number, including its assignment (user, IVR, conference), country, capabilities, and configuration. The number is identified by its phone number in E.164 format without the `+` prefix (e.g., `33140000000`).
**Permission:** `Numbers Read` required.
**Monitoring impact:**
- **OFF:** Returns the number only if it is **assigned to you**. Requesting a number belonging to another user returns `404`.
- **ON:** Returns details for **any number** in the team.'
parameters:
- name: number
in: path
description: The phone number in E.164 format without the `+` prefix (e.g., `33140000000` for a French number).
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Successful operation — returns the number details.
content:
application/json:
schema:
$ref: '#/components/schemas/number'
'400':
description: Invalid phone number format.
'401':
description: Unauthorized — invalid or missing API token, or missing `Numbers Read` permission.
'404':
description: Number not found, or not accessible with current monitoring level.
'500':
description: Internal server error.
patch:
operationId: patchNumbersNumber
tags:
- Numbers
summary: Assign a phone number to a user, IVR, or conference
x-permissions:
required: Numbers R
monitoring: optional
description: 'Reassign a phone number to a different target: a user, an IVR, or a conference room. Only one target field should be provided in the request body — `user_id`, `ivr_id`, or `conference_id`. The number must already be provisioned in your team. Reassigning a number immediately changes call routing for that number.
**Permission:** `Numbers Read` required (assignment uses read-level permission).
**Monitoring impact:**
- **OFF:** Limited assignment capabilities — restricted to your own numbers.
- **ON:** Full assignment capabilities across the entire team.'
requestBody:
description: Assignment details
content:
application/json:
schema:
type: object
properties:
user_id:
type: integer
format: int64
description: The user ID to assign the number to.
ivr_id:
type: integer
format: int64
description: The IVR ID to assign the number to.
conference_id:
type: integer
format: int64
description: The conference ID to assign the number to.
required: true
parameters:
- name: number
in: path
description: The phone number to assign, in E.164 format without the `+` prefix (e.g., `33612345678`).
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Number successfully assigned
'400':
description: Invalid request — check number format and assignment target
'401':
description: Unauthorized — invalid API key or missing `Numbers Read` permission
'404':
description: Number not found
'500':
description: Internal server error
components:
schemas:
number_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/number'
number:
type: object
properties:
number:
type: integer
description: Phone number in E.164 format without the `+` prefix (e.g., `33612345678`).
example: 33184800000
label:
type: string
description: The label of the number
example: myfavoritenumber
type:
type: string
description: The type of the number
example: PHONE
user_id:
type: integer
format: int64
description: The user identifier
example: 60907
ivr_id:
type: integer
format: int64
description: The unique identifier of the IVR. Use `GET /ivrs` to discover available IVR IDs.
example: 60908
conference_id:
type: integer
format: int64
description: The conference identifier
example: 60908
is_sms:
type: boolean
example: false
is_sms_write:
type: boolean
example: false
is_callable:
type: boolean
example: false
format:
$ref: '#/components/schemas/format_number'
format_number:
type: object
properties:
raw:
type: integer
format: int64
example: 184800000
country_code:
type: string
example: '33'
country:
type: string
example: FR
e164:
type: string
example: '+33184800000'
international:
type: string
example: +33 1 84 80 00 00
international_alt:
type: string
example: '33184800000'
national:
type: string
example: 01 84 80 00 00
national_alt:
type: string
example: 0184800000
rfc3966:
type: string
example: tel:+33-1-84-80-00-00
is_short_code:
type: boolean
example: false
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