Overview

Create a new custom email-type userfield by sending an HTTP POST request with JSON representing the email userfield to create. On success, the request will return HTTP 201 Created with a Location header pointing to the URL of the newly created userfield resource; otherwise, an appropriate error will be returned. See the failure cases section for more details.

JSON Object Definition

The following is the subset of the JSON object representing userfields applicable to the email userfield type.

{
  "type": "email",
  "name": "",
  "localizedNames": {
    // locale code : value,
    // ...
  },
  "categoryId": "",
  "orderIndex": 0,
  "size": "", // one of "small", "medium", "mediumlarge", or "large"
  "required": false,
  "constraints": {
    // constraint type : value,
    // ...
  }
}

Userfield Property Details

Property Notes
type
required
To create a email userfield, this property must be present and have the value email.
name
required
This property will be the default label on the user information form presented to the end-user.
localizedNames Allows you to provide a custom field label for specific locales.
categoryId
required
Sets the category the userfield is located within. To the end user, categories will appear as sections or groupings of userfields on the user information form. To create a category or retrieve a list of your existing categories, see the userfield category documentation.
orderIndex Specifies what position the userfield appears in within its category. This should be an integer value greater than or equal to 0. If not provided, the userfield will be placed at the end of the category.
size Determines the size of the input field shown to the end-user on the user information form. Must be one of small, medium, mediumlarge, or large. Defaults to medium.
required Sets whether the user must provide a value for this userfield. This should be a boolean true or false value.
constraints A JSON object whose properties are the names of constraints with values representing the constraint limit. Email fields support the constraints minimumLength and maximumLength. The values for both of these constraints must be integer values greater than or equal to 0. Additionally, if you specify both a minimumLength and a maximumLength, the minimumLength constraint cannot be greater than the maximumLength constraint.

Examples

Create Custom Email Userfield

This example shows the creation of a custom user-visible email userfield with one localized name and one constraint.

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

{
	"type": "email",
	"name": "Example Email Input",
	"localizedNames": { "es": "ejemplo entrada" },
	"categoryId": "5738aeadc3d0feaedcbc12876a4510e", 
	"required": true,
	"constraints": { "maximumLength": 10 }
}
Response
HTTP/1.1 201 Created 
Location: https://org.digitalchalk.com/dc/api/v5/userfields/877f00ced040feaedcbc12878679305
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

If there is no userfield resource located at the given URL, the server will issue a 400 Bad Request response with a JSON object in the response body. The object contains a message attribute describing the eror.

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

{
	"type": "email",
	"name": "Example Email Input",
	"localizedNames": { "es": "ejemplo entrada" },
	"required": true,
	"constraints": { "maximumLength": 10 }
}
Response
HTTP/1.1 400 Bad Request
Content-type: application/json
Content-length: 210

{
	message: "categoryId is required"
}

References