Oracle Fusion Workers REST API: Query, Create, Update & Terminate

Oracle Fusion Cloud HCM exposes one of the most comprehensive REST APIs in enterprise software. At the centre of it is the Workers endpoint — the primary gateway to employee data in Oracle Human Capital Management (HCM). If you’ve ever tried to pull employee records, assignment details, or person profiles programmatically, you’ve landed on GET /hcmRestApi/resources/latest/workers.

This guide covers the essentials: how the endpoint is structured, how to use the q parameter for server-side filtering, and how finders let you target specific records without loading thousands of rows.

The Workers endpoint at a glance

The full path in Oracle HCM Cloud looks like:

GET https://{your-instance}.oraclecloud.com/hcmRestApi/resources/latest/workers

It returns a paginated collection of worker records. Each record links out to child resources: assignments, salaries, national identifiers, phones, addresses, and more. The top-level response includes a count, hasMore, limit, offset, and an items array — standard Oracle REST Data Services (ORDS) pagination.

Oracle’s HCM spec alone covers 4,724 endpoint paths and over 20,875 component schemas. The Workers endpoint is the one most teams reach for first.

Filtering with the `q` parameter

The q parameter is Oracle’s proprietary server-side filter syntax. Instead of pulling all workers and filtering in your application layer, you push the condition to the server:

GET /workers?q=PersonNumber='E12345'
GET /workers?q=PrimaryWorkEmail='john.doe@example.com'
GET /workers?q=EffectiveDate between '2025-01-01' and '2025-12-31'

The syntax supports:

Equality: FieldName='value'
Comparison: <, >, <=, >=, between
String matching: LIKE 'prefix%'
Logical operators: AND, OR

The Workers endpoint exposes over 307 unique queryable fields through q. That includes assignment attributes like BusinessUnitName, DepartmentName, JobCode, and GradeCode, as well as person-level fields like DateOfBirth, CorrespondenceLanguage, and MaritalStatus.

A more targeted example pulling all active workers in a specific business unit:

GET /workers?q=PrimaryAssignmentFlag=true AND BusinessUnitName='UK Operations' AND AssignmentStatus='ACTIVE'&limit=100&offset=0

Using finders for direct lookups

When you know exactly which record you want, q is overkill. Oracle HCM REST supports finders — named lookup strategies that map to indexed queries on the backend. For the Workers endpoint there are three:

Finder	Use case
`PrimaryKey`	Look up a single worker by `WorkerUniqId`
`findByPersonId`	Retrieve by Oracle’s internal `PersonId` (numeric)
`findReports`	Get all direct reports for a given manager `PersonId`

Invoking a finder looks like this:

GET /workers?finder=findByPersonId;PersonId=12345678

or for a manager’s direct reports:

GET /workers?finder=findReports;ManagerPersonId=12345678

Finders bypass full-table scanning and are significantly faster than equivalent q queries for point lookups. Use PrimaryKey or findByPersonId any time you have the identifier.

Controlling the response shape

Oracle REST supports two parameters that dramatically reduce payload size:

fields — select which attributes to return:

GET /workers?fields=PersonNumber,DisplayName,PrimaryWorkEmail&limit=50

expand — include child resources inline:

GET /workers?expand=assignments,phones&limit=20

Without expand, child links come back as URLs you’d have to follow separately. With it, you get everything in one round-trip — useful for reporting but expensive on large result sets.

Pagination

Oracle uses offset-based pagination. The standard pattern:

GET /workers?limit=100&offset=0   → first 100
GET /workers?limit=100&offset=100 → next 100

The response includes "hasMore": true when there are additional pages. For bulk exports, walk the pages until hasMore is false. Oracle recommends a maximum limit of 500 per request for most endpoints.

Creating and updating a worker (POST / PATCH)

The Workers endpoint isn’t read-only. POST /workers creates a new hire, and PATCH /workers/{id} updates one — the part most quick-integration guides skip entirely. The request body nests three real child resources exposed on this endpoint (confirmed via /workers/describe): names, emails, and workRelationships (which itself carries the new-hire assignments block).

A minimal new-hire payload:

POST /hcmRestApi/resources/latest/workers
Content-Type: application/vnd.oracle.adf.resourceitem+json
Effective-Of: RangeStartDate=2026-08-01;RangeEndDate=4712-12-31

{
  "names": [
    { "LegislationCode": "GLOBAL", "FirstName": "Test", "LastName": "Employee" }
  ],
  "emails": [
    { "EmailType": "W1", "EmailAddress": "test.employee@example.com" }
  ],
  "workRelationships": [
    {
      "LegalEmployerName": "Acme Corp",
      "WorkerType": "E",
      "PrimaryFlag": true,
      "assignments": [
        {
          "ActionCode": "HIRE",
          "BusinessUnitName": "Acme US BU",
          "PrimaryFlag": true
        }
      ]
    }
  ]
}

A few things worth knowing before your first attempt:

