Last modified on September 7, 2023 at 5:53 pm
Overview
Create a new public userfield category. Public categories contain userfields which are visible to and modifiable by end users both on the My Account page and at new-user sign up. To create the new public 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 public 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 public userfield categories.
Request
POST /dc/api/v5/userfieldcategories HTTP/1.1
Host: api.digitalchalk.com
Content-type: application/json
Accept: application/json
{
"name": "Biographical Information",
"type": "public"
}
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." }
}