---
title: "Create user"
method: POST
path: "/v2/users/create"
tags: ["Users"]
---

# Create user

`POST /v2/users/create`

## Request

- Base URL: `https://api.brex.com`
- URL: `https://api.brex.com/v2/users/create`
- Auth: OAuth 2
  - Authorization code: `https://accounts-api.brex.com/oauth2/default/v1/authorize`
  - Token URL: `https://accounts-api.brex.com/oauth2/default/v1/token` scopes: `users`
- TypeScript: <https://skmtc.dev/brex-com/apis/team-api/docs/v2/users/create/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint creates a new user as an employee without inviting them, leaving the user `INACTIVE`.
Use it to load your team into Brex ahead of time; invite them later with
[Invite user](#tag/Users/operation/createUser), on the Dashboard, or by using auto-invite rules.

The user is assigned to `legal_entity_id` when provided, and to your account's default legal entity otherwise.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- AddUserRequest
  - `first_name` string, required
  - `last_name` string, required
  - `email` string, email, required
  - `manager_id` string, nullable
  - `department_id` string, nullable
  - `location_id` string, nullable
  - `title_id` string, nullable
  - `cost_center_id` string, nullable
  - `legal_entity_id` string, nullable: The legal entity to assign the user to. Defaults to the account's default legal entity.
  - `metadata` object, nullable: The metadata or customized attributes of the user. Maximum number of entries: 100

## Response `200`

addUser 200 response

- UserResponse
  - `id` string, required
  - `first_name` string, required: First name of the user
  - `last_name` string, required: Last name of the user
  - `email` string, required: Email address of the user
  - `status` 'INVITED' | 'ACTIVE' | 'DISABLED' | 'PENDING_ACTIVATION' | 'INACTIVE' | 'ARCHIVED': Status of the user
  - `manager_id` string, nullable: The user id of the manager of this user
  - `department_id` string, nullable
  - `location_id` string, nullable
  - `title_id` string, nullable
  - `cost_center_id` string, nullable
  - `legal_entity_id` string, nullable
  - `metadata` object, nullable: The metadata or customized attributes of the user. Maximum number of entries: 100
  - `remote_display_id` string, nullable: Identifier that is displayed on the IDP or HR system, eg, if OKTA identifies you as user xyz
  - `custom_fields` CustomField[], nullable: A list of custom field values associated with the user.
    - `key` string, required: The key of the custom field.
    - `value` union, required
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'STRING', required: The type of the custom field data.
        - `data` string, nullable: The data of the custom field.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'DECIMAL', required: The type of the custom field data.
        - `data` number, nullable: The data of the custom field.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'BOOLEAN', required: The type of the custom field data.
        - `data` boolean, nullable: The data of the custom field.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'ENUM', required: The type of the custom field data.
        - `data` string, enum, nullable: The data of the custom field.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'TIMESTAMP', required: The type of the custom field data.
        - `data` string, date-time, nullable: The data of the custom field.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'DATE', required: The type of the custom field data.
        - `data` string, date, nullable: The data of the custom field.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'MONEY', required: The type of the custom field data.
        - `data` object, nullable: The data of the custom field.
          - `amount` integer, required: The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.
          - `currency` string, nullable: The type of currency, in ISO 4217 format.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'OPTION_STRING', required: The type of the custom field data.
        - `data` object, nullable: The data of the custom field.
          - `option_id` string, nullable: The identifier when custom field data is of type option string.
          - `option_label` string, nullable: The label when custom field data is of type option string.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'STRING', required: The type of the custom field data.
        - `data` string[], nullable
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'DECIMAL', required: The type of the custom field data.
        - `data` number[], nullable
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'BOOLEAN', required: The type of the custom field data.
        - `data` boolean[], nullable
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'ENUM', required: The type of the custom field data.
        - `data` string[], nullable
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'TIMESTAMP', required: The type of the custom field data.
        - `data` string[], nullable
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'DATE', required: The type of the custom field data.
        - `data` string[], nullable
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'MONEY', required: The type of the custom field data.
        - `data` Money[], nullable
          - `amount` integer, required: The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.
          - `currency` string, nullable: The type of currency, in ISO 4217 format.
      - object: Base class for custom field values
        - `value_type` 'SINGLE_VALUE' | 'LIST', required: The type of the custom field value.
        - `data_type` 'OPTION_STRING', required: The type of the custom field data.
        - `data` OptionString[], nullable
          - `option_id` string, nullable: The identifier when custom field data is of type option string.
          - `option_label` string, nullable: The label when custom field data is of type option string.

## Changes

- **2026-09-30** `76616101e54a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/brex-com/apis/team-api/changes/v2/users/create/post.md)

---

[API](https://skmtc.dev/brex-com/apis/team-api.md) - [All operations](https://skmtc.dev/brex-com/apis/team-api/llms.txt) - [OpenAPI document](https://skmtc.dev/brex-com/apis/team-api/revisions/76616101e54a?raw)