# Create or update an employee

**Requires scope:** `external_employees`.
You can use this endpoint to send employee data to Dyflexis. This will create an external employee in Dyflexis, or update an existing external employee if one with the same unique reference already exists.
An external employee will need to be connected to either an existing or a new Dyflexis employee within the Dyflexis application. An administrator can do this by using the widget in the employee overview page, or by using the external employee connection settings screen.
Once connected, the Dyflexis employee will be kept in sync with the external employee whenever data is sent to this endpoint.

Endpoint: POST /api2/external-employees/{employeeReference}
Security: apiKey

## Path parameters:

  - `employeeReference` (string, required)
    Unique reference to the employee

## Request fields (application/json):

  - `initials` (string)
    Example: J

  - `firstName` (string)
    Example: Maria

  - `lastNamePrefix` (string)
    Example: de

  - `lastName` (string, required)
    Example: Santos

  - `nameFormat` (any)
    Defines how the employee name should be displayed in Dyflexis

  - `maritalStatus` (string)
    Whether the employee is single, married, living together or permanently separated

  - `partnerInitials` (string)
    Example: A

  - `partnerFirstName` (string)
    Example: Anne

  - `partnerLastNamePrefix` (string)
    Example: van

  - `partnerLastName` (string)
    Example: Ferguson

  - `gender` (string)

  - `phoneNumber` (string)
    Primary phone number
    Example: +31 6 12345678

  - `phoneNumber2` (string)
    Secondary phone number
    Example: +31 20 5550100

  - `email` (string)
    Example: john.doe@example.com

  - `dateOfBirth` (string)
    Example: 2026-12-31

  - `placeOfBirth` (string)
    Example: Pier 9 Bistro

  - `streetName` (string)
    Example: Damrak

  - `streetNumber` (string)
    Example: 70

  - `postalCode` (string)
    Example: 1012 LM

  - `city` (string)
    Example: Pier 9 Bistro

  - `nationality` (string)
    Example: Portuguese

  - `personnelNumber` (string)
    The personnel number as known by the connecting party
    Example: HV-014

  - `costCenter` (string)
    Cost center for the employee
    Example: Harborview Grand Hotel

  - `employerReferenceId` (string)
    Unique employer reference identifier as known by the connecting party
    Example: HV-FD-014

  - `jobDescription` (string)
    A textual description of the employee's job
    Example: Front desk receptionist

## Response 400 fields (application/json):

  - `status` (string, required)
    Always "warning".
    Enum: "warning"

  - `data` (array, required)

  - `data.fieldName` (string, required)
    The name of the field that contained incorrect data.

  - `data.value` (string, required)
    The value we tried to save.

  - `status` (string, required)
    Always "error".
    Enum: "error"

  - `data` (string, required)
    The error message. May be an empty string when no detail is provided.

## Response 401 fields (application/json):

  - `title` (string, required)
    Short, human-readable summary of the error.
    Example: Unauthorized

  - `status` (integer, required)
    The HTTP status code.
    Example: 401

  - `message` (string, required)
    Human-readable explanation of this occurrence of the error.
    Example: Invalid Token

  - `detail` (string)
    Human-readable explanation of this occurrence. Not returned by all backend versions.
    Example: Invalid Token

  - `code` (integer)
    The HTTP status code (duplicate of `status`). Not returned by all backend versions.
    Example: 401

## Response 403 fields (application/json):

  - `title` (string, required)
    Short, human-readable summary of the error.
    Example: Unauthorized

  - `status` (integer, required)
    The HTTP status code.
    Example: 401

  - `message` (string, required)
    Human-readable explanation of this occurrence of the error.
    Example: Invalid Token

  - `detail` (string)
    Human-readable explanation of this occurrence. Not returned by all backend versions.
    Example: Invalid Token

  - `code` (integer)
    The HTTP status code (duplicate of `status`). Not returned by all backend versions.
    Example: 401