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 |
|---|---|---|---|
| Worker Profile ElementHome Address, Phone & Personal Email | Read Endpoint ( person/v4 REST)GET /people/{ID}/homeAddresses, /homePhones, /homeEmails |
Write Endpoint / OperationStage via POST /staffing/v7/workers/{ID}/homeContactInformationChanges, edit /person/v4/homeContactInformationChanges/{ID}/..., then POST .../submit (or SOAP Change_Home_Contact_Information). |
Required Scope & Security PolicyScope: Contact Information; BP: Home Contact Change; Domains: Self-Service: Home Address, Home Phone, Home Email. |
| Worker Profile ElementWork Contact & Alternate Work Location | Read Endpoint ( person/v4 REST)GET /people/{ID}/workAddresses, /workPhones, /workEmails |
Write Endpoint / OperationStage via POST /staffing/v7/workers/{ID}/workContactInformationChanges, edit /person/v4/workContactInformationChanges/{ID}/..., then POST .../submit. |
Required Scope & Security PolicyScope: Contact Information; BP: Work Contact Change; Domains: Self-Service: Work Address, Work Phone, Work Email. |
| Worker Profile ElementPreferred Name | Read Endpoint ( person/v4 REST)GET /people/{ID}/preferredName |
Write Endpoint / OperationSOAP Human_Resources: Change_Preferred_Name (Use_Legal_Name_As_Preferred_Name or Name_Data). |
Required Scope & Security PolicyScope: Contact Information; BP: Preferred Name Change; Domain: Self-Service: Preferred Name. |
| Worker Profile ElementLegal Name | Read Endpoint ( person/v4 REST)GET /people/{ID}/legalName |
Write Endpoint / OperationSOAP Human_Resources: Change_Legal_Name (typically triggers HR approval + government ID document attachment). |
Required Scope & Security PolicyScope: Contact Information; BP: Legal Name Change; Domain: Self-Service: Legal Name. |
| Worker Profile ElementPronouns & Personal Info | Read Endpoint ( person/v4 REST)GET /people/{ID}/personalInformation & SOAP Get_Pronouns |
Write Endpoint / OperationSOAP Human_Resources: Change_Personal_Information (paired with Maintain Public Profile Preference). |
Required Scope & Security PolicyScope: 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:
GET /person/v4/countries/{country_WID}/addressComponentsto inspect allowed and required address lines and region prompts for the target country.POST /person/v4/phoneValidationwith{ "completePhoneNumber": "+12065550148" }(plusGET /values/commonPhone/phoneDeviceTypesand/countryPhoneCodes) to verify Workday accepts the phone format before opening a draft event.
Step 2: Create the Staged Event, Modify Subresources, and Submit
- Start the Event:
POST /ccx/api/staffing/v7/{tenant}/workers/{worker_WID}/homeContactInformationChangeswith an empty or effective-dated body{}. Workday returns the staged eventid(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 viaGET /person/v4/homeContactInformationChangesrather than creating a duplicate. - Stage Address / Phone Updates: Add or update staged subresources under
person/v4using that eventid:
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
}
}- 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
{}(passingd9e41a8c446c11de98360015c5e6daf6inbusinessProcessParameters.action.idsaves for later instead of submitting):
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 asWithholding ElectionsW-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):
<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:
Use_Legal_Name_As_Preferred_NameMutual 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, whenfalse,Name_Datamust satisfy everyRequiredname component configured for that country inMaintain Name Components by Country.- Pronoun Visibility & In-Progress Locks: Reading configured pronouns via
Get_Pronounsand updating personal details viaChange_Personal_InformationrequiresPerson Data: Personal Information/Self-Service: Personal Informationunder thePersonal Datascope, and fails immediately if anotherChange Personal Informationevent 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 inMaintain Public Profile Preferenceand the employee selectsShow to allinChange 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 (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 (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.