Oracle HCM API: The Complete Guide

What is the Oracle HCM API?

Oracle Fusion Cloud HCM (Human Capital Management) exposes its data through a large family of REST endpoints, collectively referred to as the Oracle HCM API. Each business object — workers, assignments, absences, salaries, user accounts, jobs, positions, departments — is a REST resource with its own path, query parameters, request and response schemas, and security privileges. External systems use these endpoints to read, create, update, and delete HR data over HTTPS with JSON payloads.

The scale is the first thing that surprises most developers. Oracle's published OpenAPI specification for HCM alone is roughly 200 MB of JSON, describing about 4,700 endpoint paths and more than 20,000 component schemas. A single resource like GET /workers exposes over 300 queryable fields. Nobody memorizes this surface — the practical skill is knowing how the pieces fit together: how URLs are structured, how authentication works, how filtering behaves, and where the sharp edges are. That is what this guide covers.

Base URL and versioning

Every Oracle HCM REST call follows the same URL pattern:

https://<pod>.fa.<region>.oraclecloud.com/hcmRestApi/resources/<version>/<resource>

The <pod> is your environment's hostname (each customer instance has its own), and <version> is a REST framework version such as 11.13.18.05. Oracle also accepts the alias latest in place of an explicit version. For ad-hoc exploration latest is convenient; for production integrations, pin an explicit version so behavior does not shift underneath you after an upgrade.

Note that HCM endpoints live under /hcmRestApi/, while Financials and Supply Chain (FSCM) resources use a different root (/fscmRestApi/). The URL root tells you which product pillar — and which documentation set — you are dealing with.

Authentication and security privileges

There are two authentication approaches you will encounter in practice:

HTTP Basic authentication. A Fusion username and password sent on each request. This is the fastest way to start testing and remains common for server-to-server integrations, though it means managing a service account and its password lifecycle.

OAuth 2.0 with JWT. A token issued by the Oracle identity domain (IDCS or OCI IAM) and sent as a bearer token. One detail that trips people up: the token endpoint lives on the identity domain's hostname, not on the HCM pod URL — they are separate hosts configured separately.

Authentication alone is not enough. Every HCM REST resource is protected by function and aggregate security privileges, delivered through job roles. If the calling user's roles do not carry the privilege for a resource, the API returns an authorization error even though the credentials are valid. When a call fails with 403, check the user's roles before debugging anything else.

The key Oracle HCM API endpoints

A handful of resources do most of the work in real integrations:

The /workers resource deserves special attention — it is the endpoint you will call most, and it exposes 307 queryable fields, three finders, and a deep tree of child resources. We wrote a dedicated deep-dive: the Workers endpoint, explained. For a worked example that chains /workers and /userAccounts together, see finding a user and their manager by entity.

Filtering with the q parameter

The q query parameter filters a collection on the server, so you retrieve only matching rows instead of paging through everything:

GET /hcmRestApi/resources/latest/workers?q=PersonNumber='100001'

The critical rule: only fields flagged as queryable on that specific resource are accepted. The queryable set differs per endpoint and is buried in the spec metadata — a field you can see in the response is not necessarily a field you can filter on. Filtering on a non-queryable field returns the famously unhelpful The query parameter is invalid. Filtering child data from the parent endpoint is another common cause of the same error.

Expressions support comparison and logical operators — =, >=, LIKE, AND / OR — but syntax details vary with the REST framework version. Two resources that look similar can behave differently, so treat q as resource-specific and always verify the queryable field list first. Full breakdown with failure cases: why the q parameter fails and how to fix it. If your q filter interacts badly with expand, see the q + expand troubleshooting note.

Finders: named queries

Finders are pre-built, named queries that a resource exposes as an alternative to q. Instead of writing a filter expression, you name the finder and bind its parameters:

GET /workers?finder=findByPersonId;PersonId=300000012345678

The /workers resource ships three finders: PrimaryKey, findByPersonId, and findReports. Finders can reach values that q cannot, and when one exists for your lookup it is usually the more reliable choice. Finder names and parameters are exact — if a finder call fails, check the resource metadata for the precise spelling rather than guessing. More in our guide: Oracle Fusion REST API finders, explained.

Shaping responses: fields, expand, and child resources

