---
nav: wcp_docs
parent_url: /wcp_docs/
title: Contact Information Changes REST APIs
layout: subsection
---

## Overview

The Contact Information Changes REST APIs provide the ability to to invoke contact change functionality from your integration or custom app to manage contact information updates in 2 parallel tasks:

-   Home Contact Change
-   Work Contact Change


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

-   `workers` in the <i>Staffing</i> service.
-   `homeContactInformationChanges` in the <i>Person</i> service.
-   `workContactInformationChanges` in the <i>Person</i> service.


## URL Base Path

<b>Tenant Base Paths</b>

```
https://{tenantHostname}/api/person/{version}/{tenantName}
```

```
https://{tenantHostname}/api/staffing/{version}/{tenantName}
```

<b>Examples</b>

```
https://yourTenantHostName.com/api/person/v4/gms
```

```
https://yourTenantHostName.com/api/staffing/v7/gms
```

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

For Workday Extend apps, use the regional API Gateway base URL for your company. See [Reference: Workday Extend API Gateways and Authorization Base URLs](/wcp_docs/dlh1653340161856.html) on the Developer Site. Note that the API Gateway base URL doesn’t include the tenant name.

## Workday Tasks

This table lists the Contact Information Changes REST API endpoints in the <i>Person</i> service that are equivalent to these Workday tasks:

<table><thead><tr><th>Workday Task</th><th>Endpoint</th></tr></thead><tbody><tr><td><p><b>Change Home Contact Information</b></p> <p><b>Change My Home Contact Information</b></p></td><td><p><i>POST /homeContactInformationChanges/{ID}/{subresource}</i></p> <p><i>POST /homeContactInformationChanges/{ID}/submit</i></p> <p><i>PUT /homeContactInformationChanges/{ID}/{subresource}/{subresourceID}</i></p> <p><i>PATCH /homeContactInformationChanges/{ID}/{subresource}/{subresourceID}</i></p> <p><i>DELETE /homeContactInformationChanges/{ID}/{subresource}/{subresourceID}</i></p></td></tr><tr><td><p><b>Change Work Contact Information</b></p> <p><b>Change My Work Contact Information</b></p></td><td><p><i>POST /workContactInformationChanges/{ID}/{subresource}</i></p> <p><i>POST /workContactInformationChanges/{ID}/submit</i></p> <p><i>PATCH /workContactInformationChanges/{ID}</i></p> <p><i>PATCH /workContactInformationChanges/{ID}/{subresource}/{subresourceID}</i></p> <p><i>DELETE /workContactInformationChanges/{ID}/{subresource}/{subresourceID}</i></p></td></tr></tbody></table><br/>

## Business Processes

To initiate a contact change event for home or work, call one of these endpoints on the <i>Staffing</i> service:

<table><thead><tr><th>Business Process</th><th>Endpoint</th></tr></thead><tbody><tr><td><i>Home Contact Change</i></td><td><i>POST /workers/{ID}/homeContactInformationChanges</i></td></tr><tr><td><i>Work Contact Change</i></td><td><i>POST /workers/{ID}/workContactInformationChanges</i></td></tr></tbody></table><br/>

To submit the contact change event, call one of these endpoints on the <i>Person</i> service:

<table><thead><tr><th>Business Process</th><th>Endpoint</th></tr></thead><tbody><tr><td><i>Home Contact Change</i></td><td><i>POST /homeContactInformationChanges/{ID}/submit</i></td></tr><tr><td><i>Work Contact Change</i></td><td><i>POST /workContactInformationChanges/{ID}/submit</i></td></tr></tbody></table><br/>

## Security Considerations

You can control the roles that initiate the change contact business processes using the Contact Information Changes REST APIs.

To enable the roles, configure the:

-   <b>Change Home Contact Information (REST Service)</b> initiating action on the <i>Home Contact Change</i> business process.
-   <b>Change Work Contact Information (REST Service)</b> initiating action on the <i>Work Contact Change</i> business process.


