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.
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
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
Code
Meaning
Cause
Resolution
400
Bad Request
Invalid payload, missing hierarchy
Check required fields and Person > WorkRelationship > Assignment structure
401
Unauthorized
Invalid/expired token
Re-authenticate via OAuth
403
Forbidden
Missing HCM roles or Payroll license
Assign HCM duty roles; verify Payroll license
404
Not Found
Invalid endpoint or PersonId
Verify resource version (11.13.18.05)
409
Conflict
Duplicate PersonNumber
Check for existing records; retry with jitter
429
Too Many Requests
Fair-use throttling (~60 req/s)
Exponential backoff with Retry-After header
500
Internal Server Error
Transient server issue
Retry after 30-60 seconds
HDL-001
Validation Error
Invalid .dat format
Validate METADATA/MERGE/END structure
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]
Real-time individual worker operations <500 records
Bulk imports >500 records
HDL via hcmImportAndLoadData
Querying worker details, absences
Mass compensation changes (annual review)
HDL with Salary business object
Individual absence requests
Scheduled outbound HR feeds
HCM Extracts
Change detection for real-time sync
Full HCM data migration
HDL with full business object set
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.