# 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

## Security:

  - `apiKey` (unknown)
    apiKey in header Authorization scopes: external_employees

## 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 200:

  - `200` (unknown)
    Success. On a successful upsert the body is an empty JSON array. Data
warnings and errors are reported via the `400` response instead.

## Response 400:

  - `400` (unknown)
    Response code 400 - Bad request. Two outcomes are possible:

- Warning: data may be incorrect but will still be accepted. Will empty any fields containing invalid data when linked to a Dyflexis employee.
- Error: missing required data, the operation cannot continue and nothing will be saved.

## 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:

  - `401` (unknown)
    Missing or invalid authentication.

## 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:

  - `403` (unknown)
    The token is valid but lacks the scope required for this operation.

## 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

## Response 503:

  - `503` (unknown)
    System temporary unavailable due to maintenance