---
category: [Administration & Integrations, Administration & Integrations/Workday API, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Product-Specific Integrations, Payroll, Payroll/Cloud Connect for Third Party Payroll, Payroll/Global Payroll Connect]
keyword: [effectiveChanges, Data Changes on Demand, DCoD, GPC, Global Payroll Connect]
nav: wcp_docs
parent_url: /wcp_docs/
title: Global Payroll Effective Changes REST API
layout: subsection
---

This topic provides an overview and usage guidance on the Global Payroll REST API.

## <a id="section_umd_41s_qpb"></a>Overview

The Effective Changes REST API in the Global Payroll REST service enables you to make flexible requests for external pay groups from Workday to your third-party payroll systems. It is a full-stack REST API that provides field level change detection and returns the current snapshot for each worker in a JSON format.

1.  Work with a payroll vendor to configure Data Changes on Demand in Workday. See [Steps: Set Up Data Changes on Demand](/wcp_docs/GUID-7df346e2-e8f3-4848-b136-260de4f67ee6.html).
2.  The third-party payroll vendor calls the `effectiveChanges` REST API.
3.  The third-party payroll vendor retrieves the output file from the REST API. See [Concept: Data Changes on Demand Change Detection](/wcp_docs/GUID-517c2c48-10c0-47b3-89d9-aa9726dfc2e1.html).


