Skip to content

Lookup API V3 — Developer Guide


1. Overview

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:

OperationMethodPathRequest schemaUse it when
Generic lookup (by ID)POST/api/v3/lookupLookupRequestYou already hold the entity IDs and want their details
Lookup by dimensions (by search query)POST/api/v3/lookup/dimensionsDimensionsLookupDTOYou 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.

1.1 Choosing between the two operations

You haveOperation
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 tripPOST /api/v3/lookup/dimensions — dimensionLookups[] accepts multiple lookup objects in a single request

2. Base URLs and environments

All API calls are sent to the production endpoint:

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

So the lookup resources are:

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

Replace {env} with your assigned environment identifier (prod0, prod2, prod11, and so on — see APIs | Sprinklr Developer Portal for the environment list).


3. Authentication and common headers

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.

HeaderValuePurposeRequired on
Authorization******Credential used by the API to authenticate a user with the serverAll requests
Key{{apiKey}}API key that authenticates the application with the serverAll requests
Content-Typeapplication/jsonDeclares the request body media typeAll requests (both operations are POST)
Acceptapplication/jsonDeclares the acceptable response typeAll requests

4. Lookup operations

Both operations are POST requests, but neither creates or modifies data — the request body carries the query, not a resource to persist.

4.1 Generic lookup — resolve entities by ID

POST /api/v3/lookup

Returns details of entities identified by the IDs supplied in keys, for the entity family named by lookupType.

Request body (LookupRequest)

ParameterSub-parameterRequiredTypeDescription
lookupTypeRequiredStringEntity family to resolve. Required for lookup endpoint requests. See §7.
keysRequiredArray[String] (String, Integer per V2)Identifiers related to the lookupType. Example: if lookupType is ACCOUNT_ID, keys holds account IDs.
extraParamsOptionalObjectAdditional parameters required by the given lookup type. Required when lookupType is CUSTOM_FIELD.
assetTypeRequired (within extraParams)StringAsset type associated with the custom field. If the custom field applies to multiple asset types, supply any one of the applicable asset types.

lookupType differs from use case to use case. For example, when the lookup type is ASSIGNMENT_SKILL, the call resolves the skill IDs supplied in keys into skill names.

Request

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

Request — lookupType = ASSIGNMENT_SKILL

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.


4.2 Lookup by dimensions — search entities by query

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.

Request body (DimensionsLookupDTO)

ParameterSub-parameterRequiredTypeDescription
filtersRequiredArrayCreates a new array of elements that pass the test implemented within the provided function. Send [] when no filtering is needed.
dimensionLookupsRequiredArray[Object]Array of objects that contain the query details. One entry per lookup.
lookupTypeRequiredStringEntity family to search. Required for lookup endpoint requests. See §7.
queryRequiredStringThe 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).
pagepage: Optional, size: RequiredObject (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.
additionalOptionalObject (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).

Request

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.

Request — lookupType = ACCOUNT_ID

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.

4.2.1 Resolving custom fields from report responses

Custom field lookups resolve user-defined metadata fields (for example, region, business unit, priority level):

  1. Identify the custom field ID in the report response.
  2. Extract the _c_<alphanumeric_id> value from the report response.
  3. Resolve that ID through the Lookup API to obtain its readable name and values.

4.3 Operation comparison

POST /api/v3/lookupPOST /api/v3/lookup/dimensions
InputlookupType + keys[] (known IDs)lookupType + query (search string)
Request schemaLookupRequestDimensionsLookupDTO
Multiple lookup types per callNo — one lookupType per requestYes — one entry per dimensionLookups[] element
PaginationNot documentedpage.page / page.size, with hasMore per lookup type
Extra configurationextraParams.assetType (required for CUSTOM_FIELD)filters[], additional

5. Response format and status codes

5.1 Response envelopes

POST /api/v3/lookup declares the standard V3 APIResponse envelope:

{
  "data": { },
  "errors": [],
  "metadata": { }
}
FieldTypeDescription
dataObjectLookup results. Keyed by requested ID for the generic lookup; keyed by lookup type for the dimensions lookup.
errorsArray[Error]Error objects (empty when there are no errors)
errors[].idString24-character hex ObjectId (required)
errors[].codeIntegerError code
errors[].messageStringDotted error key, for example account.not.found
metadataObjectResponse metadata. ResponseMetadata is declared with no properties in sprinklr-v3.yaml.

POST /api/v3/lookup/dimensions declares LookupResponse as its 200 schema:

FieldTypeDescription
hasMoreBooleanWhether more results are available for the lookup
resultArray[Object]Matching entities
totalHitsInteger (int32)Total number of matches

5.2 Response codes

HTTP CodeScenarioDescription
200 OKSuccessLookup completed and results returned
400 Bad RequestInvalid parametersMissing or invalid lookupType, keys, or dimensionLookups
401 UnauthorizedAuthentication failedInvalid or missing Authorization token
403 ForbiddenInsufficient permissionsCaller lacks permission on the entity being resolved
404 Not FoundNot foundNo 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.


6. V2 → V3 migration

6.1 Endpoint mapping

V2V3
POST /api/v2/lookup (Lookup By Id)POST /api/v3/lookup
POST /api/v2/lookup/byDimensions (Lookup By Dimension)POST /api/v3/lookup/dimensions

6.2 What changes

AspectAPI V2API V3Impact
Base path/api/v2/lookup/api/v3/lookupUpdate the version segment
Dimensions sub-pathbyDimensionsdimensionsRename required — the old sub-path does not carry over
Request body — generic lookuplookupType, keys, extraParamsUnchanged (LookupRequest)No payload change
Request body — dimensions lookupfilters, dimensionLookups[].lookupType / query / pageUnchanged, plus optional dimensionLookups[].additionalNo payload change; additional is new
Response envelopedata / errorsdata / errors / metadata (APIResponse)Add tolerance for the metadata object

7. Supported lookup types

7.1 Generic lookup (POST /api/v3/lookup)

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.

7.2 Dimensions lookup (POST /api/v3/lookup/dimensions)

Generic lookup types

Lookup typeResolves
ACCOUNT_IDSocial accounts
PARTNER_USERSPartner users
USERUsers
CASE_IDCases
CUSTOM_FIELDCustom fields
FACEBOOK_PLACES_LOOKUPPlaces / location IDs (only for Instagram)
SMART_SEGMENT_IDSmart segments
CATALOGCatalogs

Reporting Suite lookup types

EntityLookup types
Ad SetadSetId, 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 InitiativepaidInitiativeId, PAID_INITIATIVE_ID_PAID_INITIATIVE, PAID_INITIATIVE_ID_NAME
Ad VariantadVariantId, AD_VARIANT_ID_AD_VARIANT, AD_VARIANT_ID_NAME
Custom FieldCustom 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.


8. Use cases

8.1 Tag a post with an Instagram location

  1. POST /api/v3/lookup/dimensions with lookupType: "FACEBOOK_PLACES_LOOKUP" and the first four letters of the place name as query.
  2. Read id from the result — this is the locationId.
  3. Pass the locationId in the publishing request payload.

8.2 Turn a report export into readable labels

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.

8.3 Resolve assignment skills on a case view

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.

8.4 Build an account picker with type-ahead

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.

8.5 Resolve several entity families in one round trip

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.