Skip to content

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.

API Endpoints

User API

OperationMethodPath
Create UserPOSTapi/v3/user
Fetch UserPUT/api/v3/user?id={id} or /api/v3/user?email={email}
Fully Update UserPUT/api/v3/user?id={id} or /api/v3/user?email={email}
Partially Update UserPATCH/api/v3/user?id={id} or /api/v3/user?email={email}
Delete UserDELETE/api/v3/user?id={id} or /api/v3/user?email={email}
Upsert UserPOST/api/v3/user/upsert
Bulk Create UsersPOST/api/v3/user/bulk
Bulk Update UsersPUT/api/v3/user/bulk
Bulk Partial UpdatePATCH/api/v3/user/bulk
Bulk Upsert UsersPOST/api/v3/user/bulk/upsert
Fetch Bulk StatusGET/api/v3/user/bulk/status?processId={processId}
Fetch Calling UserGET/api/v3/me

SCIM API

OperationMethodPath
Create UserPOST/api/v3/scim/Users
List/Search UsersGET/api/v3/scim/Users
Fetch User by IDGET/api/v3/scim/Users/{userId}
Fetch User by EmailGET/api/v3/scim/email/{emailId}
Replace UserPUT/api/v3/scim/Users/{userId}
Partially Update UserPATCH/api/v3/scim/Users/{userId}
Delete UserDELETE/api/v3/scim/Users/{userId}
Update UserPUT/api/v3/scim/update/{userId}
Upsert UserPOST/api/v3/scim/upsert
Bulk Upsert UsersPOST/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 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.

HeaderValuePurpose
AuthorizationBearer {{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-Typeapplication/jsonDeclares request body media type
Acceptapplication/jsonDeclares 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

ParameterRequired/OptionalDescriptionType
idConditionalUser identifier. Specify either id or email.String
emailConditionalUser email address. Specify email email or id.String

Example Request

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

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

ParameterRequired/OptionalDescriptionType
idConditionalUser identifier. Specify either id or email.String
emailConditionalUser 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

ParameterRequired/OptionalDescriptionType
idConditionalUser identifier. Specify either id or email.String
emailConditionalUser email address. Specify email email or id.String

Example Request

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.

MethodPurpose
POST /api/v3/user/bulkBulk create users
PUT /api/v3/user/bulkBulk replace users
PATCH /api/v3/user/bulkBulk partially update users
POST /api/v3/user/bulk/upsertBulk upsert users

Request Parameters

FieldTypeDescription
recordsarrayThe users to process. Send full user objects for create, replace, and upsert; send partial update objects for patch.
callbackUrlstringURL that Sprinklr calls when the job finishes.
callbackUrlHeadersobjectOptional HTTP headers to send with the callback request, as name/value string pairs.
syncProcessingbooleanWhen 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

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}
ParameterRequired\OptionalDescriptionType
processIdRequiredProcess 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.

ParameterInTypeDescription
startIndexqueryinteger1-based index of the first result
countqueryintegerMaximum results per page
filterquerystringSCIM filter expression
sortByquerystringSort field
sortOrderquerystringSort 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.

MethodPurposeBody
GETGet user by id—
PUTReplace userUser object
PATCHPatch userSCIM patch document
DELETEDelete 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.

FieldTypeDescription
schemasarray of stringThe SCIM schema URIs this resource conforms to.
userNamestringThe unique identifier for the user in Sprinklr. This is the user's email address.
nameobjectName of the user.
emailsarrayThe user's email addresses.
phoneNumbersarrayThe user's phone numbers.
photosarrayUser photos.
activebooleanWhether the user is active. A user is created in an inactive state unless you set this to true.
localestringLocale of the user.
globalAttributesobjectPartner-level attributes that cannot be mapped to SCIM attributes.
clientAttributesarrayClient-level attributes.
userSeatsarrayThe licensed seats assigned to the user.
isSpaceUserbooleanWhether the user is a space user.
enterpriseUserobjectEnterprise user attributes.
userAssignmentConfigobjectUser assignment configuration, including routing skills, languages, channels, and capacities.
userVoiceConfigobjectUser voice configuration.
currentLoginStatusstringCurrent login status. Set by the platform.
upcomingStatusstringUpcoming status. Set by the platform.
supervisorTeamIdsarray of stringSupervisor team ids.
recordingShareConfigsarrayRecording share configurations.
customPropertiesMetadataarrayCustom 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:

FieldTypeDescription
idstringUser id
externalIdstringExternal id from the SCIM client
lyearnIdstringLearning platform id
userNamestringEmail id / SCIM userName
nameobjectDisplay name
emailsarrayEmails
phoneNumbersarrayPhone numbers
photosarrayPhotos
activebooleanActive flag
localestringLocale
globalAttributesobjectGlobal attributes update
clientAttributesarrayClient attributes update
isSpaceUserbooleanSpace user flag
metaobjectSCIM meta
enterpriseUserobjectEnterprise user attributes
userSeatsarrayUser seats
userAssignmentConfigUpdateRequestobjectAssignment config update
userVoiceConfigUpdateRequestobjectVoice config update
userAvailabilityStatusstringAgent 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:

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

Each error can include:

ParameterDescription
idError identifier
codeError code
messageError message or key

Status codes

CodeMeaningWhat to do
200SuccessRead data.
400Bad RequestMalformed payload, invalid field value, or a missing identifier. Check the errors array.
401UnauthorizedMissing, expired, or superseded credentials. Both Authorization and Key must be present. Generating a new token for an API key invalidates the previous one.
403ForbiddenCredentials are valid but the owning user lacks permission. Check the key owner's role and whether they can act in the target client environment.
404Not FoundNo 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

OperationV3 SCIM EndpointV3 User API Endpoint
Create UserPOST /api/v3/scim/UsersPOST /api/v3/user
Upsert UserPOST /api/v3/scim/upsertPOST /api/v3/user/upsert
Bulk UpsertPOST /api/v3/scim/bulk-upsertPOST /api/v3/user/bulk/upsert
Fetch UserGET /api/v3/scim/Users/{userId}GET /api/v3/user?id=
Fetch User by EmailGET /api/v3/scim/email/{emailId}GET /api/v3/user?email=
Update UserPUT /api/v3/scim/Users/{userId}PUT /api/v3/user?id=
Delete UserDELETE /api/v3/scim/Users/{userId}DELETE /api/v3/user?id=
Partial User UpdatePUT /api/v3/scim/update/{userId}PATCH /api/v3/user