Oracle CX Sales User Management API Guide

Auth method: Basic Auth (username:password Base64-encoded) or OAuth 2.0 (3-legged or 2-legged JWT)

Setup steps

1. For Basic Auth: encode 'username:password' in Base64 and pass as Authorization: Basic header.
2. For OAuth 2.0: register a confidential application in Oracle Identity Cloud Service (IDCS) or Oracle Access Manager.
3. Assign the application the required API scopes (e.g., urn:opc:resource:consumer::all or specific Fusion resource scopes).
4. Obtain an access token via the IDCS token endpoint: POST https://.identity.oraclecloud.com/oauth2/v1/token.
5. Pass the token as Authorization: Bearer on all API requests.
6. For SCIM provisioning, Basic Auth is the documented supported method; OAuth 2.0 support for SCIM may vary by release.

Required scopes

List Users (Sales Resources/Persons)

• Method: GET
• URL: https://<tenant>.fa.us2.oraclecloud.com/crmRestApi/resources/latest/salesPartyResources?fields=PersonId,Username,FirstName,LastName,EmailAddress,ActiveFlag&limit=25&offset=0
• Watch out for: The exact resource name for 'users' in CX Sales context may be salesPartyResources or resourceMembers depending on the module. Verify against your tenant's /crmRestApi/resources/latest endpoint catalog.

Request example

GET /crmRestApi/resources/latest/salesPartyResources?limit=25&offset=0
Authorization: Basic <base64>
Accept: application/json

Response example

{
  "items": [
    {"PersonId": 100001, "Username": "jdoe", "FirstName": "Jane", "LastName": "Doe", "ActiveFlag": true}
  ],
  "count": 1,
  "hasMore": false,
  "limit": 25,
  "offset": 0
}

Get Single User by PersonId

• Method: GET
• URL: https://<tenant>.fa.us2.oraclecloud.com/crmRestApi/resources/latest/salesPartyResources/{PersonId}
• Watch out for: PersonId is the path parameter, not UserId. Confusing the two returns 404.

Request example

GET /crmRestApi/resources/latest/salesPartyResources/100001
Authorization: Basic <base64>
Accept: application/json

Response example

{
  "PersonId": 100001,
  "Username": "jdoe",
  "FirstName": "Jane",
  "LastName": "Doe",
  "EmailAddress": "jdoe@example.com",
  "ActiveFlag": true
}

Create User (SCIM)

• Method: POST
• URL: https://<tenant>.fa.us2.oraclecloud.com/hcmRestApi/scim/Users
• Watch out for: SCIM endpoint is under /hcmRestApi/scim/, not /crmRestApi/. Basic Auth is the documented auth method for this endpoint. OAuth 2.0 support for SCIM is not consistently documented.

Request example

POST /hcmRestApi/scim/Users
Authorization: Basic <base64>
Content-Type: application/scim+json

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
 "userName":"jdoe","name":{"givenName":"Jane","familyName":"Doe"},
 "emails":[{"value":"jdoe@example.com","primary":true}],"active":true}

Response example

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "100001",
  "userName": "jdoe",
  "active": true,
  "meta": {"resourceType": "User", "location": "/hcmRestApi/scim/Users/100001"}
}

Update User (SCIM PATCH)

• Method: PATCH
• URL: https://<tenant>.fa.us2.oraclecloud.com/hcmRestApi/scim/Users/{id}
• Watch out for: SCIM PATCH for deactivation sets active=false but does not delete the HCM person record. Full deprovision requires additional steps in Oracle HCM.

Request example

PATCH /hcmRestApi/scim/Users/100001
Authorization: Basic <base64>
Content-Type: application/scim+json

{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 "Operations":[{"op":"replace","path":"active","value":false}]}

Response example

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "100001",
  "userName": "jdoe",
  "active": false
}

Get User (SCIM)

• Method: GET
• URL: https://<tenant>.fa.us2.oraclecloud.com/hcmRestApi/scim/Users/{id}
• Watch out for: The SCIM id field maps to the Oracle HCM PersonId. Filter by userName using ?filter=userName eq "jdoe" to look up by username.

Request example

GET /hcmRestApi/scim/Users/100001
Authorization: Basic <base64>
Accept: application/scim+json

Response example

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "100001",
  "userName": "jdoe",
  "name": {"givenName": "Jane", "familyName": "Doe"},
  "active": true
}

