Metadata Imports
Metadata imports let you add or update custom fields on existing feedback records without reprocessing the original data.
Overview
When you import feedback into Birdie, each record goes through an enrichment pipeline that includes anonymization, sentiment analysis, and AI-powered classification.
Sometimes you need to add new custom fields to existing feedback, like new filtering options or data segments. Metadata imports let you do this efficiently by updating only the custom fields, skipping the full enrichment process. This significantly reduces the costs of updating existing data.
Requirements and Limitations
Before using metadata imports, keep these requirements in mind:
Feedback must already exist: You can only update records that have already been imported into Birdie. Metadata for non-existent feedback will be discarded.
Supported record types: Metadata imports work with individual feedbacks and conversations. Conversation messages cannot be updated via metadata imports.
Setup assistance: While you can prepare your metadata files independently, the Birdie team will help you configure and run the import.
Historical backfills only: Currently, metadata imports are processed as one-time, ad-hoc operations for historical data.
Billing: Metadata updates are subject to special billing conditions based on the data being updated.
Data Format
File-Based Connectors
If you're providing data through a file-based connector (API, object storage, file shares, etc.), follow these guidelines.
Organize your files: Use separate directories to distinguish between regular imports and metadata imports. For example, use tickets/ for standard feedback ingestion and use tickets_metadata/ for metadata imports.
Conversations (support tickets, complaints, issues): Each row should represent a single conversation and include the conversation ID and any custom fields you want to add or update. Since you're only sending one row per conversation (not per message), metadata files are typically much smaller than regular imports.
Feedbacks (NPS/CSAT responses, reviews): Each row should include the feedback ID and any custom fields you want to add or update.
For example, the following content could be used for a CSV for uploading the segment and tier custom fields:
For ticket_1, it would receive the custom fields segment=Segment A and tier=premium.
For ticket_2, it would receive the custom fields tier=Basic. The segment custom field would not be added to this feedback (however, if it already had an existing value, this value would remain as is).
Native Connectors
For native integrations, metadata imports require custom configuration on Birdie's side. Please contact support to set this up.
Frequently Asked Questions
Do I need to share the custom field names beforehand?
As with all custom fields, metadata imports for new custom fields need to be shared with the Birdie team so they can correctly configure the field mappings if they don't already exist.
How do I handle optional fields with no value?
Send an empty string for optional custom fields that don't have a value. Do not use placeholder values like null, NA, or whitespace. These will be stored as actual values.
When you don't send a field for a metadata import, we will preserve the existing value (if it already exists before).
If you send any non empty value, we will overwrite the content of the custom field for that feedback with the new value you just sent.
Can I set up recurring metadata imports?
While technically possible, we don't currently support recurring metadata imports (such as daily metadata updates alongside daily feedback imports). These setups are prone to data inconsistencies, so we reserve them for very specific scenarios.
Can I update fields other than custom fields?
Currently, metadata imports only support custom fields. Some fields cannot be updated this way because they affect the enrichment process. For example, updating the feedback text would require re-running sentiment analysis and classification.
What if I need to update non-custom fields?
For specific cases, we can support partial updates through a process called patching. Unlike metadata imports, patching triggers a full re-enrichment of the record. This means the entire feedback is reprocessed, which incurs the standard processing costs.
What happens if the same field has different values in a regular import and a metadata import?
Birdie keeps the most recent value. If you send field=a in a regular import and then field=b in a metadata import, the field will be set to b.
Make sure your field values are consistent across all imports, including capitalization and formatting. Conflicting values sent in quick succession can lead to unpredictable behavior in the application. The same issue of inconsistent behaviour can happen if you send varying values for the same feedback and field within the same metadata import.
Last updated