Skip to main content

​
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 shows how to build audiences from it, and the 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:
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: 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) 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: 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) 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