Last modified on September 8, 2023 at 5:24 pm
Overview
Adding a predefined, system-provided userfield to the user information form consists of updating its categoryId property to one of your existing userfield categories. The category may be either public or private; this will determine whether the userfield is available to end-users or only to administrators.
Note that the reverse of this process works somewhat differently. According to the validation rules of the API, the categoryId property is always required. Therefore you cannot remove a system-provided userfield by simply updating its categoryId property to null. Instead, send an HTTP DELETE request for the userfield URL. This is consistent with the standard procedure for removing custom userfields.
You are not limited to updating one property at a time; all fields that are valid for a particular userfield type may be updated in a single request. All fields not specified will retain their value. See the Userfield Object Reference for a list of all the object’s fields.
Example
This example shows the request-response sequence when moving a predefined userfield to the user information form by updating its categoryId property.
Request
PUT /dc/api/v5/userfields/8da97a97a92efd18dcbc12876a4510e HTTP/1.1
Host: org.digitalchalk.com
Content-type: application/json
Accept: application/json
{
"categoryId": "5738aeadc3d0feaedcbc12876a4510e"
}
Response
HTTP/1.1 204 No Content
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
After the userfield property changes have been applied it will be re-validated. If a validation error occurs, the server will issue a 400 Bad Request response with a JSON object in the response body. The object contains a message attribute describing the eror.
Request
POST /dc/api/v5/userfields HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json
{
"categoryId": "INVALID_CATEGORY_ID"
}
Response
HTTP/1.1 400 Bad Request
Content-type: application/json
{
message: "categoryId is invalid"
}