Oracle HCM documentRecords REST API: Create, Upload, and Query Document Records

Document records are how Oracle HCM stores anything paper-shaped about a person — passports, visas, certifications, contracts, disciplinary letters. Every HR system migration and every onboarding integration eventually hits the same requirement: create a document record for a worker and attach the actual file. The REST resource that does this is documentRecords, and while the Oracle docs describe every endpoint, there is no end-to-end walkthrough of the flow developers actually need — create the record, attach the file, and get the file back out. This guide is that walkthrough, with working examples.

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

The resource at a glance

https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/documentRecords

In the real HCM spec, documentRecords is a big surface: 38 distinct paths. The ones that matter for integration work:

Path	What it does
POST /documentRecords	Create a document record (attachment can be inlined)
GET /documentRecords	List/filter records — 39 queryable q fields
GET /documentRecords/{DocumentsOfRecordId}	One record by its surrogate ID
.../child/attachments	Add or list file attachments on a record
.../child/attachments/{id}/enclosure/FileContents	Download the raw file bytes
POST /documentRecords/action/downloadAttachments	Bulk-download attachments
.../child/documentRecordsDFF / documentRecordsDDF	Descriptive / developer flexfields

The rest of the surface is UI-support machinery — access-check actions (checkManageAccess, checkViewAccess, and friends), attachment previews, banner messages — which you can ignore for a typical integration.

Authentication is standard Fusion REST — Basic Auth over TLS or an OAuth bearer token (see the authentication guide). Note that document records enforce document type security on top of API access: a 403 usually means the user’s profile can’t manage that document type for that person, not that your credentials are wrong.

Create a document record with an attachment in one call

The most common integration pattern — one POST that creates the record and inlines the file as base64:

curl -u '[email protected]:********' \
  -H 'Content-Type: application/json' \
  -X POST \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/documentRecords' \
  -d '{
    "PersonNumber": "100001",
    "DocumentType": "Passport",
    "Country": "United States",
    "DocumentNumber": "P100001",
    "IssuedDate": "2024-03-15",
    "IssuingAuthority": "U.S. Department of State",
    "DateFrom": "2024-03-15",
    "DateTo": "2034-03-14",
    "attachments": [
      {
        "DataTypeCode": "FILE",
        "FileName": "passport-100001.pdf",
        "UploadedFileContentType": "application/pdf",
        "FileContents": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
      }
    ]
  }'

Points that answer the recurring forum questions:

• FileContents is base64. Encode the file yourself (base64 -i passport.pdf) — do not send raw bytes or a URL.
• Identify the person with PersonNumber or PersonId — one of them is required; PersonNumber is usually what your source system has.
• DocumentType is the display name of a document type your pod has configured (Manage Document Types in setup). If the type is country-specific, pass Country too, or you’ll get a “document type not found” style error even though the type exists.
• Assignment-level types additionally need AssignmentNumber (or AssignmentId) — the spec exposes both on the create payload.
• A successful create returns the record with its DocumentsOfRecordId — keep it; every child call needs it.

Document records are not date-effective objects — DateFrom/DateTo here are plain validity attributes of the document, so no Effective-Of header gymnastics are needed (unlike workers and assignments).

Add an attachment to an existing record

If the record already exists, POST to the attachments child:

curl -u '[email protected]:********' \
  -H 'Content-Type: application/json' \
  -X POST \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/documentRecords/300000001234567/child/attachments' \
  -d '{
    "DataTypeCode": "FILE",
    "FileName": "passport-renewal-100001.pdf",
    "UploadedFileContentType": "application/pdf",
    "Title": "Passport renewal 2026",
    "FileContents": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
  }'

300000001234567 is the DocumentsOfRecordId from the create response. A record can hold multiple attachments, and each one gets an AttachedDocumentId of its own.

Query document records with q

The collection GET declares 39 queryable fields in the spec — enough to filter by person, type, validity window, or issuing details without downloading everything. The workhorses are PersonNumber, PersonId, DocumentType, DocumentTypeId, DocumentNumber, Country, DateFrom, DateTo, IssuedDate, IssuingAuthority, and CreationDate.

All passports for one worker:

curl -u '[email protected]:********' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/documentRecords?q=PersonNumber='\''100001'\'' and DocumentType='\''Passport'\''&onlyData=true'

Documents expiring in the next 90 days (a classic compliance report):

curl -u '[email protected]:********' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/documentRecords?q=DateTo>='\''2026-07-19'\'' and DateTo<='\''2026-10-17'\''&orderBy=DateTo&onlyData=true'

The q syntax rules are the same as everywhere else in Fusion — quote text and dates, don’t quote numbers, URL-encode the whole expression in real code; the q parameter guide covers the traps. Responses page at 25 rows by default like every Fusion collection — loop on hasMore per the pagination guide.

Download the file back

Attachments expose the raw bytes through an enclosure link, not a JSON field. First list the attachments:

curl -u '[email protected]:********' \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/documentRecords/300000001234567/child/attachments'

Each item’s links array contains a rel: "enclosure" entry named FileContents. GET that URL and you receive the file itself (with its real content type), not JSON:

curl -u '[email protected]:********' -o passport.pdf \
  'https://acme.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/documentRecords/300000001234567/child/attachments/00020000.../enclosure/FileContents'

The attachment ID in that URL (attachmentsUniqID) is a long hash-style key from the links — always follow the link the API gives you rather than constructing it.

For bulk exports there is also POST /documentRecords/action/downloadAttachments, which the Person Document Records UI uses for mass download — for most integrations, iterating the enclosure links is simpler and easier to restart.

Flexfields, if you use them

Customer-defined attributes on document records live in two child resources: documentRecordsDFF (descriptive flexfields) and documentRecordsDDF (developer descriptive flexfields, used by localization). They behave like any other Fusion DFF child — GET them under the record, and include them on create by nesting the child array in the POST payload. If your pod has legislative document data (visa details vary by LegislationCode), it will surface through the DDF.

Common errors

• 400 “invalid document type” — the DocumentType string doesn’t match a configured type visible to the calling user, or a country-specific type was used without Country.
• 403 on create with working credentials — document type security: the user’s document type access (person security profile) excludes this type. Fix the security profile, not the API call.
• Attachment created but empty file — FileContents wasn’t valid base64, or the JSON layer mangled it. Encode without line wrapping (base64 -w 0 on Linux).
• 404 on the enclosure URL — you built the attachment URL by hand; list the attachments and follow the returned enclosure link instead.

Seeing the full endpoint surface

Everything above uses paths and field names straight from the real Oracle HCM spec — 38 paths and 39 q fields on this one resource, and knowing they exist is most of the battle. You can browse the whole HCM and FSCM surface — every q field, finder, and child resource — in our endpoint reference, and the HCM examples post covers the same request patterns against workers. And if you need these uploads surfaced natively in the Redwood UI instead of via REST — for example a passport copy on Identification Info — see our passport attachments configuration guide and the passport + DOR transaction deep dive.

---

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