Create a Private Userfield Category

Last modified on August 24, 2023 at 8:08 pm

Overview

Create a new private userfield category. Private categories contain userfields which are only visible to and modifiable by your organization’s administrators. This makes these userfields useful for tracking internal information like ad campaign source, customer support history, system integration ids, etc. To create the new private category, issue a POST request with a JSON-encoded userfield category object in the request body. On success, the response will include a Location redirect header pointing to the URL of the new userfield category.

JSON Userfield Category Object Definition

The following is a full definition of all possible properties you may specify on the JSON object representing a new userfield category. Note that this is not a complete list of fields for this type; refer to the Userfield Category Object Reference for a comprehensive set of userfield category properties.

{
  "name": "",
  "type": "", // must be either "public" or "private"
  "orderIndex": ""
}

Examples

Create a new userfield category

This example demonstrates creating a new private userfield category by sending a POST request with a JSON userfield category object in the request body. Note that the orderIndex property is ommitted — in this case the category will automatically be placed at the end of the set of private userfield categories.

Request
POST /dc/api/v5/userfieldcategories HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json

{
	"name": "Integration Metadata",
	"type": "private"
}
Response
HTTP/1.1 201 Created
Content-type: application/json
Location: /dc/api/v5/userfieldcategories/65ade781cc98d136543678191005431a
Content-length: 0

Failure Cases

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

Validation error

When creating new userfield categories, several checks are performed to ensure the category is valid. For example, the type is inspected to ensure it is one of the two valid values (public or private). In cases of validation errors, the server will return an HTTP 400 response along with a JSON object describing the error. The object can have two possible properties:

  • errors — an array of strings describing the causes of the failure
  • fieldErrors — an object whose properties are names of fields on the user object, and whose values are descriptions of errors caused by the value in that field

In the following example, an attempt is made to create a new userfield category with a missing name. This demonstrates how the server will indicate an error condition.

Request
POST /dc/api/v5/userfieldcategories HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json

{
	"type": "public",
	"orderIndex":0
}
Response
HTTP/1.1 400 Bad Request
Content-type: application/json
Content-length: 210

{
	"fieldErrors": { "name" : "This field is required." }
}