---
title: "Workday Country Address & Emergency Contact Validations"
description: "How Workday Maintain Address Components by Country, Global Address Validation, libphonenumber, and Change Emergency Contacts enforce self-service rules."
url: https://kiweely.com/guides/workday-emergency-contact-home-address-change-validation-rules
---

# Validating Country-Specific Address and Emergency Contact Formats in Workday Self-Service

Workday validates home addresses, phone numbers, and emergency contacts by country—enforcing required components, extended street/house-number splits, Google libphonenumber rules, and exact Primary Priority = 1 constraints across UI tasks and REST/SOAP APIs.

-   **Checked** against Workday on November 15
-   Applies to **Workday HCM Personal Information**
-   7 min read
-   Published November 15
-   By Kiweely

Workday never treats a home address, phone number, or emergency contact as a generic universal schema: required address lines, postal codes, state/province regions, local scripts, and phone digit lengths dynamically change **per country**, while **Home Contact Change** and **Change Emergency Contacts** enforce strict primary-record invariants. Any self-service form or integration that hardcodes US `Address Line 1 + City + State + ZIP` fields will fail with `Validation_Fault` or `400 Bad Request` the moment a Canadian, German, Japanese, or Brazilian worker submits an update.

## 1\. Country-Specific Address Components, Extended Formats, and Local Scripts

Workday governs address schemas through three tenant configuration tasks: **`Maintain Address Components by Country`** (`Set Up: Contact Info, IDs, and Personal Data` domain), **`Edit Tenant Setup - Global`**, and **`Maintain Localization Settings`** (`Set Up: Tenant Setup - Global` domain).

### Baseline Required Components & Extended Address Formats

Certain baseline components are hardcoded as required by country and cannot be disabled, while additional components can be toggled **Allowed**, **Required**, and **Enforce Required in Web Services**:

| Country / Format Mode | Non-Configurable Baseline Required Components | Key Country-Specific Validation Trap |
| --- | --- | --- |
|  **United States (`USA`)** | `Address Line 1`, `City`, `Region` (labeled *State*), `Postal Code` | `Region` must match a valid US state reference; `Postal Code` validates 5-digit or ZIP+4 rules; tax authorities depend on accurate residential jurisdiction. |
|  **Canada (`CAN`)** | `Address Line 1`, `Region` (labeled *Province*), `Postal Code` (`A1A 1A1` format) | Submitting a US state code or unformatted 5-digit number fails `Region Name` and postal format checks; *City* is configurable separately from baseline. |
|  **Japan (`JPN`)** | `Postal Code`, `City`, `Address Line 1` (ordered Postal Code first) | Supports **Local Script** (Kanji/Kana) alongside Western script depending on `Western Script Required` / `Local Script Required` / `Enable Enter Western Script Check Box`. |
|  **Extended Format Countries** (29 countries including `DEU`, `FRA`, `NLD`, `ESP`, `BRA`, `SGP`, `CHE`) | Separate **Street Name** and **House Number** fields when Extended Format is enabled | Basic format satisfies postal mail; **Extended Address Format** satisfies local payroll and statutory filings. Passing a combined street+number into an disallowed line triggers `Second Address Line is not a valid address component for certain countries`. |

Two critical rules apply when configuring `Maintain Address Components by Country`:

1.  **UI vs. Web Service Parity (`Enforce Required in Web Services`):** Checking `Required` enforces the field on Workday pages, but SOAP/REST web services only enforce that custom requirement when **`Enforce Required in Web Services`** is also checked. Run the **View Address Component Configuration Sync** report (and opt in to *Address Component Sync for Get Web Services* on `Maintain Feature Opt-Ins`) to catch mismatches.
2.  **Primary Home Address Cannot Be Deleted:** Once a primary home address is recorded on a worker (`Steps: Set Up Contact Information`), Workday allows changing or sharing it—never deleting it entirely. Also note that choosing parallel **`Home Contact Change`** + **`Work Contact Change`** business processes requires disabling security policies on the combined **`Contact Change`** business process so two competing workflows are not active simultaneously.

