Set a Userfield Value

Last modified on September 11, 2023 at 2:18 pm

Overview

To modify a userfield value for a user, you can send an HTTP PUT request to the userfield value URL with a JSON object whose property names are the ids of the userfields to update for the current user, and whose values are the values to assign for the given fields.

Note that you are not limited to updating one field at a time; all existing fields may be updated in a single request. All fields not specified will retain their current value. See the JSON object definition for details on what value types should be specified based on the userfield type.

Headers

These are the HTTP headers that may be included in the POST request (not counting authentication information).

HeaderNotes
Accept
required
Indicates the content type you as the API client will accept in response from the server. Must be application/json.
Content-type
required
Indicates the content type you are providing to the server in your request. Must be application/json.
Host
required
Identifies the hostname the request is intended for. Should be api.digitalchalk.com.

Example

This example shows the request-response sequence when updating two userfield values.

Request
PUT /dc/api/v5/userfields/8da97a97a92efd18dcbc12876a4510e HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json

{
  "23875210aceace7892feefd0m239213" : 34,
  "09ebbca742233464128256512102420" : "backup_email_address2@my_organization.com"
}
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

When a new value is provided for a userfield value, it will be validated before the new value is saved. This validation checks for type-appropriate values as well as ensuring the value complies with custom constraints set on the userfield. If a validation error occurs, the server will issue a 400 Bad Request response with a JSON object in the response body. Error details will be provided in at least one of two fields: errors, an array of strings with general error descriptions, and/or fieldErrors, an object whose property names specify the property on the request object which caused an error and whose value is a description of the error.

In the following example, field id 8da97a97a92efd18dcbc12876a4510e references a field of type integer with a minimum-value constraint set to 1.

Request
POST /dc/api/v5/userfields HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json

{
	"8da97a97a92efd18dcbc12876a4510e": 0
}
Response
HTTP/1.1 400 Bad Request
Content-type: application/json
Content-length: 210

{
        "fieldErrors" : {
		"8da97a97a92efd18dcbc12876a4510e": "This field must be greater than 1"
	}
}