Ringover Ivrs API

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 Ivrs 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: ivrs
  description: 'Retrieve your IVRs (Interactive Voice Response) and their scenarios. IVRs are the automated call routing systems configured on your Ringover account.


    **Permissions required:**

    - **Read** (`IVRs R`): List IVRs and scenarios.

    - **Write** (`IVRs W`): Create tags.


    **Monitoring impact:**

    - *OFF*: Returns only **your own** IVRs and scenarios.

    - *ON*: Returns **all team** IVRs and scenarios.'
paths:
  /ivrs:
    get:
      operationId: getIvrs
      tags:
      - ivrs
      x-permissions:
        required: IVRs R
        monitoring: optional
        monitoring-off: Returns only your own IVRs.
        monitoring-on: Returns all team IVRs.
      summary: List IVRs (Interactive Voice Response)
      description: 'Retrieves all IVR (Interactive Voice Response) configurations for your team. An IVR defines an automated call flow — menu options, routing rules, welcome messages, business hours, and queue behavior. Each IVR has one or more scenarios (call flow variants). The total count is in the `list_count` field.


        **Permission:** `IVRs Read` required.


        **Monitoring impact:**

        - **OFF:** Returns only IVRs **assigned to you** (IVRs using your numbers).

        - **ON:** Returns **all IVRs** in the team.'
      responses:
        '200':
          description: Successful operation — returns the list of IVRs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ivr_list'
        '204':
          description: No IVRs found.
        '401':
          description: Unauthorized — invalid or missing API token, or missing `IVRs Read` permission.
        '500':
          description: Internal server error.
  /ivrs/{ivrId}:
    get:
      operationId: getIvrsIvrid
      tags:
      - ivrs
      x-permissions:
        required: IVRs R
        monitoring: optional
        monitoring-off: Returns IVR details only if the IVR belongs to you.
        monitoring-on: Returns details for any IVR in the team.
      summary: Get an IVR by ID
      description: 'Retrieves detailed information about a specific IVR by its identifier, including its configuration, assigned numbers, scenarios, welcome message settings, business hours, and queue parameters. Use `GET /ivrs` to discover available IVR IDs.


        **Permission:** `IVRs Read` required.


        **Monitoring impact:**

        - **OFF:** Returns the IVR only if it is **assigned to you**. Returns `404` otherwise.

        - **ON:** Returns **any IVR** in the team.'
      parameters:
      - name: ivrId
        in: path
        description: The unique identifier of the IVR. Use `GET /ivrs` to discover available IVR IDs.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful operation — returns the IVR details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ivr'
        '400':
          description: Invalid IVR identifier.
        '401':
          description: Unauthorized — invalid or missing API token, or missing `IVRs Read` permission.
        '404':
          description: IVR not found, or not accessible with current monitoring level.
        '500':
          description: Internal server error.
  /ivrs/{ivrId}/scenarios:
    get:
      operationId: getIvrsIvridScenarios
      tags:
      - ivrs
      x-permissions:
        required: IVRs R
        monitoring: optional
        monitoring-off: Returns only your own scenarios.
        monitoring-on: Returns all scenarios for the specified IVR.
      summary: List scenarios for a specific IVR
      description: 'Retrieves all scenarios (call flow variants) attached to a specific IVR. A scenario defines a complete call flow — which menu options are available, how calls are routed, and what happens at each step. An IVR typically has one default scenario but can have multiple variants for different contexts (e.g., business hours vs. after-hours). The total count is in the `list_count` field.


        **Permission:** `IVRs Read` required.


        **Monitoring impact:**

        - **OFF:** Returns only scenarios from IVRs **assigned to you**.

        - **ON:** Returns **all scenarios** for the specified IVR.'
      parameters:
      - name: ivrId
        in: path
        description: The unique identifier of the IVR. Use `GET /ivrs` to discover available IVR IDs.
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful operation — returns the list of scenarios.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scenario_list'
        '204':
          description: No scenarios found for this IVR.
        '401':
          description: Unauthorized — invalid or missing API token, or missing `IVRs Read` permission.
        '500':
          description: Internal server error.
  /ivrs/{ivrId}/scenarios/{scenarioId}:
    get:
      operationId: getIvrsIvridScenariosScenarioid
      tags:
      - ivrs
      x-permissions:
        required: IVRs R
        monitoring: optional
        monitoring-off: Returns the scenario only if it belongs to you.
        monitoring-on: Returns any scenario for the specified IVR.
      summary: Get a specific scenario for an IVR
      description: 'Retrieves detailed information about a specific scenario within an IVR. The response includes the full call flow definition — menu steps, routing rules, audio prompts, and queue configuration. Both `ivrId` and `scenarioId` must match for the scenario to be returned.


        **Permission:** `IVRs Read` required.


        **Monitoring impact:**

        - **OFF:** Returns the scenario only if the parent IVR is **assigned to you**. Returns `404` otherwise.

        - **ON:** Returns **any scenario** for any IVR in the team.'
      parameters:
      - name: ivrId
        in: path
        description: The unique identifier of the IVR. Use `GET /ivrs` to discover available IVR IDs.
        required: true
        schema:
          type: integer
          format: int64
      - name: scenarioId
        in: path
        description: The scenario identifier
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful operation — returns the scenario details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scenario'
        '400':
          description: Invalid IVR or scenario identifier.
        '401':
          description: Unauthorized — invalid or missing API token, or missing `IVRs Read` permission.
        '404':
          description: Scenario not found, or not accessible with current monitoring level.
        '500':
          description: Internal server error.
  /scenarios:
    get:
      operationId: getScenarios
      tags:
      - ivrs
      summary: List all scenarios across all IVRs
      x-permissions:
        required: IVRs R
        monitoring: optional
        monitoring-off: Returns only your own scenarios.
        monitoring-on: Returns all team scenarios.
      description: 'Retrieves all scenarios across all IVRs in a single request. This is a convenience alternative to calling `GET /ivrs/{ivrId}/scenarios` for each IVR individually. Useful for building a global overview of all call flows configured in the team.


        **Permission:** `IVRs Read` required.


        **Monitoring impact:**

        - **OFF:** Returns only scenarios from IVRs **assigned to you**.

        - **ON:** Returns **all scenarios** across all team IVRs.'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scenario_list'
        '204':
          description: No scenarios found
        '401':
          description: Unauthorized — invalid API key or missing `IVRs Read` permission
        '500':
          description: Internal server error
  /scenarios/{scenarioId}:
    get:
      operationId: getScenariosScenarioid
      tags:
      - ivrs
      summary: Get a specific scenario by ID
      x-permissions:
        required: IVRs R
        monitoring: optional
        monitoring-off: Returns the scenario only if it belongs to you.
        monitoring-on: Returns any scenario.
      description: 'Retrieves a specific scenario by its unique ID, regardless of which IVR it belongs to. This is a shortcut alternative to `GET /ivrs/{ivrId}/scenarios/{scenarioId}` when you already know the scenario ID but not the parent IVR ID.


        **Permission:** `IVRs Read` required.


        **Monitoring impact:**

        - **OFF:** Returns the scenario only if the parent IVR is **assigned to you**.

        - **ON:** Returns **any scenario** in the team.'
      parameters:
      - name: scenarioId
        in: path
        description: The unique identifier of the scenario
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scenario'
        '400':
          description: Invalid scenario ID format
        '401':
          description: Unauthorized — invalid API key or missing `IVRs Read` permission
        '404':
          description: Scenario not found or not accessible with current monitoring level
        '500':
          description: Internal server error
  /ivrs/{ivrId}/callback:
    post:
      operationId: postIvrsIvridCallback
      tags:
      - ivrs
      x-permissions:
        required: Calls W
        monitoring: none
      summary: Initiate a callback through an IVR
      description: 'Triggers a callback through a specific IVR (Interactive Voice Response) queue. The specified phone number will be called, and when the recipient picks up, they are routed through the IVR flow associated with the given `ivrId`. This is typically used to offer a "call me back" feature to customers waiting in a queue.


        IVR Callbacks are only available on the **Business** and **Advanced** plans. Standard telephony charges apply based on the destination number.


        **Permission:** `Calls Write` required.


        **Monitoring:** Not required for this route. Any valid API key with `Calls Write` permission can initiate an IVR callback regardless of the Monitoring flag.'
      parameters:
      - name: ivrId
        in: path
        description: The IVR identifier
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request_ivr_callback'
      responses:
        '200':
          description: Successful operation — the IVR callback has been initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/callback_list'
        '401':
          description: Unauthorized — missing or invalid token, or insufficient Calls Write permission.
        '404':
          description: Not found — the specified IVR does not exist.
        '500':
          description: Internal server error.
