Retrieve All Userfield Data

Overview

Retrieve a list of all userfields defined in your organization. This request follows standard practices for paging and filter restriction conventions. If no restrictions are provided, the userfields retrieved will fall into two classifications: public custom fields and private custom fields. The result of this GET request will be JSON-encoded representation of an array of userfield objects. The object definition is provided below.

Pre-defined userfields are provided by default to all organizations. They include common pieces of data such as address, city, state, etc. These fields can be identified by having their readOnly property set to true. Although these fields always show up in your list of userfields, they are not displayed to users unless they are assigned to a category.

An object reference and examples are provided here. For further information about types of userfields, what fields are present on each type, and what constraints are applicable to each type, see the appropriate section in references.

JSON Object Definition

The following is a full definition of all possible properties on the JSON object representing userfields. Not every property will be present for every type of userfield, and this will be reflected in the examples below. For details regarding which properties are valid for each userfield type, see the Userfield Types reference page. A detailed breakdown of each property is available in the Userfield Object Reference.

{
  "id": "",
  "type": "",
  "name": "",
  "orderIndex": 0,
  "categoryName": "",
  "categoryType": "", // "public" or "private"
  "required": false,
  "options": [
    // { "name": "", "selected": false },
    // …
  ],
  "constraints": {
    // constraint type : value,
    // …
  },
  "message": ""
}

Filtering

Filtering the result list can be accomplished by specifying value restrictions for the following properties:

Parameter name	Details
createdDate	String representation of a date. This can be a precise timestamp, an imprecise date implying a range, or a range of dates. See the Date Filtering documentation for more detail.
categoryType	Filter based on the type of userfield category. If specified, this must either be public or private.

Examples

Classifications Illustrated

This sample shows a response containing three userfields. One userfield of each classification (public/user-modifiable, private/admin-modifiable) is shown, and a third system-wide predefined userfield is also shown which is not included on either the public or private set of userfields. Note that public/private is determined by the value of the categoryType property. The predefined userfield is not in use because it does not have a categoryId property.

Request

GET /dc/api/v5/userfields HTTP/1.1
Host: api.digitalchalk.com
Accept: application/json

Response

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 931

[
  {
    "id": "322881a721f0fe399dc6f1086a4510e",
    "type": "number",
    "name": "Example Number Field",
    "orderIndex": 0,
    "categoryName": "Example Public Category",
    "categoryType": "public",
    "required": false,
    "constraints": {
      "maximumValue": 100
    }
  },
  {
    "id": "31984324731200022dc6f1086a4510e",
    "type": "text",
    "name": "Example Text Field",
    "orderIndex": 0,
    "categoryName": "Example Private Category",
    "categoryType": "private",
    "required": false,
    "constraints": {
      "minimumLength": 8
    }
  },
  {
    "id": "322881a721f0facd9090f18cda4510e",
    "type": "text",
    "name": "Postal Code",
    "required": false,
    "constraints": {
      "maximumLength": 32
    }
  }
]

References

• Userfield Object Reference
• Userfield Types
• Constraints