---
title: "Workday Person API: Preferred Name, Pronouns & Contact"
description: "How to stage and submit Home Contact Change, Preferred Name Change, and Personal Information pronoun updates using Workday Person/Staffing REST and SOAP APIs."
url: https://kiweely.com/guides/workday-person-api-legal-preferred-name-contact-updates
---

# Updating Preferred Name, Pronouns, and Contact Information via the Workday Person API

Workday splits worker profile updates across REST and SOAP: Home and Work Contact Changes stage subresources in staffing v7 and person v4 before POST /submit, whereas Preferred Name Change and pronoun updates use Human\_Resources SOAP (Change\_Preferred\_Name, Change\_Personal\_Information).

-   **Checked** against Workday on November 15
-   Applies to **Workday Person & HCM APIs**
-   5 min read
-   Published November 15
-   By Kiweely

Updating an employee’s contact details, preferred name, and profile pronouns in Workday spans two complementary API patterns under user-delegated OAuth: **Home and Work Contact Information Changes** use a multi-step REST staging pattern across `staffing/v7` and `person/v4` (`POST /workers/{ID}/homeContactInformationChanges` -> subresource edits -> `POST /homeContactInformationChanges/{ID}/submit`), while **Preferred Name** (`Preferred Name Change`), **Legal Name** (`Legal Name Change`), and **Pronouns** (`Change Personal Information`) read via `person/v4` REST and execute writes through the **`Human_Resources` SOAP web service** using the same OAuth Bearer credential.

Because every one of these changes initiates an audited Workday **Business Process**—affecting tax jurisdiction addresses, badge directories, and payroll records—Workday never allows raw table overwrites on `/people/{ID}`. Following Workday’s country component metadata and business-process staging rules prevents partial drafts and country validation failures.

## Mapping Profile Read & Write Operations Across REST and SOAP

| Worker Profile Element | Read Endpoint (`person/v4` REST) | Write Endpoint / Operation | Required Scope & Security Policy |
| --- | --- | --- | --- |
|  **Home Address, Phone & Personal Email** | `GET /people/{ID}/homeAddresses`, `/homePhones`, `/homeEmails` | Stage via `POST /staffing/v7/workers/{ID}/homeContactInformationChanges`, edit `/person/v4/homeContactInformationChanges/{ID}/...`, then `POST .../submit` (or SOAP `Change_Home_Contact_Information`). | Scope: `Contact Information`; BP: `Home Contact Change`; Domains: `Self-Service: Home Address`, `Home Phone`, `Home Email`. |
|  **Work Contact & Alternate Work Location** | `GET /people/{ID}/workAddresses`, `/workPhones`, `/workEmails` | Stage via `POST /staffing/v7/workers/{ID}/workContactInformationChanges`, edit `/person/v4/workContactInformationChanges/{ID}/...`, then `POST .../submit`. | Scope: `Contact Information`; BP: `Work Contact Change`; Domains: `Self-Service: Work Address`, `Work Phone`, `Work Email`. |
|  **Preferred Name** | `GET /people/{ID}/preferredName` | SOAP `Human_Resources`: `Change_Preferred_Name` (`Use_Legal_Name_As_Preferred_Name` or `Name_Data`). | Scope: `Contact Information`; BP: `Preferred Name Change`; Domain: `Self-Service: Preferred Name`. |
|  **Legal Name** | `GET /people/{ID}/legalName` | SOAP `Human_Resources`: `Change_Legal_Name` (typically triggers HR approval + government ID document attachment). | Scope: `Contact Information`; BP: `Legal Name Change`; Domain: `Self-Service: Legal Name`. |
|  **Pronouns & Personal Info** | `GET /people/{ID}/personalInformation` & SOAP `Get_Pronouns` | SOAP `Human_Resources`: `Change_Personal_Information` (paired with `Maintain Public Profile Preference`). | Scope: `Personal Data`; BP: `Change Personal Information`; Domain: `Self-Service: Personal Information`, `Person Data: Personal Information`. |

## Step-by-Step: Staging and Submitting a Home Contact Change in REST

Unlike single-shot endpoints, `person/v4` models **Home Contact Change** as a stateful staged business process so an employee can update a street address, add a mobile phone number, and remove an outdated personal email inside a **single** atomic approval event.

