Users

This object represents a verified user in your instance.

Available requests

  • GET /v1/users/:id

  • GET /v1/users

  • PATCH/v1/users/:id

  • DELETE /v1/users/:id

Example user schema

{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user",
"username": null,
"first_name": "Boss",
"last_name": "Clerk",
"profile_image_url": "https://images.clerk.services/clerk/default-profile.svg",
"primary_email_address_id": "idn_1oBNgISXFbSf5m0uP2Wl0qWtNGX",
"primary_phone_number_id": null,
"password_enabled": true,
"two_factor_enabled": false,
"email_addresses": [
{
"id": "idn_1oBNgISXFbSf5m0uP2Wl0qWtNGX",
"object": "email_address",
"email_address": "[email protected]",
"verification": {
"status": "verified",
"strategy": "email_code",
"attempts": 1,
"expire_at": 1612756733
},
"linked_to": []
}
],
"phone_numbers": [
{
"id": "idn_1q8Uq8Mc4t7WWMy9Z6Og0gNJVui",
"object": "phone_number",
"phone_number": "+15555555555",
"reserved_for_second_factor": false,
"verification": {
"status": "verified",
"strategy": "phone_code",
"attempts": 1,
"expire_at": 1616461499
},
"linked_to": []
}
],
"external_accounts": [],
"public_metadata": {},
"private_metadata": {},
"created_at": 1612756155,
"updated_at": 1612756155
}

‚Äč

get
Retrieve a user

https://api.clerk.dev/v1/users/:id
Retrieve the details of a user.
Request
Response
Request
Headers
Authentication
required
string
Bearer [YOUR_API_KEY]
Response
200: OK
// see example schema
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
}

get
List all users

https://api.clerk.dev/v1/users
List all users. Ordered by creation date, with the newest user first.
Request
Response
Request
Headers
Authorization
required
string
Bearer [YOUR_API_KEY]
Query Parameters
phone_number[]
optional
string
Returns users with the phone numbers specified. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.
email_address[]
optional
string
Returns users with the email addresses specified. Accepts up to 100 email addresses. Any email addresses not found are ignored.
user_id[]
optional
string
Returns users with the user ids specified. Accepts up to 100 user ids. Any user ids not found are ignored.
offset
optional
string
Offset allows pagination through all users. If used, returns users starting after the number supplied.
limit
optional
integer
Puts a limit on the number of users returned. You may return anywhere from 1 to 100 users at a time. Defaults to 10.
Response
200: OK
Cake successfully retrieved.
[
// see example schema
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
},
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
},
]

patch
Update a user

https://api.clerk.dev/v1/users/:id
Update a user.
Request
Response
Request
Headers
Authorization
required
string
Bearer [YOUR_API_KEY]
Form Data Parameters
public_metadata
optional
object
Metadata saved on the user, that is visible to both your frontend and backend. Note: Object passed in will replace previous value.
private_metadata
optional
object
Metadata saved on the user that is only visible to your backend. Note: Object passed in will replace previous value.
Response
200: OK
// see example schema
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
}

delete
Delete a user

https://api.clerk.dev/v1/users/:id
Delete a user.
Request
Response
Request
Headers
Authorization
required
string
Bearer [YOUR_API_KEY]
Response
200: OK
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user",
"deleted": true
}