### Postal Verification (`Global Address Validation`)

When **Global Address Validation** is marked `Active` for selected countries under `Maintain Localization Settings` (*Area: Contact Information*), Workday checks entered addresses against official postal directories (`Change My Home Contact Information`), suggests a standardized replacement (up to 5 attempts), and exposes the **`Contact Change Event has Invalid Address`** boolean condition field so administrators can route unrecognized addresses to an HR Partner `Review` or `Approval` step on the business process.

## 2\. Discovering Country Address Schemas Dynamically (`person/v4`)

Instead of hardcoding country forms, query Workday’s `person/v4` REST metadata endpoint (`Secured By Domain: REST API Public`) to render exact country labels, display order, and required flags dynamically:

http

```
GET /ccx/api/person/v4/{tenant}/countries/ISO_3166-1_Alpha-3_Code=USA/addressComponents HTTP/1.1
Accept: application/json
```

Each returned component includes `componentType`, `label` (the country-specific override, e.g., `"State"` overriding generic `"Region"`), `order`, `required`, and `webServiceAlias`.

To submit a **Home Contact Change** via `person/v4` under the signed-in employee’s OAuth token (`Self-Service: Home Contact Information` domain + `Home Contact Change` initiating BP policy), execute Workday’s three-step transactional sequence—never forgetting step 3, because changes do not persist until `/submit` is called:

1.  **Initiate Event:** `POST /staffing/v7/workers/me/homeContactInformationChanges` (or `/person/v4/homeContactInformationChanges`) -> returns `{id}` for the staged event.
2.  **Stage Address / Phone Subresources:** `POST` or `PATCH /person/v4/homeContactInformationChanges/{id}/addresses` using the **Home** usage type (`836cf00ef5974ac08b786079866c946f`) and valid country/region IDs (`/values/countryComponents/countryRegion/`).
3.  **Commit Event:** `POST /person/v4/homeContactInformationChanges/{id}/submit`.

## 3\. Phone Number Validation (`libphonenumber` & `/phoneValidation`)

Workday requires **both** `Country Phone Code` and `Phone Number` (`Concept: Entering and Validating Phone Numbers`). When **Allowed Phone Validations** is enabled by country on `Edit Tenant Setup - Global`:

-   Workday validates digit counts and national numbering plans using Google’s **`libphonenumber`** library, enforcing distinct rules for **Mobile** vs. **Landline** device types (`Maintain Phone Device Types`; **VoIP** device types skip validation).
-   Valid numbers format automatically per **Phone Number View Format** on `Edit Tenant Setup - System` (*International* `+1 925-200-6574` by default, *E164* `+19252006574`, *National* `(925) 200-6574`, or *Workday Traditional*).
-   **Pre-Flight REST Check:** External screens can validate user input *before* submitting a business process by calling `POST /ccx/api/person/v4/{tenant}/phoneValidation` with `completePhoneNumber`—Workday returns `201` when valid for that country or `400` with the exact validation error. (Audit existing bad legacy data anytime via the **Invalid Phone Numbers** report.)

## 4\. `Change Emergency Contacts` Rules and Priority Invariants

Emergency contact updates run through the **`Change Emergency Contacts`** business process in the *Personal Data* functional area, secured by **`Self-Service: Emergency Contacts`** (for workers/pre-hires) and **`Person Data: Emergency Contacts`** (for HR roles), using relationship values configured on **`Maintain Related Person Relationships`**.

Whether submitted in the Workday UI or through the `Human_Resources` SOAP operation `Change_Emergency_Contacts` (authenticated with the worker’s user-delegated OAuth Bearer header), Workday enforces strict structural validations:

