---
title: "How does DX link Claude Code users?"
canonical_url: "https://docs.getdx.com/knowledgebase/claude-code-user-linking/"
md_url: "https://docs.getdx.com/knowledgebase/claude-code-user-linking.md"
last_updated: "2026-07-24"
---

# How does DX link Claude Code users?
DX creates and links Claude Code user identities automatically by matching identity fields across connectors. This article explains how that process works and what to expect when running one or more Claude Code connectors.

## Identity fields

Claude Code telemetry can carry up to three identity fields per data point:


| Field | Source | Always present? |
| ----- | ------ | --------------- |
| Email address | `user.email` in OTel payloads; API user records | No — some OTel payloads may omit it |
| Account ID | `user.account_id` in OTel payloads | No — only present for Anthropic-managed accounts |
| User ID | `user.id` in OTel payloads; API user records | No |


DX uses these fields to identify and merge user records so that a single person is not counted twice — even when their data arrives from different connectors or at different times.

## How user records are created

Each Claude Code connector creates user records differently:

- **Claude Code (Anthropic Console)** and **Claude Code (Enterprise)** import users via the Anthropic Analytics API. Each user has an email address and a user ID.
- **Claude Code (OTel)** creates users from telemetry payloads. A user record is created the first time DX sees an identity it does not already have. Early payloads may only carry an account ID or user ID without an email address — the email is backfilled automatically when a later payload includes it.

## How user matching works

When a new OTel payload arrives, DX matches it to an existing user in this order:

1. **Match by account/user ID** — DX first looks for an existing user whose stored ID matches the payload's account ID (preferred) or user ID. If found, the existing user is reused and any missing fields (email, name) are filled in.

2. **Fall back to email** — If no ID match is found, DX looks for a user with the same email address. The email user is reused **only if** the IDs are compatible (one or both are blank). If the existing user already has a different ID, DX creates a new user record instead — this allows the same email to appear under multiple Anthropic accounts.

3. **Create a new user** — If neither lookup finds a match, a new user record is created.

## Cross-user email backfill

OTel payloads can carry both a `user.account_id` and a `user.id`. These may correspond to **separate** user records in DX (created at different times from different payloads). When a payload arrives with an email address, DX automatically backfills that email onto any other user records whose ID matches either the payload's account ID or user ID — as long as those records do not already have an email.

This means that once **any** payload for a user includes an email, all related user records are updated, and all of them become eligible for linking to a DX user.

## Linking Claude Code users to DX users

After user records are created or updated, DX links them to DX user profiles based on email address:

1. DX finds all Claude Code user records that have an email but are not yet linked.
2. If another Claude Code user with the same email is already linked to a DX user, the new record is linked to the same DX user.
3. Otherwise, DX matches by email against the DX user directory.

Multiple Claude Code user records with the same email (but different account IDs) are all linked to the same DX user.

> **Tip:** For OTel deployments using AWS Bedrock or Google Vertex AI, the Anthropic API has no visibility into those users. To ensure user linking works, set `user.email` in the `OTEL_RESOURCE_ATTRIBUTES` environment variable on each developer's machine. See the [Claude Code (OTel) setup instructions](https://docs.getdx.com/connectors/claude-code-otel/) for details.

## Running multiple connectors

When you run both an API-based connector and OTel, the same person may have user records created by both connectors. DX links all of them to a single DX user via email matching.

For reporting, **OTel data takes precedence** when a user has activity from both sources. See [Which Claude Code connector should I use?](https://docs.getdx.com/knowledgebase/claude-code-duplicate-data/) for guidance on connector selection.

## Troubleshooting

#### A user appears unlinked in the DX UI

- **Missing email:** OTel-only users may initially lack an email if early payloads did not include `user.email`. Once a payload with their email arrives, the user record is updated and linking happens automatically. For Bedrock/Vertex deployments, ensure `OTEL_RESOURCE_ATTRIBUTES` includes `user.email`.
- **Email mismatch:** The email in Claude Code must match the user's email in DX. If they differ (e.g., personal vs. work email), link the user manually in the DX UI.

#### A user appears as multiple entries

This can happen when the same person has user records with different account IDs. As long as the email is the same, all records link to the same DX user and metrics are combined in reports. If the emails differ, contact support@getdx.com for assistance.
---

## Sitemap

[Overview of all docs pages](/llms.txt)