DEV Community

Mostafa Mansour
Mostafa Mansour

Posted on • Originally published at opalapi.dev

"6 Oracle HCM REST API Requests I Copy-Paste Every Week"

#oracle #api #rest #tutorial

Oracle's HCM REST API docs describe every endpoint, but they rarely show a complete working request next to the response you'll actually get. Here are the six calls I reach for constantly — adapt the pod hostname (acme.fa.us2.oraclecloud.com) and credentials, everything else works as-is. All sample data is anonymized; Basic Auth for readability (use OAuth 2.0 in production).

Base URL for everything below:

https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05
Enter fullscreen mode Exit fullscreen mode

1. Get workers, paginated properly 

curl -u "integration.user@example.com:password" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=10"
Enter fullscreen mode Exit fullscreen mode

Always pass limit (default page size is 25, max 500). The response's hasMore: true tells you to keep going — increment offset until it flips to false.

2. One worker by person number with q 

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber='100001'"
Enter fullscreen mode Exit fullscreen mode

String values in q must be single-quoted; numbers don't. If you get "The query parameter is invalid", the field probably isn't queryable on that endpoint — workers alone has 307 queryable fields, and it's never all of them.

3. Range filter, URL-encoded once 

curl -u "user:pass" --get \
  --data-urlencode "q=PersonNumber>='100001' and PersonNumber<='100500'" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers"
Enter fullscreen mode Exit fullscreen mode

Two rules: and/or lowercase, and encode the expression exactly once (--data-urlencode does this). Double-encoding is the classic cause of silently empty results.

4. Finder instead of q — faster lookups 

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?finder=findByPersonId;PersonId=300000001234567"
Enter fullscreen mode Exit fullscreen mode

Syntax is finder=<name>;<bindVar>=<value> — semicolon, not &. Finders are pre-built indexed queries; findByPersonId beats the equivalent q filter every time. Bonus: findReports;ManagerPersonId=... answers "who reports to this manager" with zero assignment traversal.

5. Cut the payload with fields 

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber='100001'&fields=PersonId,PersonNumber,DateOfBirth"
Enter fullscreen mode Exit fullscreen mode

Routinely an 80–90% response-size cut on collections. The single easiest performance win in the whole API.

6. Inline child resources with expand 

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber='100001'&expand=names,workRelationships.assignments"
Enter fullscreen mode Exit fullscreen mode

Names, emails, and assignments are children — by default you only get links. Dot notation reaches nested children. Avoid expand=all on collections unless you enjoy timeouts.

The full post has 12 examples — including calling child collections directly, error responses (400/401/403) and what they actually mean, and pagination loops: Oracle HCM REST API Examples: 12 Real Requests You Can Copy.

I build OPAL, an offline Oracle Fusion API explorer — 59,000+ HCM/FSCM endpoints searchable without internet, with visual q filter and finder builders and a full endpoint reference.

Top comments (0)