Skip to content

Standard Entity API 3.0

Standard entities are predefined data objects available in Sprinklr. Use Standard Entity API V3 to retrieve standard entity definitions and manage their fields and records programmatically. Standard entities are also available through Entity Studio, where you can view and manage structured business data in Sprinklr.

Standard Entity API provides operations for three resources:

ResourceDescriptionSupported Operations
DefinitionDescribes a standard entity typeRead
FieldDefines a field associated with the entityCreate, read, update, delete
RecordStores data associated with the entityCreate, read, update, patch, upsert, delete

The V3 API reference exposes GET /standardEntity/definition, CRUD operations on /standardEntity/field, and CRUD plus upsert operations on /standardEntity/record.

Related Knowledge Base Article Entity Studio - An Overview

Base URL

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

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.

The resources covered in this guide are:

/standardEntity/definition
/standardEntity/field
/standardEntity/record
/standardEntity/record/upsert

Authentication

Standard Entity API V3 requires bearer-token and API-key authentication. The definition, field, and record API references specify both bearerAuth and apiKeyAuth.

HeaderValueRequired
AuthorizationBearer {{accessToken}}Yes
Key{{apiKey}}Yes
Content-Typeapplication/jsonRequests with a body
Acceptapplication/jsonRecommended

Entity Definitions

An entity definition describes the standard entity, including its name, description, base definition, permission settings, and other metadata. Standard Entity API V3 provides a read operation for retrieving a definition by entityType.

Fetch a definition

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

GET /api/v3/standardEntity/definition

Query Parameter | Parameter | Type | Required | Description | |---|---|---|---|---| | entityType | string | Yes | Type of standard entity to retrieve, for example _s_Consent. Supported entity Ids: _s_Consent, _s_PublishingQueue, _s_ConsentCatalogue, _s_PriceBook, _s_PublisherSettings |

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

The response can include fields such as id, name, pluralName, description, baseDefinitionId, icon, permissionEnabled, createdTime, and modifiedTime.


Standard Entity Fields Operations

Fields define the information stored for a standard entity. Standard Entity API V3 supports retrieving, creating, updating, and deleting fields.

Fetch fields

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

GET /api/v3/standardEntity/field

Query Parameters

ParameterInTypeRequiredDescription
fieldIdquerystringConditionalComma-separated list of field IDs
fieldNamequerystringConditionalField name
entityDefinitionIdquerystringConditionalThe definition the field belongs to. Required when identifying a field by fieldName
pageNumberqueryintegerNoPage number, 0-based
pageSizequeryintegerNoNumber of results per page. Maximum 100

The API supports fetching fields by ID or field name and listing fields with pagination.

Example: Fetch a field by name

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'

Example: List fields

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}}' \
  -H 'Accept: application/json'

Create a field

POST /api/v3/standardEntity/field

Send the field definition in the request body. The field schema supports properties such as apiName, name, description, type, entityDefinitionId, multivalued, mandatory, picklist configuration, and type-specific information.

Request Parameters

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

Body fieldTypeRequiredDescription
apiNamestringYesThe API name for the field. Prefix custom fields with _c_
namestringNoA human-readable name describing the field's purpose
typestringYesThe field's data type. Supported values include TEXT, DATE, BOOLEAN, NUMBER, DOUBLE, INTEGER
entityDefinitionIdstringYesThe definition to add the field to

Example 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"
  }'

Update a field

PUT /api/v3/standardEntity/field

Identify the field and send the updated field definition in the request body. The field resource exposes PUT as its update operation.

ParameterInTypeRequiredDescription
fieldIdquerystringConditionalThe field ID
fieldNamequerystringConditionalThe field name
entityDefinitionIdquerystringConditionalRequired when using fieldName

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

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

You can identify fields by ID or field name. When using fieldName, provide entityDefinitionId. The delete operation supports a comma-separated list of field IDs.

DELETE /api/v3/standardEntity/field
ParameterInTypeRequiredDescription
idquerystringConditionalComma-separated list of field IDs
fieldNamequerystringConditionalThe field name
entityDefinitionIdquerystringConditionalRequired when using fieldName

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


Standard Entity Records

Records contain the data stored for a standard entity. Standard Entity API V3 supports fetching, creating, replacing, partially updating, upserting, and deleting records.

Fetch records

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

GET /api/v3/standardEntity/record
ParameterInTypeRequiredDescription
entityTypequerystringYesThe definition to search in, for example _s_Consent
entityIdquerystringConditionalComma-separated list of entity IDs
recordIdquerystringConditionalComma-separated list of record IDs
primaryKeyquerystringConditionalPrimary key exact lookup
primaryKeyPrefixquerystringConditionalPrimary key prefix lookup
pageNumberqueryintegerNoPage number, 0-based
pageSizequeryintegerNoNumber of results per page. Maximum 100

The current API supports lookup using entity ID, record ID, primary key, or primary-key prefix. entityType identifies the type of standard entity being queried.

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

The response is an array of record objects and can include fields such as id, entityId, name, type, values, processedValues, tags, archived, entityMetadata, and createdBy.

Create a record

POST /api/v3/standardEntity/record