Workday secures all Contact Information Changes REST API endpoints to specific security domains. See the endpoint descriptions in the <i>Staffing</i> and <i>Person</i> REST web service documentation to determine the applicable security domains.

## Initiating a Home or Work Contact Change Event

To initiate a Home or Work Contact Change event for a worker or self, call one of these endpoints in the <i>Staffing</i> service:

-   `POST /workers/{ID}/homeContactInformationChanges`
-   `POST /workers/{ID}/workContactInformationChanges`


To construct the request, you need:

-   The Workday ID of the worker.

    Call the `GET /workers/` endpoint to get the worker ID. Specify query parameters such as `filterByOrgVisibility`, `includeTerminatedWorkers`, or `search` to filter for specific workers.

    To identify the ID of the current user, call `GET /workers/me`.

-   A request body containing at least the effective date.


Sample request:

Call the <i>Staffing</i> service to initiate a Home Contact Change event for worker Teresa Serrano with the effective date of 2026-04-14:

```
POST workers/26c439a5deed4a7dbab76709e0d2d2ca/homeContactInformationChanges
```

Request Body:

```
{
  "effective_date": "2026-04-14"
}
```

Sample Response:

```
{
  "descriptor": "Home Contact Change: Teresa Serrano",
  "effective_date": "2026-04-14",
  "href": "https://api.us.wcp.workday.com/person/v4/homeContactInformationChanges/26c439a5deed4a7dbab76709e0d2d2ca",
  "id": "f4edd719789a10011cc961767fd10000"
}
```

Save the `id` from the response as you’ll use this Home or Work Contact Change `id` in the subsequent contact information change API calls.

## Editing the Home or Work Contact Information Data

Once you initiate a Home or Work Contact Change event, call any of these endpoints in the <i>Person</i> service for the respective event to modify it:

-   `PATCH /homeContactInformationChanges/{id}/{subresource}/{subresourceID}`
-   `PATCH /workContactInformationChanges/{id}/{subresource}/{subresourceID}`
-   `PUT /homeContactInformationChanges/{id}/addresses/{subresourceID}`
-   `PUT /workContactInformationChanges/{id}/addresses/{subresourceID}`
-   `DELETE /homeContactInformationChanges/{id}/{subresource}/{subresourceID}`
-   `DELETE /workContactInformationChanges/{id}/{subresource}/{subresourceID}`


The `{subresource}` can be:

-   `webAddresses`
-   `phoneNumbers`
-   `instantMessengers`
-   `emailAddresses`
-   `addresses`

    This subresource is only applicable for DELETE endpoints.



To construct the request, you need:

-   The Home or Work Contact Change event ID.

    The ID is the `id` returned from the event equivalent endpoint responses in the <i>Staffing</i> service:

    -   `GET /workers/{id}/homeContactInformationChanges/{subresourceID}`
    -   `GET /workers/{id}/workContactInformationChanges/{subresourceID}`

-   The address ID, if calling the PUT endpoints.

    The address ID is the subresource `ID` returned from the event equivalent endpoint responses in the <i>Person</i> service:

    -   `GET /homeContactInformationChanges/{id}/addresses`
    -   `GET /workContactInformationChanges/{id}/addresses`

-   A request body containing the data to update.

    The Contact Information Changes REST APIs provide corresponding GET endpoints. You can call these endpoints in the <i>Person</i> service to retrieve existing data about the Home or Work Change Contact section:

    -   `GET /homeContactInformationChanges/{id}/{subresource}`
    -   `GET /workContactInformationChanges/{id}/{subresource}`

    Additionally, you can also call `GET /countries/{ID}/addressComponents` to retrieve country specific information for address contact information changes.

    You can use the response data to populate the request body for the PATCH, PUT, and DELETE endpoints. Note that the PATCH endpoints perform partial updates. They only update the fields included in the request body.



Sample request:

Call the <i>Person</i> service endpoint to retrieve existing home address details for Teresa Serrano.

