---
title: "Create a new user."
method: POST
path: "/users"
tags: ["users"]
---

# Create a new user.

`POST /users`

## Request

- Base URL: `https://api.smartrecruiters.com/user-api/v201804`
- URL: `https://api.smartrecruiters.com/user-api/v201804/users`
- Auth: one of:
  - API key in header `x-smarttoken`
  - OAuth 2
    - Authorization code: `https://www.smartrecruiters.com/identity/oauth/allow`
    - Token URL: `https://api.smartrecruiters.com/identity/oauth/token` scopes: `users_manage`

## Request body

- NewUser
  - `email` string, email
  - `firstName` string, name, required
  - `lastName` string, name, required
  - `systemRole` SystemRole, required
    - `id` string, required
    - `name` string
  - `externalData` string, nullable
  - `ssoIdentifier` string, nullable
  - `ssoLoginMode` 'SSO' | 'PASSWORD', nullable: User level login mode setting. Possible values are: - SSO - user can login only through SSO - PASSWORD - user can login only by password Notice: This setting _CAN_ be configured always, but it will be respected only if: - SSO is enabled at company level - employee level SSO configuration functionality is enabled for company
  - `language` object
    - `code` 'bg' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'es-MX' | 'fi' | 'fr' | 'fr-CA' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'lt' | 'nl' | 'no' | 'pl' | 'pt' | 'pt-BR' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW' | 'ka', required: Language assigned to user account. Language code, can be two-letter for the standard variant or with additional two letters after a hyphen to identify a specific locale
  - `password` string
  - `location` LocationUpdateRequest: regionCode is not recommended to be used for countries other than the United States.
    - `countryCode` string
    - `regionCode` string
    - `city` string
    - `address` string, address
    - `postalCode` string

## Response `201`

Created user

- UserEntity
  - `email` string, email
  - `firstName` string, name, required
  - `lastName` string, name, required
  - `systemRole` SystemRole, required
    - `id` string, required
    - `name` string
  - `externalData` string, nullable
  - `ssoIdentifier` string, nullable
  - `ssoLoginMode` 'SSO' | 'PASSWORD', nullable: User level login mode setting. Possible values are: - SSO - user can login only through SSO - PASSWORD - user can login only by password Notice: This setting _CAN_ be configured always, but it will be respected only if: - SSO is enabled at company level - employee level SSO configuration functionality is enabled for company
  - `language` object, required
    - `code` 'bg' | 'cs' | 'da' | 'de' | 'el' | 'en' | 'es' | 'es-MX' | 'fi' | 'fr' | 'fr-CA' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'lt' | 'nl' | 'no' | 'pl' | 'pt' | 'pt-BR' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW' | 'ka', required: Language assigned to user account. Language code, can be two-letter for the standard variant or with additional two letters after a hyphen to identify a specific locale
  - `id` string
  - `active` boolean
  - `updatedOn` string, date-time
  - `personIdExternal` string, nullable: External person ID from the managing system (e.g. SuccessFactors personIdExternal)
  - `location` Location: regionCode is not recommended to be used for countries other than the United States.
    - `country` string
    - `countryCode` string
    - `regionCode` string
    - `region` string
    - `city` string
    - `address` string, address
    - `postalCode` string
    - `longitude` string
    - `latitude` string
  - `accessGroups` object[]
    - `id` string
    - `name` string

## Other responses

- `400`: with codes * **LANGUAGE_DISABLED** User language is not available as part of company subscription plan * **INVALID_ROLE** when selected role is blank or not exist in company configuration * **INVALID_USER_NAME** when firstName or lastName contains invalid characters (e.g. leading or trailing spaces) * **PROPERTY_INVALID** when one of the properties is not valid
- `403`: with code * **PERMISSION_DENIED** Not permitted to access users
- `409`: User already exists
- `422`: Request body is invalid (e.g. values breaks model definition rules)

---

[API](https://skmtc.dev/smartrecruiters/apis/users-api.md) - [All operations](https://skmtc.dev/smartrecruiters/apis/users-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartrecruiters/apis/users-api/revisions/22cf1eb7cae7?raw)