Userfield Object Reference

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

Example Userfield Object

Below is an example of a JSON representation of a Userfield object. This illustrates how userfields are represented in server responses, and you can use this same format when creating or modifying userfields.

Note that this example is for a radiobuttons-type userfield, so all sample data in the example is appropriate for that type. Fields which normally would not show up in a response with this type have been included to indicate the presense of the field on the object. However, normally an unused field is dropped when the server composes the response JSON object. For more information on different types of fields, see the Userfield Type Reference.

  "id": "9910a2c132dfab9423010d2cabf47792",
  "type": "radios",
  "name": "Employment Status",
  "orderIndex": 0,
  "categoryName": "Internal Data",
  "categoryType": "public",
  "required": false,
  "createdDate": "2011-09-02T07:41:40Z"
  "options": [
    { "name": "Full-time", "selected": true },
    { "name": "Part-time", "selected": false },
    { "name": "Temporary", "selected": false }
  "constraints": {
    // "constraint name": "constraint value",
    // ...
  "message": ""

Property Details

PropertyJSON Data TypeDescription
idstringThe userfield’s unique identifier value. A userfield’s URL in the API is composed of /dc/api/v5/userfields/ followed by this identifier.
typestringThe type of userfield represented by this object. For a detailed list of the available userfield types, see the Userfield Type Reference.
namestringThe name of the userfield. When a user is presented with this userfield in a form, this name will be used as the input label. The exception is if the user has a locale set that that matches one of the set on the userfield, then that localized name will be used as the input label instead.

This property is not valid for message-type userfields.

orderIndexnumberControls the positioning of this userfield within the containing userfield category. The first position is at 0.
categoryNamestringThe name of the userfield category to which this userfield belongs. This property is read-only.
categoryTypestringIndicates whether the containing userfield is a public or private category. This property is read-only.
requiredbooleanControls whether the user is allowed to complete the user information form without providing a response to this userfield. This property is not available for checkbox and message userfield types.
optionsarrayAn array of option objects for choice-based userfield types. The option objects can have two properties: name, the text presented to the user, is required; and selected, a boolean, indicates whether the option is selected by default. This property is valid for checkboxes, radiobuttons, and dropdown userfield types. The checkboxes type can have multiple options selected by default; the others require that at most one option is pre-selected. For an example of the use of the options property, see the Create Checkboxes-type Userfield documentation.
constraintsobjectThe constraint rules to apply when validating user input. This should be an object where each property name is the name of a constraint, and the property value is the corresponding constraint value or limit. For more details on constraints, see the Constraint Reference.
messagestringThe message to display. This property is only valid for message-type userfields.
createdDatestringA date string representing the timestamp when the userfield was first created. For further information on the expected format, see the Date/Time Format documentation.