Loading ...

REST API: Update User Profile Fields | Axero Documentation

Home » axero documentation » Wiki » Documentation » REST API Overview » REST API: Users » REST API: Update User Profile Fields
Axero Documentation  Wiki
Public Space
Activity Stream Content
Version 42

REST API: Update User Profile Fields

0 
 /5
0 (0votes)
Open API Guide
POST/api/users/fields

Update a user's profile fields by their labels, or create the user when no match exists. It also updates user preference fields. ResponseData is the UserID of the user created or updated, and ResponseMessage names the outcome. A failure, such as a duplicate email or username, an invalid value, or no matching user to update, answers 200 with IsError true and the reason in ResponseMessage.

Request

Request Header

HeaderRequiredValueDescription
AuthorizationYESBearer YOUR_TOKENBearer token for the authenticated user. Learn how to create Bearer tokens.
Content-TypeYESapplication/jsonMust be set to application/json

Required Parameters

ParameterTypeRequiredLocationDescription
User JSONStringYESBodyThe user to update, as a JSON object (a set of named fields and their values) in the format of the example below. Each profile field is named by its label, and labels are case-sensitive. A field can also be named by its system name or its field ID. For the time zone preference, take the time zone ID from REST API: Time Zones List. To update the Reports to field, send the manager's username.

The body is not limited to profile fields. Any account property whose name matches is applied to the account in the same call, which is how an outside system sets the account's activation state at the moment it creates the account. See IsActivated and IsBanned under Optional Parameters.

For a picklist or checkbox field, send either the option's display text or its numeric option ID; both are matched. A checkbox also accepts True or False in any capitalization. The checkboxes that set an account preference take true or false only: Share my profile, the phone number and email address sharing checkboxes, the promotional emails checkbox, and Email notifications. On these, an option's text or ID answers HTTP 500 with an empty body. A value that matches no existing option creates a new option on that field, unless the AddNewOptionsFromImport system property is set to false. It defaults to true, so a misspelled value adds an option rather than returning an error. A label that matches no field is ignored, and the call still answers Success.

Optional Parameters

ParameterTypeRequiredLocationDescription
AddUserBooleanNOQuerySet to true to add a user with the specified fields. With true, a body that matches an existing account answers 200 with IsError true (User already exists or Duplicate Username). Set to false to update an existing user's profile fields. Left out, the endpoint looks for an existing user to update and adds a new user if none matches. A value other than true or false is read as left blank.
IsMultipleUsersRequestBooleanNOQuerySet to true when the body is a JSON array of user objects. The response is then a bare array with one response entry per user. For an entry that fails, ResponseMessage is the reason followed by the entry as it was sent. An empty array answers HTTP 500 with an empty body. A JSON array sent without it answers 200 with IsError true (No user found.), and a value other than true or false is read as false.
IsActivatedBooleanNOBodyWhether the account is activated. Send false to create the account and leave it in Pending Activation, so an administrator activates it later from Control Panel > People > Manage People. Send true to activate it. Omit it and a new account is created activated, while an existing account keeps its state. A value other than true or false is read as false, so an existing account is made inactive.
IsBannedBooleanNOBodyWhether the account is banned. Send it as false alongside IsActivated when creating an account, so sign-in reports the held account as pending rather than deactivated. Send true to ban the account. A value other than true or false is read as false, which lifts a ban; left out, the ban state is kept.
UserID OR Email OR UsernameIntegerNOBodyUnique identifier for a particular user. Required to update an existing user: a body that matches no user answers 200 with IsError true (No user found.). A UserID that is not a whole number answers HTTP 500 with an empty body.
EmailReceiveBooleanNOBodyWhether the person receives email notifications from the site. This route takes true or false only, in any capitalization: true stores All emails and false stores No emails. Any other value, such as a number, an option name, or other text, answers HTTP 500 with an empty body. EmailReceive stores only these two values. The account property EmailRecieve, spelled that way, takes the numbers 0 to 3 and so can store Only external emails (1) and No external emails (2).

Example

Request Header

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request URL

https://your-site.com/api/users/fields?AddUser=false

Request Body

{
  "UserID": "12",
  "Company": "Axero Solutions",
  "Phone": "5625551234",
  "Share my profile": "false"
}

Request Body: create an account in Pending Activation

Send IsActivated as false to create the account and hold it in Pending Activation. The person cannot sign in, including through single sign-on, until an administrator activates the account. Profile fields sent in the same body are stored on the held account, so the record is complete when it is activated. A new account needs Username, Email, and Password, as in this body. Send it without AddUser=false in the URL: with that setting the request can only update, and it answers No user found.

{
  "Username": "jsmith",
  "Email": "jsmith@example.com",
  "Password": "YOUR_PASSWORD",
  "First Name": "Jordan",
  "Last Name": "Smith",
  "IsActivated": "false",
  "IsBanned": "false",
  "Company": "Axero Solutions",
  "Phone": "5625551234"
}

Success Response

{
  "IsError": false,
  "ResponseMessage": "Success",
  "ResponseData": 804
}

Error Response

HTTP 400 with an empty body

Error Handling

Status CodeLikely CauseNext Action
400 Bad RequestThe body is missing or is not valid JSON. The response has no body.Send a JSON object of field labels and values.
401 UnauthorizedMissing or invalid Bearer token.Check token validity. Learn how to create Bearer tokens →
403 ForbiddenThe caller may not make the change. Updating another user's account needs the Admin Entity Update permission on users. Creating an account with AddUser left out needs the Create permission on users. The response has an empty body.Call with a token that has the permission.
415 Unsupported Media TypeThe Content-Type header names a type the endpoint cannot read, such as text/plain.Send Content-Type: application/json.
200 with IsErrorThe request was refused, and ResponseMessage says why. No account matches the body and AddUser is false (No user found.). A new account lacks Username, Email, or Password (Missing Required Information). The username or email address belongs to another account (Duplicate Username, Duplicate email, Invalid username, or User already exists). A value breaks the site's rules (Invalid Password, Invalid email address). AddUser is true and the caller lacks the Create permission on users (No Permission).Read IsError on every response, and correct the value ResponseMessage names.
500 Server ErrorEmailReceive or another account-setting checkbox is not true or false, UserID is not a whole number, or IsMultipleUsersRequest is true with an empty array. The endpoint fails with an empty body. Another internal failure also answers 500.Send those checkboxes as true or false and UserID as a number, then retry.

Rate Limits

While Axero does not enforce hard rate limits by default, we recommend the following best practices to ensure optimal performance:

  • Sustained Request Rate: Do not exceed 5 API calls per second
  • Sequential Processing: Wait for each request to complete before sending the next in automated workflows
  • Concurrent Connections: If parallel processing is required, limit to 3 or fewer simultaneous requests
  • Response Timeout: Ensure API responses complete within 15 seconds during testing

Axero may implement temporary rate restrictions if excessive API usage affects overall site performance. For high-volume integrations, contact Axero to discuss your requirements.

Wiki Index

Pages