Ringover Callbacks 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 Callbacks 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: Callbacks
  description: 'Initiate phone calls between a Ringover user and an external recipient. The system calls the user first on their chosen device, then connects them to the recipient.


    **Permissions required:** `Calls Write` required.


    **Monitoring impact:**

    - *OFF*: You can only initiate a callback from your own number.

    - *ON*: You can initiate a callback from any team member''s number using the `from_number` parameter.'
paths:
  /callback:
    post:
      operationId: postCallback
      tags:
      - Callbacks
      x-permissions:
        required: Calls W
        monitoring: optional
      summary: Initiate a callback between two numbers
      description: 'Initiates a callback: your user receives an incoming call and, once they pick up, the system automatically dials the recipient.


        Caution: this feature adds call redirection fees.


        **Call workflow:**

        1. Your user (from_number) receives a call showing the recipient''s number (to_number).

        2. Your user picks up the phone.

        3. A call is automatically made to the recipient (to_number).


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


        **Monitoring:**

        - **OFF (default):** You can only initiate a callback from your own number. The `from_number` field is ignored.

        - **ON:** You can use `from_number` to initiate the callback from any team member''s number.


        **Parameters:**

        - `to_number` *(required)* — Destination phone number in E.164 format (e.g. `33611223344`).

        - `device` *(required)* — 3-character device code indicating which device to ring: `APP`, `WEB`, `SIP`, `MOB`, `EXT`, or `ALL`.

        - `timeout` *(optional, default 20)* — Seconds to wait before aborting the call if no answer. Min: `10`, max: `300`.

        - `clir` *(optional, default false)* — If `true`, the caller''s number is hidden from the recipient (Calling Line Identification Restriction).

        - `from_number` *(optional, requires Monitoring ON)* — The team member''s number to initiate the callback from. Ignored when Monitoring is OFF.'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request_callback'
        required: true
      responses:
        '200':
          description: Successful operation — the 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 number or user could not be resolved.
        '500':
          description: Internal server error.
  /ivrs/{ivrId}/callback:
    post:
      operationId: postIvrsIvridCallback
      tags:
      - Callbacks
      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:
    request_callback:
      type: object
      required:
      - to_number
      - device
      properties:
        from_number:
          type:
          - integer
          - 'null'
          description: 'The team member''s phone number to initiate the callback from (E.164 format, digits only).

            Requires **Monitoring ON**. When Monitoring is OFF or when omitted, the authenticated user''s default number is used.

            '
          format: int64
          example: 33744332211
        to_number:
          type: integer
          format: int64
          description: Destination phone number in E.164 format (digits only). Required.
          example: 33611223344
        timeout:
          type: integer
          format: int64
          minimum: 10
          maximum: 300
          default: 20
          description: 'Number of seconds to wait before aborting the call if the communication is not established. Min: 10, max: 300, default: 20.'
          example: 45
        device:
          type: string
          enum:
          - ALL
          - APP
          - WEB
          - SIP
          - MOB
          - EXT
          description: 'Device to ring for the callback. Required. Use a 3-character code: APP (mobile app), WEB (web app), SIP (SIP phone), MOB (mobile number), EXT (external number), ALL (all devices).'
          example: ALL
        clir:
          type: boolean
          default: false
          description: Calling Line Identification Restriction. When true, the caller's number is hidden from the recipient.
          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