Oracle HCM User Management API Guide

Auth method: OAuth 2.0 (3-legged and 2-legged/JWT) or HTTP Basic Auth (for development/testing only)

Setup steps

1. In Oracle Identity Cloud Service (IDCS) or Oracle Cloud Infrastructure IAM, register a confidential application to obtain client_id and client_secret.
2. Grant the application the required HCM REST API scopes (e.g., urn:opc:resource:consumer::all or specific HCM scopes).
3. Configure the trusted application in HCM: Navigator > Setup and Maintenance > Manage OAuth Client Registrations.
4. Obtain an access token via the IDCS token endpoint: POST https://.identity.oraclecloud.com/oauth2/v1/token with grant_type=client_credentials (2-legged) or authorization_code (3-legged).
5. Include the Bearer token in the Authorization header for all HCM REST API calls.
6. For SCIM provisioning, configure the SCIM client (Okta, Azure AD) using the HCM SCIM endpoint and OAuth credentials.

Required scopes

List Workers

• Method: GET
• URL: /hcmRestApi/resources/latest/workers
• Watch out for: The workers resource returns effective-dated records. Without specifying effectiveDate, the API returns the current effective record. Use ?effectiveDate=YYYY-MM-DD to query historical or future states.

Request example

GET /hcmRestApi/resources/latest/workers?limit=25&offset=0&expand=all
Authorization: Bearer <token>

Response example

{
  "items": [
    {"PersonId": 300000012345678, "PersonNumber": "EMP001",
     "DisplayName": "Jane Doe", "WorkEmail": "jane.doe@example.com"}
  ],
  "count": 1, "hasMore": false, "limit": 25, "offset": 0
}

Get Single Worker

• Method: GET
• URL: /hcmRestApi/resources/latest/workers/{PersonId}
• Watch out for: Child resources (Names, Emails, Assignments) are not returned by default. Use ?expand=names,emails,workRelationships to include them.

Request example

GET /hcmRestApi/resources/latest/workers/300000012345678?expand=all
Authorization: Bearer <token>

Response example

{
  "PersonId": 300000012345678,
  "PersonNumber": "EMP001",
  "DisplayName": "Jane Doe",
  "WorkEmail": "jane.doe@example.com",
  "StartDate": "2022-01-15"
}

Create Worker (New Hire)

• Method: POST
• URL: /hcmRestApi/resources/latest/workers
• Watch out for: Worker creation does NOT automatically create an HCM application user account. A separate call to /users or the Autoprovision Users process is required to create login credentials.

Request example

POST /hcmRestApi/resources/latest/workers
Content-Type: application/json
{
  "EffectiveStartDate": "2024-06-01",
  "PersonTypeCode": "EMP",
  "names": [{"FirstName":"John","LastName":"Smith","NameType":"GLOBAL"}],
  "emails": [{"EmailAddress":"john.smith@example.com","EmailType":"W1"}]
}

Response example

{
  "PersonId": 300000099887766,
  "PersonNumber": "EMP002",
  "DisplayName": "John Smith",
  "EffectiveStartDate": "2024-06-01"
}

Update Worker

• Method: PATCH
• URL: /hcmRestApi/resources/latest/workers/{PersonId}
• Watch out for: PATCH creates a new effective-dated row. You must supply EffectiveStartDate for the change. Omitting it defaults to today, which may overwrite existing future-dated records.

Request example

PATCH /hcmRestApi/resources/latest/workers/300000099887766
Content-Type: application/json
{
  "EffectiveStartDate": "2024-07-01",
  "EffectiveSequence": 1
}

Response example

{
  "PersonId": 300000099887766,
  "EffectiveStartDate": "2024-07-01",
  "EffectiveEndDate": "4712-12-31"
}

List Application Users

• Method: GET
• URL: /hcmRestApi/resources/latest/users
• Watch out for: The /users resource manages HCM application user accounts (login/roles), not the person/worker record. These are distinct resources.

Request example

GET /hcmRestApi/resources/latest/users?limit=50&offset=0
Authorization: Bearer <token>

Response example

{
  "items": [
    {"UserId": 100000012345, "Username": "john.smith",
     "PersonId": 300000099887766, "UserGUID": "abc123-...",
     "ActiveFlag": true}
  ],
  "count": 1
}

Provision Roles to User

• Method: POST
• URL: /hcmRestApi/resources/latest/users/{UserId}/roles
• Watch out for: Role names must match exactly as configured in HCM. Incorrect RoleNamespace values silently fail or return a generic error.