List SCIM Users with Filter

• Method: GET
• URL: https://<tenant>.fa.us2.oraclecloud.com/hcmRestApi/scim/Users?filter=userName eq "jdoe"&startIndex=1&count=25
• Watch out for: SCIM filter syntax must be URL-encoded. Not all SCIM filter operators are supported; eq and co are most reliable.

Request example

GET /hcmRestApi/scim/Users?filter=userName+eq+%22jdoe%22&startIndex=1&count=25
Authorization: Basic <base64>
Accept: application/scim+json

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 25,
  "Resources": [{"id": "100001", "userName": "jdoe", "active": true}]
}

Assign Role to User (CRM REST)

• Method: POST
• URL: https://<tenant>.fa.us2.oraclecloud.com/hcmRestApi/resources/latest/users/{UserId}/child/userRoles
• Watch out for: Role codes are Oracle-internal identifiers (ORA_ prefix for seeded roles). Custom roles use tenant-specific codes. SCIM does not support group/role provisioning for CX Sales; use HCM REST for role assignment.

Request example

POST /hcmRestApi/resources/latest/users/100001/child/userRoles
Authorization: Basic <base64>
Content-Type: application/json

{"RoleCode": "ORA_ZBS_SALES_REPRESENTATIVE", "StartDate": "2024-01-01"}

Response example

{
  "UserId": 100001,
  "RoleCode": "ORA_ZBS_SALES_REPRESENTATIVE",
  "StartDate": "2024-01-01",
  "ActiveFlag": true
}

Deactivate User (CRM REST PATCH)

• Method: PATCH
• URL: https://<tenant>.fa.us2.oraclecloud.com/hcmRestApi/resources/latest/users/{UserId}
• Watch out for: Setting EndDate to a past date or ActiveFlag=false disables login but retains all CRM data associations. Hard delete of users is not supported via REST API.

Request example

PATCH /hcmRestApi/resources/latest/users/100001
Authorization: Basic <base64>
Content-Type: application/json

{"ActiveFlag": false, "EndDate": "2024-12-31"}

Response example

{
  "UserId": 100001,
  "Username": "jdoe",
  "ActiveFlag": false,
  "EndDate": "2024-12-31"
}

• Rate limits: Oracle Fusion Cloud applies server-side throttling. No publicly documented fixed rate-limit numbers per plan. Concurrent request limits apply per pod/tenant. Requests exceeding limits receive HTTP 503 or 429 responses.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Oracle does not publish explicit per-minute rate limits in official docs. Throttling is enforced at the infrastructure level. Recommended practice: implement exponential backoff on 503/429 responses. Batch operations (using batch REST endpoint) are preferred over high-frequency individual calls.
• Pagination method: offset
• Default page size: 25
• Max page size: 500
• Pagination pointer: offset and limit (e.g., ?offset=0&limit=25)

• Webhooks available: No
• Webhook notes: Oracle CX Sales does not offer native outbound webhooks for user lifecycle events via the standard REST API. Event-driven integration is handled through Oracle Integration Cloud (OIC) or Oracle Business Events (via ADF Business Events framework).
• Alternative event strategy: Use Oracle Integration Cloud (OIC) adapters to subscribe to Fusion business events (e.g., user creation, role assignment) and trigger downstream actions. Alternatively, poll the REST API using LastUpdateDate filter for delta sync.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise (Oracle Fusion Cloud CX Sales v11.12.1.0.0+; SSO prerequisite required)

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

• Supported operations: GET /Users (list with filter), GET /Users/{id}, POST /Users (create), PUT /Users/{id} (full replace), PATCH /Users/{id} (partial update, deactivate), DELETE /Users/{id} (supported but may only deactivate)

Limitations:

• Basic Auth is the documented authentication method; OAuth 2.0 for SCIM is not consistently supported across all releases.
• Group provisioning (/Groups endpoint) is not supported; roles must be managed via HCM REST API userRoles child resource.
• SCIM does not provision CX Sales-specific attributes (e.g., sales territory, resource organization); these require separate HCM/CRM REST calls.
• SSO must be configured as a prerequisite for SCIM provisioning to function correctly.
• DELETE via SCIM may deactivate rather than permanently delete the HCM person record.
• Not all SCIM filter operators are supported; complex filters may return errors.
• Tenant URL format varies by data center region (e.g., us2, em2, ap1).

