Standard Entity API 3.0

Standard entities are Sprinklr's pre-defined structured objects. They work like cases and messages, but they exist so you can store and manage your own external data inside the platform using a defined schema.

The Standard Entity API 3.0 gives you full CRUD across three layers: the definition that describes an entity type, the fields that make up its schema, and the records that hold your data.

A standard entity has three parts, and every integration works with all three:

Definitions are created and managed in Entity Studio. This API reads them; it does not create them. Fields and records are fully manageable through the API.

Related Knowledge Base Article Entity Studio - An Overview

The platform uses two prefixes consistently, and recognising them makes the API much easier to read:

Three identifiers appear across this API. They are not interchangeable:

The Standard Entity API 3.0 is available on Core, Care, and Lite editions and is enabled by default. No configuration is required.

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

Replace {env} with the environment your Sprinklr workspace is hosted in:

prod, prod0, prod2, prod3, prod4, prod5, prod6, prod8, prod11, prod12, prod15, prod16, prod17, prod18, prod19, prod21, prod25

Calling a different environment with otherwise valid credentials returns 401 Unauthorized. If you are seeing unexplained 401 responses, check the environment first.

Every request must carry both an access token and an API key. Sending only one of them is the most common cause of a 401 for developers new to the platform.

Each API key supports one active token pair. Generating a new access token invalidates the previous one. If two services share an API key, refreshing the token for one will break the other. Give each integration its own key.

A typical integration works top-down:

1. Read the definition to learn what entity type you are working with.
2. Read the fields to learn the schema — what columns exist, which are mandatory, what types they hold.
3. Add any custom fields your integration needs.
4. Read and write records against that schema.

You only need steps 1 to 3 once, at setup. Steps 4 runs continuously.

The following paths and methods are supported:

Retrieve the definition of a standard platform entity by entity type.

GET /api/v3/standardEntity/definition

Request

curl -X GET \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/definition?entityType=_s_Consent' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Accept: application/json'

Response fields

Fetch fields by ID or by field name, with pagination.

GET /api/v3/standardEntity/field

Supply exactly one identifier — fieldId or fieldName, never both and never neither. Supplying both returns 400; supplying neither also returns 400.

Field names are unique only within a definition, so when you look a field up by fieldName you must also send entityDefinitionId.

Request

curl -X GET \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?fieldName=_c_ConsentName&entityDefinitionId=_s_Consent' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Accept: application/json'

Returns an array of field objects. See Field reference.

POST /api/v3/standardEntity/field

Send the field definition in the request body. There are no query parameters.

Request

curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiName": "_c_ConsentName",
    "name": "User Consent Name",
    "type": "TEXT",
    "entityDefinitionId": "_s_Consent"
  }'

Returns the created field, including its generated id. Store that id — it is the most reliable way to reference the field later.

PUT /api/v3/standardEntity/field

Send the updated field object in the request body. Identify the field by either fieldId or fieldName, not both.

Request

curl -X PUT \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?fieldName=_c_ConsentName&entityDefinitionId=_s_Consent' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiName": "_c_ConsentName",
    "name": "Consent Full Name",
    "type": "TEXT",
    "entityDefinitionId": "_s_Consent"
  }'

DELETE /api/v3/standardEntity/field

Request

curl -X DELETE \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?id=0000000000000000000000a1,0000000000000000000000a2&entityDefinitionId=_s_Consent' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}'

Deleting a field removes it from the definition. Data stored in that field on existing records is no longer retrievable through the API. Confirm before you delete.

Fetch records by entity ID, record ID, primary key, or primary key prefix.

GET /api/v3/standardEntity/record

Always send entityType, plus exactly one of entityId, recordId, or primaryKey. entityType tells the platform which definition to look in; the identifier tells it which record.

Primary key lookup only works on entity types that have primary key columns defined. Types without them return 400.

Request

curl -X GET \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=6321e6684eed2b006dc0abdb' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Accept: application/json'

POST /api/v3/standardEntity/record

Send the record in the request body. There are no query parameters.

Request

curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "_s_Consent",
    "entityId": "consent-jane-doe-001",
    "identityType": "PHONE",
    "identityId": "15550100",
    "channel": "FACEBOOK"
  }'

The exact payload depends on the definition. type always carries the definition id. The remaining fields are the fields defined on that definition — read them first with Fetch fields, and note which are marked mandatory.

Some fields on a definition are primary fields. On _s_Consent, these are identityType, identityId, and channel.

At least one primary field must be present on every create and update, and the primary fields you send on update must match those you sent on create. Changing a primary field does not edit the record — it fails to match the original record entirely. This is the single most common source of updates that appear to do nothing.

