Create User Profile

post/v1/user_profiles?beta=true

Headers

anthropic-versionstring

anthropic-betastring

Request body

external_idstring nullable

Platform's own identifier for this user. Not enforced unique. Maximum 255 characters.

namestring nullable

Optional for all profiles. Real-world name of the entity this profile represents (company or individual); for a resold-to company (relationship resold / access_type passthrough), that company's name where known. Maximum 255 characters.

relationship'external' | 'resold' | 'internal'

How the entity behind a user profile relates to the platform that owns the API key. external: an individual end-user of the platform. resold: a company the platform resells Claude access to. internal: the platform's own usage.

access_type'application' | 'passthrough'

How the platform uses the API on behalf of the entity this profile represents. application: the platform sells a product that uses the API behind the scenes, and the profile represents an individual end-user of that product. passthrough: the platform resells raw inference, and the profile identifies the resold-to company.

metadataobject

Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings.

Example request

{
  "external_id": "user_12345",
  "metadata": {}
}

Response

Successful response (OK)

idstring required

Unique identifier for this user profile, prefixed uprof_.

type'user_profile' required

Object type. Always user_profile.

external_idstring nullable

Platform's own identifier for this user. Not enforced unique.

namestring nullable

Real-world name of the entity this profile represents (company or individual). For a resold-to company (access_type passthrough, or relationship resold under the user-profiles-2026-03-24 header) this is that company's name.

relationship'external' | 'resold' | 'internal'

access_type'application' | 'passthrough'

trust_grantsobject required

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

created_atstring date-time required

A timestamp in RFC 3339 format

metadataobject required

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

updated_atstring date-time required

A timestamp in RFC 3339 format

Example response

{
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "type": "user_profile",
  "external_id": "user_12345",
  "name": "Example User",
  "relationship": "external",
  "trust_grants": {
    "cyber": {
      "status": "active"
    }
  },
  "metadata": {},
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

Changes

Changed in 4 of the 67 revisions of this API.511

Aug 18, 2026d3515f9e9eca12See the full diff
- ▲
  the response property relationship became optional for the status 200
  response-property-became-optional
- ○
  added the new optional request property access_type
  new-optional-request-property
- ○
  added the optional property access_type to the response with the 200 status
  response-optional-property-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 17, 2026d2b230555b7f44See the full diff
- ▲
  the request property external_id became not nullable
  request-property-became-not-nullable
- ▲
  the request property name became not nullable
  request-property-became-not-nullable
- ▲
  response property external_id list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property name list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ○
  request property external_id list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property name list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  the external_id request property's minLength was decreased from 1 to 0
  request-property-min-length-decreased
- ○
  the name request property's minLength was decreased from 1 to 0
  request-property-min-length-decreased
May 6, 2026a4186730f56c4See the full diff
- ○
  added the new optional request property name
  new-optional-request-property
- ○
  added the new optional request property relationship
  new-optional-request-property
- ○
  added the optional property name to the response with the 200 status
  response-optional-property-added
- ○
  added the required property relationship to the response with the 200 status
  response-required-property-added
This revision also has 22 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 16, 2026e0696f59ae071See the full diff
- ○
  endpoint added
  endpoint-added

Full history