> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM Payload Examples

What Lumos actually sends to your SCIM API on each lifecycle operation, so you can verify your provider's implementation before connecting and debug it after. All payloads follow the SCIM 2.0 Protocol (RFC 7644) and Core Schema (RFC 7643).

To set up the connection itself, see [Connecting SCIM Apps with Lumos](/integrations/generics/scim/connecting-scim-apps-with-lumos).

## Testing against a live sandbox

The SCIM Playground at scim.dev (base URL `https://api.scim.dev`) is a free, live SCIM 2.0 API. Point a SCIM Token connection at it with your scim.dev API key to see the full connector lifecycle against a compliant implementation before touching a real tenant. It's also the fastest way to compare your own application's SCIM responses against a known-good reference.

## Lifecycle payloads

### Listing users (sync)

Lumos pages through `/Users` with standard SCIM pagination parameters:

```text theme={null}
GET /scim/v2/Users?startIndex=1&count=20
Authorization: Bearer {token}
```

A compliant response wraps results in a `ListResponse` with `totalResults`, and each user carries at minimum `id`, `userName`, `emails`, and `active`:

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "Resources": [
    {
      "id": "2819c223-7f76-453a-919d-413861904646",
      "userName": "jwilson@example.com",
      "name": { "givenName": "James", "familyName": "Wilson" },
      "emails": [{ "value": "jwilson@example.com", "primary": true }],
      "active": true
    }
  ]
}
```

If users are missing from your sync, compare your API's `/Users` response against this shape first. Missing `userName` or `emails` attributes and broken pagination are the two most common causes.

### Creating a user (provisioning)

```text theme={null}
POST /scim/v2/Users
```

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "sthompson@example.com",
  "name": { "givenName": "Sarah", "familyName": "Thompson" },
  "emails": [{ "value": "sthompson@example.com", "primary": true }],
  "active": true
}
```

The response must return the created user with its server-assigned `id`. Lumos uses that id for every later operation on the account.

### Deactivating a user (deprovisioning)

A partial update setting `active` to false:

```text theme={null}
PATCH /scim/v2/Users/{id}
```

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{ "op": "replace", "value": { "active": false } }]
}
```

Deleting an account permanently uses `DELETE /scim/v2/Users/{id}` instead. Which one Lumos calls depends on the deprovisioning action configured for the app.

### Managing group membership

Group assignment and removal are PATCH operations against the group, not the user:

```text theme={null}
PATCH /scim/v2/Groups/{id}
```

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "add", "path": "members", "value": [{ "value": "2819c223-7f76-453a-919d-413861904646" }] }
  ]
}
```

Removal uses `"op": "remove"` with the same shape. If membership changes fail, check that your provider supports PATCH on `/Groups` (some only support PUT replacement) in its `/ServiceProviderConfig`.

## Custom attributes

Attributes beyond the core schema, such as the enterprise extension's `department` or `employeeNumber`, sync into Lumos as custom attributes. Lumos discovers them from your API's `/Schemas` endpoint. If an expected attribute isn't appearing, confirm your provider declares it in its schema response and populates it on user records:

```json theme={null}
{
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "701984",
    "department": "Finance"
  }
}
```

## Verifying a provider before connecting

Three requests tell you most of what you need:

1. `GET /ServiceProviderConfig`: confirms SCIM 2.0 and lists supported operations (PATCH support matters for groups and deactivation).
2. `GET /Users?count=1`: confirms auth works and shows you the user shape, including which attributes are populated.
3. `GET /Groups?count=1`: confirms groups have `displayName` and a well-formed `members` array.

Run these with the exact token you'll give Lumos. If all three come back clean, the connection will almost always work on the first try.