Core HR API PATCH employee address fails with validation error for UK postal codes in up-2023.2 core-hr module

HCM UKG Pro
, , , , , , , ,
1

We’re encountering persistent validation errors when attempting to update employee addresses via PATCH requests to the Core HR API (v2023.2). The issue specifically occurs with US postal codes - our address updates work fine for most countries, but US addresses consistently return a 400 error with message “Invalid postal code format”.

Here’s our current PATCH payload:

PATCH /personnel/v1/employees/{id}/addresses
{
  "addressLine1": "123 Main St",
  "city": "Boston",
  "postalCode": "02101",
  "country": "US"
}

The postal code follows standard 5-digit format, but validation keeps failing. We’ve tried ZIP+4 format (02101-1234) which also fails. The error handling documentation mentions postal code normalization but doesn’t explain the expected format. This is blocking our quarterly address update process for 3,000+ employees. Has anyone successfully implemented address updates via the Core HR API and dealt with postal code validation requirements?

2

One more thing to check - does your UKG Pro tenant have address validation services enabled? Some organizations configure third-party address validation (like USPS or SmartyStreets) which adds additional normalization requirements beyond the standard API validation. If that’s enabled, your addresses need to match the validation service’s format exactly, which often means including standardized abbreviations (St instead of Street, etc.) and proper casing. You might need to pre-validate addresses through the same service before sending them to the API.

3

Thanks for the suggestions. I added the state field (“stateProvince”: “MA”) and specified addressType as “HOME” but still getting the same validation error. The content-type header is correctly set to application/json. I’m wondering if there’s a specific field order or if the postal code needs to be sent as a string vs number? Our payload builder was converting it to integer type which might be causing issues. Going to test with explicit string formatting.

4

Also check your content-type header. The Core HR API is particular about receiving “application/json” exactly. I’ve seen cases where “application/json; charset=utf-8” causes the validation layer to behave unpredictably. Another thing - are you including the addressType field? Residential vs mailing addresses have different validation rules in some UKG Pro configurations. Your payload should specify which address type you’re updating, especially if the employee has multiple addresses on file.

5

Based on the symptoms you’re describing, I think you’re hitting a combination of issues. Let me walk through the complete solution that worked for our implementation.

Postal Code Normalization: First, ensure postal codes are sent as strings with proper formatting. For US addresses, UKG Pro’s validation expects either 5-digit (“02101”) or 9-digit with hyphen (“02101-1234”) format. Never send as numeric type. The validation engine performs pattern matching that fails on non-string types.

Validation Error Handling: The Core HR API uses multi-layer validation. Layer 1 is schema validation (data types, required fields), Layer 2 is business rule validation (postal code/state combinations, address type rules). Your error is likely hitting Layer 2. To properly handle this:

PATCH /personnel/v1/employees/{id}/contact-information/addresses/{addressId}
{
  "addressType": "HOME",
  "addressLine1": "123 Main St",
  "city": "Boston",
  "stateProvince": "MA",
  "postalCode": "02101",
  "country": "USA"
}

Key differences from your payload: 1) Use full endpoint path with /contact-information/, 2) Include addressId in path if updating existing address, 3) Use “USA” instead of “US” for country code - UKG Pro internally normalizes to ISO 3166-1 alpha-3, 4) Include addressType in payload.

Address Update API Best Practices: Always retrieve the current address object first via GET, then modify and send back. This ensures you’re including all required fields that might not be obvious from documentation. Some fields like “effectiveDate” or “addressUsage” may be required depending on your tenant configuration. Also implement exponential backoff retry logic - address validation can occasionally timeout on the third-party validation service.

For bulk updates, consider using the batch API endpoint (/personnel/v1/employees/batch) which provides better error granularity and won’t fail the entire batch if one address has issues. The response includes per-record validation details.

One critical point: if your tenant has USPS address validation enabled (check with your UKG admin), you need to pre-standardize addresses. We implemented a pre-validation step using the USPS API directly before sending to UKG Pro, which reduced our validation failures by 95%. The standardization includes proper abbreviations, casing, and even corrects minor typos that would otherwise fail validation.

Finally, check your API user’s permissions. Some address types (like PAYROLL) require elevated permissions beyond standard HR API access. Your 400 error might actually be a permission issue masked as a validation error.

6

I ran into similar validation issues last year. The problem isn’t the postal code itself - it’s that UKG Pro expects the state/province code to be included when updating US addresses. The API validation runs postal code against state combinations. Try adding the state field to your payload and ensure it’s the two-letter abbreviation (MA for Massachusetts in your case). Without the state, the postal code validator can’t determine if the ZIP is valid for the implied location.