How to Integrate With the Oracle Fusion Cloud API

Oracle Fusion Cloud is one of the most widely deployed enterprise suites in the world. Oracle Fusion Cloud Financials, HCM, SCM, and CX together cover everything from general ledger and accounts payable to workforce management and supply chain. If you're building integrations that need to pull or push data to Oracle Fusion, you'll be working with its REST APIs. This guide walks through what you need to know to get up and running, from authentication to making your first API call and handling the quirks that aren't always obvious from the docs.

Understanding the API landscape

Oracle Fusion Cloud is not a single API. It's a collection of REST APIs organized by product pillar, each with its own base path and resource structure:

ERP / Financials / SCM: base path is /fscmRestApi/resources/{version}/. This covers Oracle Fusion Cloud Financials modules like General Ledger, Accounts Payable, Accounts Receivable, and Fixed Assets, as well as Procurement and Supply Chain.
HCM: base path is /hcmRestApi/resources/{version}/
CX / Sales: base path is /crmRestApi/resources/{version}/
Common features: base path is /fscmRestApi/resources/{version}/ (shared across pillars)

A full endpoint URL looks something like this:

https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices

The version string (e.g. 11.13.18.05) matters. Some resources have multiple versions, and newer ones may include a v1 path that uses Oracle's BOSS (Business Object Spectra Services) framework. The v1 APIs use a different, longer path pattern:

https://{instance}.fa.{datacenter}.oraclecloud.com/api/boss/data/objects/ora/{module}/{domain}/v1/$en/{resource}

You can tell which type you're working with by looking at the URL: if it contains /api/boss/, it's a BOSS v1 endpoint. If it contains /RestApi/resources/, it's the older ADF-based style.

All APIs use JSON as the default format and support standard HTTP methods: GET, POST, PATCH, and DELETE.

Authentication

This is where Oracle Fusion integrations tend to get complicated. There are three supported authentication mechanisms, and the right one depends on your use case.

Basic authentication over SSL

The simplest option. You pass a username and password in the HTTP Authorization header. This works for development and testing, but Oracle recommends against it for production.

curl -u username:password \
  -X GET "https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices" \
  -H "Content-Type: application/json"

One thing to watch out for: basic auth doesn't work if multi-factor authentication is enabled on the account.

OAuth 2.0 (recommended for production)

Oracle Fusion uses OCI Identity and Access Management (IAM) as the authorization server. You'll need to create a confidential application in the IAM identity domain linked to your Fusion instance. At a high level:

Log in to the OCI IAM Admin Console and navigate to your Fusion identity domain.
Create a confidential application.
Choose the grant type. For server-to-server integrations without user involvement, use Client Credentials. For flows where a user needs to authorize access, use Authorization Code (3-legged OAuth).
Define the access scope. For v1/BOSS APIs, the scope follows the pattern urn:opc:resource:fusion:{podname}:boss/.
Activate the application and note the Client ID and Client Secret.

To get an access token with client credentials:

curl -u {client_id}:{client_secret} \
  --basic \
  -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --request POST \
  "https://{identity-domain-url}/oauth2/v1/token" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:fusion:{podname}:boss/"

Then use the token in your API calls:

curl -X GET \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices"

If you're using Client Credentials, you also need to configure the Client ID as a user in Fusion Applications through the Security Console. The username in Fusion must match the auto-generated Client ID exactly.

JWT token authentication

For certificate-based flows, you can use a signed JWT to authenticate. This involves registering a certificate with Oracle Fusion's API Authentication configuration and using it to sign tokens. This approach gives you more control over certificate lifecycle management but requires more setup.

Making your first request

Once authenticated, the pattern is consistent across all Fusion APIs. Here's a basic example fetching worker records from HCM:

curl -u username:password \
  -X GET \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json"

To explore the structure of any resource, append /describe to the endpoint:

curl -u username:password \
  -X GET \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/describe" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json"

This returns the full schema, including available fields, child resources, and supported operations.

Creating a record

POST requests follow the same pattern. Here's a simplified example creating a supplier in the ERP module:

curl -u username:password \
  -X POST \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/suppliers" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{
    "Supplier": "Acme Corp",
    "SupplierType": "Supplier",
    "Status": "ACTIVE"
  }'

Filtering and pagination

Oracle Fusion REST APIs support query parameters for filtering, but the syntax depends on which REST Framework Version your instance uses.