### Step 1: Pre-Validate Country Address Components and Phone Format

Never assume US `addressLine1` + `city` + `countryRegion` + `postalCode` rules apply globally—Japanese, UK, and Brazilian addresses require different `webServiceAlias` fields. Call these metadata endpoints first:

1.  `GET /person/v4/countries/{country_WID}/addressComponents` to inspect allowed and required address lines and region prompts for the target country.
2.  `POST /person/v4/phoneValidation` with `{ "completePhoneNumber": "+12065550148" }` (plus `GET /values/commonPhone/phoneDeviceTypes` and `/countryPhoneCodes`) to verify Workday accepts the phone format before opening a draft event.

### Step 2: Create the Staged Event, Modify Subresources, and Submit

1.  **Start the Event:** `POST /ccx/api/staffing/v7/{tenant}/workers/{worker_WID}/homeContactInformationChanges` with an empty or effective-dated body `{}`. Workday returns the staged event `id` (for example, `f42ba27d87ed10001aa58a5d231b1621`). Note: Workday allows only **one** in-progress Home Contact Change event per person at a time; if a draft already exists, retrieve it via `GET /person/v4/homeContactInformationChanges` rather than creating a duplicate.
2.  **Stage Address / Phone Updates:** Add or update staged subresources under `person/v4` using that event `id`:

http

```
POST /ccx/api/person/v4/{tenant}/homeContactInformationChanges/f42ba27d87ed10001aa58a5d231b1621/addresses HTTP/1.1
Authorization: Bearer <user_delegated_access_credential>
Content-Type: application/json

{
  "addressLine1": "410 Terry Ave N",
  "addressLine2": "Apt 504",
  "city": "Seattle",
  "countryRegion": {
    "id": "ec3d210e446c11de98360015c5e6daf6"
  },
  "postalCode": "98109",
  "country": {
    "id": "bc33aa3152ec42d4995f4791a106ed09"
  },
  "usage": {
    "primary": true,
    "public": false
  }
}
```

1.  **Commit and Initiate Business Process Routing:** Nothing changes on the worker’s live Person record until you submit the staged parent event with an empty JSON object `{}` (passing `d9e41a8c446c11de98360015c5e6daf6` in `businessProcessParameters.action.id` saves for later instead of submitting):

http

```
POST /ccx/api/person/v4/{tenant}/homeContactInformationChanges/f42ba27d87ed10001aa58a5d231b1621/submit HTTP/1.1
Authorization: Bearer <user_delegated_access_credential>
Content-Type: application/json

{}
```

-   Tax impact warning: In Workday US Payroll, submitting a new primary Home Address in a different state or local tax jurisdiction commonly triggers conditional subprocesses on `Home Contact Change` (such as `Withholding Elections` W-4 updates or Payroll Partner review).

## Updating Preferred Name and Pronouns via `Human_Resources` SOAP

While `GET /person/v4/people/{ID}/preferredName` and `GET /person/v4/countries/{ID}/nameComponents` read current preferred names and country-specific component rules (`Maintain Name Components by Country`), submitting a **Preferred Name Change** over an API uses `Change_Preferred_Name` in the **`Human_Resources` SOAP web service**—authenticated with the exact same user-delegated OAuth 2.0 `Authorization: Bearer` header (see [calling Workday SOAP with an OAuth Bearer token](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)):

xml

```
<bsvc:Change_Preferred_Name_Request xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="v43.0">
  <bsvc:Business_Process_Parameters>
    <bsvc:Auto_Complete>true</bsvc:Auto_Complete>
    <bsvc:Run_Now>true</bsvc:Run_Now>
  </bsvc:Business_Process_Parameters>
  <bsvc:Change_Preferred_Name_Data>
    <bsvc:Person_Reference>
      <bsvc:ID bsvc:type="WID">3aa5550b7fe348b98d7b5741afc6f534</bsvc:ID>
    </bsvc:Person_Reference>
    <bsvc:Use_Legal_Name_As_Preferred_Name>false</bsvc:Use_Legal_Name_As_Preferred_Name>
    <bsvc:Name_Data>
      <bsvc:Country_Reference>
        <bsvc:ID bsvc:type="ISO_3166-1_Alpha-3_Code">USA</bsvc:ID>
      </bsvc:Country_Reference>
      <bsvc:First_Name>Sam</bsvc:First_Name>
      <bsvc:Last_Name>Rostova</bsvc:Last_Name>
    </bsvc:Name_Data>
  </bsvc:Change_Preferred_Name_Data>
</bsvc:Change_Preferred_Name_Request>
```

