{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/lucca/main/json-schema/lucca-employee-create-schema.json",
  "title": "employee.create",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lucca-api-2024-11-01.json#/components/schemas/employee.create",
  "type": "object",
  "required": [
    "givenName",
    "familyName",
    "remoteId",
    "firstEmployment"
  ],
  "allOf": [
    {
      "$ref": "#/$defs/employee.update"
    },
    {
      "type": "object",
      "properties": {
        "remoteId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Login of the employee. Must be unique."
        },
        "firstEmployment": {
          "title": "employment",
          "description": "The employment resource represents a relationship between an [employee](../employees/employee) and a [legal-entity](../organization/legal-entity) over a continuous period. It may actually represent a work contract, an internship agreement, a contractor's contract, etc...\n\nThe actual job of the employee is defined through the [job-position](/api-reference/latest/employments/job-position) resource, which references an employment. Over the course of his/her employment, the employee may occupy several job-positions.",
          "x-tags": [
            "employees"
          ],
          "type": "object",
          "properties": {
            "remoteId": {
              "type": [
                "null",
                "string"
              ],
              "minLength": 1,
              "maxLength": 200,
              "description": "Resource identifier in a third-party system."
            },
            "legalEntity": {
              "description": "Reference to a legal-entity. It must be the legal-entity of the business-establishment of the first job-position, otherwise the API returns a `400`.",
              "allOf": [
                {
                  "title": "Reference to a legal-entity",
                  "description": "Reference to a [legal-entity](../organization/legal-entity) resource.",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "required": [
                    "id"
                  ]
                }
              ]
            },
            "start": {
              "type": "object",
              "required": [
                "date"
              ],
              "additionalProperties": false,
              "properties": {
                "date": {
                  "description": "Date of the first day (included) of this employment.",
                  "type": "string",
                  "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])$",
                  "format": "date"
                }
              }
            },
            "end": {
              "type": [
                "null",
                "object"
              ],
              "additionalProperties": false,
              "required": [
                "date"
              ],
              "properties": {
                "date": {
                  "description": "Date of the last day (included) of this employment. After this date, this employment is considered terminated.\n\nLeave `null` for permanent employments (as long as the employee is kept), and set the date of the last day in case of a fixed-term employment.\n\nEndsOn date must be greater or equal than StartsOn date.",
                  "type": "string",
                  "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])$",
                  "format": "date"
                }
              }
            },
            "document": {
              "oneOf": [
                {
                  "title": "file-reference",
                  "description": "Reference to a [file](../files/file) resource.",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "required": [
                    "id"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "template": {
              "title": "employment-template-reference",
              "description": "Reference to an [employment-template](../employments/employment-template) resource.",
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "required": [
                "id"
              ]
            },
            "firstJobPosition": {
              "title": "job-position",
              "x-tags": [
                "Employees"
              ],
              "description": "The job position represents a stage in an [employee](../employees/employee)'s career during one of their [employment](/api-reference/latest/employments/employment) in a given [business-establishment](../organization/business-establishment).\n\nIt therefore outlines the attributes of the person as a professional (qualifications) and their role in the company as well as who's their manager.",
              "type": "object",
              "properties": {
                "remoteId": {
                  "minLength": 1,
                  "maxLength": 1024,
                  "description": "Resource identifier in a third-party system. No unicity constraint: two job-positions may have the same value.",
                  "type": [
                    "null",
                    "string"
                  ]
                },
                "businessEstablishment": {
                  "title": "business-establishment-reference",
                  "description": "Reference to a [business-establishment](../organization/business-establishment) resource.",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1
                    }
                  }
                },
                "jobTitle": {
                  "description": "Short description of the job occupied by this employee.",
                  "type": [
                    "null",
                    "string"
                  ],
                  "maxLength": 1024,
                  "minLength": 1
                },
                "jobQualification": {
                  "oneOf": [
                    {
                      "title": "job-qualification-reference",
                      "description": "Reference to a [job-qualification](../employee-occupations/job-qualification) resource.",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "manager": {
                  "oneOf": [
                    {
                      "title": "employee-reference",
                      "description": "Reference to an employee resource.",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "occupationCategory": {
                  "oneOf": [
                    {
                      "title": "occupation-category-reference",
                      "description": "Reference to an [occupation-category](../employee-occupations/occupation-category) resource.",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "workingTimeArrangement": {
                  "oneOf": [
                    {
                      "title": "working-time-arrangement-reference",
                      "description": "Reference to a working-time-arrangement resource.",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "department": {
                  "title": "department-reference",
                  "description": "Reference to a [department](../organization/department) resource.",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1
                    }
                  }
                },
                "document": {
                  "oneOf": [
                    {
                      "title": "file-reference",
                      "description": "Reference to a [file](../files/file) resource.",
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "t9n": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "jobTitle": {
                      "$ref": "#/$defs/t9n"
                    }
                  }
                }
              },
              "required": [
                "businessEstablishment",
                "department"
              ]
            }
          },
          "required": [
            "start",
            "legalEntity",
            "template",
            "firstJobPosition"
          ]
        }
      }
    }
  ],
  "$defs": {
    "employee.update": {
      "title": "employee",
      "x-tags": [
        "Employees"
      ],
      "description": "The employee represents the public face of an employee in the system. Note that an employee can also represent a trainee, an intern, a contractor, etc...\n\nThe `applicableEmployment` property references the employee's [employment](../employments/employment) that is:\n- currently in effect if the employee is \"active\".\n- will first be in effect if the employee has an employment starting in the future (either the first or a new one).\n- was last in effect if the employee is no longer employed and is not expected to be re-remployed in the future.\n\nThe `applicableJobPosition` property references the employee's [job-position](../employments/job-position) that matches the same logic.",
      "type": "object",
      "properties": {
        "remoteId": {
          "description": "Must be unique.",
          "type": [
            "null",
            "string"
          ],
          "minLength": 1,
          "maxLength": 100
        },
        "portrait": {
          "oneOf": [
            {
              "$ref": "#/$defs/portrait-reference"
            },
            {
              "type": "null"
            }
          ],
          "description": "Reference to the employee's portrait, which is a file (picture) representing them."
        },
        "givenName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Name given at birth. In the U.S.A., the first name of a person. In French: \"prénom\". Leading and trailing spaces are automatically removed."
        },
        "familyName": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Name inherited from the person's family. In the U.S.A., the last name of a person. In French: \"nom (de famille)\". Leading and trailing spaces are automatically removed."
        },
        "employeeNumber": {
          "type": [
            "null",
            "string"
          ],
          "minLength": 1,
          "maxLength": 50
        },
        "email": {
          "description": "Professional email of this employee. \"<\" and \">\" characters are forbidden. Some domains are blacklisted and may thus result in 400 errors.",
          "type": [
            "null",
            "string"
          ],
          "format": "idn-email",
          "minLength": 3,
          "maxLength": 255
        },
        "phoneNumber": {
          "oneOf": [
            {
              "$ref": "#/$defs/phone"
            },
            {
              "type": "null"
            }
          ],
          "description": "Professional mobile phone number of this employee."
        }
      }
    },
    "phone": {
      "title": "Phone number",
      "description": "Phone number, in international or national format (e.g. \"+33 1 23 45 67 89\" or \"01 23 45 67 89\").",
      "type": "string",
      "maxLength": 50,
      "pattern": "^[\\s0-9+()-]{6,50}$"
    },
    "portrait-reference": {
      "title": "portrait-reference",
      "description": "Reference to a [portrait](../employees/portrait) resource.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id"
      ],
      "readOnly": true,
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "readOnly": true
        },
        "type": {
          "type": "string",
          "const": "portrait",
          "readOnly": true
        },
        "url": {
          "type": "string",
          "format": "uri",
          "readOnly": true
        }
      }
    },
    "t9n": {
      "type": [
        "object",
        "null"
      ],
      "title": "Translations",
      "description": "Used for translation purposes. Object is structured as a dictionary whose keys refer to translated properties of the parent object, and whose values are a dictionary of supported languages.\n\nOn the parent object, the translated property value is considered the \"invariant\" translation. It is expected to show this value whenever the user's language has no translation in `t9n`.\n\nLanguages are identified through their RFC 4646 language tag.",
      "properties": {
        "de-DE": {
          "description": "German (Germany)",
          "type": [
            "string",
            "null"
          ]
        },
        "en-US": {
          "description": "English (United States of America)",
          "type": [
            "string",
            "null"
          ]
        },
        "en-GB": {
          "description": "English (Great Britain)",
          "type": [
            "string",
            "null"
          ]
        },
        "es-ES": {
          "description": "Spanish (Spain)",
          "type": [
            "string",
            "null"
          ]
        },
        "fr-FR": {
          "description": "French (France)",
          "type": [
            "string",
            "null"
          ]
        },
        "fr-CH": {
          "description": "French (Switzerland)",
          "type": [
            "string",
            "null"
          ]
        },
        "it-IT": {
          "description": "Italian (Italy)",
          "type": [
            "string",
            "null"
          ]
        },
        "nl-BE": {
          "description": "Dutch (Belgium)",
          "type": [
            "string",
            "null"
          ]
        },
        "nl-NL": {
          "description": "Dutch (Netherlands)",
          "type": [
            "string",
            "null"
          ]
        },
        "pt-PT": {
          "description": "Portuguese (Portugal)",
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}