| Emergency Contact Rule | Exact Workday Validation Fault When Violated | How to Prevent the Failure |
| --- | --- | --- |
|  **Mandatory Name & Relationship** | `Please Specify a Contact Name` / `Please specify the Related Person Relationship.` | Require Legal Name components valid for the contact’s country plus a relationship allowed for that country (`Specify a valid relationship value for the country`). |
|  **At Least One Reachable Channel** | `Either a phone number, or an email address must be specified for an emergency contact.` | Require at least one valid phone number (validated against `Country Phone Code`) or electronic mail address before enabling Submit. |
|  **Exactly One Primary (`Priority = 1`)** | `One and only one emergency contact can be specified as Primary.` / `Primary emergency contact must have numeric priority of 1.` | Lock the designated Primary contact’s `Priority` to `1` and assign all Alternate contacts sequential integers **`> 1`** (`2`, `3`, ...; `Alternate emergency contacts must have priority greater than 1`). |
|  **No Deleting Primary Without Replacement** | `Primary Emergency Contact cannot be deleted.` / `Primary Emergency Contact must be specified when Replace All is set.` | To remove an old primary contact (e.g., after a divorce), promote another contact to `Primary = true` (`Priority = 1`) in the same payload or set `Replace_All = true` with a new Primary contact included. |
|  **In-Flight BP Lock & Dependent Link** | `You cannot initiate this action because there are other pending or completed actions for the person.` | Check for pending `Change Emergency Contacts` approvals first; note also custom BP validation rules if your tenant blocks editing contacts linked to Benefits Dependents/Beneficiaries. |

## Verification Checklist Before Exposing Contact Updates

