Idempotency

Networks fail: a timeout does not tell you whether a write was applied. This page explains how to retry without creating duplicates, with external_id at the core.

external_id: your ERP id in xYago

Your identifier for the employee (Siesa employee code, personnel number...). Format: 1 to 128 characters A-Z a-z 0-9 . _ : @ / -.
Unique per company: two employees cannot share it and an employee has only one.
Set it on create (POST /employees) or later with PATCH /employees/{id}; it is the upsert key of the import.
Look it up with GET /employees?external_id=SIESA-000123: 0 or 1 result.

Store the xYago id in your ERP as well when you receive it, to avoid a lookup on every update.

Creating employees without duplicates

Always send external_id on create. xYago reserves it before creating the employee, so two concurrent requests with the same external_id never create two employees:

Response to a retried `POST /employees`	Meaning / what to do
`201`	Created now.
`409 external_id_already_exists`	It already exists (e.g. the first attempt did arrive). Fetch it with `GET /employees?external_id=...` and treat it as success.
`409 external_id_in_progress`	Another request is creating it right now. Wait a few seconds and look it up by `external_id`.
`502` / timeout	Unknown outcome: look it up by `external_id`; if it doesn't exist, retry the create.

Python

def upsert_employee(session, employee):
    """Create or update in xYago an ERP employee (dict with external_id)."""
    base = "https://api.xyago.com/v1/employees"
    found = session.get(base, params={"external_id": employee["external_id"]}, timeout=30)
    found.raise_for_status()
    results = found.json()["results"]
    if results:
        changes = {k: v for k, v in employee.items() if k not in ("work_shifts", "vacation_days")}
        response = session.patch(f"{base}/{results[0]['id']}", json=changes, timeout=30)
    else:
        response = session.post(base, json=employee, timeout=30)
        if response.status_code == 409 and response.json()["error"]["code"] == "external_id_already_exists":
            return upsert_employee(session, employee)  # a previous attempt created it
    response.raise_for_status()
    return response.json()

// Sketch with HttpClient + System.Net.Http.Json
var found = await http.GetFromJsonAsync<JsonElement>(
    $"employees?external_id={Uri.EscapeDataString(employee.ExternalId)}");
var results = found.GetProperty("results");
HttpResponseMessage response = results.GetArrayLength() > 0
    ? await http.PatchAsJsonAsync($"employees/{results[0].GetProperty("id")}", employeeChanges)
    : await http.PostAsJsonAsync("employees", newEmployee);
// 409 external_id_already_exists on POST => it exists: look it up again and PATCH.

Other writes

Operation	Behaviour when repeated
`PATCH /employees/{id}`	Idempotent: applying the same fields twice gives the same result.
`POST /employees/{id}/deactivate`	Idempotent: if already inactive it returns `200` with no change and no webhook.
`POST /employees/import`	Idempotent by `external_id`: resending the same file updates instead of duplicating; if the identical job is still queued or running you get the same `job_id`.
`POST /areas`	The name is unique under the same parent: a retry returns `409 area_already_exists`; find it with `GET /areas`.
`POST /time-entries`	An entry overlapping another entry of the employee returns `409 time_entry_overlap`: if it is the same entry, the first attempt was applied.
`PATCH /vacations/{id}/approve\|reject`	A retry returns `409 vacation_already_decided`; check the `status` with `GET /vacations`.
`POST /vacations`	Not idempotent: a retry may create a second pending request. Before retrying, look for a request with the same dates via `GET /vacations?employee_id=...&status=pending`.

The HR APIs do not use the Idempotency-Key header: use external_id and the checks above. POST /messages does require it (see Messages).