For reference documentation about the `effectiveChanges` REST APIs, see `globalPayroll/effectiveChanges` in the [REST API Explorer on the Developer Site](https://developer.workday.com/rest-api-explorer) or [Workday REST Services Directory](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html).

## <a id="section_6"></a>URL Base Path

<b>Workday API Gateway Base Path</b>

For REST API calls in Workday Extend and Orchestrate for Integrations, use the regional API Gateway base URL for your account. See [Reference: Workday Extend API Gateways and Authorization Base URLs](https://developer.workday.com/documentation/dlh1653340161856) on the Developer Site. Note that the API Gateway base URL doesn’t include the tenant name.

<b>Tenant Base Path</b>

For traditional Integrations using tenanted REST APIs calls:

```
https://<hostname>/api/globalPayroll/<version>/<tenant>/effectiveChanges
```

Example:

```
https://yourTenantHostName.com/api/globalPayroll/v1/gms/effectiveChanges
```

## <a id="section_securityConsiderations"></a>Workday Tasks

You can utilize the <b>View Data Changes on Demand</b> task to see:

-   Who made the request, such as vendor name and ISU.
-   What were the request parameters, such as entry ranges, effective ranges, and response filters.
-   What fields were included.
-   If there were any worker overrides.
-   An Integration Event link to the View Background Process task.


To access this task, copy the top-level event ID in the REST response and search it in Workday with the WID prefix. Example: <i>WID: 0c80b6074ebd01001944f2fdc45a0000</i>.

Example of the top-level event ID:

```
{
"id": "<b>0c80b6074ebd01001944f2fdc45a0000</b>",
"responseData": {
"status": {
"descriptor": "Processing",
"id": "d8b0c17e446c11de98360015c5e6daf6"
}
}
```

## <a id="section_1"></a>Security Considerations

You must have <i>View</i> access to the <i>Manage: Data Changes On Demand</i> domain in the Global Payroll Connect functional area to access the <b>View Data Changes on Demand</b> task. For more information on security considerations, see: [Setup Considerations: Data Changes on Demand](/wcp_docs/GUID-df169cbc-a756-4bee-a155-0340903d1420.html).

## <a id="section_constructingRequestBody"></a>Prerequisites

See the prerequisites and steps in [Steps: Set Up Data Changes on Demand](/wcp_docs/GUID-7df346e2-e8f3-4848-b136-260de4f67ee6.html)

## <a id="section_checkingValidations"></a>Generating Effective Change Data

Generate effective change data for organizations or workers based on request parameters by creating an integration event and reporting the changes in a JSON output file.

Example for requesting data for 1 worker to detect changes with these criteria parameters and response filters:

-   entryMomentFrom and entryMomentTo date range set to 2025-03-27T00:00:00.000 through 2025-03-28T00:00:00.000.
-   effectiveFrom date and effectiveTo date range set to 2025-03-01 through 2025-03-31.
-   allEffective set as false.
-   includeRequestCriteriaInResponse set as false.
-   onlyInclude these fields:

    -   Employee ID.
    -   Personal communication addresses.

-   Third Party Australia organization.
-   Worker to include employee ID: 21286
-   countryNameFormat as COUNTRY_NAME.
-   countryRegionNameFormat as COUNTRY_REGION_ID.


-   <b>Sample Request</b>

    ```
    POST /effectiveChanges
    ```

    ```
    {
    "requestCriteria": {
    "entryMomentFrom": "2025-03-27T00:00:00.000",
    "entryMomentTo": "2025-03-28T00:00:00.000",
    "effectiveFrom": "2025-03-01",
      "effectiveTo": "2025-03-31",
     "allEffective": false,
    "includeRequestCriteriaInResponse": false,
    "fields": {
      "fieldSetVersion": "v1",
      "onlyInclude": [
          {"id": "Field_Path_ID=$.workers.employeeId"},
          {"id": "Field_Path_ID=$.workers.personalCommunication.addresses.*"}
      ]
          },
    "organizations": [
      {"id": "Organization_Reference_ID=TP-Australia","descriptor": "Third Party Australia"}
      ],
    "excludeWorkers": false,
    "workers": [
      {"id": "Employee_ID=21286"}//Not Required
      ],
    "responseFilter" : {
      "countryNameFormat":"COUNTRY_NAME",
      "countryRegionNameFormat":"COUNTRY_REGION_ID"
      },
    "forceRerun": false,
    "schemaOnly": false
    }
    }
    ```

-   <b>Sample Processing Response</b>

    ```
    {
    "id": "0c80b6074ebd01001944f2fdc45a0000",
    "responseData": {
    "status": {
    "descriptor": "Processing",
    "id": "d8b0c17e446c11de98360015c5e6daf6"
    }
    }
    }
    ```

-   <b>Sample Completed Response</b>

    ```
    {
    "id": "0c80b6074ebd01001944f2fdc45a0000",
    "responseData": {
    "status": {
    "descriptor": "Completed",
    "id": "d8b0bcd8446c11de98360015c5e6daf6"
    },
    "documents": [
    {
    "documentId": "0c80b6074ebd01001944f397691b0000/787343f2-a7ff-4306-b396-121c8539f3fa",
    "documentTags": [
     {
       "id": "9391e623a658100015cdbfa4c7600045",
       "descriptor": "Document Schema"
     },
     {
       "id": "9bdbef7931771000070097cb97bd0000",
       "descriptor": "Data Changes On Demand - DIS"
     }
    ],
    "fileName": "Data Changes On Demand - DIS Schema.json"
    },
    {
    "organization": {
     "id": "3cb7ef394b564f72afedf26f2ede1b31",
     "descriptor": "Third Party - Australia",
     "Organization_Reference_ID": "TP-Australia"
    },
    "documentTags": [
     {
       "id": "9bdbef7931771000070097cb97bd0000",
       "descriptor": "Data Changes On Demand - DIS"
     },
     {
       "id": "7ca3e1bd04e4100003d394c3e53d0001",
       "descriptor": "Data - Full"
     },
     {
       "id": "0c80b6074ebd01001941f7979dd30000",
       "descriptor": "3cb7ef394b564f72afedf26f2ede1b31"
     },
     {
       "id": "df3520a3ef69432bbd9f48ed808dbd18",
       "descriptor": "Deliverable"
     }
    ],
    "fileName": "EffectiveWorkerInstances.json",
    "documentId": "0c80b6074ebd01001944f397691b0000/e55a97b8-cac4-408b-bd57-b22759b48246"
    }
    ]
    }
    }
    ```

-   <b>GET REST API Example</b>

    Retrieve processing response details of a specific Data Changes on Demand event, such as the status and documentId to retrieve the output file.

    ```
    GET /effectiveChanges/{{ID}}
    ```

-   <b>responseData Section</b>

    The effectiveChanges (v1) REST API response includes a responseData section that provides information on any exception files generated during the integration run. This is a sample of the reponseData section:

    ```
    "includedExceptionMessageCount": "1",
            "totalExceptionMessageCount": 1,
            "exceptionMessages": [
                {
                    "id": "a237cd1299e1810019c836e32a0e0000",
                    "exceptionLogs": [
                        {
                            "documentId": "a237cd1299e1010019c4e7113ad80002/6bcdaa14-631c-4a91-a87f-da2ff8ea7c50",
                            "fileName": "Exception Log-1.json",
                            "organization": {
                                "descriptor": "Third Party - Australia",
                                "id": "3cb7ef394b564f72afedf26f2ede1b31"
                            }
                        }
                    ],
                    "message": "Attaching data \"[1] Exception Log-1.json (Third Party - Australia)\" to Integration Event"
                }
            ],
    ```

    responseData.totalExceptionMessageCount is the total number of exceptions. responseData.includedExceptionMessageCount is the number of logs the integration provides, but there could be more. The integration provides up to 100 exception logs.



## <a id="section_5"></a>Retrieve Output File

After you make a POST request from your third-party payroll system, you’ll get a notification in the third-party system when the request completes. In the notification, you can retrieve the document ID and run the `myReports` API to retrieve the JSON output file:

```
https://{hostname}/cc-blobitory/{tenant}/{documentId}
```

To view the output file, the integration system user must have security access to the <i>Reports: Data Changes On Demand Results</i> domain in the Payroll Interface functional area. The default document retention policy for the JSON file is 60 days. For more information, see [Concept: My Reports API](/wcp_docs/dan1370797077490.html).

<b>Sample Output JSON file</b>

```
GET https://{{hostname}}/cc-blobitory/{{tenant}}/{{documentId}}
```

```
{
"dataChangesOnDemand": {
"workers": [
   {
       "iid": {"val": "fd30c20b3d4a4801a5c4a272327e77fd"},
       "employeeId": {"val": "21286"},
       "personalCommunication": {
           "addresses": [
               {
                   "iid": {"val": "d6d752e891f440cface5c7df26454fb9-836cf00ef5974ac08b786079866c946f-ADDRESS_REFERENCE-4-861"},
                   "usageType": {"val": "HOME"},
                   "addressId": {"val": "ADDRESS_REFERENCE-4-861"},
                   "primary": {"val": "true"},
                   "addressLine1": {
                       "val": "789 Test Street",
                       "ecs": [
                           {
                               "eff": "2025-03-27T00:00:00.000-07:00",
                               "ent": "2025-03-27T14:14:35.777-07:00",
                               "p": "123 Test Road",
                               "c": "789 Test Street"
                           }
                       ]
                   },
                   "city": {
                       "val": "Test City"
                   },
                   "postalCode": {"val": "12345"},
                   "country": {"val": "Australia"},
                   "stateProvince": {
                       "val": "Test State"
                   }
               }
           ]
       }
   }
]
}
}
```

## <a id="section_examples"></a>Limitations

See the <b>Limitations</b> section of [Setup Considerations: Data Changes on Demand](/wcp_docs/GUID-df169cbc-a756-4bee-a155-0340903d1420.html).

## <a id="section_2"></a>Performance Considerations

Running multiple integration jobs simultaneously depending on job sizes can impact performance because grid jobs share the resources. Example: You launch 2 integration jobs simultaneously that utilize the expected amount of resources for those jobs, and it took 30 minutes for each job to complete. The next day, you launch 5 integration jobs that can’t utilize the expected amount of resources for those jobs because of the tenant grid capacity, and it took 60 minutes for each job to complete.

## <a id="section_4"></a>Common Errors

To see the list of all the error codes, see the 400 Response section in the POST /effectiveChanges endpoint for the Global Payroll service in the [REST API Explorer on the Developer Site](https://developer.workday.com/rest-api-explorer) or [Workday REST Services Directory](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html).

### Related Information

[2024R2 Feature Release Note: Data Changes on Demand](https://doc.workday.com/release-notes/en-us/payexternal/6722363.html)