Ringover Sms 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 Sms 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: SMS
  description: 'Send SMS messages to phone numbers. Phone numbers must be in E.164 format.


    **Permissions required:** `Conversations Write` required.


    **Monitoring impact:**

    - *OFF*: You can send SMS from your own number only.

    - *ON*: You can send SMS on behalf of another team member using the `user_id_forced` parameter.'
paths:
  /push/sms:
    post:
      operationId: postPushSms
      tags:
      - SMS
      summary: Send an SMS
      x-permissions:
        required: Conversations W
        monitoring: optional
        monitoring-off: You can only send SMS from your own phone number.
        monitoring-on: You can send SMS from another team member's number using the user_id_forced parameter.
      description: 'Sends an SMS message. Phone numbers must be in E.164 format. If you are concerned about your consumption, please refer to "SMS: understand and control your consumption".


        **Permission:** `Conversations Write` required.


        **Monitoring:** Optional. With Monitoring **OFF**, you can only send SMS from your own phone number. With Monitoring **ON**, you can send SMS from another team member''s number using the `user_id_forced` parameter.'
      requestBody:
        description: SMS message payload including sender number, recipient number, and message body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_push_sms'
        required: true
      responses:
        '202':
          description: SMS accepted and queued for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_push_sms'
        '400':
          description: Invalid request body — check phone number format (E.164) and required fields.
        '401':
          description: Unauthorized — missing or invalid API token, or missing `Conversations Write` permission.
        '402':
          description: Payment required — your SMS credit balance is insufficient.
        '500':
          description: Internal server error.
  /push/sms/v1:
    post:
      operationId: postPushSmsV1
      tags:
      - SMS
      summary: Send a one-way SMS (admin only)
      x-permissions:
        required: Admin + Conversations W
        monitoring: none
      description: 'Sends a one-way (push) SMS. This endpoint is restricted to admin users with `Conversations Write` permission. Recipients cannot reply to one-way SMS. Phone numbers must be in E.164 format.


        **Permission:** Admin status **and** `Conversations Write` required.


        **Monitoring:** No impact.'
      requestBody:
        description: One-way SMS payload including sender number, recipient number, and message body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_oneway_sms'
        required: true
      responses:
        '200':
          description: One-way SMS successfully sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response_oneway_sms'
        '400':
          description: Invalid request body — check phone number format (E.164) and required fields.
        '401':
          description: Unauthorized — missing or invalid API token, or missing `Conversations Write` permission.
        '402':
          description: Payment required — your SMS credit balance is insufficient.
        '403':
          description: Forbidden — this endpoint requires admin privileges.
        '415':
          description: Unsupported media type — use `application/json` content type.
        '500':
          description: Internal server error.
  /sms/opt-out:
    post:
      operationId: postSmsOptOut
      tags:
      - SMS
      summary: Opt a number out of SMS
      x-permissions:
        required: Conversations W
        monitoring: none
      description: 'Adds a phone number to your team''s outbound SMS opt-out list. Any later attempt to send an SMS to that number is blocked, and nothing is charged.


        Use this endpoint when a recipient unsubscribes through a channel other than a `STOP` reply — a phone call, an email, or a form on your website — so that your Ringover opt-out list stays aligned with your own database.


        The team is taken from your API key, so it is not part of the payload. The number must be in international format (E.164), with or without the leading `+`; a national format such as `0612345678` is rejected. Opting out a number that is already opted out succeeds and changes nothing.


        The opt-out is scoped to your team only. It has no effect on other Ringover accounts, does not block inbound SMS from that number, and is unrelated to the call blacklist.


        **Permission:** `Conversations Write` required.


        **Monitoring:** No impact.'
      requestBody:
        description: The phone number to add to the opt-out list.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_sms_opt_out'
        required: true
      responses:
        '200':
          description: The number is opted out. The response has no body.
        '400':
          description: Missing `phone_number`, or the number is not in international (E.164) format.
        '401':
          description: Unauthorized — missing or invalid API token, or missing `Conversations Write` permission.
        '500':
          description: Internal server error.
  /sms/opt-in:
    post:
      operationId: postSmsOptIn
      tags:
      - SMS
      summary: Opt a number back in to SMS
      x-permissions:
        required: Conversations W
        monitoring: none
      description: 'Removes a phone number from your team''s outbound SMS opt-out list, so SMS can be sent to it again. It is the exact reverse of `POST /sms/opt-out`.


        The team is taken from your API key, so it is not part of the payload. The number must be in international format (E.164), with or without the leading `+`; a national format such as `0612345678` is rejected. Opting in a number that was never opted out succeeds and changes nothing.


        Note that this removes **every** opt-out entry your team holds for that number, whatever the sender number it was recorded against. A single call re-subscribes the recipient to all of your team''s numbers.


        **Permission:** `Conversations Write` required.


        **Monitoring:** No impact.'
      requestBody:
        description: The phone number to remove from the opt-out list.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/body_sms_opt_in'
        required: true
      responses:
        '200':
          description: The number is opted back in. The response has no body.
        '400':
          description: Missing `phone_number`, or the number is not in international (E.164) format.
        '401':
          description: Unauthorized — missing or invalid API token, or missing `Conversations Write` permission.
        '500':
          description: Internal server error.
components:
  schemas:
    body_sms_opt_in:
      type: object
      required:
      - phone_number
      properties:
        phone_number:
          type: string
          description: Number to opt back in, in international format (E.164), with or without the leading +
          example: '33611223344'
    response_push_sms:
      type: object
      properties:
        message_id:
          type: integer
          format: int64
          example: 1234567
        conv_id:
          type: integer
          format: int64
          example: 23456
    body_sms_opt_out:
      type: object
      required:
      - phone_number
      properties:
        phone_number:
          type: string
          description: Number to opt out, in international format (E.164), with or without the leading +
          example: '33611223344'
    body_push_sms:
      type: object
      properties:
        archived_auto:
          type:
          - boolean
          - 'null'
          example: false
        from_number:
          type: string
          description: International number format (E.164)
          example: '+33744332211'
        to_number:
          type: string
          description: International number format (E.164)
          example: '+33611223344'
        content:
          type: string
          example: Hello World!
        user_id_forced:
          type: integer
          format: int64
          description: (optional) force the userID of someone else in the team to send the SMS
          example: 12345
        scheduled_at:
          type: string
          format: date-time
          description: (optional) schedule the SMS to be sent at a later date in UTC
          example: '2025-08-21T07:00:00.000Z'
    body_oneway_sms:
      type: object
      properties:
        from_alphanum:
          type: string
          description: Brand name that was created in your dashboard and validated by Ringover
          example: Ringover
        to_number:
          type: integer
          description: International number format (E.164)
          example: 33611223344
        content:
          type: string
          example: Hello World!
        user_id:
          type: integer
          format: int64
          example: 12345
    response_oneway_sms:
      type: object
      properties:
        mdr_uuid:
          type: string
          example: e10ef8d7-3b92-46e1-81e4-ea660f83fd47
  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