Account-level attribution for B2B (company external ID)

The problem

In B2C, the person who clicks the ad is usually the person who buys — attribution just follows one contact. B2B breaks that assumption. Accounts payable pays the invoice; a developer on the same team clicked the ad and signed up for a free trial weeks earlier using a personal Gmail address. Grouping contacts by email domain can’t connect them, because the payer’s and the developer’s email domains don’t match, or neither address is a business address at all. What you actually want is CRM-style account-level attribution: group every contact that belongs to the same customer account together, so a conversion by one teammate can be credited to the ad another teammate clicked. company_external_id is how you tell Cometly which contacts belong to the same account.

Prerequisites

A Cometly API key.
A Space.
The Space’s Company identity mode set to “Group by your account ID” (External ID), in Space Setup → Additional Setup → Company Tracking. The other mode, “Group by email domain” (Auto), is the default and ignores company_external_id entirely.

Pick one mode and stick to it. Switching does not move existing contacts: companies that were grouped by email domain keep their current members and simply stop growing, and companies already grouped by external ID stay exactly as they are. Nothing is merged or re-grouped retroactively. While a Space is in the default Auto mode, company_external_id is still accepted on events and stored — it’s just ignored for grouping. If your events already carry the field while the Space is in Auto mode, the Company Tracking settings page shows a warning banner telling you so, so you don’t spend time debugging a company grouping that was never turned on.

The identifiers, contrasted

Three fields on Create Event sound similar but do unrelated jobs. Mixing them up either merges contacts that shouldn’t be merged, or fails to group the account at all.

Field	Does	Never
`tracking_id`	Merges events into one contact. Use a stable per-user value.	Never groups companies. Never send a shared account ID here — every teammate would merge into a single contact.
`company_external_id`	Groups contacts into a company by your own account ID.	Never merges contacts, and never takes part in contact matching.
`idempotency_key`	An exact-dedup key, unique per event. Required for high-frequency pipelines — without a distinct key per event, repeated events can collapse into each other under Cometly’s same-contact dedup window.	—

company_name rides alongside company_external_id as a fourth field: it’s a display-only name for the company, last write wins, and it’s never used for matching — two companies with the same name stay separate. It’s ignored unless company_external_id is also sent, since the name alone doesn’t identify a company.

Send it on every event

Send company_external_id on every event a member of the account triggers — sign-up, trial activation, purchase, whatever your funnel tracks — alongside a per-user tracking_id, a unique idempotency_key, and optionally company_name. Normalization rules for company_external_id and company_name: trimmed, case preserved (never lowercased), stored byte-exact, 1–190 characters (company_external_id) or 1–255 characters (company_name) after trimming, and integers are accepted. A blank string is treated as absent (null); floats, arrays, and booleans are rejected with a 422. A developer signs up with a personal address:

curl -X POST https://app.cometly.com/public-api/v1/events/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "sign_up",
    "email": "dev@gmail.com",
    "tracking_id": "user_48213",
    "idempotency_key": "evt_signup_48213_20260909",
    "company_external_id": "acct_8f3k2",
    "company_name": "Acme Inc",
    "event_time": "2026-09-09T14:02:00Z"
  }'

const response = await fetch('https://app.cometly.com/public-api/v1/events/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_name: 'sign_up',
    email: 'dev@gmail.com',
    tracking_id: 'user_48213',
    idempotency_key: 'evt_signup_48213_20260909',
    company_external_id: 'acct_8f3k2',
    company_name: 'Acme Inc',
    event_time: '2026-09-09T14:02:00Z'
  })
});

const data = await response.json();

<?php
$url = 'https://app.cometly.com/public-api/v1/events/track';
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Accept: application/json',
    'Content-Type: application/json'
];

$data = [
    'event_name' => 'sign_up',
    'email' => 'dev@gmail.com',
    'tracking_id' => 'user_48213',
    'idempotency_key' => 'evt_signup_48213_20260909',
    'company_external_id' => 'acct_8f3k2',
    'company_name' => 'Acme Inc',
    'event_time' => '2026-09-09T14:02:00Z',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>

import requests

url = 'https://app.cometly.com/public-api/v1/events/track'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

data = {
    'event_name': 'sign_up',
    'email': 'dev@gmail.com',
    'tracking_id': 'user_48213',
    'idempotency_key': 'evt_signup_48213_20260909',
    'company_external_id': 'acct_8f3k2',
    'company_name': 'Acme Inc',
    'event_time': '2026-09-09T14:02:00Z',
}

response = requests.post(url, headers=headers, json=data)

Weeks later, accounts payable pays the invoice from a different, business email address — same company_external_id, different contact:

curl -X POST https://app.cometly.com/public-api/v1/events/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "purchase",
    "email": "ap@acme.com",
    "tracking_id": "user_91004",
    "idempotency_key": "evt_purchase_ord-77213",
    "amount": 4999.00,
    "order_id": "ORD-77213",
    "company_external_id": "acct_8f3k2",
    "company_name": "Acme Inc",
    "event_time": "2026-09-25T09:15:00Z"
  }'

const response = await fetch('https://app.cometly.com/public-api/v1/events/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_name: 'purchase',
    email: 'ap@acme.com',
    tracking_id: 'user_91004',
    idempotency_key: 'evt_purchase_ord-77213',
    amount: 4999.00,
    order_id: 'ORD-77213',
    company_external_id: 'acct_8f3k2',
    company_name: 'Acme Inc',
    event_time: '2026-09-25T09:15:00Z'
  })
});

