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

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

POST /scim/v2/Users Provision a new SCIM user · Create a SCIM user #
Ask an LLM
“How do I onboard a new Ringover user over SCIM?”
“Does provisioning a SCIM user consume a license and phone number?”
Tell an agent
Provision SCIM user {userName} with roles {roles}.
Create a new Ringover user {userName} and send them an invitation.
GET /scim/v2/Users List SCIM users · List SCIM users #
Ask an LLM
“Which team members are provisioned in Ringover?”
“Can I filter SCIM users by email address?”
Tell an agent
List SCIM users matching {filter}.
Show {count} SCIM users starting at {startIndex}.
POST /scim/v2/Users/.search Search SCIM users with a body filter · Search SCIM users #
Ask an LLM
“Can I search SCIM users using a filter in the request body?”
“What's the body-search alternative to filtering SCIM users with query parameters?”
Tell an agent
Search SCIM users with body filter {filter}.
Run a body-based SCIM user search returning {count} results.
GET /scim/v2/Users/{id} Get a SCIM user · Get a SCIM user #
Ask an LLM
“How do I look up one SCIM user by id?”
“Can I get only certain attributes of a SCIM user?”
Tell an agent
Get SCIM user {id}.
Show SCIM user {id} with attributes {attributes}.
PUT /scim/v2/Users/{id} Replace a SCIM user's attributes · Replace a SCIM user #
Ask an LLM
“Can I rename a SCIM user's email address?”
“What happens if I set a SCIM user's active flag to false?”
Tell an agent
Replace SCIM user {id} with {userName} and roles {roles}.
Deactivate SCIM user {id} by setting active to {active}.
PATCH /scim/v2/Users/{id} Patch a SCIM user · Patch a SCIM user #
Ask an LLM
“Can I change a SCIM user's roles without replacing them?”
“Which SCIM user attributes can I patch?”
Tell an agent
Patch SCIM user {id} with operations {Operations}.
Change the roles of SCIM user {id} to {Operations}.
DELETE /scim/v2/Users/{id} Delete a SCIM user · Delete a SCIM user #
Ask an LLM
“How do I deprovision a SCIM user?”
“Is deleting a SCIM user the same as setting active to false?”
Tell an agent destructive · confirm first
Delete SCIM user {id}.
Deprovision SCIM user {id} permanently.
POST /scim/v2/Groups Create a SCIM ring group · Create a SCIM group #
Ask an LLM
“How do I create a new ring group over SCIM?”
“Can I add members to a SCIM group when I create it?”
Tell an agent
Create SCIM group {displayName}.
Create ring group {displayName} with members {members}.
GET /scim/v2/Groups List SCIM groups · List SCIM groups #
Ask an LLM
“Which ring groups exist in my team?”
“Can I filter SCIM groups by name?”
Tell an agent
List SCIM groups matching {filter}.
Show {count} SCIM groups starting at {startIndex}.
POST /scim/v2/Groups/.search Search SCIM groups with a body filter · Search SCIM groups #
Ask an LLM
“Can I search SCIM groups using a body filter?”
“What does the body-search for groups return?”
Tell an agent
Search SCIM groups with body filter {filter}.
Run a body-based SCIM group search returning {count} results.
GET /scim/v2/Groups/{id} Get a SCIM group with its members · Get a SCIM group #
Ask an LLM
“How do I look up a SCIM group and see who is in it?”
“Can I get only certain attributes of a SCIM group?”
Tell an agent
Get SCIM group {id} with its members.
Show SCIM group {id} with attributes {attributes}.
PUT /scim/v2/Groups/{id} Replace a SCIM group's membership · Replace a SCIM group #
Ask an LLM
“Can I overwrite a SCIM group's membership in one call?”
“Does renaming a SCIM group work when I replace it?”
Tell an agent
Replace SCIM group {id} with members {members}.
Set the membership of SCIM group {id} to {members}.
PATCH /scim/v2/Groups/{id} Patch a SCIM group's membership · Patch a SCIM group #
Ask an LLM
“Can I add or remove members from a SCIM group?”
“How do I reconcile a group's membership with a patch?”
Tell an agent
Patch SCIM group {id} with operations {Operations}.
Add and remove members from SCIM group {id} using {Operations}.
DELETE /scim/v2/Groups/{id} Delete a SCIM group · Delete a SCIM group #
Ask an LLM
“How do I delete a SCIM group?”
“Why can't I delete a group that's still attached to an IVR?”
Tell an agent destructive · confirm first
Delete SCIM group {id}.
Remove ring group {id} from the team.
GET /scim/v2/ServiceProviderConfig Get SCIM service provider config · SCIM service provider configuration #
Ask an LLM
“What SCIM features does the service provider support?”
“Which SCIM capabilities are enabled on this server?”
Tell an agent
Get the SCIM service provider configuration.
Show which SCIM features this server supports.
GET /scim/v2/ResourceTypes List SCIM resource types · SCIM resource types #
Ask an LLM
“Which resource types does the SCIM server expose?”
“What resource types are available, like User and Group?”
Tell an agent
List the SCIM resource types.
Show the resource types exposed by this SCIM server.
GET /scim/v2/Schemas List SCIM schema definitions · SCIM schemas #
Ask an LLM
“What schema definitions does the SCIM server publish?”
“Which attribute schemas are available for users and groups?”
Tell an agent
List the SCIM schema definitions.
Show the attribute schemas available to SCIM users and groups.

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"

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-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