Oracle Fusion Cloud REST API: A Practical Guide to the Workers Endpoint
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='[email protected]'
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.
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.