# Lookup API V3 — Developer Guide

- **Applies to:** Sprinklr Lookup API V3 (`/api/v3/lookup`)
- **V2 API reference:** [Lookup | Sprinklr Developer Portal](https://dev.sprinklr.com/lookup)


## 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**:

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

### 1.1 Choosing between the two operations

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


## 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](https://dev.sprinklr.com/apis) 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.

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


## 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`)

| Parameter | Sub-parameter | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `lookupType` |  | Required | String | Entity family to resolve. Required for lookup endpoint requests. See [§7](#7-supported-lookup-types). |
| `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. |


> `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

```bash
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`

```bash
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)*

```json
{
  "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`)

| 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](#7-supported-lookup-types). |
|  | `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).

#### Request

```bash
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)*

```json
{
  "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`

```bash
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/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` |


## 5. Response format and status codes

### 5.1 Response envelopes

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

```json
{
  "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 |


### 5.2 Response codes

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

## 6. V2 → V3 migration

### 6.1 Endpoint mapping

| V2 | V3 |
|  --- | --- |
| `POST /api/v2/lookup` ([Lookup By Id](https://dev.sprinklr.com/lookup-by-id)) | `POST /api/v3/lookup` |
| `POST /api/v2/lookup/byDimensions` ([Lookup By Dimension](https://dev.sprinklr.com/lookup-by-dimension)) | `POST /api/v3/lookup/dimensions` |


### 6.2 What changes

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


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

## 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.*