# Create a user

Creates a new user (agent/collaborator) in the system.
**Password requirements (RGPD):**
- Length: 12-40 characters
- Must contain: uppercase, lowercase, digit, special character

**Agency assignment:** The `agency_id` is the user's primary agency.
Use `agencies_list` to grant access to additional agencies.
**User types:** Use `GET /users/types` to discover available types
(e.g. Négociateur, Gestionnaire, etc.).
**Groups:** Use `GET /users/groups` to discover available groups
(determines access level and permissions within the agency).

Endpoint: POST /users
Version: 1.6.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer opaque

## Request fields (application/json):

  - `firstname` (string, required)
    User first name.
    Example: Marie

  - `lastname` (string, required)
    User last name.
    Example: Martin

  - `email` (string, required)
    User email address. Must be unique across the site.
Used for login and notifications.
    Example: marie.martin@agence.fr

  - `password` (string, required)
    User password. Must meet RGPD requirements:
- Length: 12-40 characters
- Must contain: uppercase, lowercase, digit, special character
    Example: S3cur3P@ss!2026

  - `status` (integer, required)
    User status:
- `1`
 — Active
- `0`
 — Archived (cannot login)
    Example: 1

  - `agency_id` (integer, required)
    Primary agency ID for the user. Must be within the authenticated site's scope.
    Example: 123

  - `agencies_list` (array | null)
    Additional agency IDs the user has access to (multi-agency access).
Each must be within the site scope.
    Example: [123,456]

  - `group_id` (integer, required)
    Permission group ID. Determines access level.
Use `GET /users/groups` to discover available groups.
    Example: 2

  - `delegation` (boolean | null)
    Whether the user can delegate their work to others.

  - `phone` (string | null)
    Office phone number.
    Example: +33498765432

  - `mobile_phone` (string | null)
    Mobile phone number.
    Example: +33698765432

  - `gender` (string | null)
    Gender code. Use `GET /users/genders` for the full list.
    Enum: "m", "f", "s"

  - `user_types` (array | null)
    User type IDs (professional roles). A user can have multiple types.
Use `GET /users/types` to discover available types.
    Example: [1]

## Response 201:

  - `201` (unknown)
    User created

## Response 201 fields (application/json):

  - `data` (object)

  - `data.id` (integer)
    ID of the created user.

## Response 403:

  - `403` (unknown)
    Access denied. The error `code` is always `FORBIDDEN`; the `message` gives the cause:
- `You do not have permission to perform this action.`
 — the access does not

hold the API pack / right required by the endpoint.
- `Insufficient scope for this request.`
 — the resource targeted by the request

(user, customer, product, agency, transaction, ...) is outside the scope of

the authenticated access.
- `Access denied for this editor.`
 /
`Your IP address has been blocked.`
 —

editor or IP restriction.

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (string, required)

  - `error.message` (string, required)

## Response 422:

  - `422` (unknown)
    Validation failed

## Response 422 fields (application/json):

  - `error` (object)

  - `error.code` (string)
    Enum: "VALIDATION_ERROR"

  - `error.message` (string)

  - `error.details` (array)

  - `error.details.field` (string)

  - `error.details.message` (string)

## Response 403 examples:

  - `Missing API pack / right` (unknown)

  - `Resource outside the scope of the access` (unknown)

