# User APIs

The User APIs enable applications to create, retrieve, update, deactivate, delete, and manage users in Sprinklr.
V3 provides two interfaces for user management:

- **The `/user` surface.** A conventional REST surface: one path with five methods, plus an asynchronous bulk family with job-status polling. This is the surface that matches the rest of API 3.0.
- **The `/scim` surface.** A SCIM 2.0-flavoured surface that preserves the API 2.0 URL shapes.
Choose the interface based on the user-management operation required by your integration.


Both surfaces read and write the same user record. The API 2.0 User APIs were the `/scim` paths, so for existing integrators `/scim` is the continuity path and `/user` is the new option. See [Migrating from API 2.0](#migrating-from-api-20).

## API Endpoints

**User API**

| Operation | Method | Path |
|  --- | --- | --- |
| Create User | POST | `api/v3/user` |
| Fetch User | PUT | `/api/v3/user?id={id}` or `/api/v3/user?email={email}` |
| Fully Update User | PUT | `/api/v3/user?id={id}` or `/api/v3/user?email={email}` |
| Partially Update User | PATCH | `/api/v3/user?id={id}` or `/api/v3/user?email={email}` |
| Delete User | DELETE | `/api/v3/user?id={id}` or `/api/v3/user?email={email}` |
| Upsert User | POST | `/api/v3/user/upsert` |
| Bulk Create Users | POST | `/api/v3/user/bulk` |
| Bulk Update Users | PUT | `/api/v3/user/bulk` |
| Bulk Partial Update | PATCH | `/api/v3/user/bulk` |
| Bulk Upsert Users | POST | `/api/v3/user/bulk/upsert` |
| Fetch Bulk Status | GET | `/api/v3/user/bulk/status?processId={processId}` |
| Fetch Calling User | GET | `/api/v3/me` |


**SCIM API**

| Operation | Method | Path |
|  --- | --- | --- |
| Create User | POST | `/api/v3/scim/Users` |
| List/Search Users | GET | `/api/v3/scim/Users` |
| Fetch User by ID | GET | `/api/v3/scim/Users/{userId}` |
| Fetch User by Email | GET | `/api/v3/scim/email/{emailId}` |
| Replace User | PUT | `/api/v3/scim/Users/{userId}` |
| Partially Update User | PATCH | `/api/v3/scim/Users/{userId}` |
| Delete User | DELETE | `/api/v3/scim/Users/{userId}` |
| Update User | PUT | `/api/v3/scim/update/{userId}` |
| Upsert User | POST | `/api/v3/scim/upsert` |
| Bulk Upsert Users | POST | `/api/v3/scim/bulk-upsert` |


## Base URL

All API calls are sent to:

```
https://api3.sprinklr.com/{env}/api/v3
```

The User API resource is:

```
https://api3.sprinklr.com/{env}/api/v3/user
```

The SCIM API resource is:

```
https://api3.sprinklr.com/{env}/api/v3/scim
```

Replace `{env}` with your assigned Sprinklr environment. See [APIs | Sprinklr Developer Portal](https://dev.sprinklr.com/apis) for the published environment list.
For the production environment at app.sprinklr.com, omit the {env} segment from the URL.

## Authentication & Headers

Every request needs two credentials.

| Header | Value | Purpose |
|  --- | --- | --- |
| `Authorization` | `Bearer {{accessToken}}` | Authenticates the user with the server. See the Authorize article to generate a token. |
| `Key` | `{{apiKey}}` | Authenticates the application with the server. See the API Key and Secret Generation article. |
| `Content-Type` | `application/json` | Declares request body media type |
| `Accept` | `application/json` | Declares acceptable response type |


Include `Content-Type`: `application/json` for requests that contain a request body.

## User Operations

### Fetch user

```
GET /api/v3/user
```

Retrieves a user by ID or email address.

**Query Parameters**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| `id` | Conditional | User identifier. Specify either `id` or `email`. | String |
| `email` | Conditional | User email address. Specify `email` email or `id`. | String |


**Example Request**

```Shell
curl --location --request GET \
'https://api3.sprinklr.com/{env}/api/v3/user?email=jane.doe%40example.com' \
--header 'Authorization: Bearer {access-token}' \
--header 'Key: {api-key}' \
--header 'Accept: application/json'
```

The operation returns an array of matching user objects.

### Create User

```
POST /api/v3/user
```

Creates a user in Sprinklr.

**Example Request**

```Shell
curl --location --request POST \
  'https://api3.sprinklr.com/{env}/api/v3/user' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Key: {api-key}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "userName": "jane.doe@example.com",
    "active": true,
    "name": {
      "givenName": "Jane",
      "familyName": "Doe"
    },
    "emails": [
      {
        "value": "jane.doe@example.com",
        "primary": true
      }
    ],
    "locale": "en_US"
  }'
```

Use active to specify whether the user is active.

### Fully Update User

```
PUT /api/v3/user
```

Replaces the user information for the specified user.

**Query Parameters**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| `id` | Conditional | User identifier. Specify either `id` or `email`. | String |
| `email` | Conditional | User email address. Specify `email` email or `id`. | String |


Use `PUT` when replacing the user resource. For targeted changes, use `PATCH`.

### Partially Update User

```
PATCH /api/v3/user
```

Updates selected user attributes without replacing the entire user resource.

**Query Parameters**

| Parameter | Required/Optional | Description | Type |
|  --- | --- | --- | --- |
| `id` | Conditional | User identifier. Specify either `id` or `email`. | String |
| `email` | Conditional | User email address. Specify `email` email or `id`. | String |


**Example Request**

```Shell
curl --location --request PATCH \
  'https://api3.sprinklr.com/{env}/api/v3/user?id=600000000' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Key: {api-key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "active": false
  }'
```

### Delete User

```
DELETE /api/v3/user
```

Deletes the specified user.

Specify either `id` or `email` as a query parameter.

### Upsert User

```
POST /api/v3/user/upsert
```

Creates or updates a user according to the supplied user information.

### Bulk User Operations

V3 supports bulk create, update, partial update, and upsert operations.

| Method | Purpose |
|  --- | --- |
| `POST /api/v3/user/bulk` | Bulk create users |
| `PUT /api/v3/user/bulk` | Bulk replace users |
| `PATCH /api/v3/user/bulk` | Bulk partially update users |
| `POST /api/v3/user/bulk/upsert` | Bulk upsert users |


**Request Parameters**

| Field | Type | Description |
|  --- | --- | --- |
| `records` | array | The users to process. Send full user objects for create, replace, and upsert; send partial update objects for patch. |
| `callbackUrl` | string | URL that Sprinklr calls when the job finishes. |
| `callbackUrlHeaders` | object | Optional HTTP headers to send with the callback request, as name/value string pairs. |
| `syncProcessing` | boolean | When true, process records synchronously in-request and return per-record results immediately. |


#### Processing Modes

- **Asynchronous** (default, `syncProcessing` absent or false). The call returns quickly with a process identifier. Wait for the callback, or poll for status.
- **Synchronous** (`syncProcessing: true`). The call blocks and returns per-record results directly. Suitable only for small batches — large synchronous batches risk gateway timeouts.


**Example Request**

```Shell
curl --location --request POST \
  'https://api3.sprinklr.com/{env}/api/v3/user/bulk' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Key: {api-key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "syncProcessing": false,
    "callbackUrl": "https://example.com/hooks/user-bulk",
    "records": [
      {
        "userName": "jane.doe@example.com",
        "active": true,
        "name": {
          "givenName": "Jane",
          "familyName": "Doe"
        }
      },
      {
        "userName": "john.smith@example.com",
        "active": true,
        "name": {
          "givenName": "John",
          "familyName": "Smith"
        }
      }
    ]
  }'
```

### Fetch Bulk Status

```
GET /api/v3/user/bulk/status?processId={processId}
```

| Parameter | Required\Optional | Description | Type |
|  --- | --- | --- | --- |
| `processId` | Required | Process identifier returned by the bulk operation. | String |


## SCIM Operations

### Create a user

```
POST /api/v3/scim/Users
```

Creates a user through the SCIM interface.

### List of search users

```
GET /api/v3/scim/Users
```

Retrieves users and supports filtering, sorting, and pagination.

| Parameter | In | Type | Description |
|  --- | --- | --- | --- |
| `startIndex` | query | integer | 1-based index of the first result |
| `count` | query | integer | Maximum results per page |
| `filter` | query | string | SCIM filter expression |
| `sortBy` | query | string | Sort field |
| `sortOrder` | query | string | Sort order |


For example, to retrieve the second page when the page size is 50, specify:

```
startIndex=51&count=50
```

### User Operations by ID

Use the following resource:

```
/api/v3/scim/Users/{userId}
```

The SCIM PATCH operation accepts a SCIM patch document.

| Method | Purpose | Body |
|  --- | --- | --- |
| `GET` | Get user by id | — |
| `PUT` | Replace user | User object |
| `PATCH` | Patch user | SCIM patch document |
| `DELETE` | Delete user | — |


### Fetch User by Email

```
GET /api/v3/scim/email/{emailId}
```

Retrieves a user by email address.

URL-encode the email address before including it in the request path.

### Upsert User

```
POST /api/v3/scim/upsert
```

Creates or updates a user.

### Bulk Upsert Users

```
POST /api/v3/scim/bulk-upsert
```

Creates or updates multiple users through the SCIM interface.

## User Object

The user object contains the primary properties used when creating, retrieving, or updating users.

| Field | Type | Description |
|  --- | --- | --- |
| `schemas` | array of string | The SCIM schema URIs this resource conforms to. |
| `userName` | string | The unique identifier for the user in Sprinklr. This is the user's email address. |
| `name` | object | Name of the user. |
| `emails` | array | The user's email addresses. |
| `phoneNumbers` | array | The user's phone numbers. |
| `photos` | array | User photos. |
| `active` | boolean | Whether the user is active. **A user is created in an inactive state unless you set this to `true`.** |
| `locale` | string | Locale of the user. |
| `globalAttributes` | object | Partner-level attributes that cannot be mapped to SCIM attributes. |
| `clientAttributes` | array | Client-level attributes. |
| `userSeats` | array | The licensed seats assigned to the user. |
| `isSpaceUser` | boolean | Whether the user is a space user. |
| `enterpriseUser` | object | Enterprise user attributes. |
| `userAssignmentConfig` | object | User assignment configuration, including routing skills, languages, channels, and capacities. |
| `userVoiceConfig` | object | User voice configuration. |
| `currentLoginStatus` | string | Current login status. Set by the platform. |
| `upcomingStatus` | string | Upcoming status. Set by the platform. |
| `supervisorTeamIds` | array of string | Supervisor team ids. |
| `recordingShareConfigs` | array | Recording share configurations. |
| `customPropertiesMetadata` | array | Custom property details. |


Some response fields can be managed by the platform and might not be writable through every operation.

### Partial Update Object

`PATCH /api/v3/user` supports targeted updates to user attributes.

Commonly used fields include:

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | User id |
| `externalId` | string | External id from the SCIM client |
| `lyearnId` | string | Learning platform id |
| `userName` | string | Email id / SCIM userName |
| `name` | object | Display name |
| `emails` | array | Emails |
| `phoneNumbers` | array | Phone numbers |
| `photos` | array | Photos |
| `active` | boolean | Active flag |
| `locale` | string | Locale |
| `globalAttributes` | object | Global attributes update |
| `clientAttributes` | array | Client attributes update |
| `isSpaceUser` | boolean | Space user flag |
| `meta` | object | SCIM meta |
| `enterpriseUser` | object | Enterprise user attributes |
| `userSeats` | array | User seats |
| `userAssignmentConfigUpdateRequest` | object | Assignment config update |
| `userVoiceConfigUpdateRequest` | object | Voice config update |
| `userAvailabilityStatus` | string | Agent availability status |


`externalId` and `lyearnId` are available only here. If you need to set the external identity-provider id for a user, `PATCH /user` is the way to do it.

Use the corresponding removal fields when removing values from collections in `userAssignmentConfigUpdateRequest`, such as `skillsToRemove`,  `languagesToRemove`, and `channelsToRemove`.

## Response format and status codes

### Response Envelope

V3 responses use the following structure:

```json
{
  "data": {},
  "errors": [],
  "metadata": {}
}
```

Each error can include:

| Parameter | Description |
|  --- | --- |
| `id` | Error identifier |
| `code` | Error code |
| `message` | Error message or key |


### Status codes

| Code | Meaning | What to do |
|  --- | --- | --- |
| `200` | Success | Read `data`. |
| `400` | Bad Request | Malformed payload, invalid field value, or a missing identifier. Check the `errors` array. |
| `401` | Unauthorized | Missing, expired, or superseded credentials. Both `Authorization` and `Key` must be present. Generating a new token for an API key invalidates the previous one. |
| `403` | Forbidden | Credentials are valid but the owning user lacks permission. Check the key owner's role and whether they can act in the target client environment. |
| `404` | Not Found | No user matches the supplied id or email. |


## Migrating from API V2 to V3

V3 retains the SCIM interface and introduces the `/user` REST interface.

### SCIM Migration

Existing V2 SCIM integrations can migrate to the equivalent V3 SCIM endpoints.

Update:

`/api/v3/scim/`

to

`/api/v3/scim/`

For V3 SCIM requests, use:

`Content-Type: application/json`

instead of:

`Content-Type: application/scim+json`

**The API 2.0 User APIs were the SCIM APIs.** Every 2.0 endpoint was `https://api3.sprinklr.com/{env}/api/v2/scim/...`, and API 3.0 keeps all of those paths under `/api/v3/scim/...`.

For many integrations the minimum viable migration is:

1. Change `v2` to `v3` in the URL.
2. Change `Content-Type` from `application/scim+json` to `application/json`.


That is the recommended first step. Port to `/scim` on 3.0, verify in a lower environment, and only then decide whether to adopt the `/user` surface.

### Endpoint mapping

| Operation | V3 SCIM Endpoint | V3 User API Endpoint |
|  --- | --- | --- |
| Create User | `POST /api/v3/scim/Users` | `POST /api/v3/user` |
| Upsert User | `POST /api/v3/scim/upsert` | `POST /api/v3/user/upsert` |
| Bulk Upsert | `POST /api/v3/scim/bulk-upsert` | `POST /api/v3/user/bulk/upsert` |
| Fetch User | `GET /api/v3/scim/Users/{userId}` | `GET /api/v3/user?id=` |
| Fetch User by Email | `GET /api/v3/scim/email/{emailId}` | `GET /api/v3/user?email=` |
| Update User | `PUT /api/v3/scim/Users/{userId}` | `PUT /api/v3/user?id=` |
| Delete User | `DELETE /api/v3/scim/Users/{userId}` | `DELETE /api/v3/user?id=` |
| Partial User Update | `PUT /api/v3/scim/update/{userId}` | `PATCH /api/v3/user` |


## Related articles

- [API Overview](https://legacy-dev.sprinklr.com/api-overview)
- [API Key and Secret Generation](https://legacy-dev.sprinklr.com/api-key-and-secret-generation)
- [Authorize](https://legacy-dev.sprinklr.com/authorize)
- [REST API Errors and Status Codes](https://legacy-dev.sprinklr.com/rest-api-error-and-status-codes)
- [APIs](https://legacy-dev.sprinklr.com/apis)
- [FAQs](https://legacy-dev.sprinklr.com/faqs)
- [Help Center](https://legacy-dev.sprinklr.com/help-center)