Oracle HCM REST API Examples: 12 Real Requests You Can Copy

Oracle’s HCM REST API documentation describes every endpoint, but it rarely shows you a complete, working request next to the response you’ll actually get back. This post collects 12 real examples you can adapt directly — from a basic workers call to filtered queries, finders, field projection, child resource expansion, and the error responses you’ll hit along the way.

All examples use Basic Auth for readability. In production, use OAuth 2.0. Replace acme.fa.us2.oraclecloud.com with your pod’s hostname, and note that all sample data below is anonymized.

The base URL for every example:

https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05

1. Get all workers (paginated)

The simplest possible call. Always pass limit — the default page size is 25 and unbounded calls against large worker populations are slow.

curl -u "[email protected]:password" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=10"

Response shape (trimmed):

{
  "items": [
    {
      "PersonId": 300000001234567,
      "PersonNumber": "100001",
      "DateOfBirth": "1990-04-12",
      "links": [ ... ]
    }
  ],
  "count": 10,
  "hasMore": true,
  "limit": 10,
  "offset": 0
}

hasMore: true tells you there are more pages — see example 9.

2. Get 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'"

String values in q must be wrapped in single quotes. Numeric comparisons don’t need quotes. If your q filter fails with “The query parameter is invalid”, the field is probably not queryable on this endpoint — here’s how to check and fix it.

3. Filter workers by multiple conditions

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"

Two things matter here: and/or must be lowercase, and the whole expression must be URL-encoded exactly once (--data-urlencode handles this). Double-encoding is one of the most common causes of silent empty results — see the q + expand troubleshooting guide.

4. Look up a worker with a finder

Finders are pre-built, indexed queries. findByPersonId on workers is much faster than an equivalent q filter:

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

Note the syntax: finder=<name>;<bindVar>=<value> — semicolon between finder name and bind variables, not &. The workers endpoint has 3 finders (PrimaryKey, findByPersonId, findReports); the full list with bind variables is on the workers endpoint reference page. More on finder syntax and discovering bind variables in the finders guide.

5. Reduce payload size with `fields`

The workers resource returns dozens of attributes by default. Project only what you need:

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

On large collections this routinely cuts response size by 80–90% and is the single easiest performance win.

6. Expand child resources inline

Names, emails, and assignments are child resources of workers — by default you only get links to them. expand inlines them:

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

Nested children use dot notation (workRelationships.assignments). Avoid expand=all on collection calls — it explodes response time. Full details in the child resources and expand guide.

7. Get a worker’s email addresses (child resource directly)

Instead of expanding, you can call the child collection itself using the parent’s composite key from the links array:

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED.../child/emails"

The hash after /workers/ is the system-generated composite key returned in links[].href — don’t try to construct it yourself; always read it from a previous response.

8. Get direct reports with `findReports`

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?finder=findReports;ManagerPersonId=300000001234567"

This is the clean way to answer “who reports to this manager” — no assignment traversal needed. A complete worked flow (user → worker → manager) is in this walkthrough.

9. Paginate through a large result set

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?limit=500&offset=1000&onlyData=true"

Loop while hasMore is true, incrementing offset by limit. onlyData=true strips the links arrays and shrinks pages dramatically. Oracle caps limit at 500 for most HCM resources.

10. Sort results

curl -u "user:pass" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?orderBy=PersonNumber:desc&limit=25"

orderBy takes field:asc or field:desc, comma-separated for multiple sort keys. Only some fields are sortable — like queryability, this is defined per endpoint in the OpenAPI spec.

11. Update a worker attribute with PATCH

curl -u "user:pass" -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"names": [{"DisplayName": "Alex Example"}]}' \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED..."

PATCH updates only the fields you send. The Content-Type header is mandatory — omitting it returns a 415. Writes require the corresponding HCM duty role on the integration user; a valid token without the role returns 403, not 401.

12. The error responses you will actually see

Status	Typical cause	Fix
400 `The query parameter is invalid`	Field in `q` isn’t queryable, or bad syntax	Check queryable fields for the endpoint; quote strings
401	Wrong credentials or expired token	Re-authenticate
403	User lacks the REST duty privilege for this resource	Assign e.g. “Use REST Service – Workers” and regenerate grants
404	Wrong resource path or composite key	Read keys from `links`, never construct them
415	Missing `Content-Type: application/json` on POST/PATCH	Add the header
429	Rate limit exceeded	Back off; batch reads with `fields` + `limit`

Finding what’s queryable before you test

Every example above depends on knowing which fields an endpoint actually supports for q, orderBy, and finder — and that information is buried in a 200MB OpenAPI spec. The workers endpoint alone has 307 queryable fields and 20 child resources. OPAL bundles the full HCM and FSCM catalogs offline and searchable, so you can check an endpoint’s q fields, finders, and children in seconds before sending a single request — start with the workers reference or browse all endpoint references.

This post is part of our complete Oracle HCM API guide — base URLs, authentication, q filters, finders, key endpoints, and common errors in one place.