Skip to content
KiweelyKiweelyKiweely

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
  • Applies to Workday HCM Personal Information
  • 7 min read
  • Published
  • By Kiweely
On this page

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
Country / Format ModeUnited States (USA) Non-Configurable Baseline Required ComponentsAddress Line 1, City, Region (labeled State), Postal Code Key Country-Specific Validation TrapRegion must match a valid US state reference; Postal Code validates 5-digit or ZIP+4 rules; tax authorities depend on accurate residential jurisdiction.
Country / Format ModeCanada (CAN) Non-Configurable Baseline Required ComponentsAddress Line 1, Region (labeled Province), Postal Code (A1A 1A1 format) Key Country-Specific Validation TrapSubmitting a US state code or unformatted 5-digit number fails Region Name and postal format checks; City is configurable separately from baseline.
Country / Format ModeJapan (JPN) Non-Configurable Baseline Required ComponentsPostal Code, City, Address Line 1 (ordered Postal Code first) Key Country-Specific Validation TrapSupports Local Script (Kanji/Kana) alongside Western script depending on Western Script Required / Local Script Required / Enable Enter Western Script Check Box.
Country / Format ModeExtended Format Countries (29 countries including DEU, FRA, NLD, ESP, BRA, SGP, CHE) Non-Configurable Baseline Required ComponentsSeparate Street Name and House Number fields when Extended Format is enabled Key Country-Specific Validation TrapBasic 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
Emergency Contact RuleMandatory Name & Relationship Exact Workday Validation Fault When ViolatedPlease Specify a Contact Name / Please specify the Related Person Relationship. How to Prevent the FailureRequire Legal Name components valid for the contact’s country plus a relationship allowed for that country (Specify a valid relationship value for the country).
Emergency Contact RuleAt Least One Reachable Channel Exact Workday Validation Fault When ViolatedEither a phone number, or an email address must be specified for an emergency contact. How to Prevent the FailureRequire at least one valid phone number (validated against Country Phone Code) or electronic mail address before enabling Submit.
Emergency Contact RuleExactly One Primary (Priority = 1) Exact Workday Validation Fault When ViolatedOne and only one emergency contact can be specified as Primary. / Primary emergency contact must have numeric priority of 1. How to Prevent the FailureLock 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).
Emergency Contact RuleNo Deleting Primary Without Replacement Exact Workday Validation Fault When ViolatedPrimary Emergency Contact cannot be deleted. / Primary Emergency Contact must be specified when Replace All is set. How to Prevent the FailureTo 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.
Emergency Contact RuleIn-Flight BP Lock & Dependent Link Exact Workday Validation Fault When ViolatedYou cannot initiate this action because there are other pending or completed actions for the person. How to Prevent the FailureCheck 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) 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 (coming next) or enabling governed employee updates in Kiweely 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

Related guides

All guides

Let Workday check the work.

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

Get the next guide in your inbox.

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

We’ll email you once to confirm. Unsubscribe in one click from any issue.