1.  Inspect **`View Address Components by Country`** and **`View Address Component Configuration Sync`** for every country where your workforce resides.
2.  Check **`View Sample Phone Number Library`** and confirm **Allowed Phone Validations** on `Edit Tenant Setup - Global` matches your target countries.
3.  Verify `Employee as Self` (and [Pre-Employee as Self for pre-day-one onboarding](https://kiweely.com/guides/workday-pre-hire-onboarding-access-before-day-one-security)) holds `Modify` on `Self-Service: Home Address`, `Self-Service: Home Phone`, `Self-Service: Home Email`, and `Self-Service: Emergency Contacts`—while omitting `Self-Service: Work Contact Information` so workers cannot overwrite corporate office addresses.

When building simplified address and emergency-contact screens in **[Kiweely Leaf](https://kiweely.com/leaf)** (coming next) or enabling governed employee updates in **[Kiweely Bridge](https://kiweely.com/bridge)** (coming next, with a before-and-after browser approval card prior to every write), reading `/countries/{ID}/addressComponents` and `/phoneValidation` live under the employee’s own Workday token guarantees every country’s postal and priority rules pass cleanly on the first submit.

## Frequently asked questions

### Why does an address payload that works for a US worker fail with 'Second Address Line is not a valid address component' or missing House Number in another country?

Workday configures Allowed and Required address components per country on Maintain Address Components by Country, and 29 countries support Extended Address Formats (where Street Name and House Number are separate fields). Submitting a component unchecked for that country triggers an immediate validation fault.

### Can an employee or API delete a worker's Primary Home Address or Primary Emergency Contact in Workday?

No. Once a primary home address exists for a worker, you can update or share it, but you cannot delete it. Similarly, Workday enforces 'Primary Emergency Contact cannot be deleted' and requires exactly one Primary emergency contact with numeric priority 1.

### How does Workday validate mobile vs. landline phone numbers across countries?

When Allowed Phone Validations is enabled for a country on Edit Tenant Setup - Global, Workday uses Google's libphonenumber library against both Country Phone Code and Phone Number (with separate mobile and landline rules where applicable; VoIP device types bypass validation).

### Why didn't a required custom address component reject a missing value in a web service call?

Marking an optional component Required on Maintain Address Components by Country enforces it in the Workday UI, but web services only enforce that custom requirement when you also select the Enforce Required in Web Services checkbox.

## Sources checked

-   [Steps: Set Up Address Components by Country](https://doc.workday.com/admin-guide/en-us/human-capital-management/worker-information/contact-and-personal-information/addresses/hel1413571157066.html)
-   [Set Up Global Address Validation](https://doc.workday.com/admin-guide/en-us/human-capital-management/worker-information/contact-and-personal-information/addresses/set-up-global-address-validation.html)
-   [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)
-   [Concept: Entering and Validating Phone Numbers](https://doc.workday.com/admin-guide/en-us/human-capital-management/worker-information/contact-and-personal-information/phone-numbers/uiy1550170414587.html)
-   [Steps: Set Up Phone Numbers](https://doc.workday.com/admin-guide/en-us/human-capital-management/worker-information/contact-and-personal-information/phone-numbers/hel1413571186863.html)

## Related guides

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

-   [### Workday Preferred Display Language vs Preferred Locale: what each one changes, and why self-service items disappear Preferred Display Language sets the language of Workday labels and notifications; Preferred Locale sets date, time and number formats. Country fields follow the business site location, not either one. Sign out and back in after changing language.](https://kiweely.com/guides/workday-manage-user-language-locale-translations-self-service)
-   [### Diagnosing Workday REST API 403 Forbidden: Missing Client Scope vs. Worker Domain Security A Workday REST API 403 Forbidden means OAuth authentication succeeded, but authorization failed at one of five checkpoints: API Client Functional Area scope, stale pre-edit access grant, Report/Task Domain Security Policy, Business Process Security Policy, or unactivated pending policy changes.](https://kiweely.com/guides/workday-rest-api-403-forbidden-user-security-vs-client-scope)
-   [### Configuring Workday Pre-Hire Security So New Employees Can Complete Tasks Before Day One Future-dated completed hires in Workday belong to Pre-Employee as Self (or Pre-Contingent Worker as Self)—not Employee as Self—until their start date arrives. Synchronizing Hire step order, business process policies, and self-service domains unlocks pre-day-one tasks.](https://kiweely.com/guides/workday-pre-hire-onboarding-access-before-day-one-security)

### More guides on Business processes and security

[All 27 guides](https://kiweely.com/guides#business-processes)

-   [How Workday Task Delegation Works When Managers Approve Through APIs](https://kiweely.com/guides/workday-delegation-rules-external-approvals-acting-on-behalf)
-   [Why Workday Says ‘This Task Is Not Available’ or ‘Waiting on Initiator’ on a Business Process Step](https://kiweely.com/guides/workday-business-process-this-task-is-not-available)
-   [Why Can’t a Security Group See a Workday Dashboard or Worklet After You Added Permission?](https://kiweely.com/guides/workday-worklet-dashboard-not-visible-security)
-   [What does rescinded mean in Workday? Rescind vs cancel vs correct, and when each applies](https://kiweely.com/guides/workday-business-process-rescind-cancel-correct)
-   [Workday custom validations and condition rules: block bad data with Critical or Warning severity](https://kiweely.com/guides/workday-custom-validations-condition-rules)
-   [Workday Role-Based, User-Based, Intersection, and Aggregation Security Groups](https://kiweely.com/guides/workday-role-based-user-based-intersection-security-groups)
-   [Workday Domain Security vs. Business Process Security Policies: Which Controls What](https://kiweely.com/guides/workday-domain-vs-business-process-security-policies)
-   [Workday Business Process Advanced Routing: Exclude Initiator, Prior Approvers, and Alternates](https://kiweely.com/guides/workday-business-process-routing-mutual-exclusion)

### From the blog on Business processes and security

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

-   [Pass-Through Workday Screens vs. Caching HR Portals: Security and Sync Tradeoffs](https://kiweely.com/blog/pass-through-workday-ui-vs-caching-hr-portals)
-   [Five Things to Check in Your Workday Sandbox Before Connecting External AI or Custom Screens](https://kiweely.com/blog/preparing-your-workday-sandbox-for-kiweely-bridge-and-leaf)
-   [Designing Privacy-Safe Mobile Push Notifications for Workday Approvals and Pay Updates](https://kiweely.com/blog/privacy-safe-push-notifications-for-workday-tasks-on-phones)

## 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.
