How address validation works
This page describes when 365 business Address Validation checks an address automatically and how sessions with and without a user interface differ.
These concepts help you judge the behavior of automatic validation in Microsoft Dynamics 365 Business Central correctly before you adjust the setup.
Trigger: only when an existing record is modified
Automatic address validation runs only when an existing record is modified and at least one of the monitored address fields has changed. When a new record is inserted, no automatic validation runs, even if the new address is already complete.
Applies to Contact, Customer, Vendor, Employee, Resource, Alternative Address, Order Address, and Ship-to Address, as well as to sales and purchase documents, each depending on the matching switch in the Address Validation Setup.
Fields checked per record
For Contact, Customer, Vendor, Employee, Resource, Alternative Address, Order Address, and Ship-to Address, automatic validation compares these fields with the previous value:
- Address
- Address 2
- Post Code
- City
- County
- Country/Region Code
For sales documents, the three address groups Sell-to, Ship-to, and Bill-to are checked separately; for purchase documents, the groups Buy-from, Ship-to, and Pay-to. Only the address group whose fields changed triggers a check.
Required fields: Address, and City or Post Code
For a check to run at all, the Address field must be filled, and in addition either City or Post Code. If either required field is missing, 365 business Address Validation treats the record as a new record and does not run a check.
Sessions with and without a user interface
Whether automatic validation runs in a session first depends on the Address Validation Scope setup field (see Address Validation Scope below). Within an allowed session, behavior then differs depending on whether a user interface is present:
| Session | Multiple matches | Confirming a suggested change | Error from the validation service |
|---|---|---|---|
| With a user interface (interactive client session) | The Address Validation Results page shows every match for selection | The Compare Address page shows the original and the suggestion, if Address Verification is enabled | A confirmation dialog asks whether to save the record without checking it |
| Without a user interface (API, web service, background session) | The first match returned by the service is applied without asking | Not applicable, the suggestion is applied without asking | Saving fails with an error |
365 business Address Validation determines this based on the running session's GuiAllowed property. For API and web service calls, and for background sessions through the job queue, this property is not set; for sessions in the web client and other interactive clients, it is set.
Confirmation on a failed check with a user interface
If you decline the confirmation dialog, the error message from the validation service appears and saving is canceled. If you confirm it, 365 business Address Validation saves the record without checking it and without a further error message.
Purchase documents: errors from the validation service stay invisible
Purchase documents are an exception to the table above: a failed call to the validation service is neither reported nor blocks saving there, regardless of whether a user interface is present.
No license or no authorization
If address validation is not licensed, or authorization with the validation service fails, 365 business Address Validation saves the record in every type of session without checking it, without asking, and without an error message.
Address Validation Scope
The Address Validation Scope field in the Address Validation Setup additionally restricts automatic validation to one type of session:
| Option | Automatic validation runs |
|---|---|
| All | in every session, with and without a user interface |
| Only enabled for client sessions with user interface | only in interactive sessions |
| Only enabled for sessions without user interface | only for API, web service, and background sessions |
Synchronous processing
Automatic validation runs synchronously within the save operation: 365 business Address Validation calls the validation service, evaluates the response, and applies the result before the record is saved. The session is blocked for the duration of the call.
Known addresses without a service call
If the address already exists in the address directory with the status Validated or Manually Checked, 365 business Address Validation reuses the stored result instead of calling the validation service again. This applies regardless of whether a user interface is present.
Carrying over to Ship-to and Bill-to
If the Ship-to or Bill-to address on a sales document matches the Sell-to address, it is not checked separately. Instead, 365 business Address Validation carries over the checked result of the Sell-to address unchanged to the other address. If the addresses differ, 365 business Address Validation checks each address group individually.
The same carryover applies on a purchase document. If Ship-to is still on its default address, it is not checked separately; 365 business Address Validation carries over the checked result of the Buy-from address unchanged. The Pay-to address follows the same rule as Bill-to on a sales document: it is carried over unchanged only if it matches the Buy-from address. If it differs, 365 business Address Validation checks the Pay-to address separately.