List Users

curl --request GET \
  --url https://api.example.com/api/v1/entities/users \
  --header 'Authorization: Bearer <token>'

[
  {
    "id": "user_abc123",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@company.com",
    "profilePictureUrl": "https://img.clerk.com/user_abc123.jpg",
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-01-15T14:30:00.000Z",
    "clerkId": "user_abc123",
    "clerkOrgId": "org_xyz789"
  },
  {
    "id": "user_def456",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@company.com",
    "profilePictureUrl": null,
    "createdAt": "2024-01-12T10:15:00.000Z",
    "updatedAt": "2024-01-12T10:15:00.000Z",
    "clerkId": "user_def456",
    "clerkOrgId": "org_xyz789"
  }
]

GET

api

entities

users

List Users

curl --request GET \
  --url https://api.example.com/api/v1/entities/users \
  --header 'Authorization: Bearer <token>'

[
  {
    "id": "user_abc123",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@company.com",
    "profilePictureUrl": "https://img.clerk.com/user_abc123.jpg",
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-01-15T14:30:00.000Z",
    "clerkId": "user_abc123",
    "clerkOrgId": "org_xyz789"
  },
  {
    "id": "user_def456",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@company.com",
    "profilePictureUrl": null,
    "createdAt": "2024-01-12T10:15:00.000Z",
    "updatedAt": "2024-01-12T10:15:00.000Z",
    "clerkId": "user_def456",
    "clerkOrgId": "org_xyz789"
  }
]

Retrieves a list of all users belonging to the currently authenticated user’s organization. This endpoint is useful for displaying team members, assigning leads to users, or managing organization-wide user data.

Authentication

This endpoint requires authentication. The user must be signed in and belong to an organization.

Only users within the same Clerk organization are returned. The requesting user must have a valid organization context.

Request

This endpoint does not require any query parameters or request body.

Response

Returns an array of user objects.

users

array

An array of user objects belonging to the organization.

Show User object properties

string

required

Unique identifier for the user (same as clerkId).

firstName

string | null

required

The user’s first name. May be null if not set in Clerk.

lastName

string | null

required

The user’s last name. May be null if not set in Clerk.

string | null

required

The user’s primary email address. May be null if no primary email is set.

profilePictureUrl

string | null

required

URL to the user’s profile picture. May be null if no image is set.

createdAt

string

required

ISO 8601 timestamp of when the user was created.

updatedAt

string

required

ISO 8601 timestamp of when the user was last updated.

clerkId

string

required

The user’s Clerk ID. This is the same value as id.

clerkOrgId

string | null

required

The Clerk organization ID the user belongs to.

Response Examples

[
  {
    "id": "user_abc123",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@company.com",
    "profilePictureUrl": "https://img.clerk.com/user_abc123.jpg",
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-01-15T14:30:00.000Z",
    "clerkId": "user_abc123",
    "clerkOrgId": "org_xyz789"
  },
  {
    "id": "user_def456",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@company.com",
    "profilePictureUrl": null,
    "createdAt": "2024-01-12T10:15:00.000Z",
    "updatedAt": "2024-01-12T10:15:00.000Z",
    "clerkId": "user_def456",
    "clerkOrgId": "org_xyz789"
  }
]

Error Codes

Status Code	Error Code	Description
400	`VALIDATION_ERROR`	User does not belong to an organization. Ensure the user has joined an organization in Clerk.
401	`UNAUTHORIZED`	User is not authenticated. Ensure a valid session exists.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

​Authentication

​Request

​Response

​Response Examples

​Error Codes

Authentication

Request

Response

Response Examples

Error Codes