Lookups Actions

Lookups actions store ID mappings between two systems and read them back in either direction. This is essential for implementing the Data Mapping Pattern in your workflows.

The node splits this across two resources: Lookup works with the mappings inside a collection, Lookup Collection works with the collections themselves.

Every mapping has a left side and a right side. Which system is which is your choice, but keep it consistent: the left of orders should always be the same system.

Available Operations

Lookup

Add - Create a mapping between a left value and a right value
Search - Find mappings by left value, right value, or partial text
Get All - Retrieve the mappings stored in a lookup
Remove - Delete a mapping

Lookup Collection

Create - Create a new lookup collection
List - Retrieve all lookup collections available to your app

Add

Create a mapping between a left value and a right value.

Add Configuration

Parameter	Type	Required	Description
Collection Name	String	Yes	Name of the lookup collection holding the mappings. Letters, numbers, hyphens and underscores only, maximum 100 characters.
Left Value	String	Yes	The left-side value in the lookup mapping. Typically an ID from one system.
Right Value	String	Yes	The right-side value in the lookup mapping. Typically the corresponding ID from another system.

The collection must already exist. Create it with Lookup Collection → Create, or from the dashboard.

Add Response

{
  "success": true,
  "data": {
    "id": "lookup_value123",
    "lookupId": "lookup123",
    "left": "ERP_CUST_123",
    "right": "SHOPIFY_CUST_456",
    "createdAt": "2024-01-01T10:00:00.000Z",
    "updatedAt": "2024-01-01T10:00:00.000Z"
  }
}

Search

Find mappings by left value, right value, or partial text.

Search Configuration

Parameter	Type	Required	Description
Collection Name	String	Yes	Name of the lookup collection holding the mappings. Letters, numbers, hyphens and underscores only, maximum 100 characters.
Search Type	Options	Yes	Type of search to perform. "General Search" uses partial matching, while "Left/Right Value" require exact matches.
Search Value	String	Yes	The value to search for. For "General Search" this will match partial text in both left and right values. For "Left/Right Value" this must match exactly.

Search Type offers:

Option	Behaviour
General Search	Search both left and right values using partial matching (contains)
Left Value (Exact)	Search by exact left value match
Right Value (Exact)	Search by exact right value match

Search Response