Send the record in the request body. The values you provide depend on the fields configured for the entity definition.

Example 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"
  }'

Before creating records, retrieve the entity's fields to understand the schema expected by that entity.

Replace a record

Use PUT to update a record:

PUT /api/v3/standardEntity/record

Identify the record using the applicable record identifier and provide the updated record in the request body. PUT is one of the supported operations on the V3 standard-entity record resource.

ParameterInTypeRequiredDescription
entityTypequerystringYesThe definition
entityIdquerystringConditionalThe entity ID
recordIdquerystringConditionalThe record ID

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"
  }'

Partially update a record

Use PATCH when you need to update specific portions of an existing record rather than replacing it. PATCH /standardEntity/record is included in the currently published V3 operations.

PATCH /api/v3/standardEntity/record
Body fieldTypeRequiredDescription
updateFieldsarrayYesList of updates to apply
updateFields[].fieldNamestringYesThe field to change
updateFields[].valueanyYesThe new value
updateFields[].opstringYesThe operation to apply. One of FIND, INSERT, PATCH, UPDATE, DELETE

Example 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" }
    ]
  }'

Upsert a record

Use the upsert operation to create or update a standard entity record:

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. The current V3 API exposes /standardEntity/record/upsert as a separate POST operation with the standard entity record object in the request body.

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"
  }'

Delete records

DELETE /api/v3/standardEntity/record

The record resource supports deletion in addition to its create, retrieve, update, partial-update, and upsert operations.

ParameterInTypeRequiredDescription
entityTypequerystringYesThe definition
entityIdquerystringConditionalComma-separated list of entity IDs
recordIdquerystringConditionalComma-separated list of record IDs
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}}'

Response format and status codes

All responses use the standard envelope:

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

Each entry in errors has this shape:

FieldTypeDescription
idstring24-character hex ObjectId for the error occurrence
codeintegerThe status code
messagestringA dotted error key or a descriptive message

Status codes

The definition, field, and record API references currently advertise the same set of HTTP responses.

CodeMeaningCommon causes
200OKThe request succeeded
400Bad requestThe request is invalid
401UnauthorizedAuthentication failed. Missing, expired, or mismatched credentials; wrong {env} in the URL
403ForbiddenThe authenticated user is not authorized to perform the operation
404Not foundThe requested resource was not found

Migrate from API 2.0

API V3 uses the standardEntity resource namespace:

/api/v3/standardEntity
For V2 - /api/v2/standard-entity/...
For V3 - /api/v3/standardEntity/...

The V3 API consolidates standard entity operations under definition, field, and record resources. When migrating, update the endpoint paths and validate request parameters and response structures against the V3 API reference rather than assuming that the V2 and V3 contracts are identical. The current V3 resources expose one definition operation, four field operations, and record operations for retrieve, create, update, patch, delete, and upsert.


Common Use Cases

Discover the schema before you write anything

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.

Add a custom field to an existing definition

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"
  }'

Keep an external system in sync

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.

Update one field without touching the rest

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

Page through a large result set

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


Best practices

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

Troubleshooting

Message or symptomCauseFix
Valid query params must be provided for standardEntityField retrieval. Provide one from: 'fieldName' or 'id' along with any additional required param as per documentation.No field identifier was sentSend either fieldName (with entityDefinitionId) or the field id
Only one of 'fieldName' or 'id' can be provided for StandardEntityField retrieval. Provided: 'fieldName' and 'id'. Choose the appropriate identifier.Both identifiers were sentSend exactly one
Valid query params must be provided for standardEntity retrieval. Provide one from: 'recordId' or 'entityId' or 'primaryKey' along with any additional required param as per documentation.No record identifier was sentSend one of recordId, entityId, or primaryKey, together with entityType
Invalid 'pageSize' parameter. Must be a positive integer not exceeding 100.Page size above 100, or zero or negativeUse a value from 1 to 100
Invalid 'pageNumber' parameter. Must be a non-negative integer (page number begins with 0).Page number is negative, or your client starts paging at 1Start at 0
Entity type _s_SurveyResponseTranslation does not have primary key columns definedPrimary key lookup attempted on a type with no primary keysLook the record up by entityId or recordId instead
StandardEntityField not found for fieldName: '...'. Verify the standardEntityField exists and you have access permissions.The field does not exist on that definition, or you cannot see itCheck the apiName spelling and the entityDefinitionId; confirm the key owner's permissions
StandardEntity not found for entityId: '...'. Verify the standardEntity exists and you have access permissions.The record does not exist, or you cannot see itConfirm the entityId and entityType; confirm permissions
401 Unauthorized on every callMissing Key header, expired token, or wrong {env}Send both Authorization and Key; confirm the environment; regenerate the token if older than 30 days
401 appearing intermittently across servicesTwo services share one API key, and each token refresh invalidates the otherIssue a separate API key per integration
An update returns success but the record is unchangedA primary field value differs from the one used at create time, so no record matchedKeep identityType, identityId, and channel identical to the create call
A PUT cleared fields you did not intend to changePUT replaces the whole recordUse PATCH with updateFields
A multi-record delete "succeeded" but records remainDelete reports per-record outcomesRead the errors array as well as data