Claude API User Profiles: Identify Each Customer

Claude API user profiles let you tell Anthropic which end customer an API request belongs to. Anthropic’s October 20, 2026 announcement identifies /v1/user_profiles as the endpoint family and says this attribution lets a safety enforcement action apply to an individual customer instead of your whole organization. This is especially relevant if you operate a platform or gateway, or resell API access. See the Claude Platform release notes.

To integrate the feature, plan how your authenticated customer identity will connect to a user profile and remain attached to that customer’s requests. There’s one implementation boundary to respect: as of October 21, 2026, the release-notes page does not list the profile request schema or the field used to identify a profile on an inference request. The local examples below help validate your application’s attribution logic; they aren’t Claude API request examples.

What Claude API user profiles change#

Consider a gateway serving several unrelated customers through your organization. Your application knows who submitted each request, but that knowledge needs to reach Anthropic for customer-specific enforcement to be possible.

User profiles provide the feature for communicating that distinction. The documented payoff is enforcement scope: Anthropic can apply a safety action to one end customer instead of the organization operating the platform. As of October 21, 2026, that is the behavior described in the launch announcement.

Read “can” carefully. The announcement describes a capability, not a guarantee that every future enforcement action will affect only a profile. It does not spell out enforcement decision criteria. Don’t turn this feature into a customer promise that your organization can never face an action.

A useful design objective is accurate attribution. Each outgoing request should represent the customer actually responsible for it. A profile mapping that exists in your database but gets lost during request dispatch won’t meet that objective.

For a practical starting point, sketch the route from customer authentication through your gateway to the outgoing API call. Mark every place where customer identity could be dropped, replaced, or confused with another identifier.

Choose the customer identity before wiring requests#

Start by deciding what “end customer” means in your product. It might be the business buying access to your gateway or the account using your application. That is an application design decision to resolve against the detailed endpoint documentation; the launch announcement does not define your account hierarchy for you.

I’d begin with the entity your application already treats as responsible for usage. Write down that choice before implementing the mapping. If one team uses a business account while another uses an individual login, the resulting attribution can become inconsistent even when both implementations appear reasonable in isolation.

Keep these concepts separate in your design:

These are suggested application concepts, not Anthropic field names or a profile schema.

Avoid letting arbitrary request content choose the responsible customer. Resolve that association in your backend. This makes the attribution rule easier to review and reduces accidental cross-customer routing.

Validate attribution locally before calling the API#

You can test a useful part of the integration without knowing the endpoint payload: whether your application consistently resolves work to the correct customer.

The following Python example uses fictional local customer keys and local mapping labels. Every key and label belongs to this demonstration. None represents an Anthropic profile ID, an accepted ID format, or an API request field.

customer_profiles = {
    "customer_alpha": "local_mapping_alpha",
    "customer_beta": "local_mapping_beta",
}

jobs = [
    {"customer": "customer_alpha", "task": "interactive"},
    {"customer": "customer_beta", "task": "interactive"},
    {"customer": "customer_alpha", "task": "background"},
]

for job in jobs:
    customer = job["customer"]
    mapping = customer_profiles[customer]
    print(f"{customer}: {job['task']} -> {mapping}")

assert customer_profiles["customer_alpha"] != customer_profiles["customer_beta"]
assert len({customer_profiles[job["customer"]] for job in jobs
            if job["customer"] == "customer_alpha"}) == 1
print("Local customer mapping checks passed.")

The checks express two application expectations: different customers retain separate associations, and one customer retains the same association across interactive and background work.

Next, decide how your application should handle missing attribution. My recommendation is to stop the affected dispatch and surface an actionable internal error until the mapping is resolved. That is an application policy recommendation, not a documented requirement of /v1/user_profiles.

Don’t silently substitute another customer’s mapping to keep traffic moving. A fallback like that makes the request appear attributed while assigning responsibility to the wrong account. Review fallback behavior just as carefully as the normal path.

What to verify before implementing /v1/user_profiles#

As of October 21, 2026, Anthropic’s release notes confirm support for the new /v1/user_profiles endpoints in the SDK and the ant CLI. The page does not list a minimum SDK version, CLI command syntax, endpoint methods, authentication requirements for those endpoints, or their request and response schemas.

That means there isn’t enough documented detail on that page to supply a correct copy-paste API call. Guessing a profile identifier field would be particularly risky: even a plausible-looking request can communicate the wrong integration contract.

Use this reference when consulting the endpoint documentation linked from the official release notes:

This table is a verification list, not a claim that a particular operation or field exists.

Keep the first integration narrow: one authenticated customer, its documented profile association, and a request sent using the documented attachment mechanism. Expand to queues and other dispatch paths after that connection is established.

Model choice does not resolve missing attribution details. Adding model IDs, token settings, or unrelated request options to an example would leave the central question unanswered: how does this request identify its end customer?

Plan for restriction and restoration notifications#

Customer attribution also creates an operational question: how will your application learn that a customer’s enforcement status has changed?

As of October 21, 2026, Anthropic’s October 20 release entry documents organization webhooks in the Admin API, in beta, using the webhooks-2026-10-07 beta header. It identifies /v1/organizations/webhooks as the endpoint family for registering webhook endpoints. Access is requested through your Anthropic account team, according to the organization webhook announcement in the release notes.

The announcement describes two event categories: one when Anthropic restricts or bans one of your organization’s user profiles, and another when that restriction or ban ends. It does not list their event identifiers or payload schemas on the release-notes page.

Design your application’s response around those categories, while leaving the actual payload parsing to the documented contract. For example, plan how an affected customer would see an account-specific status message and how your support team would identify the corresponding account.

Restoration needs a deliberate path too. An interface that can display a restriction but cannot clear it after a verified restoration notification creates avoidable support work.

For adjacent enterprise workflows, see CoreMesh’s articles on Claude Compliance API user preferences and exporting Claude instructions for enterprise audits. Treat those as separate integration topics when planning your implementation.

Common mistakes with customer attribution#

The easiest mistake is equating a conversation with a customer. Your application may create several conversations for the same account. If your mapping follows the conversation alone, customer responsibility can become fragmented. Decide the customer boundary first, then keep conversation tracking separate.

Another mistake is handling attribution only in the interactive request path. Background jobs and other delayed work still need their owning customer preserved. Check the point where work enters a queue and the point where a worker dispatches it; both should agree about ownership.

A shared catch-all mapping is also a poor fallback. It merges customers your integration is supposed to distinguish. Prefer an explicit unresolved state in your application so a missing association is visible and repairable.

Don’t copy the webhook beta header into profile requests on the assumption that both features share the same requirements. As of October 21, 2026, the release notes associate webhooks-2026-10-07 with organization webhooks. They do not state a user-profile header requirement.

Finally, avoid treating SDK support as a complete implementation specification. The announcement confirms support, but the exact method names and request shapes still need the relevant reference documentation. The same applies to ant: support is documented; a particular CLI invocation is not shown on the release-notes page.

Customer attribution implementation checklist#

Use this checklist to turn the feature announcement into a reviewable integration plan:

• Define which entity in your product counts as the end customer.
• Resolve that customer from trusted backend context.
• Keep a clear association between the customer and its profile.
• Verify endpoint methods, authentication, schemas, and request attachment details in the official reference.
• Check attribution in interactive requests and delayed work.
• Make missing mappings visible rather than silently sharing another association.
• Plan customer-facing handling for restrictions and their end.
• Verify webhook access and payload details before implementing event handling.

As of October 21, 2026, the official release notes establish the feature’s purpose and endpoint families. Use their linked user-profile and webhook documentation to check the current implementation contract before shipping.

Quick answers