Skip to main content

Manager Links

employment.manager records who a worker reports to. It is the one field on a worker that points at another worker, which makes it the one field where the order your records arrive in matters — and the one most likely to be written by two systems at once.

Set it with the same PATCH you use for any other worker field; the Workers & Credentials tutorial covers the basic update. This page covers what's specific to manager references: how to name the manager, what happens when they don't exist yet, and who wins when an HRIS feed writes the same field.

Naming the manager​

Reference the manager with exactly one of id (the synthetic wkr_ identifier) or externalId (your upstream HRIS identifier) — the same pattern as credential owner references.

# By synthetic id
curl -sS -X PATCH "$OHO_BASE/workers/$WKR" \
  -H "Authorization: Bearer $OHO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "employment": { "manager": { "id": "wkr_M9nAgErW0rKeRiD1" } } }'

# By your HRIS id — add sourceSystem if the same externalId exists in multiple systems
curl -sS -X PATCH "$OHO_BASE/workers/$WKR" \
  -H "Authorization: Bearer $OHO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "employment": { "manager": { "externalId": "WD-100001", "sourceSystem": "workday" } } }'

Responses return "manager": { "id": "wkr_..." } once linked.

Out-of-order syncs are fine. If the manager's externalId doesn't match any worker yet, the reference is accepted and parked as pending — you'll see it echoed back as "manager": { "externalId": "WD-100001", "sourceSystem": "workday" } (no id). The moment a worker carrying that source.externalId is created or updated via the API, the link completes automatically and the response switches to the id form. No two-pass ordering is needed when you bulk-sync from your HRIS.

Manager validation
  • A manager.id must reference an existing, non-deleted worker → otherwise 400
  • A worker cannot be their own manager → 400
  • An externalId matching multiple workers → 400; narrow with sourceSystem
  • An externalId matching no worker → accepted as pending (see above)
  • To clear the manager (linked or pending), use PUT and omit employment.manager (PATCH leaves an omitted manager unchanged)
HRIS ingestion also writes this field

If this worker is synced from an HRIS feed (e.g. the SFTP workforce connector with manager_worker_id / manager_email columns), the next sync run overwrites whatever the API set — the most recent writer wins. Set the manager in your HRIS when it is the source of truth.