---
title: "Create a new User"
method: POST
path: "/api/v3/users"
tags: ["Users"]
---

# Create a new User

`POST /api/v3/users`

Create a new user

## Query parameters

- `fields` string

## Request body

- UserWrite
  - `id` number — Unique identifier
  - `url` string, uri
  - `firstName` string, required — Employee's first name (given name).
  - `lastName` string, required — Employee's last name (family name).
  - `name` string — Concatenation of both the firstName and lastName
  - `displayName` string — Concatenation of both the lastName and firstName.
  - `login` string, required — **Unique** identifier of this employee.
  - `mail` string, required — Employee's professional email address.
  - `dtContractStart` string, date-time, required — First day of employment.
  - `dtContractEnd` string, date-time, nullable — Last day of employment. Leave `null` if unknown.
  - `legalEntityId` integer, required — Establishment this employee works for.
  - `legalEntity` object — Embedded representation of the establishment this employee works for.
    - `id` integer
    - `name` string
    - `url` string, uri
  - `employeeNumber` string, nullable, required — Employee number. Must be unique by establishment (i.e. legalEntity).
  - `departmentId` integer, required — Identifier of the department this employee works in.
  - `department` object — Embedded representation of the department. Read more about [departments](/api-reference/legacy/organization/departments/department).
    - `id` integer — Identifier of the department this user/employee works in.
    - `name` string — Name of the department this user/employee works in.
    - `url` string, uri — URL of the department resource.
  - `managerId` integer, nullable, required — Identifier this user/employee's manager. Is also a user/employee. `Null` may be interpreted as "this employee has no manager but themselves".
  - `manager` object
    - `id` integer — Identifier this user/employee's manager. Is also a user/employee.
    - `firstName` string — The manager's first name.
    - `lastName` string — The manager's last name.
    - `url` string, uri
  - `cspId` integer, nullable — Identifier of the socio-professional category of this employee.
  - `nationalityId` string, nullable — ISO 3166-1 alpha-2 country code
  - `seniorityDate` string, date-time, nullable — Seniority date of this employee. If left `null`, you may fall back on this employee's `dtContractStart`.
  - `birthDate` string, date-time, nullable, required — Birth date of this employee.
  - `insuranceNumber` string, nullable — Social security number of this employee.
  - `cultureID` integer, required — Language code identifiers (LCID).
  - `calendarId` integer, nullable, required — Unique identifier of this employee's business-holidays calendar.
  - `calendar` object
    - `id` integer, required — Unique identifier of the business-holidays calendar that applies to this user/employee.
    - `url` string
    - `name` string
  - `userWorkCycles` object[] — Work-cycles describe the expected (recurring) working hours of the employee. An employee may be given multiple work-cycles over their career, but no two may overlap.
    - `id` integer
    - `ownerID` integer — Identifier of the employee.
    - `workCycleID` integer, required — Identifier of the workcycle.
    - `startsOn` string, date-time, required
    - `endsOn` string, date-time, nullable, required
    - `workCycle` object
      - `id` integer
      - `name` string
      - `url` string, uri
  - `picture` object — Profile picture of this user/employee.
    - `id` string, uuid, required — Unique identifier of the user/employee's picture file.
    - `href` string, uri — Follow this link in order to retrieve the image file.
  - `rolePrincipalId` integer, required — Identifier of the "primary" role this user/employee has. There are two types of roles: "primary" and "secondary". A user/employee must have a single primary role, that dictates their overall level of access, as well as zero or several complementary "secondary" roles.
  - `rolePrincipal` object
    - `id` number, required — Identifier of the "primary" role this user/employee has.
    - `name` string — Name of the "primary" role this user/employee has.
    - `url` string
  - `habilitedRoles` object[], required — List of "secondary" (complementary) roles given to this user/employee.
    - `id` integer, required
    - `name` string
    - `url` string
  - `address` string, nullable — Personal address of this user/employee.
  - `directLine` string, phone, nullable — Professional landline phone number of this user/employee.
  - `jobTitle` string, nullable — Job title of this user/employee.
  - `gender` 'Undefined' | 'Male' | 'Female' | 'Misc' — Employee declared gender.
  - `personalEmail` string, email, nullable — Personal email address of this user/employee.
  - `personalMobile` string, phone, nullable — Personal mobile phone number of this user/employee.
  - `professionalMobile` string, phone, nullable — Professional mobile phone number of this user/employee.
  - `allowsElectronicPayslip` boolean, nullable — Whether this user/employee gave their consent to receive their payslip in an electronic format (i.e. PDF and email) rather than through physical means. This property is used by the Lucca Payslips application.
  - `quote` string, nullable — Optional personal quote of this user/employee. Reflects their mood and/or character. Displayed in the "who's who".
  - `personalCard` string, nullable — Personal credit card number. Only when Lucca Expenses is installed.
  - `corporateCard` string, nullable — Coporate credit card number. Only when Lucca Expenses is installed.
  - `bankName` string, nullable — Name of bank of this user/employee bank account.
  - `rib` string, nullable — Employee personal bank account RIB (French: "Relevé d'identité Bancaire").
  - `iban` string, nullable — Employee personal bank account IBAN (International Bank Account Number).
  - `bic` string, nullable — Employee personal bank account SWIFT BIC code (routing number).
  - `frenchCarTaxHorsePower` integer, nullable — Number of fiscal horspowers of the employee car in the context of mileage-related expense claims. Only when Lucca Expenses is installed.
  - `frenchMotocyclesTaxHorsePower` integer, nullable — Number of fiscal horspowers of the employee motorcycle in the context of mileage-related expense claims. Only when Lucca Expenses is installed.
  - `unitSellPrice` number, double, nullable — Legacy property. Should not be used.
  - `modifiedAt` string, date-time — Timestamp of the last time this user/employees attributes were modified.
  - `profile_figgo` object, nullable — Leave accrual profile in Lucca Absences
    - `id` integer
    - `name` string
    - `url` string, url
  - `fullTimeEquivalent` object, nullable — Full-time equivalent ratio in Lucca Compensation.
    - `value` string
    - `link` object, nullable
  - `theoreticalRemuneration` object, nullable — Theoretical compensation in Lucca Compensation.
    - `value` string
    - `link` object, nullable
      - `url` string, url
      - `text` string
  - `manager2Id` integer, nullable — Manager 2 may be used in the Lucca Absences approval workflow (depends on how it is configured). `manager2Id` should be used in write requests, and `manager2` in read requests in order to retrieve the corresponding user representation.
  - `manager2` object, nullable
    - `id` integer
    - `name` string
    - `url` string, uri

