---
title: "Create User"
method: POST
path: "/users"
tags: ["Users"]
---

# Create User

`POST /users`

## Request

- Base URL: `https://env.unqork.io/api/1.0`
- URL: `https://env.unqork.io/api/1.0/users`
- Auth: OAuth 2
  - Client credentials
  - Password
  - Token URL: `https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token`
- TypeScript: <https://skmtc.dev/unqork/apis/unqork-customer-api/docs/users/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new user. If userId is not specified, it is auto-generated and returned.
### Authorization Required:
  - Designer Administrator

## Query parameters

- `shouldNotify` boolean
- `skipTemporaryPassword` boolean

## Request body

- UserPost
  - `userId` string: The userId can only include letters, numbers, and the following characters @,+-_. plus letters from non-Latin scripts. Forward slashes are rejected with `400 Forward slashes are not allowed in user ID`. Stored lowercased and trimmed, so the value returned may differ from the value sent.
  - `name` string, required: The name can only include letters, numbers, and the following characters @,+-_.'
  - `email` string, email, required: Quotes and special characters `"(),:;<>@[]\` are not allowed. The local portion of the email (e.g. local@domain.com) must be > 0 characters and < 64 charaters. There cannot be consecutive dots (e.g. `..`) in the email
  - `phone` string: Must be a valid US phone number unless the country code is specified, in which case it is validated with [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js#definitions)
  - `role` string: One of the roles configured in Unqork
  - `expressRoles` string[]: Express roles configured in Unqork. Every name is validated against the environment's roles - an unknown name is rejected with `400 Role not found`. When omitted or empty, the deprecated `role` value is used to populate it.
  - `groups` string[]: List of groups configured in Unqork OR comma-separated list of groups configured in Unqork (e.g. "group1,group2"). Every group must already exist or the request is rejected. An empty string or null is equivalent to an empty array.
  - `applicationRoles` object: Map of applications to roles OR comma-separated list of application-role mappings (e.g. "application1:role1,application2:role2")
  - `password` string, password: Complexity is enforced from the environment's password requirements, so the effective bounds are per-environment rather than fixed. Read that configuration for the values that apply; the platform defaults are a minimum length of 12, a maximum of 64, and at least one lowercase letter, one uppercase letter, one number, and one symbol. Service users (`isServiceUser: true`) are the exception - their minimum length is forced to 32 and their maximum to 64, overriding whatever the environment configures, and all four character classes are always required.
  - `isServiceUser` boolean
  - `...customAttributes` string: Custom attributes can be included as additional keys in the request body. Only string values of custom attributes are supported - an object value is rejected with `400 Invalid attribute "<key>": Object not allowed`. Reserved keys are silently dropped rather than rejected, so a custom attribute must not reuse one of: `userId`, `email`, `phone`, `name`, `role`, `password`, `created`, `modified`, `passwordHash`, `passwordHistory`, `passwordStatus`, `passwordExpiry`, `credentialExpired`, `groups`, `applicationRoles`, `lastLogin`, `isServiceUser`, `designerRoles`, `expressRoles`, `isUserLocked`, `description`, `clientSecret`.

## Response `201`

User created

- UserResponse
  - `userId` string, required
  - `name` string, required
  - `email` string, required
  - `phone` string
  - `role` string: One of the roles configured in Unqork
  - `expressRoles` string[]: Express roles configured in Unqork
  - `groups` string[]: List of groups configured in Unqork
  - `applicationRoles` object: Map of applications to roles
  - `created` string, date-time, required
  - `modified` string, date-time, required
  - `isServiceUser` boolean
  - `lastLogin` string, date-time
  - `...customAttributes` string: Custom attributes will be included as additional keys in the response body.

## Other responses

- `409`: A user with that userId or email already exists
- `default`: Error

## Changes

- **2026-10-27** `13dad4096373`: 1 info
  - added the non-success response with the status `409`

[Operation history](https://skmtc.dev/unqork/apis/unqork-customer-api/changes/users/post.md)

---

[API](https://skmtc.dev/unqork/apis/unqork-customer-api.md) - [All operations](https://skmtc.dev/unqork/apis/unqork-customer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unqork/apis/unqork-customer-api/revisions/13dad4096373?raw)