> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# B2B accounts: golden records and hierarchy

> What a B2B account entity is in Orbit: the explicit group_id key, the golden record built by recency survivorship, member contacts, the parent/child hierarchy, access roles, and how accounts relate to Account Scores and segmentation.

# B2B accounts: golden records and hierarchy

A B2B go-to-market rarely targets one contact at a time — it targets the
**organization** the contacts belong to. Orbit models that organization as a
first-class **account**: every distinct group your SDK identifies becomes an
account entity with a golden record, a member roster, and a place in a
parent/child hierarchy. This page defines that entity; the
[CDP segments guide](/guides/cdp-segments) shows how to build audiences from
it, and the [CDP event model](/concepts/cdp-event-model) defines the
underlying `group` events the entity is projected from.

## Section 1 — What an account entity is

An account materializes from the Segment-compatible `group` call. When your
SDK (or the `/api/v1/cdp/group` ingest endpoint) sends a `group` event with a
`groupId` and a traits bag, each distinct non-empty `groupId` becomes one
account:

```json theme={null}
{
  "type": "group",
  "userId": "user_42f8",
  "groupId": "acme-corp",
  "traits": {
    "name": "Acme Corporation",
    "industry": "logistics",
    "employees": 480,
    "parent_group_id": "acme-holdings"
  }
}
```

The account's **golden record** is a recency-survivored merge of every
`group` call you have sent for that `groupId`: the most recent meaningful
value per trait wins. A later call that omits a field never erases an
established value — blanks and nulls never overwrite — so partial updates
are safe. The entity is a read-side projection over the event stream described
in [The CDP event model](/concepts/cdp-event-model): there is nothing extra
to ingest, no separate table to keep in sync, and the record recomputes from
your events on every read.

Membership is explicit: the contacts a `group` call associates with the
`groupId` (once identity resolution has bound them — see
[Identity resolution](/guides/identity-resolution)) are that account's
members, with first-seen and last-seen times per member.

Read the entities:

* Dashboard — **Audience → Accounts**: the ranked account list, with
  golden-record and member drill-down.
* API — `GET /api/v1/cdp/accounts/profiles` for the list (sortable by
  `members`, `events`, `recent`, `created`, `name`, or `group_id`; filter
  with `min_members`; search by name or id with `q`) and
  `GET /api/v1/cdp/accounts/profile?group_id=<id>` for one account's golden
  traits, members, parent, and children. Both are read-only.

## Section 2 — Parent/child hierarchy

Accounts nest. Set a parent trait on the child account — any of
`parent_group_id`, `parent_account_id`, or `parent_account` (snake\_case or
camelCase both resolve) — and Orbit treats the child as sitting under that
parent. The parent is read off the golden record, so the most recent
meaningful parent value you sent is the one in effect.

The detail response (`GET /api/v1/cdp/accounts/profile?group_id=<id>`)
returns both directions:

* `parent_group_id` — this account's parent, or `null` for a hierarchy root.
* `children` — the accounts whose latest parent trait points back at this one.

Use the hierarchy for holding-company structures, subsidiaries, or
department-level rollups: model one account per organizational unit, point
children at their parent, and the detail view shows the whole subtree.

## Section 3 — Access: owner, admin, developer

The golden record and member roster carry PII-bearing group traits and
contact rows, so the surface is gated the same way as the contact profile:
both the dashboard view and the API endpoints require the **owner**, **admin**,
or **developer** role with the `contacts:read` scope. Other roles receive a
403; the dashboard does not render the view for them either. Grant access by
assigning one of those roles — there is no separate accounts permission to
toggle.

## Section 4 — Accounts versus Account Scores

The two surfaces under **Audience** complement each other but key differently
and answer different questions:

|              | Accounts (`/audience/accounts`)                           | Account Scores (`/insights/account-scores`)            |
| ------------ | --------------------------------------------------------- | ------------------------------------------------------ |
| What it is   | The account **entity**: golden record, members, hierarchy | A **health ranking**: churn, intent, propensity, value |
| Keyed by     | Your explicit `groupId`                                   | The contact's `company` attribute, grouped             |
| How it forms | Sent explicitly with `group` calls                        | Derived automatically from contact scores              |
| Use it to    | Model the org chart, list members, drill into one record  | Triage which accounts need attention this week         |

Scores rank accounts; profiles define them. An account can exist as a profile
(someone sent a `group` call) without a score (no scored contacts share its
company name), and a scored company can have no explicit profile (you never
sent a `group` call for it). When you use both, send `group` calls with a
`name` or `company` trait that matches the `company` attribute on member
contacts — the two views then describe the same organizations.

## Section 5 — Using accounts in segmentation

Account entities feed the same audience machinery contacts feed:

1. **Locate the accounts you care about.** Query
   `GET /api/v1/cdp/accounts/profiles?min_members=5&sort=members` for the
   established organizations, or browse **Audience → Accounts** and note the
   `group_id` values.
2. **Collect the member contact ids.** The account detail response lists them
   with join and last-seen times; filter by hierarchy level with
   `parent_group_id` or the `children` array.
3. **Build the segment.** Create a segment over those contacts in
   **Audience → Segments** (see [CDP segments](/guides/cdp-segments)) with
   whatever behavioral conditions the campaign needs — event activity,
   lifecycle stage, or computed traits — and activate it like any other
   audience.

Account Scores add the prioritization layer on top: pick the accounts worth
spending against from the score ranking, then build the segment of their
members here.

## Cross-references

* [The CDP event model](/concepts/cdp-event-model) — the `group` events the
  entity is projected from.
* [CDP segments](/guides/cdp-segments) — building audiences from account
  members; includes the Account Scores ranking.
* [Identity resolution](/guides/identity-resolution) — how group events bind
  to member contacts.
* [CDP API reference](/api-reference/endpoints/cdp) — endpoint-level detail
  for the Account Scores endpoints.