Help Search

Users Create

Only users with Admin role can create other users. To create a new User, make a POST request to /users.json?api-version=v2 with the user data in request body.

POST /users.json?api-version=v2

Request data

The request body expects the following request data

Parameter Description Required Validation Constraints
username Username for this login. This is also their email address Yes
  1. Valid utf8 string
  2. Valid email address
  3. Must be unique
  4. Must not exceed 255 characters
role_id ID of the role to be assigned to this user. No
  1. Valid UUID
  2. Must exist in the database.
profile Profile data for the new user Yes
profile.first_name First name for the new user Yes
  1. Valid utf8 string
  2. Must not exceed 255 characters
profile.last_name Last name for the new user Yes
  1. Valid utf8 string
  2. Must not exceed 255 characters

Possible responses

Code Description
200 OK
The User was created. The response body will contain the newly created user object
400 Bad Request
Some of the data validation failed.
403 Authentication Failure
The user making the request is not authenticated

Examples

Successful request

And a valid request body will look like:

POST /users.json?api-version=v2
{
  "username": "user@domain.com",
  "profile": {
    "first_name": "John",
    "last_name": "Doe"
  },
  "role_id": "<uuid_of_the_role_object>"
}

Validation error response

A successful request must pass all the validation checks. For example sending a blank request body will return:

{
    "header": {
        "id": "a91e1c30-568f-4889-8eec-dd78c0a00543",
        "status": "error",
        "servertime": 1554981597,
        "title": "app_users_addPost_error",
        "action": "a1a15b91-72f6-5708-8d7f-6940e51d8595",
        "message": "Could not validate user data.",
        "url": "\/users.json?api-version=v2",
        "code": 400
    },
    "body": {
        "username": {
            "_required": "A username is required."
        },
        "profile": {
            "_required": "This field is required"
        }
    }
}

Last updated

This article was last updated on April 23rd, 2019.

If you are familiar with the high level API concepts and only looking for the endpoint implementation details, there is a repository with the latest OpenAPI 2.0 specifications (compatible with Swagger).

OpenAPI Specs