Update a Userfield Category

Overview

To update a user’s basic properties, you can send an HTTP PUT request to the user’s URL with a JSON object containing the properties you wish to modify along with their new values. On success, the server will respond with an HTTP 201 No Content status.

Note that you are not limited to updating one property at a time; all fields may be updated in a single request. All fields not specified will retain their value.

JSON User Object Definition

The following is a full definition of all possible properties you may specify on the JSON object representing a user. Note that this is not a complete list of fields for this type; refer to the Userfield Category Object Reference for a comprehensive set of userfield category properties.

{
  "firstName": "",
  "lastName": "",
  "username": "",
  "email": "",
  "password": "",
  "tags": [ "", ... ],
  "locale": ""
}

Example

This example shows the request-response sequence when updating a user’s tags. If the user previously had any other tags, they will be cleared and replaced by the newly specified tags.

Request

PUT /dc/api/v5/users/8d7a97a97a92efd18dcbc12876a4510e HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json

{
	"tags": [ "earlyaccess", "summerprogram" ]
}

Response

HTTP/1.1 204 No Content
Content-length: 0

Failure Cases

Below is a list of the most common failure scenarios your code should be prepared to handle. This list is not exhaustive.

Validation error

When creating new users, several checks are performed to ensure the user is valid. For example, the email address and username are checked to ensure they are not already taken by another user. When a collision is found, a validation error occurs. In cases of validation errors, the server will return an HTTP 400 response along with a JSON object describing the error. The object can have two possible properties:

• errors — an array of strings describing the causes of the failure
• fieldErrors — an object whose properties are names of fields on the user object, and whose values are descriptions of errors caused by the value in that field

In the following example, an attempt is made to specify an invalid empty value for the user’s first name. Because a first name is required, the validation step will reject the empty string, return a response with an HTTP 400 status, and provide a description of the problem in the fieldErrors property.

Request

PUT /dc/api/v5/users/8d7a97a97a92efd18dcbc12876a4510e HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json

{
	"firstName": "", 
}

Response

HTTP/1.1 400 Bad Request
Content-type: application/json
Content-length: 210

{
	"fieldErrors" : {
		"firstName" : "This field is required"
	}
}