Request example

POST /hcmRestApi/resources/latest/users/100000012345/roles
Content-Type: application/json
{
  "RoleName": "Employee",
  "RoleNamespace": "oracle.apps.hcm"
}

Response example

{
  "UserId": 100000012345,
  "RoleName": "Employee",
  "RoleCode": "ORA_PER_EMPLOYEE_ABSTRACT",
  "StartDate": "2024-06-01"
}

Terminate Worker

• Method: POST
• URL: /hcmRestApi/resources/latest/workers/{PersonId}/child/workRelationships/{workRelationshipId}/action/terminate
• Watch out for: Termination does not automatically revoke HCM user account access. A separate user account deactivation or SCIM deprovision step is required.

Request example

POST .../workers/300000099887766/child/workRelationships/300000099887767/action/terminate
Content-Type: application/json
{
  "TerminationDate": "2024-08-31",
  "ActionCode": "RESIGNATION"
}

Response example

{
  "PersonId": 300000099887766,
  "TerminationDate": "2024-08-31",
  "ActionCode": "RESIGNATION",
  "WorkerType": "E"
}

SCIM Get Users

• Method: GET
• URL: /hcmRestApi/scim/v2/Users
• Watch out for: SCIM in Oracle HCM is primarily designed for inbound provisioning from IdPs (Okta, Azure AD). Direct SCIM API calls require the same OAuth credentials and HCM security roles as REST API calls.

Request example

GET /hcmRestApi/scim/v2/Users?filter=userName+eq+"john.smith"
Authorization: Bearer <token>

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "Resources": [
    {"id":"abc123","userName":"john.smith","active":true,
     "emails":[{"value":"john.smith@example.com","primary":true}]}
  ]
}

• Rate limits: Oracle HCM Cloud does not publish explicit per-minute or per-hour rate limit tiers in public documentation. Limits are enforced at the pod/tenant level and governed by Oracle's Fair Use Policy. Concurrent REST connections are throttled by the platform.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Oracle recommends using bulk/batch endpoints and HCM Data Loader (HDL) for high-volume operations rather than individual REST calls. Excessive REST calls may result in HTTP 503 responses.
• Pagination method: offset
• Default page size: 25
• Max page size: 500
• Pagination pointer: offset and limit query parameters (e.g., ?offset=0&limit=100)

• Webhooks available: No
• Webhook notes: Oracle HCM Cloud does not offer native outbound webhooks for user or worker events. Event-driven integration is achieved through Oracle Integration Cloud (OIC) adapters, HCM Extracts, or the Business Events framework (which publishes to Oracle Messaging Service/JMS queues, not HTTP webhooks).
• Alternative event strategy: Use Oracle Integration Cloud (OIC) HCM Adapter with event subscriptions (e.g., New Hire, Termination business events via JMS/AQ), or schedule HCM Extracts/BI Publisher reports for periodic data sync.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (included with Oracle HCM Cloud; requires SSO/IDCS configuration)

• Endpoint: https://.fa.us2.oraclecloud.com/hcmRestApi/scim/v2

• Supported operations: GET /Users (list/filter users), GET /Users/{id} (get single user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user, including activate/deactivate), DELETE /Users/{id} (deprovision user), GET /Groups (list groups/roles), GET /ServiceProviderConfig, GET /Schemas

Limitations:

• SCIM provisioning requires Oracle Identity Cloud Service (IDCS) or OCI IAM to be configured as the identity provider.
• SCIM primarily manages HCM application user accounts and role assignments, not the full worker/person record (hire, job changes require HCM REST API or HDL).
• Group (role) management via SCIM is limited; complex HCM role hierarchies may not map cleanly to SCIM Groups.
• SSO must be enabled as a prerequisite for SCIM provisioning.
• Tested and documented integrations are with Okta and Azure AD (Entra ID); other IdPs may require custom configuration.
• SCIM attribute mapping to HCM-specific fields (e.g., LegislativeDataGroup, PersonType) is not supported natively through SCIM.

Three integration patterns cover the majority of production use cases:

New hire onboarding requires two separate API calls: POST /workers to create the person and employment record, then POST /users to create the HCM application user account linked to the returned PersonId. These are independent operations - creating a worker does not create login credentials. Role assignment is a third call to POST /users/{UserId}/roles. If an IdP (Okta, Azure AD) is connected via SCIM, it will detect the new user through SCIM polling and cascade SSO provisioning, but only after the HCM user account exists.