components:
  schemas:
    ivr_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/ivr_without_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'
    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
    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
    ivr_without_number:
      type: object
      properties:
        ivr_id:
          type: integer
          format: int64
          description: The identifier if the ivr
          example: 123456
        color:
          type: string
          enum:
          - ff6b6b
          - F06292
          - BA68C8
          - 9575CD
          - 7986CB
          - 64B5F6
          - 4FC3F7
          - 4DD0E1
          - 4DB6AC
          - 81C784
          - AED581
          - DCE775
          - FFD54F
          - FFB74D
          - FF8A65
          - A1887F
          - E0E0E0
          - 90A4AE
          example: ff6b6b
        name:
          type: string
          description: The name of the ivr
          example: StandardFacile
        scenarios:
          type: array
          items:
            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
        is_open:
          type: boolean
          example: true
          description: The ivr is open or not
    scenario_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/scenario'
    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
    SalesforceIntegration:
      type: object
      properties:
        object:
          type: string
          example: Opportunity
        object_id:
          type: string
          example: SF_ID
    request_ivr_callback:
      type: object
      properties:
        from_number:
          description: The IVR Number to display
          type: integer
          format: int64
          example: 33744332211
        clir:
          type: boolean
          description: 'Calling line identification restriction: The CLIR service blocks calling party address information from being presented to the called user.'
          example: false
        to_number:
          type: integer
          format: int64
          example: 33611223344
        timeout:
          type: integer
          format: int64
          minimum: 20
          maximum: 300
          description: Number of seconds before the call is aborted if the communication isn't etablished.
          example: 45
        integrations:
          $ref: '#/components/schemas/Integrations'
    Integrations:
      type: object
      properties:
        salesforce:
          $ref: '#/components/schemas/SalesforceIntegration'
    callback_list:
      type: object
      properties:
        call_id:
          type: integer
          format: uint64
          example: 1234567890987654321
        channel_id:
          type: integer
          format: uint64
          example: 12345678909876543210
  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