Call tracking & dynamic number insertion

Call tracking answers the question a click-level analytics tool cannot: which marketing source made the phone ring. DNI (dynamic number insertion) is the mechanism: your site shows a different inbound number to visitors from different campaigns, so every inbound call lands on a DID that maps back to exactly one source. On Orbit the loop has three parts — a tracking pool (a named container that binds a set of tracking DIDs to a source, campaign, and match rules), a resolve endpoint the website snippet calls to pick the right DID for the current visitor, and the call attribution report that rolls inbound calls on tracking DIDs up by source and campaign. This complements the channel-level Agent ROI attribution guide, which prices an agent’s resolved outcomes against its model-call cost. Call tracking is the offline→online attribution join for the inbound voice channel: nothing is written to the call ledger, and the source mapping is resolved at read time. Tracking DIDs are inbound-only. They terminate inbound calls; outbound (MT) voice and SMS never route through them. Reads need the numbers:read scope; creating pools and assigning DIDs need numbers:write. Pool config is stored in organization settings (JSONB), so it survives without any data migration and stays isolated to your organization.

1. When to use it

Use a tracking pool when paid or organic traffic drives inbound calls and you need per-source attribution on the phone channel: Google Ads PPC clicks that end in a call, a partner or affiliate link that dials, an email campaign with a click-to-call button. Skip it for your one permanent main line — DNI only helps when different visitors should see different numbers.

2. Create a tracking pool

Create one pool per source you want to attribute. The pool carries a label, the source it attributes calls to, an optional campaign and medium, and match rules that decide which visitors see its numbers.

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/tracking-pools \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Google Ads — Brand",
    "source": "google",
    "campaign": "brand-search",
    "medium": "cpc",
    "match": {
      "utmSource": "google",
      "referrerContains": "google.com",
      "requireGclid": true
    }
  }'

Field	Required	Description
`label`	yes	Operator-facing name, up to 120 characters.
`source`	yes	The marketing source inbound calls attribute to (e.g. `google`).
`campaign`	no	Campaign name reported alongside the source.
`medium`	no	Marketing medium reported alongside the source (e.g. `cpc`).
`match`	no	Rule set the resolver scores a visitor against — every defined condition must hold. Undefined conditions are “don’t care”.
`swapStrategy`	no	`sticky` (default) pins each session to one DID deterministically; `fixed` shows the pool’s first DID to everyone.
`enabled`	no	Defaults to `true`. Disabled pools are skipped by the resolver but retained for history.

A pool with no match rules matches every visitor — a catch-all fallback for any traffic not claimed by a more specific pool. When several pools match, the resolver picks the one with the most defined match conditions; ties break deterministically by creation time and id. Match rules available per pool:

Rule	Matches when
`utmSource` / `utmMedium` / `utmCampaign` / `utmTerm`	Case-insensitive exact match on the corresponding UTM parameter.
`referrerContains`	The document referrer contains this substring, case-insensitive (e.g. `google.com`).
`requireGclid`	A Google click id (`gclid`) is present on the request.

Update a pool later with PATCH, and list or inspect with GET:

curl https://api.orbit.devotel.io/api/v1/numbers/tracking-pools \
  -H "X-API-Key: dv_live_sk_..."

3. The DNI snippet contract

The GET /numbers/tracking-pools/resolve endpoint is what your site’s swap snippet calls. Pass the visitor’s UTM parameters, referrer, and a stable session key (any cookie/session id you already have); it returns the DID to display, the pool that produced it, and the attributed source and campaign. When nothing matches it returns number: null and the page keeps its default number.

curl "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/resolve?utm_source=google&utm_medium=cpc&gclid=abc123&session=s_xyz" \
  -H "X-API-Key: dv_live_sk_..."

Response:

{
  "data": {
    "number": "+14155550142",
    "poolId": "trackingPool_9k2m8p",
    "source": "google",
    "campaign": "brand-search"
  }
}

The query parameters — all optional, snake_case: utm_source, utm_medium, utm_campaign, utm_term, referrer, gclid, session. Before — a static site number:

<a href="tel:+14155550100">Call us: +1 (415) 555-0100</a>

After — swap by referrer/UTM/session:

<a id="call-track-link" href="tel:+14155550100">Call us: +1 (415) 555-0100</a>
<script>
  (async () => {
    const el = document.getElementById("call-track-link");
    const session =
      // Prefer your existing session cookie; fall back to generating one
      // && persist it so the sticky strategy sees a stable key.
      crypto.randomUUID();
    const url = new URL(location.href);
    const params = new URLSearchParams({
      utm_source: url.searchParams.get("utm_source") ?? "",
      utm_medium: url.searchParams.get("utm_medium") ?? "",
      utm_campaign: url.searchParams.get("utm_campaign") ?? "",
      utm_term: url.searchParams.get("utm_term") ?? "",
      referrer: document.referrer,
      gclid: url.searchParams.get("gclid") ?? "",
      session,
    });
    try {
      // Call resolve from your backend or an endpoint that holds the API key;
      // do not ship a secret API key to the browser.
      const res = await fetch(
        "/orbit/dni-resolve?" + params.toString()
      );
      const { data } = await res.json();
      if (data.number) {
        el.href = "tel:" + data.number;
        el.textContent = "Call us: " + data.number;
      }
    } catch {
      // Network or API failure — keep the page's default number.
    }
  })();
