REST API for Oracle Fusion Cloud HCM

Manage User Accounts

You may need to manage user accounts for the workers in your organization to provide access to certain applications or task flows that workers are required to use in their work assignments. You can use the userAccounts API to perform actions such as view, create, update, link, unlink, and so on. You can also perform custom actions such as password reset and update.

Let's discuss these scenarios:

View all the user accounts
Create a user account
View a user account
Unlink a user account
Link a user account
Update the user name of an account
Update the password of an account
Trigger a password reset for an account
Suspend a user account
Unsuspend a user account

View All User Accounts

Let's say that Jason is an administrator who manages user accounts for the workers in his organization. He wants to retrieve all the user accounts and view the account details.

To view all the user accounts:

Perform a GET operation on the userAccounts resource.
Verify the account details returned in the response.

Example URL

Use this resource URL format.

GET

/hcmRestApi/resources/11.13.18.05/userAccounts

Example Response

Here's an example of the response body in JSON format.

{
   "items": [
      {
         "UserId": 60,
         "Username": "CUST_CONTRACT_MGR_OPERATIONS",
         "SuspendedFlag": false,
         "PersonId": 100010024201426,
         "PersonNumber": "WRKR-10024201426",
         "CredentialsEmailSentFlag": true,
         "GUID": "5A25572D96277A00C0547E3A715EF682",
         "CreatedBy": "0",
         "CreationDate": "2009-05-25T00:00:00+00:00",
         "LastUpdatedBy": "TM-MFITZIMMONS",
         "LastUpdateDate": "2019-09-10T18:10:15.321+00:00",
         "links": [
             {
              ...}
         ]
      },
      {
         "UserId": 300100003417358,
         "Username": "DATA_STEWARD_MANAGER_VISION_CORPORATION",
         "SuspendedFlag": false,
         "PersonId": null,
         "PersonNumber": null,
         "CredentialsEmailSentFlag": true,
         "GUID": "C79DBCC8F107FDE2CD3B938BEF5A94CE",
         "CreatedBy": "HCM_USER10",
         "CreationDate": "2011-12-02T04:30:33.660+00:00",
         "LastUpdatedBy": "FUSION",
         "LastUpdateDate": "2013-08-14T00:48:18+00:00",
         "links": [
            {
             ...}
         ]
      },
      {
         "UserId": 100100081660000,
         "Username": "john.doe@example.com",
         "SuspendedFlag": false,
         "PersonId": 300100069778195,
         "PersonNumber": "WRKR-955160008183775",
         "CredentialsEmailSentFlag": true,
         "GUID": "8091FA12603D206DE050F50AE3921F70",
         "CreatedBy": "useraccountsuper",
         "CreationDate": "2019-02-14T21:01:35.180+00:00",
         "LastUpdatedBy": "useraccountsuper",
         "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
         "links": [
            {
             ...}
         ]
    ]
}

Create a User Account

Let's say that Jason needs to create a new user account for Andy who recently joined the organization.

To create a new user account:

Make sure that Manage Enterprise HCM Information task in Oracle HCM Cloud allows user account creation.
Query the worker by using a query parameter such as person number and retrieve the person ID.
Set the Content-Type to application/vnd.oracle.adf.resourceitem+json.
Perform a POST operation on the userAccounts resource by providing the user name and person ID in the request body.
Verify the details of the new user account returned in the response.

Example URL

Use this resource URL format.

POST

/hcmRestApi/resources/11.13.18.05/userAccounts

Example Request

Here's an example of the request body in JSON format.

{	
  "PersonId": "300100069778195",
  "Username": "john.doe@example.com",
  "CredentialsEmailSentFlag": "true"
}

Example Response

Here's an example of the response body in JSON format.

{
    "UserId": 100100081660000,
    "Username": "john.doe@example.com",
    "SuspendedFlag": false,
    "PersonId": "300100069778195",
    "PersonNumber": "WRKR-955160008183775",
    "CredentialsEmailSentFlag": true,
    "GUID": "8091FA12603D206DE050F50AE3921F70",
    "CreatedBy": "useraccountsuper",
    "CreationDate": "2019-02-14T21:01:35.180+00:00",
    "LastUpdatedBy": "useraccountsuper",
    "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
    "links": : [
      {...
          }
    ]
}

View a User Account

Jason wants to view the user account that he created for Andy and verify that the details are correct.

To retrieve a user account:

Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
Perform a GET operation on the userAccounts resource by using the GUID.
Verify the user account details returned in the response.

Example URL

Use this resource URL format.

GET

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70

Example Response

Here's an example of the response body in JSON format.

{
    "UserId": 100100081660000,
    "Username": "john.doe@example.com",
    "SuspendedFlag": false,
    "PersonId": 300100069778195,
    "PersonNumber": "WRKR-955160008183775",
    "CredentialsEmailSentFlag": true,
    "GUID": "8091FA12603D206DE050F50AE3921F70",
    "CreatedBy": "useraccountsuper",
    "CreationDate": "2019-02-14T21:01:35.180+00:00",
    "LastUpdatedBy": "useraccountsuper",
    "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
    "links": : [
       {...
          }
    ]
}

Unlink a User Account

Jason realized that Scott has been assigned an incorrect user account by mistake. He wants to unlink the account.

To unlink a user account:

Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
Set the Content-Type to application/vnd.oracle.adf.resourceitem+json.
Perform a PATCH operation on the userAccounts resource by using the GUID and providing a null value for PersonID in the request body.
Verify the user account details returned in the response.

Example URL

Use this resource URL format.

PATCH

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70

Example Request

Here's an example of the request body in JSON format.

{
 "PersonId": null
}

Example Response

Here's an example of the response body in JSON format.

{
    "UserId": 100100081660000,
    "Username": "john.doe@example.com",
    "SuspendedFlag": false,
    "PersonId": null,
    "PersonNumber": null,
    "CredentialsEmailSentFlag": true,
    "GUID": "8091FA12603D206DE050F50AE3921F70",
    "CreatedBy": "useraccountsuper",
    "CreationDate": "2019-02-14T21:01:35.180+00:00",
    "LastUpdatedBy": "useraccountsuper",
    "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
    "links": : [
       {...
          }
    ]
}

Link a User Account

Let's say that Jason wants to link Andy's person record to a new user account, which isn't linked to any person record yet.

To link a user account:

Query the worker by using a query parameter such as person number and obtain the person ID.
Query the user account to be assigned by using a query parameter such as person name and obtain the GUID of the user account.
Set the Content-Type to application/vnd.oracle.adf.resourceitem+json.
Perform a PATCH operation on the userAccounts resource by using the GUID and providing the obtained person ID value for PersonID in the request body.
Verify the user account details returned in the response.

Example URL

Use this resource URL format.

PATCH

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70

Example Request

Here's an example of the request body in JSON format.

{
 "PersonId": 300100069778195
}

Example Response

Here's an example of the response body in JSON format.

{
    "UserId": 100100081660000, 
    "Username": "johndoe@example.com", 
    "SuspendedFlag": false,
    "PersonId": 300100069778195,
    "PersonNumber": "WRKR-955160008183775",
    "CredentialsEmailSentFlag": true,
    "GUID": "8091FA12603D206DE050F50AE3921F70",
    "CreatedBy": "useraccountsuper",
    "CreationDate": "2019-02-14T21:01:35.180+00:00",
    "LastUpdatedBy": "useraccountsuper",
    "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
    "links": : [
       {...
          }
    ]
}

Update a User Name

Jason noticed that the user name of an existing user account is incorrect and wants to update it.

To update a user name:

Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
Set the Content-Type to application/vnd.oracle.adf.resourceitem+json.
Perform a PATCH operation on the userAccounts resource by using the GUID and providing the new value for Username in the request body.
Verify the user account details returned in the response.

Example URL

Use this resource URL format.

PATCH

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70

Example Request

Here's an example of the request body in JSON format.

{
  "Username": "jane.doe@example.com"
}

Example Response

Here's an example of the response body in JSON format.

{
    "UserId": 100100081660000, 
    "Username": "jane.doe@example.com", 
    "SuspendedFlag": false,
    "PersonId": 300100069778195,
    "PersonNumber": "WRKR-955160008183775",
    "CredentialsEmailSentFlag": true,
    "GUID": "8091FA12603D206DE050F50AE3921F70",
    "CreatedBy": "useraccountsuper",
    "CreationDate": "2019-02-14T21:01:35.180+00:00",
    "LastUpdatedBy": "useraccountsuper",
    "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
    "links": : [
       {...
          }
    ]
}

Update a Password

Let's say that Jason wants to update the password of an existing user account to a specific value for a test user.

To update a password:

Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
Set the Content-Type to application/vnd.oracle.adf.action+json.
Perform a POST operation on the userAccounts resource by using the GUID and the custom action updatePassword, and providing the new password in the request body.
Verify the result in the response.

Example URL

Use this resource URL format.

POST

 /hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70/action/updatePassword

Example Request

Here's an example of the request body in JSON format.

{ 
  "pwd": "NewPassw0rd"
}

Example Response

Here's an example of the response body in JSON format.

{
  "result": "Success"
}

Trigger a Password Reset

Let's say that Jason wants to trigger a password reset flow for a user account to reset the password.

To trigger a password reset:

Query the user account by using a query parameter such as person number and obtain the GUID of the user account.
Set the Content-Type to application/vnd.oracle.adf.action+json.
Perform a POST operation on the userAccounts resource by using the GUID and the custom action resetPassword.
Verify the result in the response.

Example URL

Use this resource URL format.

POST

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70/action/resetPassword

Example Response

Here's an example of the response body in JSON format.

{
  "result": "Success"
}

Suspend a User Account

Let's say that Jason wants to limit Andy's access to the application and suspend his user account temporarily.

To suspend a user account:

Query the user account by using a query parameter such as person number and get the GUID of the user account.
Set the Content-Type to application/vnd.oracle.adf.resourceitem+json.
Perform a PATCH operation on the userAccounts resource by using the GUID and providing the value true for the SuspendedFlag attribute in the request body.
Verify the user account details returned in the response.

Example URL

Use this resource URL format.

PATCH

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70

Example Request

Here's an example of the request body in JSON format.

{
  "SuspendedFlag": true
}

Example Response

Here's an example of the response body in JSON format.

{
    "UserId": 100100081660000,
    "Username": "jane.doe@example.com",
    "SuspendedFlag": true,
    "PersonId": 300100069778195,
    "PersonNumber": "WRKR-955160008183775",
    "CredentialsEmailSentFlag": true,
    "GUID": "8091FA12603D206DE050F50AE3921F70",
    "CreatedBy": "useraccountsuper",
    "CreationDate": "2019-02-14T21:01:35.180+00:00",
    "LastUpdatedBy": "useraccountsuper",
    "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
    "links": : [
       {...
          }
    ]
}

Unsuspend a User Account

Jason now wants to allow access to Andy, whose user account is currently suspended.

To unsuspend a user account:

Query the user account by using a query parameter such as person number and obtain GUID of the the user account.
Set the Content-Type to application/vnd.oracle.adf.resourceitem+json.
Perform a PATCH operation on the userAccounts resource by using the GUID and providing the value false for the SuspendedFlag attribute in the request body.
Verify the user account details returned in the response.

Example URL

Use this resource URL format.

PATCH

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70

Example Request

Here's an example of the request body in JSON format.

{
 "SuspendedFlag": false
}

Example Response

Here's an example of the response body in JSON format.

{
    "UserId": 100100081660000,
    "Username": "jane.doe@example.com",
    "SuspendedFlag": false,
    "PersonId": 300100069778195,
    "PersonNumber": "WRKR-955160008183775",
    "CredentialsEmailSentFlag": true,
    "GUID": "8091FA12603D206DE050F50AE3921F70",
    "CreatedBy": "useraccountsuper",
    "CreationDate": "2019-02-14T21:01:35.180+00:00",
    "LastUpdatedBy": "useraccountsuper",
    "LastUpdateDate": "2019-02-14T21:01:35.288+00:00",
    "links": : [
       {...
          }
    ]
}

Delete a User Account

Let's say that Jason created an incorrect user account and wants to delete it.

To delete a user account:

Query the user account by, using a query parameter such as person number and obtain the user account GUID.
Set the Content-Type to application/vnd.oracle.adf.resourceitem+json.
Perform a DELETE operation on the userAccounts resource by using the GUID.
Verify the status in the response.

Example URL

Use this resource URL format.

DELETE

/hcmRestApi/resources/11.13.18.05/userAccounts/8091FA12603D206DE050F50AE3921F70

Example Response

Here's an example of the response body in JSON format.

Status: 204 - No content