- Applies to: Sprinklr Lookup API V3 (
/api/v3/lookup) - V2 API reference: Lookup | Sprinklr Developer Portal
The Lookup API resolves Sprinklr identifiers and reference values into human-readable entity details. It answers the question "what is the entity behind this ID, or what IDs match this search term?" — for example, resolving an assignment-skill ID into a skill name, resolving a custom field ID (_c_<hex>) taken from a report response into its readable name, or searching Facebook/Instagram places to obtain a locationId before publishing a post.
V3 exposes the API as two POST operations on the /lookup resource:
| Operation | Method | Path | Request schema | Use it when |
|---|---|---|---|---|
| Generic lookup (by ID) | POST | /api/v3/lookup | LookupRequest | You already hold the entity IDs and want their details |
| Lookup by dimensions (by search query) | POST | /api/v3/lookup/dimensions | DimensionsLookupDTO | You have a search string, not an ID, and want matching entities with pagination |
The path change from V2 is limited to the version segment and the dimensions sub-path: V2 used /api/v2/lookup and /api/v2/lookup/byDimensions; V3 uses /api/v3/lookup and /api/v3/lookup/dimensions.
For more details refer to the Lookup V3 API reference.
| You have | Operation |
|---|---|
| A list of concrete IDs (account IDs, case IDs, skill IDs, custom field IDs) | POST /api/v3/lookup with lookupType + keys[] |
| A partial name or search term (a place name, an account name) | POST /api/v3/lookup/dimensions with lookupType + query + page |
| Both, for different entity families, in one round trip | POST /api/v3/lookup/dimensions — dimensionLookups[] accepts multiple lookup objects in a single request |
All API calls are sent to the production endpoint:
https://api3.sprinklr.com/{env}/api/v3So the lookup resources are:
https://api3.sprinklr.com/{env}/api/v3/lookup
https://api3.sprinklr.com/{env}/api/v3/lookup/dimensionsReplace {env} with your assigned environment identifier (prod0, prod2, prod11, and so on — see APIs | Sprinklr Developer Portal for the environment list).
All Lookup API calls are authenticated with OAuth 2.0. See the Authorize section on the developer portal for access-token generation and the Getting Started guide for API key generation.
| Header | Value | Purpose | Required on |
|---|---|---|---|
Authorization | ****** | Credential used by the API to authenticate a user with the server | All requests |
Key | {{apiKey}} | API key that authenticates the application with the server | All requests |
Content-Type | application/json | Declares the request body media type | All requests (both operations are POST) |
Accept | application/json | Declares the acceptable response type | All requests |
Both operations are POST requests, but neither creates or modifies data — the request body carries the query, not a resource to persist.
POST /api/v3/lookup
Returns details of entities identified by the IDs supplied in keys, for the entity family named by lookupType.
| Parameter | Sub-parameter | Required | Type | Description |
|---|---|---|---|---|
lookupType | Required | String | Entity family to resolve. Required for lookup endpoint requests. See §7. | |
keys | Required | Array[String] (String, Integer per V2) | Identifiers related to the lookupType. Example: if lookupType is ACCOUNT_ID, keys holds account IDs. | |
extraParams | Optional | Object | Additional parameters required by the given lookup type. Required when lookupType is CUSTOM_FIELD. | |
assetType | Required (within extraParams) | String | Asset type associated with the custom field. If the custom field applies to multiple asset types, supply any one of the applicable asset types. |
lookupTypediffers from use case to use case. For example, when the lookup type isASSIGNMENT_SKILL, the call resolves the skill IDs supplied inkeysinto skill names.
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/lookup' \
-H 'Authorization: ******' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"lookupType": "ACCOUNT_ID",
"keys": [
"600044848"
]
}'curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/lookup' \
-H 'Authorization: ******' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"lookupType": "ASSIGNMENT_SKILL",
"keys": [
"5fbfc48accb38e37b031cb65",
"5e9fdead02ec853ab5c73c78",
"5eaff2c302ec853f2150258f"
]
}'Response (illustrative example, based on the V2 reference payload and the V3 APIResponse envelope)
{
"data": {
"5fbfc48accb38e37b031cb65": "skill 1",
"5e9fdead02ec853ab5c73c78": "skill 2",
"5eaff2c302ec853f2150258f": "skill 3"
},
"errors": []
}data is an ID-keyed map, not an array: each requested key maps to its resolved value. An ID that cannot be resolved is simply absent from the map — iterate your input list against the response keys rather than assuming positional alignment.
POST /api/v3/lookup/dimensions
Returns entities that match a search string for one or more lookup types, with per-lookup pagination. For example, searching with FACEBOOK_PLACES_LOOKUP returns a unique location ID for every matching location.
| Parameter | Sub-parameter | Required | Type | Description |
|---|---|---|---|---|
filters | Required | Array | Creates a new array of elements that pass the test implemented within the provided function. Send [] when no filtering is needed. | |
dimensionLookups | Required | Array[Object] | Array of objects that contain the query details. One entry per lookup. | |
lookupType | Required | String | Entity family to search. Required for lookup endpoint requests. See §7. | |
query | Required | String | The first four letters of the location you are looking for (V2 guidance for place lookups; for other lookup types, the search term for the entity name). | |
page | page: Optional, size: Required | Object (Integer members) | Limits the number of items in the response when the result set is large. page — the page number you want in the response; if no page number is provided, the first page is returned by default. size — the maximum number of results shown in a response. | |
additional | Optional | Object (String values) | Additional key–value attributes for the lookup, per DimensionLookupDTO in sprinklr-v3.yaml. Not documented on the V2 page. |
filters[] entries follow the ExternalFilter schema: dimensionName (String), filterType (String), values (Array), details (Object).
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/lookup/dimensions' \
-H 'Authorization: ******' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"filters": [],
"dimensionLookups": [
{
"lookupType": "FACEBOOK_PLACES_LOOKUP",
"query": "cali",
"page": {
"page": 0,
"size": 1
}
}
]
}'Response (illustrative example)
{
"data": {
"FACEBOOK_PLACES_LOOKUP": {
"hasMore": true,
"result": [
{
"id": "84115026000887",
"name": "ABC",
"address": "United States",
"location": {
"city": "Denver",
"state": "CO",
"country": "United States",
"zip": "80219",
"latitude": 39.71184,
"longitude": -105.02464,
"street": "253 S Federal Blvd"
}
}
]
}
},
"errors": []
}For Instagram place lookups, the lookup type is FACEBOOK_PLACES_LOOKUP. Once you have the locationId, pass it in the publishing request payload to attach the location to a post.
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/lookup/dimensions' \
-H 'Authorization: ******' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"filters": [],
"dimensionLookups": [
{
"lookupType": "ACCOUNT_ID",
"query": "Twitter",
"page": {
"page": 0,
"size": 1
}
}
]
}'The ACCOUNT_ID result objects carry account attributes including id, type, displayName, channelId, channelType, owner, spaceId, partnerCustomProperties, permalink, active, deactivationReason, deleted, createdTime, and modifiedTime.
Custom field lookups resolve user-defined metadata fields (for example, region, business unit, priority level):
- Identify the custom field ID in the report response.
- Extract the
_c_<alphanumeric_id>value from the report response. - Resolve that ID through the Lookup API to obtain its readable name and values.
POST /api/v3/lookup | POST /api/v3/lookup/dimensions | |
|---|---|---|
| Input | lookupType + keys[] (known IDs) | lookupType + query (search string) |
| Request schema | LookupRequest | DimensionsLookupDTO |
| Multiple lookup types per call | No — one lookupType per request | Yes — one entry per dimensionLookups[] element |
| Pagination | Not documented | page.page / page.size, with hasMore per lookup type |
| Extra configuration | extraParams.assetType (required for CUSTOM_FIELD) | filters[], additional |
POST /api/v3/lookup declares the standard V3 APIResponse envelope:
{
"data": { },
"errors": [],
"metadata": { }
}| Field | Type | Description |
|---|---|---|
data | Object | Lookup results. Keyed by requested ID for the generic lookup; keyed by lookup type for the dimensions lookup. |
errors | Array[Error] | Error objects (empty when there are no errors) |
errors[].id | String | 24-character hex ObjectId (required) |
errors[].code | Integer | Error code |
errors[].message | String | Dotted error key, for example account.not.found |
metadata | Object | Response metadata. ResponseMetadata is declared with no properties in sprinklr-v3.yaml. |
POST /api/v3/lookup/dimensions declares LookupResponse as its 200 schema:
| Field | Type | Description |
|---|---|---|
hasMore | Boolean | Whether more results are available for the lookup |
result | Array[Object] | Matching entities |
totalHits | Integer (int32) | Total number of matches |
| HTTP Code | Scenario | Description |
|---|---|---|
200 OK | Success | Lookup completed and results returned |
400 Bad Request | Invalid parameters | Missing or invalid lookupType, keys, or dimensionLookups |
401 Unauthorized | Authentication failed | Invalid or missing Authorization token |
403 Forbidden | Insufficient permissions | Caller lacks permission on the entity being resolved |
404 Not Found | Not found | No matching entity for the request |
400, 401, 403, and 404 are the error responses declared for both operations in sprinklr-v3.yaml. No 500 response is declared for the Lookup paths.
| V2 | V3 |
|---|---|
POST /api/v2/lookup (Lookup By Id) | POST /api/v3/lookup |
POST /api/v2/lookup/byDimensions (Lookup By Dimension) | POST /api/v3/lookup/dimensions |
| Aspect | API V2 | API V3 | Impact |
|---|---|---|---|
| Base path | /api/v2/lookup | /api/v3/lookup | Update the version segment |
| Dimensions sub-path | byDimensions | dimensions | Rename required — the old sub-path does not carry over |
| Request body — generic lookup | lookupType, keys, extraParams | Unchanged (LookupRequest) | No payload change |
| Request body — dimensions lookup | filters, dimensionLookups[].lookupType / query / page | Unchanged, plus optional dimensionLookups[].additional | No payload change; additional is new |
| Response envelope | data / errors | data / errors / metadata (APIResponse) | Add tolerance for the metadata object |
The following Lookup types are supported: ACCOUNT_ID, USER_ID, CASE_ID, CUSTOM_FIELD, FACEBOOK_PLACES_LOOKUP (for Instagram), ASSIGNMENT_SKILL, LOCATION_IDS, SMART_SEGMENT_ID, and ASSIGNMENT_SKILL.
Generic lookup types
| Lookup type | Resolves |
|---|---|
ACCOUNT_ID | Social accounts |
PARTNER_USERS | Partner users |
USER | Users |
CASE_ID | Cases |
CUSTOM_FIELD | Custom fields |
FACEBOOK_PLACES_LOOKUP | Places / location IDs (only for Instagram) |
SMART_SEGMENT_ID | Smart segments |
CATALOG | Catalogs |
Reporting Suite lookup types
| Entity | Lookup types |
|---|---|
| Ad Set | adSetId, AD_SET_ID_AD_SET, AD_SET_ID_AD_SET_NAME, AD_SET_ID_NAME, AD_SET_CHANNEL_ID, AD_SET_CHANNEL_ID_NAME, AD_SET_ID_LOOKUP |
| Paid Initiative | paidInitiativeId, PAID_INITIATIVE_ID_PAID_INITIATIVE, PAID_INITIATIVE_ID_NAME |
| Ad Variant | adVariantId, AD_VARIANT_ID_AD_VARIANT, AD_VARIANT_ID_NAME |
| Custom Field | Custom field (CF) lookups resolve user-defined metadata fields, for example region, business unit, priority level |
For Reporting Suite, use the entity IDs that appear in exports and field mappings (adSetId, paidInitiativeId, adVariantId) plus custom field lookups.
POST /api/v3/lookup/dimensionswithlookupType: "FACEBOOK_PLACES_LOOKUP"and the first four letters of the place name asquery.- Read
idfrom the result — this is thelocationId. - Pass the
locationIdin the publishing request payload.
A report response returns opaque IDs. Extract the _c_<alphanumeric_id> custom field IDs and resolve them in one POST /api/v3/lookup call with lookupType: "CUSTOM_FIELD", keys set to the extracted IDs, and extraParams.assetType set to the applicable asset type. Cache the resulting ID → name map; custom field names change rarely.
Cases carry skill IDs, not skill names. Send the IDs in one POST /api/v3/lookup call with lookupType: "ASSIGNMENT_SKILL" and read the ID-keyed data map to label your UI. Batch all IDs on the screen into a single request rather than issuing one call per ID.
Call POST /api/v3/lookup/dimensions with lookupType: "ACCOUNT_ID", the typed text as query, and a small page.size (for example 10). Use hasMore to decide whether to show a "load more" control, and increment page.page for the next page.
dimensionLookups[] accepts multiple objects, each with its own lookupType, query, and page. A dashboard that needs both matching accounts and matching smart segments for the same search term can issue a single request instead of two.
All JSON payloads in this guide are illustrative examples derived from the supplied Postman collection, sprinklr-v3.yaml, and the published V2 references. They are not real customer data and are not guaranteed production responses. All credentials are placeholders (******, {{apiKey}}) and must never be committed or logged.