> 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/core-concepts-and-entities/accounts.md).
# Accounts
## What Are Accounts?
An Account tells you who is behind your feedback: a customer profile such as a user, a business, or a subscription. Accounts are a complementary and optional data type in Birdie, different to [Feedbacks and Conversations](https://ask.birdie.ai/core-concepts-and-entities/pages/5Z8b5BkvkdE2oYhrsKO8#id-2.-understanding-data-types) which drive our product.
Accounts can adapt to your business model:
* **B2B companies** can use Accounts to identify their client companies, grouping the feedback from every contact at a client under the same business profile (e.g., "Acme Inc.").
* **B2C companies** can use Accounts to identify the individual users who publish Feedbacks and Conversations, with attributes such as plan, region, or signup date.
Accounts let you bring customer context into Birdie separately from the feedback itself. This context usually lives in systems other than the ones that hold feedback, and it comes in two layers:
* **Profile**: who the customer is. Attributes such as plan, industry, company size, region, or lifecycle stage typically live in a CRM, a billing system, or a data warehouse.
* **Behavior**: what the customer does. With Cohort Sync, you can also bring behavioral cohorts from product analytics platforms such as Mixpanel or Amplitude into Birdie. Each cohort is attached to the accounts that belong to it, so you can segment your Voice of Customer data by real product behavior, not just by profile. For example, you can:
* Compare feedback from users who dropped off at a key journey step (such as onboarding or checkout) with feedback from those who converted.
* Understand why one variant of an A/B test outperforms the other by reading what users exposed to each version are saying.
* See how power users and dormant users react differently to a newly launched feature.
* Track complaints and praise from users who triggered a specific event, such as downgrading a plan or contacting support more than once in a week.
Instead of copying account attributes into every feedback record, you upload each account once, and Birdie links it to every Feedback and Conversation that shares the same account identifier. This keeps account data normalized: each profile is stored in a single place within Birdie, and updating it doesn't require re-sending the feedback associated with it.
{% hint style="info" %}
You may also see Accounts referred to as **Audience**, for example in the Ingestion API path `/ingestion/audience/accounts`.
{% endhint %}
## How Accounts Are Linked to Feedbacks and Conversations
The link between an Account and your feedback data is the `account_id` field:
* **Feedbacks** (reviews, NPS, CSAT, CES) carry the `account_id` on the top level record, inside its kind fields.
* **Conversations** (support tickets, complaints, social media posts, issues) can carry the account ID in the kind fields at the top level (conversation) or the message level, which requires consistency with the conversation to ensure the correct behaviour.
* **Accounts** carry the same `account_id` as their unique identifier.
Each Feedback or Conversation belongs to one (or zero) Accounts, while a single Account can be linked to any number of Feedbacks and Conversations, from any source. Conversations/Feedbacks that don't have accounts will function normally since providing accounts is optional. Accounts without feedbacks won't be matched to any feedbacks, but may be analysed by themselves.
For example, the account below is linked to an NPS response and a support ticket, even though each record came from a different system:
| Record | Source | `account_id` | Data |
| --------------------- | ---------- | ------------ | ------------------------------------ |
| Account | Salesforce | `acct-123` | `plan`: Platinum, `industry`: Retail |
| Feedback (NPS) | Qualtrics | `acct-123` | Rating 4: "Checkout keeps failing" |
| Conversation (Ticket) | Zendesk | `acct-123` | "I can't complete my purchase..." |
{% hint style="warning" %}
The `account_id` must be the **exact same string** across all data types. If an NPS response uses `123` and a support ticket uses `acct-123`, Birdie treats them as different accounts and the link silently fails.
{% endhint %}
## Uploading Accounts
An Account record requires only an `account_id`. Every other attribute (plan, region, industry, churn risk, etc.) is sent as a custom field. See the [Accounts schema](/integrations-and-data-ingestion/data-schema-definitions-for-birdie-ingestion.md#accounts) for the full definition.
{% hint style="info" %}
Account attributes are only persisted if a matching custom field mapping exists with the record type set to **Account**. Configure the mappings in **Settings > Data Management > Custom fields** before uploading your accounts. See [Custom Fields](https://ask.birdie.ai/core-concepts-and-entities/pages/5Z8b5BkvkdE2oYhrsKO8#id-4.-custom-fields) for details.
{% endhint %}
Accounts can be uploaded through the different integration paths:
* [Birdies Ingestion API](/integrations-and-data-ingestion/ingestion-api.md)
* Data lake and data warehouses connectors, e.g. [S3](/integrations-and-data-ingestion/how-to-integrate-with/s3-azure-gcs.md) and [Snowflake](/integrations-and-data-ingestion/how-to-integrate-with/snowflake.md).
* [Salesforce connector](/integrations-and-data-ingestion/how-to-integrate-with/salesforce.md)
* Cohort sync connectors like [Amplitude](/integrations-and-data-ingestion/how-to-integrate-with/amplitude-cohort-sync.md) and [Mixpanel](/integrations-and-data-ingestion/how-to-integrate-with/mixpanel-cohort-sync.md).
Updates append new fields to the entire account record, preserving unsent fields. This behaviour was implemented to allow incremental cohort syncs like the ones implemented by Amplitude and Mixpanel.
## Before uploading accounts
* Define a single `account_id` format and use it across every source that sends Feedbacks, Conversations and Accounts.
* Calculating / maintaining a single global account id in all platforms may be complex. Birdie supports account id normalization, which allows you to share / upload normalization lists so N unique identifiers can be mapped to one single true value, e.g. (user-1, Usr-1, USER1, 1) -> User-1. See [Field Lookups](/integrations-and-data-ingestion/field-lookups.md) to configure this option.
* Create the custom field mappings for the Account record type before the first upload, since mappings are applied at ingestion time.
* Accounts are never anonymized, they are stored as is. Avoiding using PII fields for identifiers or for configuring custom fields, as they will be stored and displayed as-is within the Birdie platform.
* If you absolutely have to use a PII field, reach out to Birdie so we can configure [field cryptography](/integrations-and-data-ingestion/field-hashing.md) for the PII fields before you upload the data.
* Schedule regular account uploads from your source of truth (CRM, data warehouse, etc.) so filters and segments reflect the current state of your customers.
## Using Accounts in Your Analysis
Accounts can be analyzed on their own, or linked to your Feedbacks and Conversations.
### Analyzing Accounts Linked to Feedbacks and Conversations
When exploring feedback, account attributes are available as filters alongside the feedback fields.
Account filters in the Exploration page
When you select an account filter, Birdie performs the match between Accounts and your feedback data, returning only the Feedbacks and Conversations whose `account_id` belongs to an account that matches the filter.
This lets you answer questions such as:
* What are the most relevant opportunities for accounts on the Platinum plan?
* How does sentiment differ between enterprise and SMB accounts?
* Which Areas concentrate complaints from accounts at risk of churning?
Account filters can be combined with any other filter, and can be used to:
* Create Account-level [Segments](/core-concepts-and-entities/segments.md), such as segmentation by industry, plan, lifecycle stage, company size or revenue.
* Narrow down your analysis, e.g., combine the Sentiment filter with a plan filter to read only the negative feedback from Platinum accounts.
* Build focused [Dashboards](/customer-intelligence/dashboards-and-reporting/custom-dashboards.md), e.g., a dashboard where every widget only shows feedback from your enterprise clients.
* Ask [Skye](/core-concepts-and-entities/understanding-and-using-skye-in-birdie.md) about a group of accounts with a specific account behaviour.
* Get [Digests](/admin-and-settings/notifications/digests.md) containing a weekly summary of the feedback from your top clients
* Get [Alerts](/admin-and-settings/notifications/alerts.md) when a negative feedback is published by a critical account.
{% hint style="info" %}
Feedbacks and Conversations without an `account_id` are excluded from results that use account filters (e.g account id or a specific account field).
{% endhint %}
Another set of supported account filters are the cross reference filters. These filters allow you to filter feedbacks and conversations based on the other records of the same account. For example, you can find the support tickets from accounts that answered an NPS survey with a rating of 6 or lower, even though the tickets themselves don't have a rating. Cross reference filters are available under the **Cross-reference** option of the filter menu.
When using cross reference filters, keep in mind that:
* All cross reference conditions must match the same record. Filtering for NPS responses with a negative sentiment only matches accounts that have a negative NPS response. An account with a positive NPS response and a negative support ticket doesn't match.
* The filtered record also counts as one of the account's records. Filtering for accounts with an NPS response returns every record from these accounts, including the NPS responses themselves. Combine it with a regular filter to narrow down the results, e.g., to only see support tickets.
* You can also filter by the number of days between the records. Positive values mean the other record was posted after the record in your results, and negative values mean it was posted before. For example, filtering support tickets with a cross reference to negative NPS responses and 0 to 7 days between records returns the tickets opened up to 7 days before a negative NPS response. This filter only works together with other cross reference filters.
* Only the 100 most recent feedbacks and conversations of each account are considered.
* The text and messages of the other records can't be used in cross reference filters.
* Cross reference results are updated a few minutes after new records are ingested for an account.
### Analyzing Accounts on Their Own
Account data is useful even before it's combined with feedbacks. You can:
* **Quantify accounts** that match specific criteria, such as the number of accounts on the Platinum plan, or in a given industry.
* **Track how accounts evolve over time** with historical analysis. Birdie keeps the history of changes to account attributes, so you can analyze behaviour changes e.g.:
* Find accounts that recently upgraded from a Gold to a Platinum plan.
* Track account retention over time.
* Identify accounts that have recently churned.
{% hint style="info" %}
As of now, this type of analysis is still undergoing internal testing, but this type of analysis will soon be available via our APIs and MCP.
{% endhint %}
---
# 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/core-concepts-and-entities/accounts.md?ask=&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.
