Ringover

Ringover SCIM API

Ringover exposes a **SCIM 2.0** server (RFC 7643 / RFC 7644) so your identity provider (Okta, Microsoft Entra ID, OneLogin, …) can automatically provision, update and deprovision Ringover users and groups. ### Base URL | Region | SCIM Base URL | |--------|---------------| | Europe | `https://public-api.ringover.com/v2/scim/v2` | | US | `https://public-api-us.ringover.com/v2/scim/v2` | ### Authentication SCIM uses the **same API key** as the REST API, passed **raw** in the `Authorization` header (no `Bearer ` prefix). Unauthenticated requests receive a `401` carrying a `WWW-Authenticate: Bearer` challenge. ``` Authorization: ``` ### Content type Request and response bodies use the SCIM media type `application/scim+json`. `application/json` is also accepted on input. ### Permissions & Monitoring | Operation | Permission required | |-----------|---------------------| | Read (Get, List, `.search`) | `Users Read` | | Write (Create, Replace, Patch, Delete) | `Users Write` | Because SCIM operates on the **whole team** (an IdP manages every user), the API key must have **Monitoring ON**. Without it, listings are restricted to your own data and most provisioning operations are refused. ### Integration steps Follow these steps to connect a user manager — an identity provider such as Okta / Microsoft Entra ID, or a custom provisioning system — to Ringover: 1. **Create an API key** in the Ringover Dashboard (**Developer > API Keys**) with **Users Read + Write** and **Monitoring ON**. This single key authenticates every SCIM request. 2. **Point your SCIM connector** at the base URL `https://public-api.ringover.com/v2/scim/v2`. For the credentials, use an **HTTP Header Token** auth type and paste the API key **raw** as the token — it must reach Ringover as `Authorization: `, without a `Bearer ` prefix. 3. **Verify connectivity** by calling `GET /ServiceProviderConfig` — it returns the supported features and confirms authentication. Most IdPs expose this as a "Test connection" button. 4. **Map attributes**: at minimum, map your directory's login / UPN to `userName` **as an email address** (a valid email is mandatory to provision). Optionally map `name`, `title` and group membership. To assign a Ringover profile, map `roles` and send the **numeric profile id** (discover it via `GET /profiles`) as `roles[].value`. 5. **Provision** users with `POST /Users` and groups with `POST /Groups`; store the returned `id` to address the resource later. 6. **Push updates** with `PATCH /Users/{id}` (or `PUT`), and **deprovision** by sending `active: false` via `PATCH` (or `DELETE /Users/{id}`) — in Ringover this **deletes** the user. 7. **Reconcile** by `userName` (or `id`) — not by `externalId` (see limitations). The **end-to-end example** below walks through the full lifecycle as raw HTTP calls. ### Resources | Resource | Endpoint | Description | |----------|----------|-------------| | User | `/Users` | Ringover team members | | Group | `/Groups` | Ring groups | Discovery endpoints (`/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`) describe the server's capabilities. ### User attribute mapping | SCIM attribute | Ringover field | Notes | |----------------|----------------|-------| | `id` | user id | Raw Ringover user id (string). | | `userName` | email / login | Required. Used as the unique identifier. | | `name.givenName` / `name.familyName` | firstname / lastname | Writable. | | `displayName` | — | **Read-only**, derived from the name. A value sent by the client is ignored. | | `title` | job title | Writable. | | `emails` | account email | **Immutable** after onboarding. The primary email is the account identifier. | | `roles` | Ringover profile | Single profile. On input, `roles[].value` **must be the numeric profile id** (discover it via `GET /profiles`). On output, `value` is the id and `display` the profile name. | | `active` | lifecycle | `false` deprovisions (deletes) the user; `true` (or absent) is a no-op. | | `externalId` | — | **Not persisted.** Echoed in the create response only; never returned on reads. | ### Group attribute mapping | SCIM attribute | Ringover field | Notes | |----------------|----------------|-------| | `id` | group id | Raw Ringover group id (string). | | `displayName` | group name | Set at creation. **Rename is not supported** and is ignored on update. | | `members` | group users | `members[].value` is a user id. | ### Querying: filter, sort, pagination, projection - **Filter** (`filter`): a single comparison `attribute op "value"`, with `op` one of `eq`, `sw` (starts-with), `ew` (ends-with), `co` (contains). Filterable attributes: Users `userName`, `externalId`, `emails`; Groups `displayName`, `externalId`. Any other operator returns `400 invalidFilter`. - **Sort** (`sortBy`, `sortOrder`): case-insensitive, default ascending. An unsupported `sortBy` is ignored. - **Pagination** (`startIndex` 1-based, `count`): `count` is capped at **100** per page. - **Projection** (`attributes` / `excludedAttributes`): comma-separated, **top-level attributes only**; `schemas`, `id` and `meta` are always returned. ### PATCH `PATCH` follows RFC 7644 §3.5.2 with `add` / `remove` / `replace` operations. On groups, membership operations are reconciled into a single upstream update. ### End-to-end example (provisioning from a user manager) A typical provisioning lifecycle, shown as raw HTTP calls (replace `$TOKEN` with your API key). All requests target the EU base URL `https://public-api.ringover.com/v2/scim/v2`. **1. Verify the connection** ```bash curl -s https://public-api.ringover.com/v2/scim/v2/ServiceProviderConfig \ -H "Authorization: $TOKEN" ``` **2. Create a user** — this is a real onboarding: it sends an invitation and consumes a license and a phone number. ```bash curl -s -X POST https://public-api.ringover.com/v2/scim/v2/Users \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "ada@example.com", "name": { "givenName": "Ada", "familyName": "Lovelace" }, "emails": [{ "value": "ada@example.com", "primary": true }], "active": true }' ``` Response (`201 Created`) — store the `id` for the next calls: ```json { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "42", "userName": "ada@example.com", "active": true, "meta": { "resourceType": "User", "location": "/scim/v2/Users/42" } } ``` **3. Assign a role (Ringover profile)** — profile ids are discovered via the REST `GET /profiles` endpoint, then passed as `roles[].value`: ```bash # a) discover profile ids (REST API) curl -s https://public-api.ringover.com/v2/profiles -H "Authorization: $TOKEN" # b) assign profile id 12 to the user curl -s -X PATCH https://public-api.ringover.com/v2/scim/v2/Users/42 \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace", "path": "roles", "value": [{ "value": "12", "primary": true }] } ] }' ``` **4. Create a group and add the user as a member** ```bash curl -s -X POST https://public-api.ringover.com/v2/scim/v2/Groups \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Support", "members": [{ "value": "42" }] }' ``` **5. Update the user** (e.g. change the first name) ```bash curl -s -X PATCH https://public-api.ringover.com/v2/scim/v2/Users/42 \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace", "path": "name.givenName", "value": "Augusta" } ] }' ``` **6. Deprovision the user** — set `active: false` (soft delete) or issue a `DELETE`: ```bash curl -s -X PATCH https://public-api.ringover.com/v2/scim/v2/Users/42 \ -H "Authorization: $TOKEN" \ -H "Content-Type: application/scim+json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace", "path": "active", "value": false }] }' ``` > Reconcile users by `userName` or `id`; `externalId` is not returned on reads, so do not rely on it for matching. ### Behavior & limitations - **Provisioning is a real onboarding operation.** Creating a user sends an invitation and consumes a **license and a phone number** from your team. A valid email is required: provide a primary `emails` value or an email-formatted `userName`, otherwise the request is rejected with `400 invalidValue`. - **`emails` is immutable**: it cannot be changed, removed or replaced via `PUT`/`PATCH`. - **`displayName` is read-only** and derived from the name. - **Group rename is not supported**: `displayName` is fixed after creation; updates only reconcile members. - **`active: false` deletes the user** (soft delete — the only deprovisioning lever). **`active: true` is a no-op** and there is **no reactivation** via SCIM. - **`roles[].value` must be a numeric profile id.** A non-numeric value (e.g. a role name) is **silently ignored** (no error), leaving the user with no profile assigned. Discover profile ids via `GET /profiles`. - **`externalId` is not persisted**: it is returned only in the create response, never on reads. Consequently `filter=externalId eq "..."` never matches, and reconciliation by `externalId` does not work — reconcile by `userName` or `id`. - **Multi-attribute `PUT`/`PATCH` on a user is not atomic**: each field is applied upstream independently, so a later failure can leave earlier fields already changed. - **`meta.created` / `meta.lastModified` are currently omitted** (they will be populated once available upstream). - **`Bulk` and custom resource types are not supported.**