```
GET /homeContactInformationChanges/f4edd719789a10011cc961767fd10000/address
```

Sample Response:

```
{
  "data": [
    {
      "addressLine1": "265 East 68th Street, #18",
      "city": "New York",
      "usage": {
        "primary": true,
        "public": false,
        "usageType": {
          "descriptor": "Home",
          "id": "836cf00ef5974ac08b786079866c946f"
        }
      },
      "effective": "2026-04-14",
      "country": {
        "ISO_3166-1_Alpha-3_Code": "USA",
        "id": "bc33aa3152ec42d4995f4791a106ed09",
        "ISO_3166-1_Numeric-3_Code": 840,
        "ISO_3166-1_Alpha-2_Code": "US",
        "descriptor": "United States of America"
      },
      "Address_ID": "Teresa_Serrano_265_East_68th_Street_18",
      "countryRegion": {
        "Country_Region_ID": "USA-NY",
        "ISO_3166-2_Code": "NY",
        "descriptor": "New York",
        "id": "9819bf0148e54f89adb255aa7bead635"
      },
      "postalCode": "10021",
      "id": "3a872245e3cc4d438e01febf619c3275"
    }
  ],
  "total": 1
}
```

Sample Request:

Call the <i>Person</i> service endpoint to change the home address section of the Home Contact Change event:

```
PUT /homeContactInformationChanges/f4edd719789a10011cc961767fd10000/address/3a872245e3cc4d438e01febf619c3275
```

Request Body:

```
{
  "addressLine1": "26 East 68th Street, #1",
  "city": "New York",
  "usage": {
    "primary": true,
    "public": false,
    "usageType": {
      "descriptor": "Home",
      "id": "836cf00ef5974ac08b786079866c946f"
    }
  },
  "country": {
    "ISO_3166-1_Alpha-3_Code": "USA",
    "id": "bc33aa3152ec42d4995f4791a106ed09",
    "ISO_3166-1_Numeric-3_Code": 840,
    "ISO_3166-1_Alpha-2_Code": "US",
    "descriptor": "United States of America"
  },
  "countryRegion": {
    "Country_Region_ID": "USA-NY",
    "ISO_3166-2_Code": "NY",
    "descriptor": "New York",
    "id": "9819bf0148e54f89adb255aa7bead635"
  },
  "postalCode": "10021",
  "id": "3a872245e3cc4d438e01febf619c3275"
}
```

Sample Response:

```
{
  "addressLine1": "26 East 68th Street, #1",
  "city": "New York",
  "usage": {
    "primary": true,
    "public": false,
    "usageType": {
      "descriptor": "Home",
      "id": "836cf00ef5974ac08b786079866c946f"
    }
  },
  "effective": "2026-04-14",
  "country": {
    "ISO_3166-1_Alpha-3_Code": "USA",
    "id": "bc33aa3152ec42d4995f4791a106ed09",
    "ISO_3166-1_Numeric-3_Code": 840,
    "ISO_3166-1_Alpha-2_Code": "US",
    "descriptor": "United States of America"
  },
  "Address_ID": "Teresa_Serrano_265_East_68th_Street_18",
  "countryRegion": {
    "Country_Region_ID": "USA-NY",
    "ISO_3166-2_Code": "NY",
    "descriptor": "New York",
    "id": "9819bf0148e54f89adb255aa7bead635"
  },
  "postalCode": "10021",
  "id": "3a872245e3cc4d438e01febf619c3275"
}
```

## Submitting a Home or Work Contact Change Event

Submit the Home or Work Contact Change event after editing the events by calling the respective endpoint in the <i>Person</i> service and using the event ID:

-   `POST /homeContactInformationChanges/{id}/submit`
-   `POST /workContactInformationChanges/{id}/submit`


Specify an empty request body.

Sample request:

Call the <i>Person</i> service endpoint to submit the Home Contact Change event for address update for Teresa Serrano:

