Oracle Fusion REST API /describe Endpoint: Discovering Fields and Actions

Every Oracle Fusion REST resource carries more shape than any single doc page shows: which attributes exist, which ones you can actually set, what child resources hang off it, which finders it supports, and — for flexfield-bearing objects — segments that are different in every tenant because they were configured by whoever set up that instance. Oracle’s own documentation covers this, but it’s split across dozens of module-specific pages, and most integration write-ups skip it entirely and jump straight to a POST body copied from a blog post that may not match your tenant’s configuration. The /describe endpoint is how you ask the resource itself, on your own tenant, right now — instead of guessing from documentation for a different release.

All examples use an anonymized pod (acme.fa.us2.oraclecloud.com) and placeholder identifiers — swap in your own.

The basic request

Append /describe to any resource endpoint:

curl -u integration.user \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/describe"

The response is metadata, not data — no worker records come back, just the shape of the workers resource: its attributes, actions, child resources, and finders, as configured on your tenant right now.

metadataMode: full vs. list

By default /describe returns full metadata. If you only need the list of resource URLs without the attribute-level detail, add metadataMode=list:

curl -u integration.user \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/describe?metadataMode=list"

Use list when you’re mapping what’s available across a module; use the default (full) when you’re about to build a request against one specific resource and need to know its attributes, actions, and children.

What’s actually in the response

A full /describe response documents, per resource:

• Attributes — name, data type, and flags including whether it’s mandatory, updatable, and queryable
• Actions — custom operations beyond plain CRUD (the kind covered in our erpintegrations post, like submitESSJobRequest)
• Child resources — nested collections reachable from the parent
• Finders — named, parameterized lookups (see our finders guide for the general syntax)
• LOV (list-of-values) resources — where a field’s valid values come from

None of this is static across the whole product — it reflects what’s actually enabled and configured on the tenant you’re querying, which is the whole reason to call it instead of trusting a doc page written against a different release or a different customer’s configuration.

A real example: workers

The workers resource (GET /workers, GET /workers/{id}, PATCH /workers/{id}, POST /workers) has 307 queryable fields in its full shape and 3 finders — Employee (bind variable E), Worker (bind variable C), and Nonworker (bind variable N). Its /describe response also lists 20 child resources, including addresses, citizenships, disabilities, driverLicenses, emails, ethnicities, externalIdentifiers, legislativeInfo, messages, and names. You’d have to read through all of that by hand from the module-specific doc page to reconstruct the same picture /describe hands you in one call — see the full breakdown on our workers endpoint reference.

The FSCM invoices resource looks completely different: its /describe response lists child resources like invoiceDff, invoiceGdf, invoiceLines, invoiceInstallments, appliedPrepayments, availablePrepayments, and attachments, with 88 queryable fields (see the invoices reference). Same endpoint pattern, entirely different shape — which is exactly why calling /describe on the specific resource you’re integrating with beats generalizing from a different module’s example.

Discovering flexfield segments per tenant

This is where /describe stops being a convenience and becomes necessary. Descriptive flexfield (DFF) segment names — the actual attribute names inside a workersDFF or invoiceDff child resource — are configured per tenant and can’t be copied from any guide, including this one. Our DFF/EFF/DDF post covers the __FLEX_Context pattern in depth; the short version is that a GET on the DFF child resource’s /describe (or the child resource itself once you have a valid __FLEX_Context) is how you find out what segments exist on your instance before you try to PATCH one.

OpenAPI format

Metadata is also available in OpenAPI 3.0 format by requesting it with the appropriate Accept header:

curl -u integration.user \
  -H "Accept: application/vnd.oracle.openapi3+json" \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/describe"

This returns a full OpenAPI document for the resource — useful if you’re generating client code or importing the shape into tooling that consumes OpenAPI directly, rather than parsing Oracle’s native metadata format yourself.

Gotcha: describe output depends on REST-Framework-Version

Like every other part of the API, the shape /describe returns is tied to the REST-Framework-Version header on the request. Describe a resource without pinning the header and you may get the framework’s default version’s shape — not necessarily the one your integration code is actually built against. This is the same gotcha our Postman setup post flags for regular requests: pin the header explicitly, on describe calls too, so what you discover matches what you’ll actually call.

Practical workflow

/describe is metadata about a resource, not the resource’s data — call it once per resource per integration build-out, not on every request. A reasonable pattern:

1. Call /describe on the resource during development to confirm attributes, child resources, and finders against your actual tenant.
2. Cache that shape in your integration’s documentation or code comments — it won’t change on every deploy, only when Oracle ships a new release or someone reconfigures a flexfield.
3. Re-check after quarterly updates or after a functional team reports a flexfield or LOV change, since those are exactly the kind of tenant-specific configuration /describe exists to surface.

Common gotchas

• Treating /describe output as static across environments. Test and production instances can have different flexfield configurations — don’t assume dev’s /describe response matches prod’s.
• Skipping the REST-Framework-Version header on describe calls. The shape you discover should match the shape you’ll actually request against.
• Calling /describe on every request in production code. It’s a development-time discovery tool, not a runtime dependency — bake the shape into your integration once you’ve confirmed it.
• Assuming a doc page for a different release matches your tenant. Doc pages are versioned by release; your tenant’s actual configuration (especially flexfields) is the one source of truth, and /describe is how you read it.

Where this fits with everything else

/describe is the discovery step that should come before you write the request — it’s how you confirm the q filter fields that actually exist, the finders a resource supports, and the DFF segments configured on your tenant, instead of guessing from a guide written against someone else’s instance. For the rest of the request lifecycle — auth, base URLs, key endpoints — see the full Oracle Fusion API guide and the endpoint catalog.

---

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