Effective-Of on write — the same RangeStartDate/RangeEndDate header used to read as-of-date data (see our effective-dating guide) also sets the hire’s effective start date here.
WorkerType — E is employee, C is contingent worker, N is nonworker. This is the same three-value set the Employee/Worker/Nonworker finders (covered above) filter on.
PersonNumber is optional on create — omit it and Oracle assigns the next value from your person-number generation rule; a successful create returns 201 Created with the system-generated PersonId you’ll use for findByPersonId lookups afterward.

Updating an existing worker looks like:

PATCH /hcmRestApi/resources/latest/workers/{PersonId}
If-Match: "<etag-from-a-prior-GET>"
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
  "names": [ { "FirstName": "Tested" } ]
}

Two gotchas trip up most first PATCH attempts: you need a fresh If-Match ETag or you’ll get a 412 Precondition Failed — see our ETag / If-Match guide for the full capture-and-retry flow — and date-effective changes (an assignment change, not a typo fix) need RangeMode=CORRECTION vs UPDATE in the Effective-Of header, which is where most Workday-migration integrations get the semantics wrong; our effective-dating guide covers the distinction in depth.

If your worker has descriptive or extensible flexfields configured per legal employer, nest workersDFF / workersEFF in the same create payload — see our DFF/EFF/DDF guide for the __FLEX_Context pattern that governs which segments apply.

Terminating and rehiring a worker

The other operation most quick-integration guides skip: ending a workRelationships record — the same real child resource the create/update section above nests assignments under. Termination isn’t a DELETE; Oracle models it as an action on the specific work relationship, using the relationship’s PeriodOfServiceId:

POST /hcmRestApi/resources/latest/workers/{workersUniqID}/child/workRelationships/{PeriodOfServiceId}/action/terminate
Content-Type: application/vnd.oracle.adf.action+json
REST-Framework-Version: 4

{
  "actionCode": "RESIGNATION",
  "terminationDate": "2026-08-31",
  "reasonCode": "VOLUNTARY",
  "recommendedForRehire": "Y"
}

A successful call returns 200 OK with Content-Type: application/vnd.oracle.adf.actionresult+json — not the resource body you get back from a normal PATCH, which trips people up if they’re expecting the standard worker payload. Made a mistake? Oracle exposes the mirror action on the same relationship:

POST /hcmRestApi/resources/latest/workers/{workersUniqID}/child/workRelationships/{PeriodOfServiceId}/action/reverseTermination
Content-Type: application/vnd.oracle.adf.action+json
REST-Framework-Version: 4

The gotcha that catches every integration once: terminating a work relationship does not touch the worker’s Oracle application login. If your worker was ever provisioned an HCM user account (see POST /users in Oracle’s identity docs), that account stays active until you deactivate it separately — either through the scheduled Autoprovision Users process or your own follow-up call. Teams that assume termination = access revoked end up with terminated employees who can still sign in for however long the scheduled job takes to run. Treat “end the work relationship” and “revoke the login” as two calls, always.

Rehire is the one Oracle doesn’t give you a clean recipe for. There’s no action/rehire endpoint — it’s one of the most-asked unanswered questions on Cloud Customer Connect (two separate threads, no accepted single answer). In practice teams either PATCH the existing workRelationships/{PeriodOfServiceId} with a rehire-flavored ActionCode from the assignment actionsLOV your instance has configured, or create a fresh work relationship the same way the “creating a worker” example earlier in this guide does. Which one is correct depends on whether your instance treats rehire-within-N-days as a continuation of the old PeriodOfServiceId or a new one — that’s an HR-configuration question (grace-period rules), not a REST question, so confirm it with whoever owns your HCM configuration before you pick an approach.

Exploring without a live instance

One challenge with Oracle HCM REST APIs is that you typically need a running Oracle Cloud instance — a dev sandbox at minimum — to inspect what fields are available, what values finders accept, and what the actual response structure looks like.

OPAL was built to solve exactly this. It bundles the full Oracle Fusion Cloud OpenAPI specification (HCM, FSCM, and BPM) locally, so you can browse all 59,000+ endpoints, inspect every q-queryable field, and read schema definitions offline — no instance, no VPN, no waiting for a sandbox environment to be provisioned.

If you’re building an HCM integration or preparing API calls ahead of a client engagement, OPAL gives you the complete spec in a searchable desktop app.

Summary

Need	Approach
Filter by field value	`q` parameter
Look up by known ID	`finder=findByPersonId` or `PrimaryKey`
Reduce payload size	`fields=...` projection
Include child data	`expand=assignments,...`
Walk large result sets	`limit` + `offset` pagination

The Workers endpoint is well-documented in Oracle’s OpenAPI spec but the spec itself is 200MB of JSON. Having it searchable and browsable locally — while you’re building — saves hours. That’s what OPAL is for.

This post is part of our complete Oracle HCM API guide — base URLs, authentication, q filters, finders, key endpoints, and common errors in one place.