-
create-or-fill-userCreate or Fill User -
search-usersSearch Users by Profile Fields -
set-user-rolesSet User Roles
Create or Fill User
Creates a user on the current site with the unclaimed role, or fills only what an existing account is missing. It takes name, email, core user fields (user_url, nickname, display_name, description) and profile fields, and fills an existing account when existing_user is fill_missing and the email (or a registered email alias) already belongs to it. The email is lowercased before lookup and creation. unclaimed is the only role it assigns: an existing user with no account on the current site is added with it, and one with an account but no role on the site is given it; a user who already has a role on the site keeps it. Never overwrites an existing value, except that a nickname or display name still set to a placeholder (an email address or the login) counts as empty; the address (street_address, town, postcode) is filled as one unit only when all three are empty. user_nicename cannot be set. Invalid values are reported per field and never stored. No membership or group changes for existing users. For an existing user, action is unchanged when nothing was or would be filled and the user already had a role on the site. dry_run defaults to true: set it to false to write. Requires promote_users. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
email |
string | Yes | Email address. Lowercased, then used as the login for a new user, and to find an existing one (including registered email aliases). | |
first_name |
string | No | First name. For an existing user, only filled if currently empty. | |
last_name |
string | No | Last name. For an existing user, only filled if currently empty. | |
user_url |
string | No | Website, e.g. a supplier’s site. http or https only; a bare domain such as example.com is given https://. At most 100 characters. For an existing user, only filled if currently empty. | |
nickname |
string | No | Nickname. For an existing user, only filled if currently empty or still a placeholder (an email address or the login). | |
display_name |
string | No | Display name, e.g. a supplier’s trading name. For a new user it replaces the name built from first_name and last_name; for an existing user it is only filled if currently empty or still a placeholder (an email address or the login). At most 250 characters. |
|
description |
string | No | Biographical info. Line breaks are kept and HTML is removed. For an existing user, only filled if currently empty. | |
group_id |
integer | No | Optional BuddyPress group to add a NEW user to. Ignored for existing users. | |
existing_user |
string | No | "refuse" |
What to do when the email already belongs to an account: refuse (return an error, change nothing) or fill_missing. One of: refuse, fill_missing. |
dry_run |
boolean | No | true |
When true (the default) nothing is written; the result reports what would happen. |
fields |
object | No | Profile fields. Each is only filled if the user currently has no value for it; the address (street_address, town, postcode) is filled as one unit, only when all three are empty. Invalid values are reported per field and never stored. |
|
task_id |
integer | No | Optional. The lh-tasks task this call is working on. Pass with claim_token: the call is refused unless you hold that claim, and a successful call renews it. |
|
claim_token |
string | No | Optional. The claim_token from claim-next-task for task_id. Required when task_id is given. |
|
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Search Users by Profile Fields
Searches WordPress users on the current site by user ID and any combination of account and profile fields. The fields are id (exact user IDs; always a restriction on top of the other fields), email, user_login and display_name (partial), phone (primary and secondary, partial match against digits only, tolerant of spacing/formatting, stored values are E.164), first_name/last_name (partial), gender (exact match, one of: Male, Female, Organisation, Robot – case-sensitive, no other values are ever stored), country/state_province/town/street_address (partial), postcode (exact), and birthdate_before/birthdate_after (single date bounds, not arrays, forming an inclusive range). Every other field parameter accepts an array of values OR-ed together within that field; match_mode controls whether the fields combine with AND (default) or OR across each other. Page with limit and offset. Each result includes the user’s login and their roles on the current site. Results are always restricted to users with an account on the current site. Other active plugins can add search parameters and result fields; the input and output schemas list them. Requires promote_users. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id |
array of integer | No | Exact user IDs. Always a restriction on top of the other fields, whatever match_mode is. |
|
phone |
array of string | No | Phone numbers, matched against primary and secondary phone by digits only, so spacing and a leading 0 do not matter. | |
email |
array of string | No | Partial matches on the account email. | |
user_login |
array of string | No | Partial matches on the username. | |
first_name |
array of string | No | Partial matches on first name. | |
last_name |
array of string | No | Partial matches on last name. | |
display_name |
array of string | No | Partial matches on display name. | |
gender |
array of string | No | Exact gender values, case-sensitive. | |
country |
array of string | No | Partial matches on country. | |
state_province |
array of string | No | Partial matches on state or province. | |
town |
array of string | No | Partial matches on town. | |
postcode |
array of string | No | Exact postcodes. | |
street_address |
array of string | No | Partial matches on street address. | |
birthdate_before |
string | No | Born on or before this date, Y-m-d. A single date, not an array. | |
birthdate_after |
string | No | Born on or after this date, Y-m-d. A single date, not an array. | |
match_mode |
string | No | "all" |
all (the default) requires every field given to match; any requires at least one. One of: all, any. |
limit |
integer | No | 20 |
Users to return, 1 to 100. Default 20. |
offset |
integer | No | 0 |
Users to skip, for paging. Default 0. |
is_member |
boolean | No | Membership of this site (LH Membership): true for members of any member type, false for users who are not members. A hard restriction whatever match_mode is. |
|
member_type |
array of string | No | LH Membership member type slugs, OR-ed: members of any of these types. A hard restriction whatever match_mode is. An unknown slug returns an error listing the member types on this site. |
|
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
Set User Roles
Adds and removes roles for one user on the current site. Only roles the caller could assign in wp-admin are accepted, and never a privileged role: one whose capabilities include promote_users, edit_users, manage_options or install_plugins (such as administrator). A user who already holds a privileged role, a super admin and the calling account are refused, as is a user with no account on the current site (use create-or-fill-user to add one). A change that would leave the user with no role is refused. Every role is checked before anything is written, so one refused role changes nothing. Roles already held (in add) or not held (in remove) are reported and left alone, so repeating a call is safe. dry_run defaults to true: set it to false to write. Returns roles before and after. Requires promote_users, plus promote_user on the target user. Pass site_id to act on another site you belong to.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
user_id |
integer | Yes | The user whose roles on the current site change. | |
add |
array of string | No | Role slugs to add, e.g. author. | |
remove |
array of string | No | Role slugs to remove. | |
dry_run |
boolean | No | true |
When true (the default) nothing is written; the result reports what would happen. |
task_id |
integer | No | Optional. The lh-tasks task this call is working on. Pass with claim_token: the call is refused unless you hold that claim, and a successful call renews it. |
|
claim_token |
string | No | Optional. The claim_token from claim-next-task for task_id. Required when task_id is given. |
|
site_id |
integer | No | Optional. ID of another site in the network to act on; list-my-sites gives the sites you belong to. Permissions are checked on that site. Omit for this site. |