If you do not supply an entityId, the platform generates one and returns it in the response. Setting a meaningful entityId yourself — one derived from your own system's key — makes every later lookup, update, and upsert simpler.

PUT /api/v3/standardEntity/record

PUT replaces the record with the body you send. Include the primary fields, and make sure they match the values used at create time.

curl -X PUT \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=consent-jane-doe-001' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "_s_Consent",
    "entityId": "consent-jane-doe-001",
    "identityType": "PHONE",
    "identityId": "15550100",
    "channel": "FACEBOOK"
  }'

PATCH /api/v3/standardEntity/record

Takes the same query parameters as PUT, but the body names only the fields you want to change.

Request

curl -X PATCH \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=consent-jane-doe-001' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "updateFields": [
      { "fieldName": "_c_ConsentName", "value": "Jane Doe", "op": "UPDATE" }
    ]
  }'

Prefer PATCH over PUT for routine writes. It touches only the fields you name, it does not require you to reconstruct the whole record, and it avoids accidentally clearing a field you forgot to include.

POST /api/v3/standardEntity/record/upsert

Creates the record if it does not exist, updates it if it does. Send the record in the request body; there are no query parameters.

curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record/upsert' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "_s_Consent",
    "entityId": "consent-jane-doe-001",
    "identityType": "PHONE",
    "identityId": "15550100",
    "channel": "FACEBOOK"
  }'

Upsert is the right choice for synchronisation jobs, where you do not know or do not care whether a record already exists.

DELETE /api/v3/standardEntity/record

curl -X DELETE \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=consent-jane-doe-001,consent-jane-doe-002' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}'

When you delete several records in one call, some may succeed while others fail. The response reports both outcomes:

{
  "data": [
    { "id": "consent-jane-doe-001", "message": "Successfully Deleted" }
  ],
  "errors": [
    {
      "id": "0000000000000000000000a1",
      "code": 404,
      "message": "StandardEntity not found for entityId: 'consent-jane-doe-002'. Verify the standardEntity exists and you have access permissions."
    }
  ]
}

Always inspect both data and errors after a multi-record delete. The HTTP status alone does not tell you whether every record was removed.

Check mandatory before writing records — a mandatory field must be present in every record write for that definition.

All responses use the standard envelope:

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

Each entry in errors has this shape:

The Standard Entity API returns detailed, specific error messages that name the offending parameter and state the constraint. Log them and show them to your users rather than replacing them with a generic message.

API 2.0 carried every identifier in the URL path. API 3.0 moves every identifier into a query parameter, leaving stable, predictable resource paths. Field and payload names are unchanged.

There is also a spelling change that is easy to overlook: the path segment was standard-entity in API 2.0 and is standardEntity in API 3.0.

Fourteen API 2.0 endpoints become eleven API 3.0 operations. Two consolidations do the work:

• The three record fetches — by entity id, by primary key, by primary key prefix — become one GET /standardEntity/record distinguished by which query parameter you send.
• The two upserts — by entity id and by primary key — become one POST /standardEntity/record/upsert.

curl -X GET \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?entityDefinitionId=_s_Consent&pageNumber=0&pageSize=100' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}'

Look at mandatory and type on every field returned. Those two properties tell you exactly what a valid record payload must contain.

curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiName": "_c_LoyaltyTier",
    "name": "Loyalty Tier",
    "type": "TEXT",
    "entityDefinitionId": "_s_Consent"
  }'

Use POST /standardEntity/record/upsert with an entityId derived from your own system's primary key. Every sync run then becomes idempotent — no existence check, no branch between create and update.

Use PATCH with a single entry in updateFields. This is safer than PUT, which replaces the whole record.

Start at pageNumber=0, request pageSize=100, and stop when a page returns fewer than 100 results.

• Set your own entityId at create time. Derive it from your source system's key. Every later lookup, update, upsert, and delete becomes trivial, and your integration stops needing a local id mapping table.
• Read the field list before you write records. The mandatory flag is the authoritative list of what a payload must contain — do not hard-code it.
• Prefer PATCH to PUT. It avoids clearing fields you forgot to include and avoids the primary-field matching trap.
• Prefer upsert for synchronisation jobs. It removes an entire round trip and a race condition.
• Never change a primary field on an update. It will not update the record.
• Give every integration its own API key. Sharing a key across services means refreshing one token silently breaks the others.
• Cache the definition and field list. They change rarely. Re-reading them on every record write is wasted latency.
• Store the field id returned at create time. Referencing a field by id avoids having to send entityDefinitionId alongside fieldName on every call.
• Check data and errors on every multi-id call. Partial success is a normal outcome, not an edge case.
• Batch conservatively. Comma-separated id lists are supported, but keep them to a reasonable size so that a partial failure is easy to interpret and retry.