Userfield Object Reference

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

Property	JSON Data Type	Description
id	string	The userfield’s unique identifier value. A userfield’s URL in the API is composed of /dc/api/v5/userfields/ followed by this identifier.
type	string	The type of userfield represented by this object. For a detailed list of the available userfield types, see the Userfield Type Reference.
name	string	The 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.
orderIndex	number	Controls the positioning of this userfield within the containing userfield category. The first position is at 0.
categoryName	string	The name of the userfield category to which this userfield belongs. This property is read-only.
categoryType	string	Indicates whether the containing userfield is a public or private category. This property is read-only.
required	boolean	Controls 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.
options	array	An 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.
constraints	object	The 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.
message	string	The message to display. This property is only valid for message-type userfields.
createdDate	string	A date string representing the timestamp when the userfield was first created. For further information on the expected format, see the Date/Time Format documentation.