Skip to main content
GET
/
api
/
v1
/
entities
/
users
/
{id}
Get User
curl --request GET \
  --url https://api.example.com/api/v1/entities/users/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "user_abc123def456",
  "firstName": "John",
  "lastName": "Doe",
  "username": null,
  "primaryEmailAddressId": "idn_xyz789",
  "primaryEmailAddress": {
    "id": "idn_xyz789",
    "emailAddress": "john.doe@example.com",
    "verification": {
      "status": "verified"
    }
  },
  "emailAddresses": [
    {
      "id": "idn_xyz789",
      "emailAddress": "john.doe@example.com",
      "verification": {
        "status": "verified"
      }
    }
  ],
  "primaryPhoneNumberId": null,
  "phoneNumbers": [],
  "imageUrl": "https://img.clerk.com/user_abc123def456",
  "hasImage": true,
  "externalId": null,
  "publicMetadata": {},
  "privateMetadata": {
    "bullhornUserId": 12345
  },
  "unsafeMetadata": {},
  "createdAt": 1704067200000,
  "updatedAt": 1704153600000,
  "lastSignInAt": 1704153600000,
  "twoFactorEnabled": false,
  "banned": false,
  "locked": false
}
Retrieves the full details of a user by their Clerk user ID. This endpoint returns user profile information including contact details, profile picture, and metadata.
User management (creation, updates, deletion) is handled directly through Clerk. This endpoint provides read-only access to user data.

​
Authentication

This endpoint requires authentication. The user must be signed in.

​
Request

​
id
string
required
The Clerk user ID of the user to retrieve (e.g., user_abc123).

​
Response

Returns the complete Clerk user object.
​
id
string
required
Unique Clerk user identifier.
​
firstName
string | null
required
The user’s first name. May be null if not set.
​
lastName
string | null
required
The user’s last name. May be null if not set.
​
username
string | null
required
The user’s username. May be null if not set.
​
primaryEmailAddressId
string | null
required
ID of the user’s primary email address.
​
primaryEmailAddress
object | null
The user’s primary email address object.
​
emailAddresses
array
required
Array of all email addresses associated with this user.
​
primaryPhoneNumberId
string | null
required
ID of the user’s primary phone number. May be null if not set.
​
phoneNumbers
array
required
Array of all phone numbers associated with this user.
​
imageUrl
string
required
URL to the user’s profile image.
​
hasImage
boolean
required
Whether the user has uploaded a custom profile image.
​
externalId
string | null
required
External identifier for the user if set. May be null.
​
publicMetadata
object
required
Public metadata object for the user. Accessible from frontend.
​
privateMetadata
object
required
Private metadata object for the user. Only accessible from backend.
​
unsafeMetadata
object
required
Unsafe metadata object that can be modified from frontend.
​
createdAt
number
required
Unix timestamp (milliseconds) of when the user was created.
​
updatedAt
number
required
Unix timestamp (milliseconds) of when the user was last updated.
​
lastSignInAt
number | null
required
Unix timestamp (milliseconds) of the user’s last sign-in. May be null if never signed in.
​
twoFactorEnabled
boolean
required
Whether the user has two-factor authentication enabled.
​
banned
boolean
required
Whether the user is banned from the organization.
​
locked
boolean
required
Whether the user account is locked.

​
Response Examples

{
  "id": "user_abc123def456",
  "firstName": "John",
  "lastName": "Doe",
  "username": null,
  "primaryEmailAddressId": "idn_xyz789",
  "primaryEmailAddress": {
    "id": "idn_xyz789",
    "emailAddress": "john.doe@example.com",
    "verification": {
      "status": "verified"
    }
  },
  "emailAddresses": [
    {
      "id": "idn_xyz789",
      "emailAddress": "john.doe@example.com",
      "verification": {
        "status": "verified"
      }
    }
  ],
  "primaryPhoneNumberId": null,
  "phoneNumbers": [],
  "imageUrl": "https://img.clerk.com/user_abc123def456",
  "hasImage": true,
  "externalId": null,
  "publicMetadata": {},
  "privateMetadata": {
    "bullhornUserId": 12345
  },
  "unsafeMetadata": {},
  "createdAt": 1704067200000,
  "updatedAt": 1704153600000,
  "lastSignInAt": 1704153600000,
  "twoFactorEnabled": false,
  "banned": false,
  "locked": false
}

​
Error Codes

Status CodeError CodeDescription
401UNAUTHORIZEDUser is not authenticated. Ensure a valid session exists.
404NOT_FOUNDNo user exists with the specified Clerk ID.
500INTERNAL_ERRORAn unexpected server error occurred.