Oracle Fusion API: The Complete Guide

What is the Oracle Fusion API?

"Oracle Fusion API" is shorthand for something bigger than one API. Oracle Fusion Cloud Applications is a suite of product pillars — Human Capital Management (HCM), ERP and Financials, Supply Chain and Manufacturing (SCM), and Customer Experience (CX) — and each pillar exposes its business objects as REST resources. Workers, invoices, purchase orders, suppliers, opportunities: every one of them is an endpoint with its own path, query parameters, request and response schemas, and security privileges, all speaking JSON over HTTPS.

The scale is what surprises developers first. The 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. FSCM adds another ~1,300 paths in an 83 MB spec. Across all pillars, Oracle Fusion Cloud exposes on the order of 10,000–12,000 REST endpoints. Nobody memorizes this surface. The practical skill — and the point of this guide — is understanding the conventions that all of these endpoints share, so that any individual endpoint becomes predictable.

If your work is primarily HR data, we maintain a dedicated companion guide: the complete Oracle HCM API guide. This page covers the layer above it — the rules common to every Fusion pillar.

Product pillars and base URLs

Every Oracle Fusion REST call follows the same URL shape:

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

The <pod> is your environment's hostname — every customer instance has its own. The <root> segment tells you which pillar you are talking to, and which documentation set applies:

The <version> segment is a REST framework version such as 11.13.18.05; Oracle also accepts the alias latest. Use latest for exploration, but pin an explicit version in production integrations so an upgrade cannot silently change behavior underneath you.

One consequence of the pillar split that costs real debugging time: a resource name means nothing outside its root. There is no /workers under /fscmRestApi/, and calling the right resource under the wrong root returns a generic 404 rather than a helpful "wrong pillar" hint.

Authentication and security privileges

Two authentication approaches cover nearly all real-world usage:

HTTP Basic authentication. A Fusion username and password on every request. Fastest way to start testing, and still common in server-to-server integrations — at the cost of managing a service account and its password lifecycle.

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

Authentication is necessary but not sufficient. Every Fusion REST resource is guarded by function and aggregate security privileges delivered through job roles. A user with valid credentials but missing privileges gets 403 Forbidden — so when a call fails with 403, fix the job roles in the Security Console, not the request.

Filtering with the q parameter

Across every pillar, collections filter server-side with the q query parameter:

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

The rule that governs everything: only fields flagged as queryable on that specific resource are accepted. The queryable set differs per endpoint and lives buried in the resource metadata — a field you can see in a response is not necessarily a field you can filter on. Filtering on a non-queryable field, or on child data from the parent endpoint, returns the famously unhelpful The query parameter is invalid.

Expressions support comparison and logical operators — =, >=, LIKE, AND / OR — but the accepted syntax varies with the REST framework version, so treat q as resource-specific and verify the queryable field list before writing the filter. The full failure catalog is in why the q parameter fails and how to fix it, and if q interacts badly with expand, see the q + expand troubleshooting note.

Finders: named queries

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

GET /workers?finder=findByPersonId;PersonId=300000012345678

Finders can reach values q cannot, and when one exists for your lookup it is usually the more reliable choice. Names and parameters are exact — if a finder call fails, check the resource metadata for the precise spelling rather than guessing. The pattern is the same in every pillar; the deep dive is in Oracle Fusion REST API finders, explained.

Shaping responses: fields, expand, and child resources

Fusion resources are hierarchical: a worker has assignments, an invoice has lines, a purchase order has schedules. Two tools work with that hierarchy everywhere:

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

Child endpoints — such as /workers/{id}/child/assignments — give the nested collection 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. On heavy resources this shrinks payloads dramatically, and combining q + fields + pagination (limit / offset, with hasMore in the response) is the standard shape of an efficient Fusion read.

Framework versions and content types

Requests can carry a REST-Framework-Version header, and 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 works in one environment and fails in another, compare framework versions before assuming the data is different.

On writes, Oracle's ADF-based endpoints frequently expect Content-Type: application/vnd.oracle.adf.resourceitem+json rather than plain application/json. If a POST or PATCH that looks correct is rejected with a content error, the content type is the first thing to check.

Reading a resource's metadata with /describe

Every Fusion REST resource answers a GET /describe request that returns its own metadata: the attributes it exposes, which of them are queryable, the finders it ships and their bound parameters, the child collections underneath it, and the actions it supports. When the documentation and the environment disagree — which happens, because pods run different patch levels — /describe is the ground truth for that pod:

GET /hcmRestApi/resources/latest/workers/describe

The catch is volume. A describe document for a heavy resource runs to megabytes of JSON, and answering a simple question — "is this field queryable?" — means digging through deeply nested structures by hand. It is the most reliable source of truth and the least pleasant one to read, which is exactly why pre-indexed, searchable catalogs of this metadata (covered at the end of this guide) exist.

A related environment note: every customer gets separate production and test pods, refreshed on different schedules and often running different quarterly update patch levels. An integration validated only against the test pod can still surprise you in production if the framework versions differ — pin versions explicitly, and re-run your integration tests after each quarterly update lands on each pod.

When REST is the wrong tool: FBDI, HDL, BICC, and events

The Fusion REST APIs are built for record-level, real-time operations: look up a supplier, create an absence, update an invoice hold, drive a workflow step. They are not built for moving whole datasets. Oracle's integration guidance maps each job to a purpose-built tool:

The rule of thumb: if an integration pages an entire collection from offset 0 to the end on a schedule, that job belongs in a bulk tool, with REST reserved for the per-record operations in between. Oracle also recommends keeping POST batches under 500 records per request — beyond that you are in bulk territory.

Rate limits and common errors

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

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

403 — Forbidden. Authenticated, but missing the REST security privilege for the resource. Fix the job roles, not the request.

404 — Not found. Check the pillar root first — the resource may exist, just not under the root you called.

429 — Too Many Requests. Oracle rate-limits API traffic per identity domain, and the thresholds are not published — unofficial estimates put them in the low thousands of calls per hour per user, varying by domain type. Treat the limit as real but unknowable: batch reads, cache reference data that rarely changes, spread scheduled jobs away from peak windows, and back off with jitter on 429 rather than retrying immediately. A single misbehaving retry loop can consume the whole domain's budget and take unrelated integrations down with it.

Finding the right endpoint — without reading a 200 MB spec

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

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

Download OPAL — free for macOS, Windows, and Linux (including a portable ZIP version for locked-down enterprise machines) — or read the API explorer docs.

Frequently asked questions