{
  "success": true,
  "searchType": "left",
  "searchValue": "ERP_CUST_123",
  "lookupName": "customer-mapping",
  "results": [
    {
      "id": "lookup_value123",
      "lookupId": "lookup123",
      "left": "ERP_CUST_123",
      "right": "SHOPIFY_CUST_456",
      "createdAt": "2024-01-01T10:00:00.000Z",
      "updatedAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1
}

A search that matches nothing is not an error: results is empty and count is 0. Branch on count to tell "mapping exists" from "needs creating".

Get All

Retrieve the mappings stored in a lookup.

Get All Configuration

Parameter	Type	Required	Description
Collection Name	String	Yes	Name of the lookup collection holding the mappings. Letters, numbers, hyphens and underscores only, maximum 100 characters.

Under Advanced Settings → Pagination:

Parameter	Type	Required	Description
Page	Number	No	Page number to retrieve (starts from 1).
Items Per Page	Number	No	Maximum number of lookup values to return per page (1-100).
Offset (Advanced)	Number	No	Number of items to skip from the beginning.

Set none of the three and the node reads every page and returns the whole lookup. Set any of them and it returns exactly that page.

Get All Response

{
  "items": [
    {
      "id": "lookup_value123",
      "lookupId": "lookup123",
      "left": "ERP_CUST_123",
      "right": "SHOPIFY_CUST_456",
      "createdAt": "2024-01-01T10:00:00.000Z",
      "updatedAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "totalCount": 1,
    "totalPages": 1
  }
}

Remove

Delete a mapping.

Remove Configuration

Parameter	Type	Required	Description
Collection Name	String	Yes	Name of the lookup collection holding the mappings. Letters, numbers, hyphens and underscores only, maximum 100 characters.
Value to Remove	String	Yes	The lookup value ID, or a left or right value, depending on what the Remove By field is set to. Removing by a left or right value removes every matching row.
Remove By	Options	No	What the Value to Remove field contains: a lookup value ID, a left value, or a right value. Defaults to Lookup Value ID.

Remove By offers Lookup Value ID, Left Value (all matching rows) and Right Value (all matching rows).

Remove Response

The incoming item passes through, with the outcome added. Removing by ID:

{
  "orderId": "12345",
  "removed": true,
  "removedCount": 1,
  "value": "lookup_value123",
  "result": {}
}

Removing by left or right value, where several rows can match:

{
  "orderId": "12345",
  "removed": true,
  "removedCount": 3,
  "left": "ERP_CUST_123"
}

removed is false and removedCount is 0 when nothing matched.

Create

Create a new lookup collection. Found under the Lookup Collection resource.

Create Configuration

Parameter	Type	Required	Description
Collection Name	String	Yes	Name of the lookup collection to create or read. Letters, numbers, hyphens and underscores only, maximum 100 characters.

Under Additional Fields:

Parameter	Type	Required	Description
Description	String	No	Optional human-readable description explaining the purpose of this lookup collection.
Left System	String	No	Optional identifier for the left-side system in the mapping (e.g., "Salesforce", "internal-db").
Right System	String	No	Optional identifier for the right-side system in the mapping (e.g., "HubSpot", "external-api").
Allow Left Duplicates	Boolean	No	Whether to allow duplicate values on the left side. Defaults to true.
Allow Right Duplicates	Boolean	No	Whether to allow duplicate values on the right side. Defaults to true.
Allow Left-Right Duplicates	Boolean	No	Whether to allow the same left-right pair to exist multiple times. Defaults to true.
Strict Checking	Boolean	No	Whether to enforce strict validation rules when adding mappings. Defaults to false.

The three duplicate settings decide the shape of the relation. Turn Allow Left Duplicates off for a one-to-many mapping keyed on the left; turn both off for a strict one-to-one. They are enforced on Add, which fails with a 409 when a rule is broken.

Create Response

{
  "id": "lookup123",
  "name": "customer-mapping",
  "description": "Map customer IDs between ERP and Shopify",
  "leftSystem": "erp",
  "rightSystem": "shopify",
  "appId": "app123",
  "createdAt": "2024-01-01T10:00:00.000Z",
  "updatedAt": "2024-01-01T10:00:00.000Z"
}

List

Retrieve all lookup collections available to your app. Found under the Lookup Collection resource.

List Configuration

No required parameters.

Under Advanced Settings → Pagination:

Parameter	Type	Required	Description
Page	Number	No	Page number to retrieve (starts from 1).
Items Per Page	Number	No	Maximum number of lookup collections to return per page (1-100).
Offset (Advanced)	Number	No	Number of items to skip from the beginning.

Set none of the three and the node reads every page.

List Response

{
  "items": [
    {
      "id": "lookup123",
      "name": "customer-mapping",
      "description": "Map customer IDs between ERP and Shopify",
      "leftSystem": "erp",
      "rightSystem": "shopify",
      "appId": "app123",
      "createdAt": "2024-01-01T10:00:00.000Z",
      "updatedAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "totalCount": 1,
    "totalPages": 1
  }
}

Common Patterns

Data Mapping Pattern

Implement the data mapping pattern for system integration:

Search for an existing mapping
If count is 0, create the record in the target system
Add the mapping so the next run finds it

Step 1: Search
  Collection Name: customer-mapping
  Search Type: Left Value (Exact)
  Search Value: {{ $json.shopifyCustomerId }}

Step 2: (IF node on {{ $json.count }} equals 0) create the customer in the CRM

Step 3: Add
  Collection Name: customer-mapping
  Left Value: {{ $json.shopifyCustomerId }}
  Right Value: {{ $json.crmCustomerId }}

When you also need to mark the source record as handled, do both writes in one call with Complete Lookup-Uniq.

Bidirectional Lookups

The same collection reads in both directions. Only Search Type changes:

Forward, Shopify ID → CRM ID
  Search Type: Left Value (Exact)
  Search Value: shopify_12345

Reverse, CRM ID → Shopify ID
  Search Type: Right Value (Exact)
  Search Value: crm_67890

Errors

Failures raise an error carrying the HTTP status from the server, for example 409 when a mapping breaks one of the collection's duplicate rules. With Continue on Fail enabled the item carries an error object with status, message, code and details instead of stopping the workflow.

Next Steps

Ready to explore more actions? Check out:

Locks Actions - Coordinate resource access
Last Updated Actions - Enable incremental polling
Complete Lookup-Uniq - Map and mark in one call
App Info Actions - Read the app and check server health

Available Operations​

Lookup​

Lookup Collection​

Add​

Add Configuration​

Add Response​

Search​

Search Configuration​

Search Response​

Get All​

Get All Configuration​

Get All Response​

Remove​

Remove Configuration​

Remove Response​

Create​

Create Configuration​

Create Response​

List​

List Configuration​

List Response​

Common Patterns​

Data Mapping Pattern​

Bidirectional Lookups​

Errors​

Next Steps​