Oracle HCM REST API Effective Dates: The Effective-Of Header Explained

Almost every core HR object in Oracle Fusion HCM is date-effective: workers, assignments, salaries, locations, grades. Each logical record is stored as a series of rows, and every row carries an effectiveStartDate and effectiveEndDate. The REST API hides this until it suddenly matters — a GET returns data you know is “wrong” (it’s just the current-dated row), or a PATCH silently rewrites history instead of inserting a change. The switch that controls all of this is the Effective-Of HTTP header, and it is one of the least-documented parts of the HCM REST API in practical terms.

This guide covers reading date-effective data (as-of a date, and across a range) and writing it (update vs correction), with curl examples. All examples use an anonymized pod (acme.fa.us2.oraclecloud.com) and placeholder identifiers — swap in your own.

How date-effective storage works

Say worker 100001 moved departments on 2026-03-01. In the database that’s two assignment rows:

Row	effectiveStartDate	effectiveEndDate	Department
1	2023-05-15	2026-02-28	Support
2	2026-03-01	4712-12-31	Engineering

4712-12-31 is Oracle’s “end of time.” A plain GET returns only the row effective today — history and future-dated rows are invisible unless you ask for them.

That default explains two classic surprises:

• A worker with a future-dated hire returns nothing from GET /workers until the hire date arrives.
• A GET after a retroactive change shows the new values, and you can’t see what the record looked like before — unless you query as-of a date.

Reading: as-of a date

To read the record as it was (or will be) on a specific date, send Effective-Of with a RangeStartDate:

curl -u '[email protected]:YourPassword' \
  -H 'Effective-Of: RangeStartDate=2025-06-01' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber=100001'

The response contains the row(s) effective on 2025-06-01 — in the example above, the Support-department assignment. Dates are always yyyy-MM-dd strings, and multiple header parameters are separated with semicolons.

Reading: a date range

To pull the full change history between two dates, pass both ends of the range:

curl -u '[email protected]:YourPassword' \
  -H 'Effective-Of: RangeStartDate=2023-01-01;RangeEndDate=2026-12-31' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber=100001'

Now the collection includes every date-effective row that overlaps the range, each with its own effectiveStartDate/effectiveEndDate pair. This is the pattern for building audit views or syncing history into a downstream system — one call instead of probing date by date.

The header accepts six parameters in total: RangeMode, RangeSpan, RangeStartDate, RangeEndDate, RangeStartSequence, and RangeEndSequence. For reads you mostly need the two dates; the sequences matter only when multiple changes share the same day.

Writing: UPDATE vs CORRECTION

This is where the header stops being optional. When you PATCH a date-effective resource, RangeMode decides whether Oracle inserts a new row or rewrites an existing one:

RangeMode	What it does	Use when
UPDATE	Inserts a new date-effective row starting at RangeStartDate; the previous row is end-dated the day before	A real change happened (transfer, salary change) and history must be preserved
CORRECTION	Overwrites the row effective on RangeStartDate in place — no new row, history is replaced	The existing row was simply wrong (typo, wrong department entered)

A date-tracked update — worker moves to a new location on 2026-08-01:

curl -u '[email protected]:YourPassword' -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'Effective-Of: RangeMode=UPDATE;RangeStartDate=2026-08-01' \
  -d '{"LocationCode": "HQ_LONDON"}' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED.../child/workRelationships/.../assignments/...'

A correction — the location on the current row was entered wrong and should be fixed as if it had always been HQ_LONDON:

curl -u '[email protected]:YourPassword' -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'Effective-Of: RangeMode=CORRECTION;RangeStartDate=2026-03-01' \
  -d '{"LocationCode": "HQ_LONDON"}' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED.../child/workRelationships/.../assignments/...'

Same payload, different history. Pick CORRECTION when UPDATE was intended and you’ll create a spurious extra row; pick UPDATE when CORRECTION was intended and you’ll silently destroy the audit trail. Integrations that sync HR changes should almost always use UPDATE.

RangeMode has further values for advanced surgery on the row series — including REPLACE_UPDATE, REPLACE_CORRECTION, RECONCILE_UPDATE, RECONCILE_CORRECTION, and ZAP (remove all changes) — but UPDATE and CORRECTION cover the overwhelming majority of integration work. Test anything beyond those two in a sandbox pod first: they rewrite row series in ways that are hard to undo.

Common errors and gotchas

• “The effective start date is not valid” on POST /workers — the payload’s effective date conflicts with the object’s existing rows (for a new hire, dates in child objects must align with the hire date).
• PATCH succeeds but nothing changed as of today — you updated with a future RangeStartDate; the new row exists but isn’t effective yet. Read it back with an as-of-date GET.
• Missing header on a date-effective PATCH — some resources reject the request, others apply a default you didn’t intend. Always send Effective-Of explicitly on writes.
• Date format — yyyy-MM-dd only. Timestamps or locale formats fail.
• Not every resource is date-effective — plain resources (documents of record, many FSCM objects) ignore the header entirely.

Finding out which fields you can actually change

The header tells Oracle when; the harder daily question is what — which attributes an endpoint exposes, which are patchable, and which q fields can locate the record. The workers endpoint alone has 307 queryable fields and 20 child resources — browsable offline in OPAL’s workers reference page, along with the rest of the endpoint catalog. For end-to-end request walkthroughs (auth, pagination, expand), see the HCM REST API examples post.

---

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