Payers

Override a user address in compliance tooling

Internal operators can update a user's address through the compliance tooling route when address validation fails or the address needs manual correction. This guide explains when to skip validation and which address fields are required.

This workflow is for internal admin and compliance staff only. End customers cannot access this override path. Use it when Google or USPS validation rejects an address that is confirmed correct by external evidence.

When to skip address validation

The compliance tooling route validates addresses by default through Google Maps (and USPS for US addresses). Validation can fail when:

  • The address exists but isn't in Google's or USPS's validation database

  • The address is in a country with limited address validation coverage

  • The user provided a valid address in a non-standard format

In these cases, if you've confirmed the address is correct through external evidence (support conversation, document upload, or other verification), you can bypass validation to complete the compliance update.

Skip validation only when you have confirmed the address is deliverable. Bypassing validation removes the normalization step that corrects formatting issues.

Address field requirements

The compliance tooling route has different field requirements based on country.

All addresses

Every address update requires:

  • line_1 — Street address

  • city — City or locality

  • country — Two-letter country code (e.g., US, GB, CA)

US addresses

For addresses where country is US, the following fields are required:

  • state — Two-letter state abbreviation (e.g., CA, NY)

  • postcode — ZIP code matching the pattern XXXXX or XXXXX-XXXX

When validation is enabled (the default), the route enforces these requirements and validates the address against USPS data.

Non-US addresses

For addresses outside the US, state is not required. The postcode field is optional but recommended when available.

Update a user address with validation

By default, the compliance tooling route validates the address through Google Maps or USPS. This normalizes the address to a standard format.

To update an address with validation enabled:

  1. Call the compliance update route: PUT /users/{user_id}/compliance

  2. Include the address object with all required fields for the country

  3. Omit validate_address or set it to true

If validation succeeds, the normalized address is saved and the user's compliance record is updated.

Validation normalizes addresses to a standard format. The saved address may differ slightly from the input (for example, St may become Street).

Update a user address without validation

When address validation fails but you've confirmed the address is correct, you can skip validation.

To update an address without validation:

  1. Call the compliance update route: PUT /users/{user_id}/compliance

  2. Set validate_address to false

  3. Include the address object with all required fields

The address is saved exactly as provided, without normalization or validation checks.

Common errors

"Address could not be validated"

This error occurs when validation is enabled and the address fails Google or USPS validation. If you've confirmed the address is correct, retry the update with validate_address set to false.

"Cannot update compliance information for users in the US or territories during January"

Compliance updates for US-based users are blocked during January due to year-end tax processing. Wait until February to make address changes.

Missing required field errors

Ensure your address payload includes all required fields for the country:

  • US addresses require line_1, city, state, postcode, and country

  • Non-US addresses require line_1, city, and country

Was this helpful?
Was this helpful?