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.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelistoverlay
GET/teamsGet full team information · Get team information#
Ask an LLM
“Which phone numbers, IVRs and users belong to my team?”
“Can I see the full team object with all its resources?”
Tell an agent
Show my team's complete information.
List the numbers, IVRs and users in my team.
GET/teams/plans_dataGet subscription plans and licence counts · Get team subscription plans#
Ask an LLM
“How many licences do I have and how many are used?”
“What subscription plans are available for my team?”
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
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 Teams 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: Teams
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.'
paths:
/teams:
get:
operationId: getTeams
tags:
- Teams
x-permissions:
required: none
monitoring: optional
monitoring-off: Returns limited team data
monitoring-on: Returns full team data including all numbers, users, IVRs, conferences, tags and groups
summary: Get team information
description: 'Retrieves a complete `team` object containing lists of `numbers`, `users`, `ivrs`, `conferences`, `tags` and `groups`.
**Permission:** No specific permission required.
**Monitoring impact:**
- *OFF*: Returns limited team data.
- *ON*: Returns the full team object with all nested resources.'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/team'
'401':
description: Authentication token is missing, invalid, or expired
'500':
description: Internal server error
/teams/plans_data:
get:
operationId: getTeamPlansData
tags:
- Teams
x-permissions:
required: none
monitoring: none
summary: Get team subscription plans
description: 'Retrieves the team''s available subscription plans with name, ID, and licence counts (used and owned).
**Permission:** No specific permission required. A valid API key is sufficient.
**Monitoring:** Not needed.'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/plans_data_response'
'401':
description: Unauthorized — missing, invalid, or expired API key.
'500':
description: Internal server error
components:
schemas:
team:
type: object
properties:
team_id:
type: integer
format: int64
description: Unique identifier for the object
example: 123456
name:
type: string
description: The name of your team
example: My Company
total_numbers_count:
type: integer
format: int64
description: The size of numbers array
example: 1
numbers:
type: array
items:
$ref: '#/components/schemas/number'
total_users_count:
type: integer
format: int64
description: The size of users array
example: 1
users:
type: array
items:
$ref: '#/components/schemas/user_full'
total_ivrs_count:
type: integer
format: int64
description: The size of ivrs array
example: 1
ivrs:
type: array
items:
$ref: '#/components/schemas/ivr'
total_conferences_count:
type: integer
format: int64
description: The size of conferences array
example: 1
conferences:
type: array
items:
$ref: '#/components/schemas/conference'
total_tags_count:
type: integer
format: int64
description: The size of tags array
example: 1
tags:
type: array
items:
$ref: '#/components/schemas/tag'
total_groups_count:
type: integer
format: int64
description: The size of groups array
example: 1
groups:
type: array
items:
$ref: '#/components/schemas/group_light'
plans_data_response:
type: array
items:
type: object
properties:
plan_id:
type: integer
format: int64
plan_name:
type: string
nb_licences_used:
type: integer
format: int64
nb_licences:
type: integer
format: int64
scenario:
type: object
properties:
scenario_id:
type: integer
format: int64
description: The scenario identifier
example: 123456
ivr_id:
type: integer
format: int64
description: The unique identifier of the IVR. Use `GET /ivrs` to discover available IVR IDs.
example: 1234
name:
type: string
description: The name of the scenario
example: myscenario
color:
type: string
example: '123456'
scenario_type:
type: string
enum:
- menu
- announce
- queue
- sms
- webhook
- input
description: The type of the scenario
example: menu
is_default:
type: boolean
example: true
tag:
type: object
properties:
tag_id:
type: integer
format: int64
description: The identifier of the tag
example: 123
name:
type: string
description: The name of the tag
example: mytag
color:
type: string
enum:
- ff6b6b
- F06292
- BA68C8
- 9575CD
- 7986CB
- 64B5F6
- 4FC3F7
- 4DD0E1
- 4DB6AC
- 81C784
- AED581
- DCE775
- FFD54F
- FFB74D
- FF8A65
- A1887F
- E0E0E0
- 90A4AE
example: ff6b6b
description:
type: string
description: The description of the tag
example: my tag description
creation_date:
type: string
format: date-time
example: '2018-08-12T12:12:40.53Z'
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
ivr:
type: object
properties:
ivr_id:
type: integer
format: int64
description: The identifier of the ivr
example: 123456
name:
type: string
description: The name of the ivr
example: StandardFacile
color:
type: string
enum:
- ff6b6b
- F06292
- BA68C8
- 9575CD
- 7986CB
- 64B5F6
- 4FC3F7
- 4DD0E1
- 4DB6AC
- 81C784
- AED581
- DCE775
- FFD54F
- FFB74D
- FF8A65
- A1887F
- E0E0E0
- 90A4AE
example: ff6b6b
numbers:
type: array
items:
$ref: '#/components/schemas/number'
description: The numbers of the ivr
scenarios:
type: array
items:
$ref: '#/components/schemas/scenario'
description: The scenario of the ivr
is_open:
type: boolean
example: true
description: The ivr is open or not
user_full:
allOf:
- $ref: '#/components/schemas/user_light'
- type: object
properties:
numbers:
type: array
items:
$ref: '#/components/schemas/number'
description: The numbers of the user
plan:
type: object
description: The licence plan assigned to the user
properties:
id:
type: integer
format: int64
description: The plan identifier
example: 3
name:
type: string
description: The commercial name of the plan
example: BUSINESS
type:
type: string
description: The category of the plan
example: voice
plantype:
type: string
description: The category of the plan, mirrors `plan.type`
example: voice
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
conference:
type: object
properties:
conference_id:
type: integer
format: int64
description: The conference identifier
example: 60908
name:
type: string
description: The name of the conference
example: SoConference
numbers:
type: array
items:
$ref: '#/components/schemas/number'
description: The numbers of the conference
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