The lookup helper retrieves data from a lookup you define in the same flow step. Use it to map field values to other values or to pull in data from a destination application search without leaving your Handlebars template.
Before you begin
In the Advanced field editor (AFE), select Create/manage lookup to configure lookups. The lookup helper can only reference lookups defined in the same flow step. It can't access lookups from other steps. Each lookup must have a unique alphanumeric name.
Two lookup types are available:
- Dynamic search — defines a search in the destination application and returns a single string value from the results.
-
Static: value to value — defines explicit value mappings (for example,
"California"→"CA").
Syntax
For a dynamic search lookup, reference the lookup name without quotes:
{{lookup.myDynamicLookup}}
For a static value to value lookup, wrap the lookup name in quotes and supply the field to match:
{{lookup "myStaticLookup" record.someField}}
Standard Handlebars {{lookup this "key"}} notation doesn't work in integrator.io, because the lookup helper replaces it.
Examples
Use a dynamic search lookup
{{lookup.shippingLookup}}
A dynamic lookup named shippingLookup is configured to retrieve shipping[0].method from the destination application. If the search returns "Overnight", the helper outputs "Overnight".
Use a static value to value lookup
{{lookup "stateAbbreviation" record.shippingAddress.state}}
A static lookup named stateAbbreviation maps full state names to abbreviations:
| Input | Output |
|---|---|
"California" |
"CA" |
"New York" |
"NY" |
"Texas" |
"TX" |
If record.shippingAddress.state is "Texas", the helper returns "TX".
Preview lookup results
When you preview an HTTP import's request body, a lookup expression that calls a static lookup shows the value the lookup returns. That's the same value the flow sends when it runs, so you can confirm the expression before you run the flow.
| When | Preview shows |
|---|---|
| Static lookup, and the value is in the map | The mapped value |
| Static lookup, and the value isn't in the map | An error if Action to take if unique match not found is Fail record (the default); otherwise, the default value you chose |
| Lookup name isn't defined on the import | A lookup-not-found error |
| Dynamic search lookup | A placeholder, such as {$ASYNCID$0$1$}
|
| Any lookup outside the HTTP request body, such as in mappings | A placeholder, such as {$ASYNCID$0$1$}
|
A placeholder isn't an error. A dynamic search lookup runs against your destination application only when the flow runs, so run the flow to check its result.
If a static lookup shows a placeholder, check that the lookup name is in quotes.
Usage notes
- Dynamic lookup names are referenced without quotes:
{{lookup.name}}. Static lookup names are wrapped in quotes:{{lookup "name" field}}. Using the wrong convention causes the lookup to fail silently. - Lookup names must match exactly what you defined in Create/manage lookup, including capitalization.
- For dynamic lookups, verify that the JSON path to the return value in the destination application's response is valid (for example,
products[0].name).