Sync employees with an external HRIS

This is a one-way read. The public API has no write endpoints, so OnTime cannot be the target of an automated sync. You can detect drift; applying it happens elsewhere. See Applying changes below.

Reading the directory

GET /api/public/v1/employees returns the whole directory in one response — there is no pagination.

{
  "meta": { "count": 3 },
  "data": [
    {
      "id": "3f1c9b2a-5d84-4e7a-9c11-2b6f8d0a4e73",
      "code": "EMP-0421",
      "name": "Rhea Varma",
      "email": "rhea.varma@example.com",
      "department": "Operations",
      "status": "Active"
    },
    {
      "id": "8a2e4d61-7c93-4b05-8f2d-1e5c9a3b7d40",
      "code": "EMP-0518",
      "name": "Arjun Nair",
      "email": "arjun.nair@example.com",
      "department": "Sales",
      "status": "Probation"
    },
    {
      "id": "c05b7f38-1a92-4e6d-b840-9f3c2e1a5d67",
      "code": "EMP-0733",
      "name": "Meera Iyer",
      "email": null,
      "department": null,
      "status": "Exited"
    }
  ]
}

The public employee shape is deliberately minimal: identity, department and status. It does not include manager, location, shift, joining date, compensation or contact details.

Choosing a match key

Field	Use as key?
`id`	Yes, once you have it. A stable UUID. Store it in your system after the first match.
`code`	Yes, for the initial match. Unique within the organization, and usually the field both systems share. Can be changed by an administrator.
`email`	No. It identifies the person, who may be a member of several organizations, and it can be `null`.
`name`	No.

First run: match on code

Both systems typically know an employee number. Match on it, then record the OnTime id against each of your records.

Subsequent runs: match on the stored id

Immune to a code being reassigned or corrected.

The reconciliation

const BASE = "https://app.ontime.hosai.app";

type OnTimeEmployee = {
  id: string;
  code: string;
  name: string;
  email: string | null;
  department: string | null;
  status: string;
};

type Drift = {
  kind: "missing_in_ontime" | "missing_in_hris" | "field_mismatch";
  code: string;
  detail?: string;
};

async function reconcile(hris: Map<string, { name: string; department: string | null; active: boolean }>) {
  const res = await fetch(`${BASE}/api/public/v1/employees`, {
    headers: { Authorization: `Bearer ${process.env.ONTIME_API_KEY}` },
  });
  if (!res.ok) throw new Error(`OnTime ${res.status}: ${await res.text()}`);

  const { data } = (await res.json()) as { data: OnTimeEmployee[] };
  const ontime = new Map(data.map((e) => [e.code, e]));
  const drift: Drift[] = [];

  for (const [code, source] of hris) {
    const target = ontime.get(code);
    if (!target) {
      drift.push({ kind: "missing_in_ontime", code });
      continue;
    }
    if (source.name !== target.name) {
      drift.push({ kind: "field_mismatch", code, detail: `name: "${target.name}" → "${source.name}"` });
    }
    if (source.department !== target.department) {
      drift.push({ kind: "field_mismatch", code, detail: `department: "${target.department}" → "${source.department}"` });
    }
    // "Exited" in OnTime vs active in the HRIS is the one that matters most —
    // an exited employee who is still active elsewhere is an access problem.
    const targetActive = target.status !== "Exited";
    if (source.active !== targetActive) {
      drift.push({ kind: "field_mismatch", code, detail: `status: OnTime ${target.status}, HRIS ${source.active ? "active" : "inactive"}` });
    }
  }

  for (const [code] of ontime) {
    if (!hris.has(code)) drift.push({ kind: "missing_in_hris", code });
  }

  return drift;
}

Applying changes

Because the public API is read-only, you have three options for acting on the drift:

Report it

Emit a drift report and let an administrator apply it in the console. Simple, auditable, and the right choice when drift is rare.

CSV import

For bulk onboarding, produce a CSV and use the directory’s bulk import. Remember imported employees need a password set before they can sign in.

MCP

The MCP server does expose employee create and update tools, acting as a bound employee with that person’s permissions. This is the only programmatic write path. See the AI & MCP tab.

Do not attempt to drive the internal /api/employees routes. They authenticate with a session cookie, are not versioned, and may change without notice.

Status values

Status	Meaning
`Onboarding`	Record created, not yet started.
`Probation`	Started, within probation.
`Active`	The normal state.
`Exited`	Left. Retained for history, payroll and compliance.

Exited employees remain in the directory and continue to be returned by this endpoint — their attendance, payslips and documents are part of the statutory record. Filter them out yourself if your target system should not see them.

Scheduling

There is no employee-change webhook, so this is a poll. Daily is usually right; the directory does not change fast enough to justify more, and each run is a single request.

Getting Started

Concepts

Webhooks

Guides

Sync employees with an external HRIS

Reading the directory

Choosing a match key

The reconciliation

Applying changes

Report it

CSV import

MCP

Status values

Scheduling

​Reading the directory

​Choosing a match key

​The reconciliation

​Applying changes

Report it

CSV import

MCP

​Status values

​Scheduling

Reading the directory

Choosing a match key

The reconciliation

Applying changes

Status values

Scheduling