Provisioning a new sales rep via SCIM is a three-phase operation. First, POST to /hcmRestApi/scim/Users to create the account and capture the returned SCIM id.

Second, POST to /hcmRestApi/resources/latest/users/{UserId}/child/userRoles with the appropriate RoleCode (e. g.

, ORA_ZBS_SALES_REPRESENTATIVE) and a StartDate. Third, if territory-based data access is required, add the user to a sales territory resource pool via /crmRestApi/resources/latest/territories.

SCIM alone does not complete CX Sales provisioning; skipping steps two or three produces a user who can authenticate but sees no CRM data.

Deactivating a departed user via SCIM PATCH (active=false) disables login but does not remove role assignments or territory memberships. These persist on the HCM record and require separate cleanup via HCM REST if the account is ever reactivated or audited. Hard deletion of user records is not supported via REST API or the standard UI.

For delta sync, use the LastUpdateDate filter on /crmRestApi/resources/latest/salesPartyResources with ISO 8601 format including timezone offset (?q=LastUpdateDate>='2024-01-01T00:00:00+00:00'). Pagination uses offset/limit for CRM REST and startIndex/count for SCIM - do not mix parameters across endpoint types. Inactive records may be excluded from delta results by default; add an explicit ActiveFlag filter to capture deactivations.

Provision a new sales rep via SCIM

1. POST to /hcmRestApi/scim/Users with userName, name.givenName, name.familyName, emails[0].value, active=true.
2. Capture the returned SCIM id (maps to PersonId/UserId).
3. POST to /hcmRestApi/resources/latest/users/{UserId}/child/userRoles with RoleCode='ORA_ZBS_SALES_REPRESENTATIVE' and StartDate.
4. If territory assignment is needed, use the CRM REST API to add the user to a sales territory resource pool via /crmRestApi/resources/latest/territories.

Watch out for: SCIM alone does not complete CX Sales provisioning. Role and territory assignment require separate HCM/CRM REST calls after SCIM user creation.

Deactivate a departed user

1. Look up the user's SCIM id: GET /hcmRestApi/scim/Users?filter=userName eq "jdoe".
2. PATCH /hcmRestApi/scim/Users/{id} with Operations: [{op: replace, path: active, value: false}].
3. Optionally, PATCH /hcmRestApi/resources/latest/users/{UserId} with EndDate set to today's date to expire the FND_USER account.
4. Verify deactivation: GET /hcmRestApi/scim/Users/{id} and confirm active=false.

Watch out for: SCIM deactivation sets active=false on the user account but does not remove role assignments or territory memberships. These persist and may need separate cleanup via HCM REST.

Delta sync: fetch users updated since last run

1. Store the timestamp of the last successful sync.
2. GET /crmRestApi/resources/latest/salesPartyResources?q=LastUpdateDate>='2024-06-01T00:00:00+00:00'&limit=500&offset=0.
3. Iterate through pages using offset increments until hasMore=false.
4. For each returned record, compare with local state and apply creates/updates/deactivations as needed.
5. Update the stored timestamp to the current run time.

Watch out for: LastUpdateDate filter requires URL-encoded ISO 8601 with timezone offset. Records deleted (deactivated) in Oracle may not appear in delta results if ActiveFlag=false records are excluded by default; add explicit filter: &q=LastUpdateDate>='...' to include inactive records.

Oracle does not publish explicit per-minute rate limits. Throttling is enforced at the infrastructure level under Oracle's Fair Use Policy; exceeded limits return HTTP 503 or 429 with no Retry-After header and no rate-limit headers in the response. Implement exponential backoff on both status codes and prefer the batch REST endpoint over high-frequency individual calls.

SCIM group provisioning (/Groups endpoint) is not supported for CX Sales. Role assignment must go through the HCM REST userRoles child resource, and CX Sales-specific attributes - sales territory, resource organization - are outside SCIM scope entirely and require separate CRM REST calls.

Any identity graph that relies solely on SCIM will be structurally incomplete for this application.

Webhooks are not available natively for user lifecycle events. Event-driven integration requires Oracle Integration Cloud (OIC) adapters subscribed to Fusion business events. Without OIC, the only option for near-real-time sync is polling with a LastUpdateDate filter, which carries the deactivation-visibility caveat noted above.