Claude Platform Docs

Update User Profile

$ ant beta:user-profiles update
POST/v1/user_profiles/{user_profile_id}

Update User Profile

Parameters
--user-profile-id: string⁠Path parameter

The ID of the user profile to update (uprof_...).

--access-type: optional "application" or "passthrough"

If present, replaces the stored access type. Omit to leave unchanged.

--external-id: optional string

If present, replaces the stored external_id. Omit to leave unchanged. Maximum 255 characters. Accepted under the user-profiles-2026-03-24 and user-profiles-2026-08-18 beta headers; under user-profiles-2026-09-04 send external_user_details.reference_id instead.

minLength1
maxLength255
--external-user-details: optional object{ account_status, country, email_hash, 4 more }

Details about the entity this profile represents, as the platform states them. Each field sent replaces the stored value; omit a field to leave it unchanged. Once set, a value cannot be cleared and null is rejected. Accepted under the user-profiles-2026-09-04 beta header only.

--external-user-onboarded-at: optional string

If present, replaces the stored account creation time. Omit to leave unchanged; once set, the value cannot be cleared and null is rejected. Must be a complete RFC 3339 timestamp no more than 1 minute in the future. Accepted under the user-profiles-2026-08-18 beta header; under user-profiles-2026-09-04 send external_user_details.onboarded_at instead.

formatdate-time
--metadata: optional map[string]

Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters.

--name: optional string

If present, replaces the stored name. Omit to leave unchanged. Maximum 255 characters.

minLength1
maxLength255
--beta: optional array of AnthropicBeta⁠Header parameter

Optional header to specify the beta version(s) you want to use.

--workspace-id: optional string⁠Header parameter

Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).

Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

Returns
beta_user_profile: object{ type: "user_profile", id, created_at, 8 more }

A record of an entity that the platform serves through the API, such as an end-user of the platform's product or a company that the platform resells Claude access to.

A Messages, Message Batches or token counting request can send a profile's id in the anthropic-user-profile-id header to attribute the request to that entity.

type: "user_profile"

Object type. Always user_profile.

id: string

Unique identifier for this user profile, prefixed uprof_.

created_at: string

When this user profile was created, in RFC 3339 format.

formatdate-time
metadata: map[string]

Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

trust_grants: map[BetaUserProfileTrustGrant { status }]

Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

status: "active" or "pending" or "rejected"

Status of the trust grant.

One of the following:
"active"
"pending"
"rejected"
updated_at: string

When this user profile was last modified, in RFC 3339 format. Trust-grant status changes also bump this timestamp.

formatdate-time
access_type: optional "application" or "passthrough"

How the platform uses the API for this entity: application (default) or passthrough. Present under the user-profiles-2026-08-18 and later beta headers.

One of the following:
"application"

The user profile represents an individual end-user of a product that the platform builds on the API. New profiles get this value by default.

"passthrough"

The user profile represents a company that the platform resells Claude access to.

external_id: optional string

Platform's own identifier for this user. Not enforced unique. Present under the user-profiles-2026-03-24 and user-profiles-2026-08-18 beta headers; under user-profiles-2026-09-04 the value is external_user_details.reference_id.

external_user_details: optional object{ account_status, country, email_hash, 4 more }

Details about the entity this profile represents, as the platform states them; not verified by Anthropic. Present under the user-profiles-2026-09-04 beta header, with every field present and null until the platform supplies a value; the earlier beta headers serve reference_id as the top-level external_id, and user-profiles-2026-08-18 serves onboarded_at as external_user_onboarded_at.

account_status: "active" or "suspended" or "blocked"

The status of the entity's account on the platform: active, suspended or blocked. null until the platform supplies one.

One of the following:
"active"

The platform has neither restricted nor barred the account of the entity that the user profile represents.

"suspended"

The platform has restricted the account of the entity that the user profile represents and may restore it.

"blocked"

The platform has barred the account of the entity that the user profile represents.

country: string

The country the platform associates with the entity, as an ISO 3166-1 alpha-2 code. null until the platform supplies one.

email_hash: string

The platform-computed hash of the entity's email address. null until the platform supplies one.

entity_type: "individual" or "business" or "non_profit" or "government"

What kind of entity the profile represents: individual, business, non_profit or government. null until the platform supplies one.

One of the following:
"individual"
"business"
"non_profit"
"government"
name_hash: string

The platform-computed hash of the entity's name. null until the platform supplies one.

onboarded_at: string

When the entity opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). null until the platform supplies one.

formatdate-time
reference_id: string

The platform's own reference for the entity. null until the platform supplies one.

external_user_onboarded_at: optional string

When the entity this profile represents opened its account with the platform, as stated by the platform, in RFC 3339 format (UTC). null until the platform supplies one. Present under the user-profiles-2026-08-18 beta header; under user-profiles-2026-09-04 the value is external_user_details.onboarded_at.

formatdate-time
name: optional string

Real-world name of the entity this profile represents (company or individual). For a company the platform resells Claude access to (access_type passthrough) this is that company's name.

Update User Profile
ant beta:user-profiles update \
  --api-key my-anthropic-api-key \
  --user-profile-id uprof_011CZkZCu8hGbp5mYRQgUmz9
Returns Examples
Response 200
{
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "created_at": "2026-03-15T10:00:00Z",
  "metadata": {},
  "trust_grants": {
    "cyber": {
      "status": "active"
    }
  },
  "type": "user_profile",
  "updated_at": "2026-03-15T10:00:00Z",
  "access_type": "application",
  "external_id": "user_12345",
  "external_user_details": {
    "account_status": "active",
    "country": "country",
    "email_hash": "email_hash",
    "entity_type": "individual",
    "name_hash": "name_hash",
    "onboarded_at": "2019-12-27T18:11:19.117Z",
    "reference_id": "reference_id"
  },
  "external_user_onboarded_at": "2024-11-02T08:15:00Z",
  "name": "Example User"
}