Create a New User

Last modified on August 22, 2023 at 8:13 pm

Overview

Create a new user by issuing a POST request to the users resource with a JSON-encoded user object in the request body. On success, the response will include a Location redirect header pointing to the URL of the new user.

JSON User Object Definition

The following is a full definition of all possible properties you may specify on the JSON object representing a new user. Note that this is not a complete list of fields for this type; refer to the User Object Reference for a complete list of fields and further details.

{
  "firstName": "",
  "lastName": "",
  "username": "",
  "email": "",
  "password": "",
  "tags": [ "", ... ],
  "locale": ""
}

Examples

Create a New User

This example demonstrates creating a new user by sending a POST request with a JSON user object in the request body.

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

{
	"firstName": "Joe",
	"lastName": "Porter",
	"username": "jporter",
	"email": "jporter@exampleorg.com",
	"password": "randompass123",
	"tags": [ "santafe", "nm" ],
	"locale": "en"
}
Response
HTTP/1.1 201 Created
Content-type: application/json
Location: /dc/api/v5/users/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 users, several checks are performed to ensure the user is valid. For example, the email address and username are checked to ensure they are not already taken by another user. When a collision is found, a validation error occurs. 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 register a user with an email address that is already in the system (into an organization which does not have username enabled). This demonstrates how the server will indicate an error condition.

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

{
	"firstName": "Joe",
	"lastName": "Porter",
	"email": "jporter@exampleorg.com",
	"password": "randompass123",
	"tags": [ "santafe", "nm" ],
	"locale": "en"
}
Response
HTTP/1.1 400 Bad Request
Content-type: application/json
Content-length: 210

{
	"fieldErrors": { "email" : "This email address is in use." }
}

Reference