HCM resources are hierarchical. A worker has assignments; an assignment has a manager; and many parents expose child collections as their own sub-endpoints. You have two tools for working with this hierarchy:

expand inlines child collections into the parent response — convenient for exploration and small payloads, for example GET /workers?expand=assignments.

Child endpoints — such as /workers/{id}/child/assignments — give you direct access to the nested collection with its own filtering and paging. When you need to filter or page child data accurately, call the child endpoint instead of expanding the parent. The trade-offs are covered in child resources: expand vs. child endpoints.

Separately, the fields parameter projects only the attributes you name, which can shrink large responses dramatically — worth doing on any endpoint as heavy as /workers.

Pagination

Collections page with limit and offset. Responses include hasMore to signal remaining pages, and totalResults appears when you request totalResults=true. Walk large result sets with a stable sort and increasing offset — and combine pagination with q and fields so you page over as little data as possible.

Framework versions and effective dates

Beyond the version segment in the URL, requests can carry a REST-Framework-Version header. The framework version changes real behavior — most visibly the q syntax, where later versions support richer expressions while rejecting some older query-by-example forms. If a filter that works on one environment fails on another, compare the framework version before assuming the data is different. When you pin a version, pin it consistently: in the URL, in the header where required, and in your integration tests.

HCM adds one more dimension most REST APIs do not have: date-effective objects. A worker's assignment is not a single row — it is a history of rows, each valid for a date range. Reads default to the current effective date, and the Effective-Of header lets you read or update the record as of a specific date or range. If an integration reports "missing" data that clearly exists in the UI, check whether you are querying the right effective date — future-dated hires and transfers are the classic case. Date-effective updates (corrections vs. updates vs. new date ranges) are also why a plain PATCH against an assignment can behave differently than you expect; always confirm the range mode the business change requires.

When REST is the wrong tool: HDL and extracts

The Oracle HCM API is designed for record-level, real-time operations: look up a worker, create an absence, update a phone number, drive an onboarding workflow. It is not designed for moving the whole workforce in or out of the system.

For bulk loads — migrations, mass updates, thousands of records per run — Oracle's supported path is HCM Data Loader (HDL), which itself has a REST-triggerable interface for submitting load files. For bulk exports, HCM Extracts and BI-based extraction are built for full-population snapshots that would take thousands of paged REST calls to reproduce. A good integration architecture typically combines them: HDL or extracts for the heavy lifting on a schedule, and the REST API for the event-driven, per-record operations in between. If you find yourself paging /workers from offset 0 to the end every night, that job probably belongs in an extract.

Common errors and how to read them

400 — "The query parameter is invalid." Almost always a q problem: a non-queryable field, a child field filtered from the parent, or version-specific syntax. Verify the queryable field list for the exact resource.

401 — Unauthorized. Bad credentials or an expired token. With OAuth, confirm you requested the token from the identity domain host, not the pod host.

403 — Forbidden. The user authenticated but lacks the REST security privilege for the resource. Fix the job roles, not the request.

415 / unexpected content errors on writes. Oracle's ADF-based endpoints often expect Content-Type: application/vnd.oracle.adf.resourceitem+json rather than plain application/json on POST and PATCH.

429 — Too Many Requests. Oracle rate-limits API traffic per identity domain. Batch reads, cache reference data, and back off on 429s rather than retrying immediately.

Finding the right endpoint and fields — without the 200 MB spec

The hardest part of the Oracle HCM API is rarely the HTTP call — it is discovery. Which of the ~4,700 endpoints holds the field you need? Is that field queryable? Which finder takes which parameters? Oracle's online documentation answers these questions one page at a time, and the raw OpenAPI spec is too large to open in an editor.

This is the problem OPAL was built to solve: the full HCM, FSCM, and BPM specification pre-indexed in a local database, searchable by endpoint, parameter, or field name in under 200 ms — fully offline. You can search every endpoint that carries a given field (see finding BloodType across 93 endpoints), build q filters visually from the actual queryable field list, and generate finder URLs from real metadata. How the offline catalog works: an offline Oracle Fusion Cloud API explorer.

Download OPAL — free for macOS, Windows, and Linux — or read more in the API explorer docs.

Frequently asked questions