Oracle Fusion REST API Finders Explained

Oracle Fusion REST APIs support two common ways to retrieve filtered data:

The q parameter.
Named finders.

Many developers start with q, because it looks simple. But in many Oracle Fusion APIs, a finder is the better option because Oracle has already defined a specific search pattern for the resource.

If you have seen requests like this:

GET /hcmRestApi/resources/11.13.18.05/workers?finder=findByPersonId;PersonId=300000123456789

then you have already seen a finder.

This article explains what finders are, when to use them, and how to troubleshoot finder errors.

What is a finder in Oracle Fusion REST APIs?

A finder is a named search method exposed by an Oracle Fusion REST resource.

Instead of writing a free-form filter with q, you call a predefined finder and pass its expected parameters.

The format usually looks like this:

finder=FinderName;Parameter1=value1;Parameter2=value2

Example:

GET /hcmRestApi/resources/11.13.18.05/workers?finder=findByPersonId;PersonId=300000123456789

The resource decides what the finder does internally.

That means a finder can be more reliable than trying to guess which fields are queryable through q.

Finder vs q parameter

The q parameter is useful when you need a simple filter on supported queryable fields.

Example:

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

A finder is useful when Oracle provides a predefined search path.

Example:

GET /hcmRestApi/resources/11.13.18.05/workers?finder=findByPersonId;PersonId=300000123456789

The difference is important:

Feature	q parameter	Finder
Style	Free-form filter	Predefined search method
Parameters	Field/operator/value	Named parameters
Flexibility	More flexible when supported	More controlled
Best for	Simple filters	Known business searches
Common issue	Field not queryable	Missing or wrong finder parameter

In practice, you should check both. Some problems are easier with q, others are easier with a finder.

Basic finder syntax

The basic format is:

?finder=FinderName;ParameterName=ParameterValue

Example:

GET /hcmRestApi/resources/11.13.18.05/workers?finder=findByPersonId;PersonId=300000123456789

For multiple parameters:

GET /fscmRestApi/resources/11.13.18.05/invoices?finder=FinderName;BusinessUnit=Vision Operations;InvoiceNumber=INV-1001

Always URL encode values that contain spaces or special characters.

For example:

Vision Operations

should become:

Vision%20Operations

Common finder mistakes

1. Wrong finder name

Finder names are not always obvious.

This will fail if the finder does not exist:

?finder=findByInvoiceNumber;InvoiceNumber=INV-1001

Even if the name looks logical, it must match the finder exposed by that endpoint.

Fix

Check the resource metadata and copy the exact finder name.

2. Missing required parameter

Some finders require specific parameters.

For example:

?finder=findByPersonId

This is incomplete because the finder expects PersonId.

Correct:

?finder=findByPersonId;PersonId=300000123456789

Fix

Check all required finder parameters before testing.

3. Wrong parameter name

Finder parameters also have exact names.

This may fail:

?finder=findByPersonId;personId=300000123456789

Correct:

?finder=findByPersonId;PersonId=300000123456789

The casing matters.

Fix

Use the exact parameter name from the metadata.

4. Wrong value type

If the finder expects an internal ID, do not pass the display value.

For example, a finder may expect:

PersonId=300000123456789

not:

PersonNumber=10001

Or it may expect a business unit ID instead of a business unit name.

Fix

Confirm whether the finder expects an ID, code, name, or number.

5. Spaces are not encoded

This is a common problem in Financials, Procurement, and SCM APIs.

Bad:

?finder=FinderName;BusinessUnit=Vision Operations

Better:

?finder=FinderName;BusinessUnit=Vision%20Operations

Fix

URL encode finder values, especially names with spaces, commas, slashes, or ampersands.

Example: Workers finder

A common HCM pattern is to retrieve worker data by person ID:

GET /hcmRestApi/resources/11.13.18.05/workers?finder=findByPersonId;PersonId=300000123456789

This is useful when you already have the internal PersonId from another API call or from Fusion data.

If you only have the worker number, a q filter may be better:

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

The best choice depends on the identifier you have.

Example: Document Records finder

Document Records often require person-level searches.

A typical pattern is:

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

Then you can combine the result with expand when needed:

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

Use this carefully because expand=all can return a large payload.

Example: Finder with child resources

Some resources expose child endpoints after you retrieve the parent.

For example:

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

Then:

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

In this case, a parent finder may help you reach the correct worker first, but assignment filtering may still need to happen at the assignment child endpoint.

Why a finder may return 400 Bad Request

A finder request often returns 400 Bad Request when:

The finder name is wrong.
A required parameter is missing.
The parameter name is wrong.
The parameter value is not encoded.
The value type is wrong.
The endpoint version does not expose that finder.
The user does not have access to the data returned by the finder.

The response message is not always clear, so it helps to reduce the request to the simplest possible finder call first.

Finder troubleshooting checklist

Use this checklist when a finder does not work:

Confirm the endpoint path.
Confirm the finder exists on that endpoint.
Copy the exact finder name.
Check the required parameters.
Copy the exact parameter names.
Confirm whether the value should be an ID, code, name, or number.
URL encode values with spaces or special characters.
Test one finder parameter at a time if optional parameters exist.
Compare the same request in another REST client.
Check whether your user has data access for the returned record.

Should you use latest or a fixed version?

Oracle Fusion APIs often appear with paths like:

/hcmRestApi/resources/latest/workers

or:

/hcmRestApi/resources/11.13.18.05/workers

For long-term integrations, many teams prefer a fixed version path because it makes testing and behavior easier to control.

For discovery or quick testing, latest can be useful.

The important point is to test the same path you plan to use in production.

How OPAL helps

Finder discovery is difficult when you rely only on documentation pages.

OPAL makes this easier by indexing Oracle Fusion REST metadata and showing available finders, parameters, endpoint paths, child resources, and request options in one place.

You can use OPAL to:

Search for a REST resource.
Check which finders are available.
Inspect finder parameter names.
Compare finder options with q filters.
Test the request against your Fusion environment.

Download OPAL here:

https://opalapi.dev

Final recommendation

Use q when you need a simple supported filter.

Use finders when Oracle exposes a named search method for the business object.

If a finder fails, do not keep changing the payload randomly. Check the metadata first, confirm the exact finder name and parameters, then test the smallest possible request.

That approach will save time and make your Fusion REST API testing much more predictable.

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.