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": "radiobuttons",
  "name": "Employment Status",
  "localizedNames": {
    "es": "Situación de Empleo"
  },
  "orderIndex": 0,
  "size": "",
  "orientation": "horizontal",
  "categoryId": "a72d3ec132dfab9423010d2cabf2ca91",
  "categoryName": "Internal Data",
  "categoryType": "public",
  "required": false,
  "options": [
    { "name": "Full-time", "selected": true },
    { "name": "Part-time", "selected": false },
    { "name": "Temporary", "selected": false }
  ],
  "constraints": {
    // "constraint name": "constraint value",
    // ...
  },
  "message": "",
  "readOnly": false,
  "createdDate": "2011-09-02T07:41:40Z"
}

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.

localizedNames object Alternate names for the userfield to present to users in other locales. The object property names correspond to ISO 639-1 locale codes (e.g. “es”, “fr”, “de”, etc). The code “en” may not be used since it is the default locale, and the name property will be used for users who are in this locale. The property values correspond to the translation for the given locale.

Example:

{ "es" : "Número de Casa", "fr" : "Numéro de la Maison" }
orderIndex number Controls the positioning of this userfield within the containing userfield category. The first position is at 0.
size string Indicates the size of the input field. Valid values are small, medium, mediumlarge, and large. This property is only valid for text, email, number, decimal and message userfield types.
orientation string Determines the positioning of elements when a userfield consists of multiple controls, like radiobuttons or checkboxes. There are two possible values: the horizontal option presents the input elements side by side; vertical stacks the elements vertically on the page. This property is valid for checkboxes, radiobuttons, truefalse, and yesno userfield types.
categoryId string The identifier of the userfield category to which this userfield belongs. Which category a userfield is in determines whether the userfield is private or public; that is, if a userfield is contained in a public category, it is visible to end-users, and if it is in a private category it is visible only to administrators. Note that it is possible to change a userfield’s category after it has been created, including moving a userfield between private and public categories. For more information, see the documentation on Userfield Categories.
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 category 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.
readOnly boolean This property indicates whether the userfield is modifiable. The main case where readOnly is true is for pre-defined system-provided userfields. These userfields exist in your list of userfields by default, but they are not assigned to any category, so they are not available either to end-users or to administrators until you move them into one of your own categories.
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.