const data = await response.json();

<?php
$url = 'https://app.cometly.com/public-api/v1/events/track';
$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Accept: application/json',
    'Content-Type: application/json'
];

$data = [
    'event_name' => 'purchase',
    'email' => 'ap@acme.com',
    'tracking_id' => 'user_91004',
    'idempotency_key' => 'evt_purchase_ord-77213',
    'amount' => 4999.00,
    'order_id' => 'ORD-77213',
    'company_external_id' => 'acct_8f3k2',
    'company_name' => 'Acme Inc',
    'event_time' => '2026-09-25T09:15:00Z',
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>

import requests

url = 'https://app.cometly.com/public-api/v1/events/track'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

data = {
    'event_name': 'purchase',
    'email': 'ap@acme.com',
    'tracking_id': 'user_91004',
    'idempotency_key': 'evt_purchase_ord-77213',
    'amount': 4999.00,
    'order_id': 'ORD-77213',
    'company_external_id': 'acct_8f3k2',
    'company_name': 'Acme Inc',
    'event_time': '2026-09-25T09:15:00Z',
}

response = requests.post(url, headers=headers, json=data)

Both events carry the same company_external_id, so once External ID mode is on, both contacts land in the same company — even though they never share a tracking_id, an email domain, or a name.

Send it via webhooks or Stripe metadata

If you’re sending events through a webhook instead of the API directly, Company External ID and Company Name are available as mapping destinations in the webhook mapping step, alongside your other field mappings. For Stripe specifically, your account ID typically travels in the object’s metadata rather than as a top-level field. Map the source field data.object.metadata.<your key> (for example data.object.metadata.account_id) to the Company External ID destination, and optionally another metadata key to Company Name.

The source-field dropdown in the mapping step is only populated from the sample payloads Cometly received while you were setting up the webhook (Check for Data). If your metadata key wasn’t present on any of those sample events, it won’t show up as an option. Send a test event carrying the metadata key first, then re-run Check for Data, before mapping it.

Ad-platform conversions (CAPI) go out roughly 14 minutes after the conversion itself. For a teammate’s ad click to be picked up when accounts payable’s purchase is sent to Meta or Google, the developer’s account membership (their company_external_id) needs to already be recorded by then. Send sign-up and membership events in real time as they happen, not batched into a nightly job — a sign-up event that arrives after the conversion it should inform has already been sent is too late to change how that conversion was attributed.

Turn on ad-platform conversion identity = company

Company grouping alone doesn’t change who a conversion is attributed to when it’s sent to Meta, Google, and the other ad platforms — it only groups contacts for reporting. To also redirect the ad-platform conversion’s identity to the right teammate, turn on the second Company Tracking setting: Ad-platform conversion identity → “Send as the teammate who clicked the ad” (company mode, on the same Company Tracking page). With this on:

A conversion is sent under the identity of the teammate in the same company whose ad click is the most recent before the conversion — their email, name, phone, and click IDs. It’s always one person’s identity, never a blend of two people.
If no teammate in the company clicked an ad more recently, the conversion falls back to being sent as the person who actually converted.
It never changes conversion facts: amount, order_id, and the conversion time are always the real ones.
It requires company grouping — a contact with no company (in either identity mode) is always sent as themselves.

Fix a grouping, or link a contact that never sends events

Some contacts never send an event carrying company_external_id at all — an inbound lead created via CRM sync, for instance. Two endpoints let you fix that without waiting for another event:

Update Company — set or change a company’s external_id directly.
Attach Contact Company / Detach Contact Company — move a contact onto a company, or off it entirely.

What happens after a manual attach or detach depends on the Space’s company identity mode: in Auto mode, the tracker only assigns a company to a contact that currently has none, so a manual attach sticks (it isn’t undone by a later event) and a manual detach is undone by the contact’s next business-email event. In External ID mode, the next event carrying a company_external_id re-points the contact again either way.

Read it back

Get Company and List Companies both return external_id alongside domain and name.
The Companies dataset in the data warehouse carries external_id as a column — join on an exact match against your own account IDs.
If you’re enabling External ID mode on a Space that already has history, run a one-time export over all history on the Companies dataset. Incremental exports are windowed on created_at, so a company that gains an external_id after its original creation window won’t be re-exported by a recurring run.

Reality note

Cometly groups companies by business-email domain (Auto mode) or by your own company_external_id (External ID mode) — it does not read association data from HubSpot, Salesforce, or any other CRM’s company/account records. If you need Cometly’s company grouping to match your CRM’s account structure, send that CRM’s account identifier as company_external_id on every event, rather than expecting CRM associations to be picked up automatically.

Concepts

How-to guides

Account-level attribution for B2B (company external ID)

The problem

Prerequisites

The identifiers, contrasted

Send it on every event

Send it via webhooks or Stripe metadata

Turn on ad-platform conversion identity = company

Fix a grouping, or link a contact that never sends events

Read it back

Reality note

​The problem

​Prerequisites

​The identifiers, contrasted

​Send it on every event

​Send it via webhooks or Stripe metadata

​Timing: send sign-up events in real time

​Turn on ad-platform conversion identity = company

​Fix a grouping, or link a contact that never sends events

​Read it back

​Reality note

The problem

Prerequisites

The identifiers, contrasted

Send it on every event

Send it via webhooks or Stripe metadata

Timing: send sign-up events in real time

Turn on ad-platform conversion identity = company

Fix a grouping, or link a contact that never sends events

Read it back

Reality note