## Response `200`

OK

- object
  - `data` object
    - `id` number — Unique identifier
    - `url` string, uri
    - `firstName` string, required — Employee's first name (given name).
    - `lastName` string, required — Employee's last name (family name).
    - `name` string — Concatenation of both the firstName and lastName
    - `displayName` string — Concatenation of both the lastName and firstName.
    - `login` string, required — **Unique** identifier of this employee.
    - `mail` string, required — Employee's professional email address.
    - `dtContractStart` string, date-time, required — First day of employment.
    - `dtContractEnd` string, date-time, nullable — Last day of employment. Leave `null` if unknown.
    - `legalEntityId` integer, required — Establishment this employee works for.
    - `legalEntity` object — Embedded representation of the establishment this employee works for.
      - `id` integer
      - `name` string
      - `url` string, uri
    - `employeeNumber` string, nullable, required — Employee number. Must be unique by establishment (i.e. legalEntity).
    - `departmentId` integer, required — Identifier of the department this employee works in.
    - `department` object — Embedded representation of the department. Read more about [departments](/api-reference/legacy/organization/departments/department).
      - `id` integer — Identifier of the department this user/employee works in.
      - `name` string — Name of the department this user/employee works in.
      - `url` string, uri — URL of the department resource.
    - `managerId` integer, nullable, required — Identifier this user/employee's manager. Is also a user/employee. `Null` may be interpreted as "this employee has no manager but themselves".
    - `manager` object
      - `id` integer — Identifier this user/employee's manager. Is also a user/employee.
      - `firstName` string — The manager's first name.
      - `lastName` string — The manager's last name.
      - `url` string, uri
    - `cspId` integer, nullable — Identifier of the socio-professional category of this employee.
    - `nationalityId` string, nullable — ISO 3166-1 alpha-2 country code
    - `seniorityDate` string, date-time, nullable — Seniority date of this employee. If left `null`, you may fall back on this employee's `dtContractStart`.
    - `birthDate` string, date-time, nullable, required — Birth date of this employee.
    - `insuranceNumber` string, nullable — Social security number of this employee.
    - `cultureID` integer, required — Language code identifiers (LCID).
    - `calendarId` integer, nullable, required — Unique identifier of this employee's business-holidays calendar.
    - `calendar` object
      - `id` integer, required — Unique identifier of the business-holidays calendar that applies to this user/employee.
      - `url` string
      - `name` string
    - `userWorkCycles` object[] — Work-cycles describe the expected (recurring) working hours of the employee. An employee may be given multiple work-cycles over their career, but no two may overlap.
      - `id` integer
      - `ownerID` integer — Identifier of the employee.
      - `workCycleID` integer, required — Identifier of the workcycle.
      - `startsOn` string, date-time, required
      - `endsOn` string, date-time, nullable, required
      - `workCycle` object
        - `id` integer
        - `name` string
        - `url` string, uri
    - `picture` object — Profile picture of this user/employee.
      - `id` string, uuid, required — Unique identifier of the user/employee's picture file.
      - `href` string, uri — Follow this link in order to retrieve the image file.
    - `rolePrincipalId` integer, required — Identifier of the "primary" role this user/employee has. There are two types of roles: "primary" and "secondary". A user/employee must have a single primary role, that dictates their overall level of access, as well as zero or several complementary "secondary" roles.
    - `rolePrincipal` object
      - `id` number, required — Identifier of the "primary" role this user/employee has.
      - `name` string — Name of the "primary" role this user/employee has.
      - `url` string
    - `habilitedRoles` object[], required — List of "secondary" (complementary) roles given to this user/employee.
      - `id` integer, required
      - `name` string
      - `url` string
    - `address` string, nullable — Personal address of this user/employee.
    - `directLine` string, phone, nullable — Professional landline phone number of this user/employee.
    - `jobTitle` string, nullable — Job title of this user/employee.
    - `gender` 'Undefined' | 'Male' | 'Female' | 'Misc' — Employee declared gender.
    - `personalEmail` string, email, nullable — Personal email address of this user/employee.
    - `personalMobile` string, phone, nullable — Personal mobile phone number of this user/employee.
    - `professionalMobile` string, phone, nullable — Professional mobile phone number of this user/employee.
    - `allowsElectronicPayslip` boolean, nullable — Whether this user/employee gave their consent to receive their payslip in an electronic format (i.e. PDF and email) rather than through physical means. This property is used by the Lucca Payslips application.
    - `quote` string, nullable — Optional personal quote of this user/employee. Reflects their mood and/or character. Displayed in the "who's who".
    - `personalCard` string, nullable — Personal credit card number. Only when Lucca Expenses is installed.
    - `corporateCard` string, nullable — Coporate credit card number. Only when Lucca Expenses is installed.
    - `bankName` string, nullable — Name of bank of this user/employee bank account.
    - `rib` string, nullable — Employee personal bank account RIB (French: "Relevé d'identité Bancaire").
    - `iban` string, nullable — Employee personal bank account IBAN (International Bank Account Number).
    - `bic` string, nullable — Employee personal bank account SWIFT BIC code (routing number).
    - `frenchCarTaxHorsePower` integer, nullable — Number of fiscal horspowers of the employee car in the context of mileage-related expense claims. Only when Lucca Expenses is installed.
    - `frenchMotocyclesTaxHorsePower` integer, nullable — Number of fiscal horspowers of the employee motorcycle in the context of mileage-related expense claims. Only when Lucca Expenses is installed.
    - `unitSellPrice` number, double, nullable — Legacy property. Should not be used.
    - `modifiedAt` string, date-time — Timestamp of the last time this user/employees attributes were modified.
    - `extendedData` object — Dictionary of extended data, which are custom extensions to the base user/employee model. Keys are the custom extended-data definition identifier (e.g. `e_Emergency-Contact`). The value is polymorphic, and its type depends on the extended-data definition. Read more about [extended data](/api-reference/legacy/directory/guides/extended-data).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal Server Error

---

[API](https://skmtc.net/luccasoftware/apis/lucca-expenses.md) · [All operations](https://skmtc.net/luccasoftware/apis/lucca-expenses/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/luccasoftware/lucca-expenses/versions/110f9897756c/schema)