Watch two strict validation rules on `Change_Preferred_Name` and `Change_Personal_Information`:

1.  **`Use_Legal_Name_As_Preferred_Name` Mutual Exclusivity:** If a worker resets their preferred name back to match their legal name (`<bsvc:Use_Legal_Name_As_Preferred_Name>true</bsvc:Use_Legal_Name_As_Preferred_Name>`), you **must omit** `<bsvc:Name_Data>`—sending both throws a schema validation error. Conversely, when `false`, `Name_Data` must satisfy every `Required` name component configured for that country in `Maintain Name Components by Country`.
2.  **Pronoun Visibility & In-Progress Locks:** Reading configured pronouns via `Get_Pronouns` and updating personal details via `Change_Personal_Information` requires `Person Data: Personal Information` / `Self-Service: Personal Information` under the `Personal Data` scope, and fails immediately if another `Change Personal Information` event is already awaiting approval for that worker (`You cannot submit this request because another personal information change event is already in progress for this worker`). Pronouns also appear to coworkers on the public Worker Profile only when the admin enables **Pronoun** in `Maintain Public Profile Preference` and the employee selects `Show to all` in `Change Public Profile Preferences`.

Whether you want new hires to confirm their preferred name, pronouns, and home address on day one in a clean onboarding page via **[Kiweely Leaf](https://kiweely.com/leaf)** (coming next, stateless pass-through screens without a Workday Extend license) or let employees update their home address from **Claude, ChatGPT, or Gemini** via **[Kiweely Bridge](https://kiweely.com/bridge)** (coming next, pausing on an out-of-band browser card showing *Now* vs. *After* before calling `submit`), running every call under user-delegated OAuth preserves Workday’s exact business process approvals and audit trail.

## Frequently asked questions

### Why does person v4 REST have GET /people/{ID}/preferredName without a direct PUT /preferredName endpoint?

In person v4, name and personal information subresources under /people/{ID} are read-only projections. Updating a worker's preferred name or legal name triggers the Preferred Name Change or Legal Name Change business process via Change\_Preferred\_Name or Change\_Legal\_Name in the Human\_Resources SOAP web service.

### How does staging work for Home Contact Change in the Workday REST API?

First initiate a draft event via POST /staffing/v7/workers/{ID}/homeContactInformationChanges to obtain an event ID, then POST, PATCH, PUT, or DELETE staged addresses, phoneNumbers, or emailAddresses on /person/v4/homeContactInformationChanges/{eventID}/..., and finally call POST /homeContactInformationChanges/{eventID}/submit with {}.

### Why do address or name submissions fail for international workers across countries?

Each country defines its own allowed and required fields in Maintain Name Components by Country and country address formats. Always query GET /person/v4/countries/{ID}/addressComponents and GET /countries/{ID}/nameComponents (and POST /phoneValidation) before constructing payloads.

### Which tasks control whether a worker's pronouns appear on their public Workday profile?

Administrators enable the Pronoun checkbox in Maintain Public Profile Preference (Set Up: Public Profile), and workers set both their pronoun value in Change Personal Information (Person Data: Personal Information) and their sharing visibility (Show to all) in Change Public Profile Preferences.

## Sources checked

-   [Steps: Set Up Contact Information](https://doc.workday.com/admin-guide/en-us/human-capital-management/worker-information/contact-and-personal-information/contact-information/dan1370796752303.html)
-   [Set Up Name Components](https://doc.workday.com/admin-guide/en-us/human-capital-management/worker-information/contact-and-personal-information/names/mnj1565029510116.html)
-   [Maintain Name Components by Country](https://doc.workday.com/admin-guide/en-us/human-capital-management/country-specific-information-and-reporting/locally-required-information/dsk1548262477716.html)
-   [Steps: Set Up Gender Pronouns to Display on a Worker Profile](https://doc.workday.com/admin-guide/en-us/human-capital-management/worker-information/contact-and-personal-information/personal-information/kll1613084574255.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token Send Workday SOAP requests with an HTTP Authorization Bearer header issued from a user-delegated OAuth 2.0 Authorization Code grant and leave the SOAP XML Header element empty. Workday evaluates both the API Client Functional Area scope and the signed-in worker’s Integration Permissions.](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)
-   [### Parsing Workday Business Process Custom Validation Errors Returned by REST and SOAP APIs Workday REST APIs return HTTP 400 JSON payloads containing an errors array with code, field, path, and severity (Critical or Warning), whereas Workday SOAP Web Services return HTTP 500 envelopes containing Validation\_Fault (with Xpath) or Processing\_Fault elements.](https://kiweely.com/guides/workday-business-process-validation-errors-rest-soap-responses)
-   [### How Workday Audits Business Processes Initiated via REST or SOAP Web Services Workday records every web-service-initiated business process in the Full Process Record and View Audit Trail under the authenticated Workday account. Whether that audit trail shows a real employee or a shared system bot depends on whether the caller used user-delegated OAuth or an ISU.](https://kiweely.com/guides/workday-business-process-audit-trail-initiated-via-web-service)
-   [### How to Configure User-Delegated OAuth 2.0 Authorization Code Grant in Workday Register a user-delegated Workday OAuth 2.0 client using Register API Client with Authorization Code Grant, PKCE (S256), and Bearer credentials so external applications authenticate employees through SSO and run under their own Workday permissions.](https://kiweely.com/guides/workday-authorization-code-grant-user-delegated-oauth-setup)

### More guides on Integrations and APIs

[All 89 guides](https://kiweely.com/guides#integrations)

-   [Restricting Workday OAuth Token Use by IP with Maintain IP Ranges](https://kiweely.com/guides/workday-maintain-ip-ranges-manage-authentication-policies-api)
-   [Why Browser Single-Page Apps Hit CORS and Token Limits Against Workday APIs—and How to Fix It](https://kiweely.com/guides/workday-cors-browser-api-calls-why-backend-pass-through-needed)
-   [Approving, Denying, and Sending Back Workday Business Process Steps via REST and SOAP APIs](https://kiweely.com/guides/workday-business-process-approve-deny-rest-soap-api)
-   [How Workday Studio PutIntegrationMessage Severity Levels Control Completed-with-Warnings vs. Aborted Runs](https://kiweely.com/guides/workday-studio-error-severity-critical-warning-abort)
-   [How to Fix Workday Studio SDKProfile Not Current and Unsigned Software Startup Errors on Mac and Windows](https://kiweely.com/guides/workday-studio-sdkprofile-not-current-unsigned-macos-errors)
-   [How to Authenticate Workday Studio and External Tools Using an OAuth API Client with PKCE (When SSO Blocks Passwords)](https://kiweely.com/guides/workday-api-client-pkce-sso-without-workday-password)
-   [Workday PECI vs. PICOF Payroll Connectors: How Effective-Dated Stack and Retro Changes Export](https://kiweely.com/guides/workday-peci-picof-payroll-connector-change-detection)
-   [Why does my Workday Accounting Journal EIB fail? Balancing, worktag and period errors](https://kiweely.com/guides/workday-financials-accounting-journal-eib-validation-errors)

### From the blog on Integrations and APIs

[All posts](https://kiweely.com/blog)

-   [Mapping Microsoft Teams, Slack, DingTalk, and Lark Identities to Workday Worker OAuth](https://kiweely.com/blog/mapping-teams-slack-lark-sso-identities-to-workday-workers)
-   [How Workday’s Twice-Yearly Releases Break In-House MCP Servers and REST Integrations](https://kiweely.com/blog/how-workday-twice-yearly-releases-break-custom-mcp-servers)
-   [Turning Your Existing Workday RaaS Reports into Governed AI Tools](https://kiweely.com/blog/exposing-existing-workday-raas-reports-to-claude-and-chatgpt)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