In Framework Version 1 (the default on most instances), the q parameter uses query-by-example syntax with semicolons separating conditions:

GET /fscmRestApi/resources/11.13.18.05/invoices?q=InvoiceNumber='INV-001';InvoiceCurrency=USD

In Framework Version 2 and later, the q parameter uses RowMatch expressions with SQL-like operators:

GET /fscmRestApi/resources/11.13.18.05/invoices?q=InvoiceNumber = 'INV-001' and InvoiceCurrency = 'USD'

Version 2 also supports like, between, in, and or operators. You can check which version your instance uses (or set it via the REST-Framework-Version request header).

For predefined queries, use the finder parameter. Finders are resource-specific and discoverable via the /describe endpoint. The syntax uses semicolons before the first variable and commas between subsequent ones:

GET /fscmRestApi/resources/11.13.18.05/currencyRates?finder=CurrencyRatesFinder;fromCurrency=INR,toCurrency=USD

Pagination is handled through offset and limit parameters. The default page size varies by resource, so always check the hasMore flag in the response:

{
  "items": [...],
  "count": 25,
  "hasMore": true,
  "limit": 25,
  "offset": 0
}

Choosing the right integration pattern

Not every integration scenario calls for REST APIs. Oracle provides multiple patterns, and picking the wrong one will cause headaches down the line.

REST APIs are best for real-time, low-volume operations. Think: creating or updating a single record, looking up a customer, or syncing a handful of transactions. Oracle enforces rate limits that vary by identity domain type and returns a 429 error when exceeded. Unofficial estimates put the threshold at roughly 5,000 API calls per hour per user, which is workable for transactional use cases but not enough for bulk operations.

File-Based Data Import (FBDI) is the recommended approach for high-volume data loads. You prepare CSV files, upload them to Oracle's Universal Content Management (UCM) server, and trigger an import process. This is batch-oriented, so it won't give you real-time feedback, but it handles millions of records reliably.

Business events are Oracle's publish/subscribe mechanism. When something changes in Fusion (a PO is approved, an invoice is created), the system raises an event. You can subscribe to these events to trigger downstream workflows. Outbound business events can invoke web services or send messages, but they require Oracle Integration Cloud (OIC) for third-party integrations.

BICC (Business Intelligence Cloud Connector) is built for large-volume data extraction from ERP and SCM. If you need to sync historical data or run incremental extracts, BICC is more appropriate than the REST APIs.

The general rule: use REST APIs for real-time reads and writes of individual records. Use FBDI for bulk imports. Use BICC for bulk exports. Use business events for event-driven workflows.

Common pitfalls

A few things that trip up most developers building Oracle Fusion integrations for the first time:

POST operations have a record limit. Oracle recommends limiting POST operations to a maximum of 500 records per request. Exceeding this can lead to timeouts or partial failures.

Not all operations are supported on every resource. If a GET works but a PATCH doesn't, check whether the resource supports that method. Some resources are read-only. When an operation isn't available, Oracle's documentation usually points you to alternatives like SOAP services or FBDI.

Security roles and permission groups. Access to the API isn't just about authentication. The user or service account needs the right job roles assigned in the Fusion Security Console. For v1/BOSS APIs specifically, the roles also need permission groups enabled. Without these, you'll get 403 errors that can be difficult to troubleshoot.

Content-Type headers matter. Oracle Fusion APIs often expect application/vnd.oracle.adf.resourceitem+json rather than a plain application/json. Using the wrong content type can result in cryptic error responses.

Nested/child resources return limited data by default. When you fetch a parent resource, child data may not be included unless you explicitly expand it using the expand query parameter or request specific fields with fields.

Rate limiting is per user, not per application. If multiple systems share the same integration user, they share the same rate limit pool.

Using a unified API to simplify Oracle Fusion integrations

Building direct integrations to Oracle Fusion works, but the authentication setup, permission management, and pillar-specific API differences add up fast, especially if your product also needs to integrate with other ERPs, accounting platforms, or HRIS systems.

Unified API platforms can abstract away the Oracle-specific complexity and give you a single interface that works across Oracle Fusion and dozens of other connectors. Instead of managing OAuth flows, permission groups, and content-type quirks for each system, you authenticate once and use a normalized data model.

This is particularly useful if you're integrating accounting, HRIS, or CRM data across customers who may be running Oracle Fusion, NetSuite, SAP, Workday, or QuickBooks. Rather than building and maintaining separate integrations for each, a unified API lets you build once and support all of them.