GitHub OpenAPI
Business capability
Tenant Identity Federation BC-4230.50

Operations 17

POST /scim/v2/Users Create a SCIM user #
GET /scim/v2/Users List SCIM users #
POST /scim/v2/Users/.search Search SCIM users #
GET /scim/v2/Users/{id} Get a SCIM user #
PUT /scim/v2/Users/{id} Replace a SCIM user #
PATCH /scim/v2/Users/{id} Patch a SCIM user #
DELETE /scim/v2/Users/{id} Delete a SCIM user #
POST /scim/v2/Groups Create a SCIM group #
GET /scim/v2/Groups List SCIM groups #
POST /scim/v2/Groups/.search Search SCIM groups #
GET /scim/v2/Groups/{id} Get a SCIM group #
PUT /scim/v2/Groups/{id} Replace a SCIM group #
PATCH /scim/v2/Groups/{id} Patch a SCIM group #
DELETE /scim/v2/Groups/{id} Delete a SCIM group #
GET /scim/v2/ServiceProviderConfig SCIM service provider configuration #
GET /scim/v2/ResourceTypes SCIM resource types #
GET /scim/v2/Schemas SCIM schemas #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/ringover/openapi/ringover-scim-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/ringover/json-schema/ringover-calls-filter-schema.json
📊
JSONSchema
https://artifacts.apis.io/ringover/json-schema/ringover-empower-logs-calls-response-schema.json
📊
JSONSchema
https://artifacts.apis.io/ringover/json-schema/ringover-empower-logs-calls-request-schema.json
📊
JSONSchema
https://artifacts.apis.io/ringover/json-schema/ringover-call-empower-schema.json
📊
JSONSchema
https://artifacts.apis.io/ringover/json-schema/ringover-conversation-light-schema.json
📊
JSONSchema
https://artifacts.apis.io/ringover/json-schema/ringover-get-call-empower-res-body-schema.json

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-scim-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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. See our Privacy Policy and Terms.

GitHub Google LinkedIn

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

OpenAPI Specification

ringover-scim-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 SCIM 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:


# --- truncated at 32 KB (41 KB total) ---
# Full source: https://artifacts.apis.io/ringover/openapi/ringover-scim-api-openapi.yml