> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/field-lookups.md).

# Field Lookups

Field lookups let Birdie complete or normalize incoming records with data you share separately. For example, they can replace the different IDs each platform uses with a single consistent ID across all platforms.

A field lookup has two parts:

* Lookup records: small records you upload to Birdie. Each one has a lookup type, an ID, and the fields to add to the records that match it.
* The lookup: set up once by the Birdie team for a source and record type. It reads a field from every incoming record, finds the lookup record whose ID matches the field value, and adds its fields to the record.

Once a lookup is set up, you can upload and update any number of lookup records at any time, with no further setup.

## How It Works

For example, say you want to enable [Account analytics](/core-concepts-and-entities/accounts.md) for your feedbacks / conversations.

From the account documentation, we know we require one global and consistent account identifier.

If the feedback comes from one platform, e.g. Salesforce, and the conversation from another, e.g. Zendesk, you might have inconsistent IDs that need to be normalized as you ingest these feedbacks and conversations. Lookups are basically the configuration that tells Birdie this needs to happen, and the lookup records tell Birdie what old value needs to be replaced with a new value. In the table below, we show that by uploading "id mappings" you can produce a consistent ID for your uploads:

| Lookup type          | ID       | New account ID |
| -------------------- | -------- | -------------- |
| `account_identifier` | `zd-881` | `acct-123`     |
| `account_identifier` | `sf-ff9` | `acct-123`     |
| `account_identifier` | `zd-882` | `acct-456`     |
| `account_identifier` | `sf-ffa` | `acct-456`     |

With these lookup records, both IDs are normalized to the same global ID:

```mermaid
flowchart LR
    c((  ))
    z[Zendesk Account ID]  --> c
    s[Salesforce Account ID] --> c
    c -->|Lookup| g[Global Account ID]
```

When a lookup is applied:

* Values are matched exactly. `ZD-881` doesn't match `zd-881`, and leading or trailing spaces count.
* Fields from the lookup record overwrite the fields with the same name in the incoming record. Lists are replaced, not merged.
* Records without a matching lookup record are kept unchanged, unless the lookup is set up to reject them.
* Only records ingested after the lookup record is uploaded are updated. Records ingested before it must be ingested again.

## Lookup Types

The lookup type defines where the fields of the lookup record are added.

* Account identifier: Replaces the record's (feedback or conversation) account ID with the one you use everywhere else, so the record is linked to the right [Account](/core-concepts-and-entities/accounts.md).
* Additional fields: Adds fields to the record, which can be stored as [custom fields](https://ask.birdie.ai/integrations-and-data-ingestion/pages/5Z8b5BkvkdE2oYhrsKO8#id-4.-custom-fields).
  * Create the custom field mappings before the lookup is set up. Fields without a mapping are discarded.

## Setting Up a Lookup

Contact the Birdie team and share:

* The lookup type.
* The source and record type it applies to, e.g. Zendesk tickets.
* The field in those records whose value is matched against the lookup record IDs, e.g. `account_id`.
* Whether records without a matching lookup record should be rejected.

## Uploading Lookup Records

Each lookup record is identified by its type and ID:

* IDs can only contain letters, numbers, hyphens (`-`) and underscores (`_`).
* The IDs represent the value of the configured field you want to match to perform the match and inject the lookup record fields.
* Uploading a lookup record with an existing type and ID replaces it.
* Upload lookup records before the records that depend on them.

Lookup records can be uploaded through different connectors as needed by clients. Below is a list of supported connectors:

* [Ingestion API](/integrations-and-data-ingestion/ingestion-api.md#lookup-endpoint): one `PUT /ingestion/lookup/{type}/{id}` request per lookup record.
* [Snowflake](/integrations-and-data-ingestion/how-to-integrate-with/snowflake.md): each row of a table becomes a lookup record, with one column for the ID and one column per field. The whole table is read again on every scheduled run, so changes to the table are applied automatically. Rows removed from the table are not removed from Birdie.

It's important to upload the lookup records before the feedback / conversations that depend on the lookup.

## Frequently Asked Questions

### Should I use field lookups or metadata imports?

Use field lookups to complete or normalize records as they are ingested, from lookup records you keep up to date. Lookups are only applied as data is ingested. Modifying lookup records without re-ingesting the feedbacks / conversations will not persist the new fields of the lookup to records that were already ingested.

Use [metadata imports](/integrations-and-data-ingestion/metadata-imports.md) to backfill the custom fields of records that were already ingested without re-uploading the conversations or feedbacks, knowing that it will only apply for filtering and basic analytics.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ask.birdie.ai/integrations-and-data-ingestion/field-lookups.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.