```
POST /homeContactInformationChanges/f4edd719789a10011cc961767fd10000/submit
```

Request Body:

```
{ }
```

Sample Response:

```
{
  "businessProcessParameters": {
    "for": {
      "descriptor": "Teresa Serrano",
      "href": "https://api.us.wcp.workday.com/person/v4/people/2f1daceacd464fdbae3cd6b267d679c6",
      "id": "2f1daceacd464fdbae3cd6b267d679c6"
    },
    "overallBusinessProcess": {
      "descriptor": "Home Contact Change: Teresa Serrano",
      "id": "f4edd719789a10011cc961767fd10000"
    },
    "overallStatus": "Successfully Completed",
    "transactionStatus": {
      "descriptor": "Successfully Completed",
      "id": "b90bc51be01d4ae99b603b02b073714d"
    }
  },
  "descriptor": "Home Contact Change: Teresa Serrano",
  "id": "f4edd719789a10011cc961767fd10000"
}
```

## Saving the Home or Work Contact Change Event

After editing the Home or Work Change Contact Data by using the PATCH, PUT, or DELETE endpoints, you have the option to save the event for a later submission. To save the event for later, call either of these endpoints in the <i>Person</i> service:

-   `POST /homeContactInformationChanges/{id}/submit`, where the `id` is the Home Change Contact event ID.
-   `POST /workContactInformationChanges/{id}/submit`, where the `id` is the Work Change Contact event ID.


Specify this exact request body, which contains the Save for Later action `id`:

```
{
  "businessProcessParameters": {
    "action":{
      "id": "d9e41a8c446c11de98360015c5e6daf6"
    }
  }
}
```

The `POST /jobChanges/{ID}/submit` endpoint is equivalent to clicking <b>Save for Later</b> on the <b>Change Home Contact Information</b> or <b>Change Work Contact Information</b> task. This endpoint submits the business process and sets the status to <i>In Progress</i>. After submission, you can no longer submit any of the Contact Information Changes REST APIs with the same event ID. Users with the correct permissions can revise the events and submit it in the Workday UI.

Sample request:

Call the <i>Person</i> service to save the Home Contact Change event with the address update for later:

```
POST /homeContactInformationChanges/f4edd719789a10011cc961767fd10000/submit
```

Request Body:

```
{
  "businessProcessParameters": {
    "action":{
      "id": "d9e41a8c446c11de98360015c5e6daf6"
    }
  }
}
```

Sample Response:

```
{
  "businessProcessParameters": {
    "for": {
      "descriptor": "Teresa Serrano",
      "href": "https://api.us.wcp.workday.com/person/v4/people/2f1daceacd464fdbae3cd6b267d679c6",
      "id": "2f1daceacd464fdbae3cd6b267d679c6"
    },
    "overallBusinessProcess": {
      "descriptor": "Home Contact Change: Teresa Serrano",
      "id": "f4edd719789a10011cc961767fd10000"
    },
    "overallStatus": "In Progress",
    "transactionStatus": {
      "descriptor": "In Progress",
      "id": "e2d08afc53614c37b32b31270bb8bee3"
    }
  },
  "descriptor": "Home Contact Change: Teresa Serrano",
  "id": "f4edd719789a10011cc961767fd10000"
}
```

## Limitations

The Contact Information Changes REST APIs don’t support Global Address Lookup. However, users can perform this change in the Workday UI.

## Common Errors

<table><thead><tr><th>Error</th><th>Error Code</th><th>Cause and Solution</th></tr></thead><tbody><tr><td><i>Missing fields are required for [proposed country]: [missing required fields].</i></td><td>A662</td><td><p>Country fields on the PUT calls require specific information. To find those values, you can use the <code>GET countries/{ID}/addressComponents</code> endpoint in the <i>Person</i> service.</p> <p>To construct the request, you need the ID of the country. Call the <code>GET /countries/</code> endpoint to get the country ID.</p></td></tr></tbody></table><br/>