Termination and access revocation also requires two explicit steps: POST to the terminate action on the worker's workRelationships sub-resource, then a separate PATCH /scim/v2/Users/{UserGUID} with active: false to deactivate the HCM user account. These are not linked automatically. Relying on the scheduled 'Autoprovision Users' process for deactivation introduces a time lag that may not meet security policy requirements for immediate revocation.

Bulk worker sync uses paginated GET /workers with expand=emails,names,assignments and increments offset by limit until hasMore returns false. For tenants with more than 10,000 workers, REST pagination is slow and risks throttling; Oracle's documented recommendation for this volume is HCM Extracts or BI Publisher scheduled reports. Cross-referencing GET /users is required to map PersonId to Username and UserGUID for identity graph correlation across downstream systems.

New Employee Onboarding (Hire + Provision Access)

1. POST /hcmRestApi/resources/latest/workers with EffectiveStartDate, PersonTypeCode=EMP, names[], emails[], and workRelationships[] (including LegalEmployerName, StartDate, JobCode).
2. Retrieve the generated PersonId from the response.
3. POST /hcmRestApi/resources/latest/users to create the HCM application user account, linking to PersonId and setting Username.
4. POST /hcmRestApi/resources/latest/users/{UserId}/roles to assign required HCM security roles (e.g., Employee, line-of-business roles).
5. If using SCIM IdP (Okta/Azure AD), the IdP will detect the new user via SCIM GET /Users polling or push and provision SSO access automatically.

Watch out for: Steps 1 and 3 are independent API calls. If step 3 is skipped, the worker exists in HCM but cannot log in. The 'Autoprovision Users' scheduled process can automate step 3 but runs on a schedule, not in real time.

Employee Termination (Offboarding + Revoke Access)

1. GET /hcmRestApi/resources/latest/workers/{PersonId}?expand=workRelationships to retrieve the active workRelationshipId.
2. POST /hcmRestApi/resources/latest/workers/{PersonId}/child/workRelationships/{workRelationshipId}/action/terminate with TerminationDate and ActionCode.
3. GET /hcmRestApi/resources/latest/users?q=PersonId={PersonId} to find the linked UserId.
4. PATCH /hcmRestApi/scim/v2/Users/{UserGUID} with {"active": false} to deactivate the HCM user account, or DELETE to fully remove.
5. If Okta/Azure AD is the IdP, SCIM deprovisioning will cascade to revoke SSO and downstream app access.

Watch out for: Termination (step 2) and user deactivation (step 4) are not linked automatically. Both must be executed explicitly. Relying on the scheduled 'Autoprovision Users' process for deactivation introduces a time lag that may violate security policy.

Sync HCM Users to External System (Bulk Export)

1. GET /hcmRestApi/resources/latest/workers?limit=500&offset=0&expand=emails,names,assignments to retrieve the first page of workers.
2. Check hasMore in the response; if true, increment offset by limit and repeat until hasMore=false.
3. For each worker, extract PersonId, DisplayName, WorkEmail, AssignmentStatusTypeCode, DepartmentName, ManagerId.
4. Cross-reference with GET /hcmRestApi/resources/latest/users to map PersonId to Username and UserGUID for identity correlation.
5. Write transformed records to the target system.

Watch out for: For tenants with >10,000 workers, REST pagination is slow and may trigger throttling. Oracle recommends using HCM Extracts or BI Publisher scheduled reports for bulk data extraction instead of paginating the REST API.

The most consequential architectural assumption to validate before building on Oracle HCM's API is that the worker record and the user account are separate objects with no automatic linkage. A POST /workers call that succeeds does not mean the person can log in; a termination that succeeds does not mean access is revoked.

Every lifecycle automation must explicitly handle both objects or it is incomplete.

The date-effective data model compounds this. Nearly all write operations require an explicit EffectiveStartDate. Omitting it defaults to today and may silently overwrite existing future-dated records.

Reads return the record valid as of today unless ?effectiveDate= is supplied. Pipelines that do not account for temporal rows will produce incorrect state reads and destructive writes.

For identity graph construction, the PersonId is the stable internal key, but PersonNumber (employee number) is the business key used in HR workflows and downstream systems.

ManagerId references another PersonId, enabling hierarchy traversal, but the management chain is only accurate if the HCM org structure is maintained correctly - a data quality dependency that lives outside the API.

SCIM integration is tested and documented for Okta and Azure AD; other IdPs may require non-standard configuration and should be validated against the SCIM limitations before committing to that path.