</script>

Proxy /orbit/dni-resolve from your own backend to GET /numbers/tracking-pools/resolve with your API key, or use a publishable flow that adds the key server-side — an API key must never reach the browser. On failure or no-match, the snippet leaves the default number untouched.

4. Assign tracking DIDs to the pool

A pool with no DIDs never swaps. Assign owned DIDs with POST /numbers/tracking-pools/:id/assign:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/trackingPool_9k2m8p/assign \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155550142" }'

The assignment rules:

The number must be in E.164 (+14155550142) — anything else returns 422.
The number must belong to your organization; an unknown or foreign DID returns 404 so you cannot enumerate another org’s numbers.
A DID belongs to at most one pool. Assigning it to a new pool moves it out of the old pool atomically, so one number always maps to exactly one source.
Remove a DID with POST /numbers/tracking-pools/:id/unassign and the same body shape.
Buy the DIDs first with the normal purchase flow — see Buy and provision numbers. Toll-free and local voice-capable DIDs both work as tracking numbers.

5. Read attribution

Inbound calls to tracking DIDs show up on GET /insights/call-attribution, grouped by source and campaign with per-source call, answered, and duration aggregates:

curl "https://api.orbit.devotel.io/api/v1/insights/call-attribution?days=30" \
  -H "X-API-Key: dv_live_sk_..."

Parameter	Description
`days`	Lookback window, 1–365 days. Defaults to 30.
`from` / `to`	Explicit ISO window; overrides `days`. Over-long windows clamp to 365 days.
`pool_id`	Restrict the summary to one pool.

curl "https://api.orbit.devotel.io/api/v1/insights/call-attribution?from=2026-08-01&to=2026-08-24" \
  -H "X-API-Key: dv_live_sk_..."

The response carries totals (calls, answered, per-DID rows, distinct sources) plus a sources array — one row per source/campaign pair — sorted by call volume. The same data renders under Insights → Call attribution in the dashboard. Because the join is read-time (DID → pool → source), a call to a DID that is not assigned to any pool does not attribute, and deleting a pool keeps history for the remaining pools but drops that source row going forward.

6. Constraints

Inbound-only. Tracking DIDs terminate inbound calls. No outbound (MT) voice or SMS path is created by a pool, and assignment only ever gates on number ownership.
Storage. Pools live in your organization’s settings JSONB, so no migration is needed and sibling sub-accounts never share pools.
Scope. Reads require numbers:read; create, update, delete, assign, and unassign require numbers:write. Resolve reads through numbers:read.
Quotas. Up to 200 pools per organization and 1,000 tracking DIDs per pool; over-quota writes return 429. Delete an unused pool or move DIDs to unblock.
One pool per DID. A DID maps to one source by design, so never assign the same DID to parallel pools expecting both to attribute.

7. Troubleshooting

Symptom	Check
The page never swaps the number.	The pool has no tracking DIDs — assign at least one. The pool is disabled (`enabled: false`). No pool’s match rules hold for the visitor — `/resolve` returns `number: null` and the snippet keeps the default. The snippet’s `session` key changes per call, so `sticky` re-hashes. `gclid`/UTM parameters are lost between the landing page and the page running the snippet — capture them at first touch.
Attribution is empty.	`days`/`from`/`to` does not cover the call window. The calls dialed the default site number, not a pool’s DID. Assignments happened after the calls (the join is read-time, so re-assign and the historical calls attribute correctly).
A session sees a stale or wrong DID.	The pool was edited or the DID was moved between page loads. Under `sticky`, the same session hashes to the same DID from whatever the pool currently holds — the resolver is deterministic per call, so a moved DID changes what an old session sees on the next load.
`422` on assign.	`phoneNumber` is not E.164 — pass `+14155550142` with no spaces or punctuation.
`404` on assign.	The DID is not owned by your organization (or the pool id is wrong) — buy the DID first or check the id.
`429` on create/assign.	Pool-count or per-pool DID-count quota reached. Delete an unused pool or keep a pool’s DID set under 1,000.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Call tracking & dynamic number insertion (DNI)

Call tracking & dynamic number insertion

1. When to use it

2. Create a tracking pool

3. The DNI snippet contract

4. Assign tracking DIDs to the pool

5. Read attribution

6. Constraints

7. Troubleshooting

​Call tracking & dynamic number insertion

​1. When to use it

​2. Create a tracking pool

​3. The DNI snippet contract

​4. Assign tracking DIDs to the pool

​5. Read attribution

​6. Constraints

​7. Troubleshooting

Call tracking & dynamic number insertion

1. When to use it

2. Create a tracking pool

3. The DNI snippet contract

4. Assign tracking DIDs to the pool

5. Read attribution

6. Constraints

7. Troubleshooting