Oracle Fusion REST API Child Resources and expand Explained

Oracle Fusion REST APIs are built around parent and child resources.

This design is powerful, but it also causes many common integration issues:

expand returns too much data.
q does not filter nested child records.
Attachment links work in one tool but fail in another.
A child endpoint requires IDs that are not obvious from the UI.
Developers are not sure whether to call the parent endpoint or the child endpoint directly.

This article explains how child resources work in Oracle Fusion REST APIs and how to troubleshoot them correctly.

What is a child resource?

A child resource is a REST resource that belongs under a parent resource.

For example, a worker can have work relationships. A work relationship can have assignments.

Conceptually:

workers
  └── workRelationships
        └── assignments

In REST path format, that can look like:

/hcmRestApi/resources/11.13.18.05/workers/{workersUniqID}/child/workRelationships

and then:

/hcmRestApi/resources/11.13.18.05/workers/{workersUniqID}/child/workRelationships/{workRelationshipsUniqID}/child/assignments

The parent resource and child resource are separate API levels. This matters a lot when filtering data.

What does expand do?

The expand parameter asks Oracle Fusion REST to include related child data in the response.

Example:

GET /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber='10001'&expand=workRelationships

This returns the worker and includes work relationships in the same response.

You may also see deeper expansion:

GET /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber='10001'&expand=workRelationships.assignments

This can be useful for reading related data in one call.

But expand is not the same as child-level filtering.

The common mistake: expecting q to filter expanded child data

Many developers expect this logic:

Get workers
Expand assignments
Filter assignments where AssignmentStatusType = ACTIVE

So they try something like:

GET /hcmRestApi/resources/11.13.18.05/workers?q=AssignmentStatusType='ACTIVE'&expand=workRelationships.assignments

The problem is that /workers is the parent resource. The q filter is applied at the worker level, not necessarily at the nested assignment level.

If AssignmentStatusType is a field on the assignment child resource, the parent worker resource may not allow it in q.

The result is usually one of these:

Invalid query parameter.
The filter is ignored.
The parent is filtered, but child rows still include extra data.
You receive more assignment records than expected.

How to fix child filtering issues

If you need to filter child data, call the child endpoint directly.

For example, instead of trying to filter assignments through /workers, first get the worker, then call the assignment child resource.

Example flow:

Step 1: Find the worker

GET /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber='10001'

Step 2: Get work relationships

GET /hcmRestApi/resources/11.13.18.05/workers/{workersUniqID}/child/workRelationships

Step 3: Get assignments and filter at the assignment level

GET /hcmRestApi/resources/11.13.18.05/workers/{workersUniqID}/child/workRelationships/{workRelationshipsUniqID}/child/assignments?q=AssignmentStatusType='ACTIVE'

This is more API work, but it applies the filter where the field actually exists.

When expand is still useful

expand is useful when:

You want a quick full view of related data.
The child data volume is small.
You are doing analysis or debugging.
You need links to child resources.
You want to inspect available child records before building the final integration.

expand is not ideal when:

The child data is large.
You need strict child-level filtering.
You need pagination on child data.
You only need one specific child record.
The expanded payload becomes too large or slow.

Example: Invoice attachments

Attachments are a common child resource in Fusion Financials.

A request may look like:

GET /fscmRestApi/resources/11.13.18.05/invoices?q=InvoiceNumber='INV-1001'&expand=attachments

The response may include attachment links such as:

/fscmRestApi/resources/11.13.18.05/invoices/{invoiceId}/child/attachments/{attachmentId}

and file content links such as:

/fscmRestApi/resources/11.13.18.05/invoices/{invoiceId}/child/attachments/{attachmentId}/enclosure/FileContents

If the file download link works in Postman but fails in another tool, compare:

The exact generated URL.
The Accept header.
Authentication context.
REST-Framework-Version header.
Whether the client is rewriting the resource path.
Whether the attachment ID is encoded correctly.

A 404 from an agent or workflow tool does not always mean the attachment does not exist. It may mean the tool is calling a different path than the one you tested manually.

Example: Purchase Orders and DFF child data

Purchase Orders can expose complex structures, including descriptive flexfields and draft document resources.

If you can update a value in the Fusion UI but a REST API returns 403 Forbidden, the problem is often not the endpoint structure alone.

Check:

Does the REST user have the required role?
Does the user have data access to the Procurement BU?
Is the user set up as a procurement agent if required?
Are you using the draft resource when updating draft POs?
Are you sending the DFF segment in the correct request body structure?

OPAL or another REST client can help confirm the endpoint and body shape, but missing privileges must be fixed in Fusion security.

Example: Document Records child resources

Document Records can include child resources such as flexfield data, attachments, and workflow-related banner messages.

A common pattern is:

GET /hcmRestApi/resources/11.13.18.05/documentRecords?finder=findByPersonId;PersonId=300000123456789&expand=all

This can be helpful for analysis, but expand=all may return a large payload.

For production integrations, it is usually better to request only the child resource you need.

Why child resource IDs look strange

Oracle Fusion child resource URLs often use internal unique IDs. These IDs may not match the business number you see in the UI.

For example:

workersUniqID
workRelationshipsUniqID
attachmentsUniqID

These values are usually returned in the parent response links.

Do not try to manually build child URLs from UI values unless the documentation clearly says the path expects that value.

The safest method is:

Call the parent resource.
Read the links section.
Use the child link returned by Oracle.
Add filters only after confirming the child resource supports them.

Child resource troubleshooting checklist

When a child resource call fails, check this:

Is the parent endpoint correct?
Did you retrieve the correct parent unique ID?
Are you using the child link returned by Oracle?
Is the child name correct?
Are you filtering at the correct resource level?
Are you using expand only for reading, not assuming it filters children?
Does the user have access to the child resource data?
Are headers the same between tools?
Is the REST-Framework-Version header different?
Is the path encoded correctly?

Should you use resources/latest or a fixed version?

You may see paths like:

/hcmRestApi/resources/latest/workers

or:

/hcmRestApi/resources/11.13.18.05/workers

For development and documentation discovery, latest can be convenient.

For production integrations, many teams prefer fixed paths because they make behavior easier to test and control.

Whatever you choose, use the same version consistently when comparing results across Postman, OPAL, Oracle Integration, Workflow, or AI Agent tools.

How OPAL helps

OPAL makes parent and child resource exploration easier.

You can use it to:

Search for the parent endpoint.
See available child resources.
Inspect q fields and finders.
Test expand behavior.
Compare headers and response links.
Validate the endpoint before moving to Postman, OIC, Workflow, or AI Agent Studio.

This is useful for large resources such as Workers, Invoices, Purchase Orders, Document Records, Learning, and Procurement APIs.

Download OPAL here:

https://opalapi.dev

Final recommendation

Use expand for exploration and small related payloads.

Use child endpoints when you need accurate filtering, paging, or direct access to nested records.

Most Oracle Fusion REST child resource problems become easier once you stop treating the response as one flat object and start thinking in parent-child API levels.

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.