# Create a user

Creates a user that belongs to the buyer that the logged-in user belongs to. To Create an Authorised User you would need a stepped-up token. After calling this endpoint you need to step-up ( issue a challenge /stepup/challenges/otp/{channel} ). More details on how to step-up a token can be found here Step-Up.

Once on-boarded, users have access and manage the buyer's payment runs.

Users are assigned roles which limit the level of access they have and what they can do on behalf of the buyer.


Required user role: ADMIN

Endpoint: POST /v1/users
Version: v1
Security: apiKey, authToken

## Header parameters:

  - `idempotency-ref` (string)
    A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

## Request fields (application/json):

  - `name` (string, required)
    The first name of the user.

  - `surname` (string, required)
    The last name of the user.

  - `email` (string, required)
    E-mail Address of the user

  - `mobile` (object)
    Mobile number of the user

  - `mobile.countryCode` (string, required)
    The country code of the Buyer's admin user mobile number (e.g. +44).

  - `mobile.number` (string, required)
    The mobile number of the Buyer's admin user - excluding country code.

  - `dateOfBirth` (object)
    Date of birth of the authorised user.

  - `dateOfBirth.year` (integer, required)

  - `dateOfBirth.month` (integer, required)

  - `dateOfBirth.day` (integer, required)

  - `roles` (array, required)
    Roles define the level of access assigned to the user.

* CREATOR: Users assigned this role can create, view and update payment runs.
* CONTROLLER: Users assigned this role can view and link their company's bank accounts as well as fund payment runs.
    Enum: "CREATOR", "CONTROLLER"

## Response 200 fields (application/json):

  - `id` (string, required)
    The unique identifier of the user.

  - `buyerId` (string, required)
    The identifier for the identity.

  - `name` (string, required)
    The first name of the user.

  - `surname` (string, required)
    The last name of the user.

  - `email` (string, required)
    E-mail Address of the user

  - `mobile` (object)
    Mobile number of the user

  - `mobile.countryCode` (string, required)
    The country code of the Buyer's admin user mobile number (e.g. +44).

  - `mobile.number` (string, required)
    The mobile number of the Buyer's admin user - excluding country code.

  - `active` (boolean, required)
    The state of the user. If the active attribute is false, then the user will not be able to log in.

  - `dateOfBirth` (object)
    Date of birth of the authorised user.

  - `dateOfBirth.year` (integer, required)

  - `dateOfBirth.month` (integer, required)

  - `dateOfBirth.day` (integer, required)

  - `roles` (array, required)
    Roles define the level of access assigned to the user.

* CREATOR: Users assigned this role can create, view and update payment runs.
* CONTROLLER: Users assigned this role can view and link their company's bank accounts as well as fund payment runs.
    Enum: "CREATOR", "CONTROLLER"

  - `addedBy` (object)

  - `addedBy.rolesNames` (array)
    Roles define the level of access assigned to the user.

* ADMIN: Users assigned to this role can create a business and ensure that systems and processes are effectively managed.
    Enum: "ADMIN"

  - `addedBy.userId` (string, required)
    The unique identifier of the user who added this user.

## Response 400 fields (application/json):

  - `message` (string)
    When present helps to identify and fix the problem.

  - `syntaxErrors` (object)
    Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.

  - `syntaxErrors.invalidFields` (array)

  - `syntaxErrors.invalidFields.params` (array)

  - `syntaxErrors.invalidFields.fieldName` (string)

  - `syntaxErrors.invalidFields.error` (string)
    Enum: "REQUIRED", "HAS_TEXT", "REQUIRES", "SIZE", "RANGE", "IN", "NOT_IN", "REGEX", "EXACTLY", "AT_LEAST", "AT_MOST", "ALL_OR_NONE"

## Response 403 fields (application/json):

  - `errorCode` (string)
    Enum: "STEP_UP_REQUIRED"

## Response 409 fields (application/json):

  - `errorCode` (string)
    Enum: "EMAIL_NOT_UNIQUE", "MOBILE_NOT_UNIQUE", "MOBILE_OR_COUNTRY_CODE_INVALID", "EMAIL_DOMAIN_NOT_ALLOWED", "INSUFFICIENT_PERMISSIONS", "IDEMPOTENT_REQUEST_IN_PROGRESS"

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)


## Response 401 fields

## Response 413 fields

## Response 422 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields