Oracle HCM Cloud API Capabilities — REST, HDL, HCM Extracts, Payroll, Workers

TL;DR

• Bottom line: Oracle Fusion Cloud HCM exposes REST APIs for real-time worker management and HDL (HCM Data Loader) for bulk inbound operations. HCM Extracts and BIP handle outbound extraction. REST is limited to ~500 records per operation — anything above that must use HDL.
• Key limit: REST fair-use throttling at ~60 req/s (HTTP 429); HDL max 250 MB per file with 20 concurrent loader threads per pod; REST pagination capped at 500 records per page.
• Watch out for: Payroll REST APIs require a separate Oracle Payroll license — they return 403 or empty results without it, and the error message does not clearly indicate a licensing issue.
• Best for: REST for real-time individual worker operations (hire, terminate, query <500 records); HDL for bulk loads (new hire imports, compensation updates, benefits enrollment); HCM Extracts for scheduled outbound feeds.
• Authentication: OAuth 2.0 JWT Bearer flow recommended for server-to-server via Oracle IDCS (3600s token lifetime, no refresh — re-authenticate on expiry).

System Profile

Oracle Fusion Cloud HCM is Oracle's SaaS human capital management suite. The REST API covers Core HR (workers, assignments, employment), Workforce Management, Compensation, Benefits, Talent, Learning, and Payroll (separate license). HDL handles bulk inbound via structured .dat files. HCM Extracts provide configurable outbound extraction. This card covers Oracle Fusion Cloud HCM only — not EBS HRMS, Taleo, or PeopleSoft.

API Surfaces & Capabilities

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Authentication Gotchas

• OAuth JWT Bearer flow does not provide refresh tokens — re-authenticate every 3600s. IDCS admins can change the timeout. [src6]
• Integration user must have correct HCM duty roles — missing roles produce 403, not 401. Role assignment determines which workers are visible (data security). [src6]
• IDCS token endpoint URL varies by data center region. Wrong region endpoint returns connection errors, not auth errors. [src6]
• HDL imports inherit the integration user's security context — user needs HCM Data Loader role AND object-level security roles. [src2]

Constraints

• REST API is NOT suitable for bulk operations (>500 records) — use HDL. No bulk endpoint equivalent to Salesforce Bulk API.
• HDL .dat files must follow Oracle's exact Business Object structure with pipe-delimited fields and METADATA/MERGE/END blocks.
• Payroll REST APIs require separate Oracle Payroll license — endpoints return 403 or empty results without it.
• HCM Extracts are outbound-only — cannot be used for inbound data loading.
• SOAP APIs are maintenance-only — Oracle recommends REST + HDL for all new integrations.
• Worker records require correct hierarchical order (Legal Employer > Assignment > Work Relationship).
• Effective-dated records require explicit EffectiveStartDate — omitting defaults to system date.

Integration Pattern Decision Tree

START — User needs to integrate with Oracle HCM Cloud
├── What's the data direction?
│   ├── Inbound (writing to HCM)
│   │   ├── Volume < 500 records? → REST API
│   │   │   ├── Hire → POST /workers
│   │   │   ├── Update assignment → PATCH /workers/{id}/child/assignments/{id}
│   │   │   └── Terminate → POST /workers/{id}/child/workRelationships/{id}/action/terminate
│   │   ├── Volume 500-50,000? → HDL (.dat file via hcmImportAndLoadData)
│   │   └── Volume > 50,000? → HDL — split into multiple files (<250 MB each)
│   ├── Outbound (reading from HCM)
│   │   ├── Real-time queries → REST API: GET /workers
│   │   ├── Scheduled bulk extraction → HCM Extracts
│   │   └── Change tracking → HCM Atom Feeds
│   └── Bidirectional → REST + HCM Extracts + HDL
├── Error tolerance?
│   ├── Zero-loss → HDL with error file download + reconciliation
│   └── Best-effort → REST with retry on 429/5xx

Quick Reference

Step-by-Step Integration Guide

1. Authenticate via OAuth 2.0 JWT Bearer

Register a Confidential Application in Oracle IDCS, obtain Client ID and Client Secret. [src6]

curl -X POST \
  "https://{identity-domain}.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all"

Verify: Response contains "access_token" field and "expires_in": 3600

2. Query Workers via REST

Retrieve worker records with expanded child objects. [src1]

curl -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber=12345&expand=assignments,names,emails&onlyData=true" \
  -H "Authorization: Bearer {access_token}"

Verify: Response contains "items" array with worker details

3. Hire a New Worker via REST

POST with the required hierarchy: Person > WorkRelationship > Assignment. [src1]

curl -X POST \
  "https://{host}.fa.{dc}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{ "names": [{"FirstName":"Jane","LastName":"Smith","LegislationCode":"US"}],
        "workRelationships": [{"LegalEmployerName":"US Legal Entity","WorkerType":"E",
        "StartDate":"2026-04-01","assignments":[{"BusinessUnitName":"US BU",
        "JobName":"Software Engineer","ActionCode":"HIRE"}]}] }'

Verify: Response HTTP 201 with PersonId populated

4. Upload HDL File for Bulk Import

Prepare .dat file, ZIP, base64-encode, upload via hcmImportAndLoadData. [src2]

curl -X POST \
  "https://{host}.fa.{dc}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/hcmImportAndLoadData" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{"ContentType":"zip","FileName":"Worker.zip","DocumentContent":"{base64_encoded_zip}"}'

Verify: Poll GET /hcmImportAndLoadData/{FlowId} until status = COMPLETED

Code Examples

Python: Hire Worker with Error Handling

# Input:  Oracle HCM host, OAuth token, hire data dict
# Output: Created PersonId or error details

import requests  # requests==2.31.0

def hire_worker(host, token, hire_data):
    url = f"https://{host}/hcmRestApi/resources/11.13.18.05/workers"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/vnd.oracle.adf.resourceitem+json"
    }
    resp = requests.post(url, headers=headers, json=hire_data)
    if resp.status_code == 201:
        return {"success": True, "person_id": resp.json().get("PersonId")}
    elif resp.status_code == 429:
        return {"success": False, "error": "throttled",
                "retry_after": resp.headers.get("Retry-After", "60")}
    else:
        return {"success": False, "status": resp.status_code, "detail": resp.text}

JavaScript/Node.js: Query Workers by Department

// Input:  Oracle host URL, OAuth token, department name
// Output: Array of worker objects

import fetch from 'node-fetch'; // [email protected]

async function getWorkersByDepartment(host, token, department) {
  const url = new URL(`https://${host}/hcmRestApi/resources/11.13.18.05/workers`);
  url.searchParams.set('q', `assignments.DepartmentName=${department}`);
  url.searchParams.set('expand', 'names,assignments,emails');
  url.searchParams.set('onlyData', 'true');
  url.searchParams.set('limit', '500');
  const resp = await fetch(url.toString(), {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  if (!resp.ok) throw new Error(`Query failed: ${resp.status}`);
  return (await resp.json()).items || [];
}

cURL: Test Authentication

# Step 1: Get token
curl -s -X POST \
  "https://{idcs}.identity.oraclecloud.com/oauth2/v1/token" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all" \
  | python -m json.tool

# Step 2: Test against workers endpoint
curl -s -X GET \
  "https://{host}.fa.{dc}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=5&onlyData=true" \
  -H "Authorization: Bearer {access_token}" \
  | python -m json.tool

Data Mapping

HDL Worker Business Object — Key Fields

Data Type Gotchas

• HDL uses YYYY/MM/DD dates; REST uses YYYY-MM-DD — mixing causes silent failures. [src1]
• HDL uses pipe-delimited METADATA/MERGE/END blocks — any formatting deviation fails the entire file. [src2]
• Person names in HDL require separate Name business object rows — NOT inline columns on the Worker row. [src2]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• HDL upload succeeds but import fails silently: POST returns 200 but import job fails. Errors only in HDL error log. Fix: Always poll import status AND download error file. [src2]
• Payroll endpoints return 403 without clear licensing error: Without Payroll license, endpoints return 403. Fix: Verify Payroll license before building payroll integrations. [src3]
• Effective date confusion creates incorrect history: Omitting EffectiveStartDate defaults to system date. Fix: Always set EffectiveStartDate explicitly. [src1]
• OAuth token expires during HDL processing: Large imports take hours. Fix: Re-authenticate before each poll; never cache tokens beyond 3500s. [src6]

Anti-Patterns

Wrong: Querying all workers one-at-a-time for change detection

# BAD — O(N) API calls; hits throttling quickly
for pid in all_person_ids:
    resp = requests.get(f"{base}/workers/{pid}", headers=headers)
    if resp.json()["LastUpdateDate"] > last_sync:
        process_change(resp.json())

Correct: Use HCM Atom Feeds for change detection

# GOOD — single feed request returns all changes
resp = requests.get(f"{base}/atomFeeds/workers?since={last_token}", headers=headers)
for entry in parse_atom(resp.text):
    process_change(entry)

Wrong: Using REST for mass compensation update

# BAD — 10,000 individual PATCH calls
for emp in employees:
    requests.patch(f"{base}/salaries/{emp['id']}", json={"Amount": emp["new"]}, headers=headers)

Correct: Use HDL for bulk compensation changes

# GOOD — single HDL file for any volume
buf = io.StringIO()
buf.write("METADATA|Salary|AssignmentNumber|SalaryAmount|DateFrom\n")
for emp in employees:
    buf.write(f"MERGE|Salary|{emp['asn']}|{emp['new']}|2026-04-01\n")
buf.write("END\n")
# ZIP, base64, upload via hcmImportAndLoadData

Common Pitfalls

• Assuming REST handles bulk: Oracle HCM REST has no bulk endpoint. Fix: Design for HDL if volume exceeds 500 records. [src5]
• Building payroll integrations without verifying license: Payroll endpoints exist in docs regardless of licensing. Fix: Confirm Payroll license with Oracle admin first. [src3]
• Not downloading HDL error files: Developers see "FAILED" but miss the actual errors. Fix: Always download the error file after every import. [src2]
• Using INSERT mode in HDL: INSERT fails on retry if record exists. Fix: Always use MERGE mode in production. [src2]
• Ignoring hierarchical worker model: Flat designs miss required Person > WorkRelationship > Assignment structure. Fix: Study the composite object before designing. [src1]

Diagnostic Commands

# Test OAuth authentication
curl -s -X POST "https://{idcs}.identity.oraclecloud.com/oauth2/v1/token" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all" | python -m json.tool

# Query first 5 workers (verify connectivity + HCM access)
curl -s -X GET "https://{host}.fa.{dc}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=5&onlyData=true" \
  -H "Authorization: Bearer {token}" | python -m json.tool

# Check HDL import status
curl -s -X GET "https://{host}.fa.{dc}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/hcmImportAndLoadData/{FlowId}" \
  -H "Authorization: Bearer {token}" | python -m json.tool

# Describe workers resource (field metadata)
curl -s -X GET "https://{host}.fa.{dc}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/describe" \
  -H "Authorization: Bearer {token}" | python -m json.tool

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Oracle does not publish fixed API rate limits — fair-use throttling varies by pod and time of day. Production may hit 429s during payroll runs or open enrollment.
• Payroll REST APIs require a separate Oracle Payroll license. Documentation lists endpoints regardless of licensing.
• HDL is the only supported bulk inbound path — no REST bulk endpoint exists.
• The hierarchical worker data model is non-negotiable — flat integration patterns will fail.
• Effective-dated operations are pervasive — nearly every HCM update requires explicit effective dates.
• HCM Extracts are outbound-only despite the name suggesting bidirectional capability.
• API endpoint availability depends on which Oracle HCM modules are licensed and opted in.