Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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.

  • Additional fields: Adds fields to the record, which can be stored as 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: one PUT /ingestion/lookup/{type}/{id} request per lookup record.

  • Snowflake: 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 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.

Last updated