Oracle Fusion REST API Descriptive Flexfields (DFF): Reading and Writing Segments

Almost every object in Oracle Fusion — workers, invoices, positions, document records, credit memos — ships with a flexfield: a set of extra attributes your implementation configured that don’t exist in the base schema. Over REST, flexfields show up as their own child resource with their own quirks (a special __FLEX_Context field, segments that change depending on that context, and 400 errors that make no sense until you understand why). Every search result for this today is Oracle’s own reference documentation — module by module, endpoint by endpoint, with no practical walkthrough of the pattern itself. This is that walkthrough.

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

Three kinds of flexfield, one REST pattern

Fusion has three flexfield types that all follow the same child-resource shape over REST, with different behavior:

• DFF (Descriptive Flexfield) — single row per parent, context-driven: which segments are visible/required depends on the value of a context field. This is the common case — workersDFF, invoiceDff, receivablesCreditMemoDFF.
• EFF (Extensible Flexfield) — like a DFF but supports multiple rows per category, used where an object can have several sets of extra attributes at once (workersEFF).
• DDF (Developer Descriptive Flexfield) — used mainly for localization/legislative attributes, seeded by Oracle rather than freely configured (documentRecordsDDF carries country-specific document data, for example).

All three are exposed as a child resource on their parent, named after the pattern <parent>DFF / <parent>EFF / <parent>DDF. Real examples from the catalog: workers → workersDFF + workersEFF, invoices (FSCM) → invoiceDff, receivablesCreditMemos → receivablesCreditMemoDFF + receivablesCreditMemoTransactionDFF, documentRecords → documentRecordsDFF + documentRecordsDDF, positions → PositionCustomerFlex, jobs → JobCustomerFlex.

Why you can’t copy segment names from a blog post

This is the part every generic guide skips, and the reason Oracle’s own docs read the way they do: segment names are configured per tenant. Two Fusion pods running the same module can have completely different DFF segments, because an administrator built them in the Flexfields task in Setup and Maintenance. There is no universal CustomAttribute1 you can rely on — what exists on your pod is whatever your implementation team defined. That’s exactly why the practical challenge is discovery, not memorization.

Discovering what’s configured: GET the DFF child

Before writing anything, GET the flexfield child resource under a real parent record to see the shape you’re working with:

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

A populated response looks like:

{
  "items": [
    {
      "PersonId": 300000001234567,
      "__FLEX_Context": "Global Data Elements",
      "__FLEX_Context_DisplayValue": "Global Data Elements",
      "links": [ ... ]
    }
  ],
  "count": 1,
  "hasMore": false
}

__FLEX_Context is the field that determines which segment set is active. If your pod has segments configured for this context, they appear as additional attributes alongside it — named whatever your implementation called them. If the row is empty aside from the context, no values have been entered yet, not that no segments exist.

The describe endpoint: structure without a populated row

If no record has flexfield data yet, or you need the full attribute list (including type and required-ness) before you build a payload, use /describe on the resource:

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

The response includes the DFF/EFF child definitions with their available contexts and, per context, the segment attributes and data types — this is the authoritative source for “what fields exist,” not a sample payload from any guide (including this one).

Creating a record with flexfield segments

Once you know the active context and its segment names for your tenant, nest the DFF child array in the parent POST — same pattern used on documentRecords:

curl -u integration.user -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "PersonNumber": "100001",
    "workersDFF": [
      {
        "__FLEX_Context": "Global Data Elements",
        "CustomField1": "Value1"
      }
    ]
  }' \
  "https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers"

CustomField1 here stands in for whatever your tenant’s admin named the segment — confirm it against your own /describe response, not this example. Updating an existing row is a PATCH to the DFF child’s own URL (.../child/workersDFF/{contextId}), same as any other child resource.

Why a valid-looking payload still 400s

This is the recurring integration bug with flexfields specifically:

• Wrong or stale context. You send __FLEX_Context: "Global Data Elements" but the segment you’re setting only exists under a different context on your pod (say, a country-specific one) — Oracle rejects the unrecognized attribute.
• Segment required under one context, absent under another. Contexts don’t just add fields, they can make a segment mandatory that was optional (or absent) elsewhere — a payload that worked for one worker can 400 for another if their applicable context differs.
• Copy-pasted segment names from documentation or another tenant. The single most common flexfield bug: a name that’s real on a training/demo pod but doesn’t exist on production, because someone else configured it.
• Case and exact match on __FLEX_Context. The context value must match the configured name exactly, including its display casing — it’s compared as data, not normalized.
• EFF rows without the category key. Extensible flexfields group segments by category as well as context; omitting the category attribute alongside __FLEX_Context on an EFF child produces a different error than the DFF case, easy to conflate if you haven’t hit both.

Where this fits with everything else

Flexfields are additive to the base resource — they don’t change how q filters or finders work against the parent’s standard fields, and ETag/If-Match concurrency applies to flexfield child updates the same as any other PATCH. You’ll hit this pattern on HCM objects (workers, document records) and FSCM objects (invoices, receivables credit memos) alike — for full request walkthroughs on each, see the HCM REST API examples post and the FSCM REST API guide. The endpoint catalog lists which child resources — DFF, EFF, or otherwise — exist on each of the top HCM and FSCM endpoints, including workers, invoices, and receivables credit memos.

---

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