Lookup caches API endpoints

Anitha Abraham

Updated February 26, 2025 10:16

Relative URI	Method	Success code	Description
/lookupcaches	GET	200	Gets a list of all the lookup caches in your account.
/lookupcaches/<_lookupcacheId>	GET	200	Gets high-level fields such as name, description, etc from a lookup cache in your account.
/lookupcaches/<_lookupcacheId>	DELETE	200	Deletes a lookup cache from your account.
/lookupcaches/<_lookupcacheId>/getData	POST	200	Gets data from a lookup cache in your account. When no request body is sent Returns page-wise data from a lookup cache. A maximum of 1000 keys or up to 5 MB can be returned as a response. If the data exceeds 1000 keys or 5 MB, `nextPageURL` is returned. When an array of keys is sent Accepts an array of keys in the request body, and returns key-value pairs in the response. If the data returned is >5 MB, an error occurs. When the body param "startsWith" for keys is sent Accepts the body param in the request `{"startsWith": "abc"}`, and returns keys starting with the given characters and their values in the the response. When the query param "startAfterKey" is sent `v1/lookupcaches/<_lookupcacheId>/getdata?startAfterKey=abcKey` Returns data for key-values pairs starting after the given key, "abcKey" .
/lookupcaches/<_lookupcacheId>/data	POST	200	Upserts data to a lookup cache in your account. The request body accepts an array of keys to be upserted. Maximum limit of 1000 entries as key-value pairs `({ "keys": [<string>] })` or 5 MB in the request body.
/lookupcaches/<_lookupcacheId>/data	DELETE	200	Deletes the data from a lookup cache in your account. The request body accepts an array of keys to be deleted. Maximum limit: 1000 keys provided as array strings `({ "keys": [<string>] })` in the request body
/lookupcaches/<_lookupcacheId>/data/purge	DELETE	204	Purges the data from a lookup cache in your account

Authentication

Lookup cache APIs, like other integrator.io APIs, use API tokens for authentication. For more information, see Getting started with standard REST API.

Common error codes and what they mean

Code	What it means	Possible reason
400	Bad Request	Invalid reference or value
401	Unauthorized	Permissions not adequate
403	Forbidden	Bad request CSRF
404	Not Found Error	Invalid reference or value
415	Unsupported Media	Content-Type should match application/json
422	Unprocessable Entity	Required field not present

Examples

Given below are a few examples:

Example 1: Gets data from a lookup cache

Request

POST /v1/lookupcaches/<_lookupcacheId>/getData

Parameters

Name	Description
_lookupCacheId *	The lookup cache ID

Request body

{
  "keys": [
    "keyExist",
    "keyExist1",
    "keyExist2"
  ]
}

Sample response

{
  "data": [
    {
      "key": "keyExist",
      "value": "value1"
    },
    {
      "key": "keyExist1",
      "value": "value2"
    },
    {
      "key": "keyExist2",
      "value": {
        "value3": "value4"
      }
    }
  ],
  "success": true
}

Example 2: Adds data to a lookup cache