Ringover Teams API

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.

GitHub OpenAPI

Operations 2

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 Evangelist overlay

GET /teams Get 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_data Get 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?”
Tell an agent
Show my team's subscription plans.
List licence counts for each plan.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/ringover:ringover-teams-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

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.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

ringover-teams-api-openapi.yml Raw ↑
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