Retrieve a Specific Userfield By Id

Last modified on September 11, 2023 at 1:57 pm

Overview

Retrieves a specific userfield with the specified id. The result of this GET request will be a JSON-encoded representation of a userfield object. 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. These fields are not actually in use unless the categoryId property is set.

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": ""
}

Examples

Retrieve Custom Userfield by ID

This example shows the retrieval of a custom user-visible checkboxes userfield with the first two options pre-checked. Because it has an orderIndex value of 1, it also appears as the second option within its category.

Request
GET /dc/api/v5/userfields/322881a721f0feaedcbc12876a4510e HTTP/1.1
Host: api.digitalchalk.com
Accept: application/json
Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 456 

{
  "id": "322881a721f0feaedcbc12876a4510e",
  "type": "checkboxes",
  "name": "Newsletter Subscriptions",
  "orderIndex": 1,
  "categoryName": "Contact Options",
  "categoryType": "public",
  "options": [
    { "name": "New Feature Alerts", "selected": true },
    { "name": "Course Development Tips", "selected": true },
    { "name": "Partner Discounts", "selected": false }
  ]
}

Retrieve Pre-defined System Userfield by ID

This example shows a response containing a system-provided userfield which has not been added to any category, and therefore is not present on either the user-visible information form or the admin-only form.

Request
GET /dc/api/v5/userfields/f2d2885c21f0fe399dc6f1086a4510e HTTP/1.1
Host: api.digitalchalk.com
Accept: application/json
Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 160 

{
  "id": "f2d2885c21f0fe399dc6f1086a4510e",
  "type": "text",
  "name": "Postal Code",
  "constraints": {
    "maximumLength": 32 
  }
}

Failure Cases

Below is a list of the most common failure scenarios your code should be prepared to handle. This list is not exhaustive.

Invalid ID

If there is no userfield resource located at the given URL, the server will issue a 404 Not Found response.

Request
GET /dc/api/v5/userfields/INVALID_ID_HERE HTTP/1.1
Host: org.digitalchalk.com
Accept: application/json
Response
HTTP/1.1 404 Not Found
Content-type: application/json
Content-length: 55

{
	errors: [ "No userfield (32808114888d0e1501888d1194d0004da)" ]
}

References