Ringover Presences API

Retrieve real-time presence information about users: planning status, snooze status, connected device, and whether they are currently in a call. **Permissions required:** - `Users Read` for individual user presence (`GET /users/{userId}/presences`). - No specific permission for team-wide presences (`GET /presences`), but **Monitoring must be ON**. **Monitoring impact:** - *OFF*: You can only retrieve **your own** presence. Team-wide presences route returns `401`. - *ON*: You can retrieve **any user's** presence and the team-wide presences endpoint is available.

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 /users/{userId}/presences Get one user's presence status · Get a user's presence status #
Ask an LLM
“Is a specific Ringover user available or on a call right now?”
“Which device is a user connected from and are they in snooze mode?”
Tell an agent
Get the presence status of user {userId}.
Show whether {userId} is available, on a call or in snooze.
GET /presences List presence for all team members · List all team presences #
Ask an LLM
“Can I see the presence status of every user on my team at once?”
“What is the bulk way to get everyone's availability for a team dashboard?”
Tell an agent
List presence for all users in my team.
Show everyone's availability state and active snooze.

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-presences-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-presences-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 Presences 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: Presences
  description: 'Retrieve real-time presence information about users: planning status, snooze status, connected device, and whether they are currently in a call.


    **Permissions required:**

    - `Users Read` for individual user presence (`GET /users/{userId}/presences`).

    - No specific permission for team-wide presences (`GET /presences`), but **Monitoring must be ON**.


    **Monitoring impact:**

    - *OFF*: You can only retrieve **your own** presence. Team-wide presences route returns `401`.

    - *ON*: You can retrieve **any user''s** presence and the team-wide presences endpoint is available.'
paths:
  /users/{userId}/presences:
    get:
      operationId: getUsersUseridPresences
      tags:
      - Presences
      x-permissions:
        required: Users R
        monitoring: optional
        monitoring-off: Returns presence only if the userId matches your own
        monitoring-on: Returns any user's presence
      summary: Get a user's presence status
      description: 'Retrieves the current presence status for a specific user — whether they are available, on a call, in snooze mode, or offline. The presence data includes the user''s current availability state, active snooze information (if any), and the device they are connected from.


        **Permission:** `Users Read` required.


        **Monitoring impact:**

        - **OFF:** Returns presence only if `userId` matches **your own** user ID. Requesting another user''s presence returns `404`.

        - **ON:** Returns **any user''s** presence in the team. For a bulk view of all team presences, use `GET /presences` instead (also requires Monitoring ON).'
      parameters:
      - name: userId
        in: path
        description: The identifier of the user
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user_presences'
        '400':
          description: The provided user ID is invalid
        '401':
          description: Authentication token is missing, invalid, expired, or Users Read permission is missing
        '404':
          description: No user found with the specified ID (or you do not have access to this user without monitoring)
        '500':
          description: Internal server error
  /presences:
    get:
      operationId: getPresences
      tags:
      - Presences
      x-permissions:
        required: none
        monitoring: required
      summary: List all team presences
      description: 'Retrieves presence information for **all users** in your team in a single request. Each entry includes the user''s current availability state (available, on call, in snooze, offline), active snooze details, and connected device. This is the bulk equivalent of `GET /users/{userId}/presences` — ideal for building a team dashboard or monitoring panel.


        **Permission:** No specific permission required. A valid API key is sufficient.


        **Monitoring:** **Required.** This is a team-wide supervisory view. Returns `401 Unauthorized` if Monitoring is OFF on your API key. For individual user presence without Monitoring, use `GET /users/{userId}/presences` instead.'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/users_presences'
        '401':
          description: Authentication token is missing, invalid, expired, or monitoring is not enabled on the API key
        '500':
          description: Internal server error
components:
  schemas:
    user_presences:
      type: object
      properties:
        team_id:
          type: integer
          format: int64
          description: The user's team id
          example: 123456
        user_id:
          type: integer
          format: int64
          description: The user's id
          example: 123456
        in_call:
          type: integer
          format: int64
          description: Number of current calls (it can be more than 1)
          example: 1
        connected_devices:
          type: integer
          format: int64
          description: Number of devices connected to myringover
          example: 3
        planning_enable:
          type: boolean
          description: True if the user have the planning option activated on myringover
          example: true
        is_planning:
          type: boolean
          description: True if the user is currently in his planning schedule
          example: true
        is_planned_snooze:
          type: boolean
          description: False if the user is currently in his planning schedule
          example: false
        is_snoozed:
          type: boolean
          description: True if the user is currently in snooze
          example: true
        snooze_type:
          type: string
          description: The type of snooze currently used. Null if is_snoozed is false
          example: meeting
        snooze_end:
          type: string
          description: End date/time of the snooze
          example: '2020-07-17 10:14:24'
    users_presences:
      type: object
      properties:
        list_count:
          type: integer
          format: int64
          description: The size of the array <em>list</em>, corresponds to the number of presences retrieved
          example: 1
        list:
          type: array
          items:
            $ref: '#/components/schemas/user_presences'
  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