Browse: Home / REST API Handbook / Reference / Users

Users Edit

Topics

Schema Schema

The schema defines all the fields that exist within a user record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.

id

integer 		Unique identifier for the user.

Read only

Context: embed, view, edit
username

string 		Login name for the user.

Context: edit
name

string 		Display name for the user.

Context: embed, view, edit
first_name

string 		First name for the user.

Context: edit
last_name

string 		Last name for the user.

Context: edit
email

string,
email
 		The email address for the user.

Context: edit
url

string,
uri
 		URL of the user.

Context: embed, view, edit
description

string 		Description of the user.

Context: embed, view, edit
locale

string 		Locale for the user.

Context: edit

One of: , en_US

nickname

string 		The nickname for the user.

Context: edit
slug

string 		An alphanumeric identifier for the user.

Context: embed, view, edit
registered_date

string,
datetime (details)
 		Registration date for the user.

Read only

Context: edit
roles

array 		Roles assigned to the user.

Context: edit
password

string 		Password for the user (never included).

Context:

capabilities

object 		All capabilities assigned to the user.

Read only

Context: edit
extra_capabilities

object 		Any extra capabilities assigned to the user.

Read only

Context: edit
avatar_urls

object 		Avatar URLs for the user.

Read only

Context: embed, view, edit
meta

object 		Meta fields.

Context: view, edit

Top ↑

List Users List Users

Query this endpoint to retrieve a collection of users. The response you receive can be controlled and filtered using the URL query parameters below.

Definition Definition

GET /wp/v2/users

Top ↑

Example Request Example Request

$ curl https://example.com/wp-json/wp/v2/users

Top ↑

Arguments Arguments

context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

page Current page of the collection.

Default: 1

per_page Maximum number of items to be returned in result set.

Default: 10

search Limit results to those matching a string.
exclude Ensure result set excludes specific IDs.
include Limit result set to specific IDs.
offset Offset the result set by a specific number of items.
order Order sort attribute ascending or descending.

Default: asc

One of: asc, desc

orderby Sort collection by object attribute.

Default: name

One of: id, include, name, registered_date, slug, include_slugs, email, url

slug Limit result set to users with one or more specific slugs.
roles Limit result set to users matching at least one specific role provided. Accepts csv list or single role.
who Limit result set to users who are considered authors.
One of: authors

Top ↑

Create a User Create a User

Top ↑

Arguments Arguments

username Login name for the user.

Required: 1

name Display name for the user.
first_name First name for the user.
last_name Last name for the user.
email The email address for the user.

Required: 1

url URL of the user.
description Description of the user.
locale Locale for the user.
One of: , en_US
nickname The nickname for the user.
slug An alphanumeric identifier for the user.
roles Roles assigned to the user.
password Password for the user (never included).

Required: 1

meta Meta fields.

Top ↑

Definition Definition

POST /wp/v2/users

Top ↑

Retrieve a User Retrieve a User

Top ↑

Definition & Example Request Definition & Example Request

GET /wp/v2/users/<id>

Query this endpoint to retrieve a specific user record.

$ curl https://example.com/wp-json/wp/v2/users/<id>

Top ↑

Arguments Arguments

id Unique identifier for the user.
context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

Top ↑

Update a User Update a User

Top ↑

Arguments Arguments

id Unique identifier for the user.
username Login name for the user.
name Display name for the user.
first_name First name for the user.
last_name Last name for the user.
email The email address for the user.
url URL of the user.
description Description of the user.
locale Locale for the user.
One of: , en_US
nickname The nickname for the user.
slug An alphanumeric identifier for the user.
roles Roles assigned to the user.
password Password for the user (never included).
meta Meta fields.

Top ↑

Definition Definition

POST /wp/v2/users/<id>

Top ↑

Example Request Example Request

Top ↑

Delete a User Delete a User

Top ↑

Arguments Arguments

id Unique identifier for the user.
force Required to be true, as users do not support trashing.
reassign Reassign the deleted user's posts and links to this user ID.

Required: 1

Top ↑

Definition Definition

DELETE /wp/v2/users/<id>

Top ↑

Example Request Example Request

$ curl -X DELETE https://example.com/wp-json/wp/v2/users/<id>

Top ↑

Retrieve a User Retrieve a User

Top ↑

Definition & Example Request Definition & Example Request

GET /wp/v2/users/me

Query this endpoint to retrieve a specific user record.

$ curl https://example.com/wp-json/wp/v2/users/me

Top ↑

Arguments Arguments

context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

Top ↑

Update a User Update a User

Top ↑

Arguments Arguments

username Login name for the user.
name Display name for the user.
first_name First name for the user.
last_name Last name for the user.
email The email address for the user.
url URL of the user.
description Description of the user.
locale Locale for the user.
One of: , en_US
nickname The nickname for the user.
slug An alphanumeric identifier for the user.
roles Roles assigned to the user.
password Password for the user (never included).
meta Meta fields.

Top ↑

Definition Definition

POST /wp/v2/users/me

Top ↑

Example Request Example Request

Top ↑

Delete a User Delete a User

Top ↑

Arguments Arguments

force Required to be true, as users do not support trashing.
reassign Reassign the deleted user's posts and links to this user ID.

Required: 1

Top ↑

Definition Definition

DELETE /wp/v2/users/me

Top ↑

Example Request Example Request

$ curl -X DELETE https://example.com/wp-json/wp/v2/users/me