Country and Subdivision Validation vs. Postal Address Verification
A checkout can receive CA with US-CA, or it can receive a valid country and region attached to a mistyped street. These failures look similar in a support ticket, but they need different checks. Decide what your form needs to establish before you pick a validation service.
For the shared country and region fields, start with the website form guide.
What you need
This is for teams collecting country and region codes for routing, reporting or shipping. Use a CountriesDB project, a public key and an allowed hostname for the widget. For backend checks, keep the private key on the server and check the Backend Validation API for your plan's access.
Decide what to validate
1. Collect values your server can check
Use labeled country and region selects and store codes separately from display names. This makes a pair such as US and US-CA easier to check and map downstream.
<script src="https://unpkg.com/@countriesdb/widget@latest/dist/index.js?public_key=YOUR_PUBLIC_KEY"></script>
<label for="country">Country</label>
<select id="country" name="country" class="country-selection"
data-name="country" data-label="Select country" data-preselected="" required></select>
<label for="region">State / province / region</label>
<select id="region" name="region" class="subdivision-selection"
data-country="country" data-label="Select region" data-prefer-official></select>
2. Validate the geographic pair
Check the country code and, when the region is required or provided, check the subdivision against that country. Use the subdivision validation endpoint. Return a field-level correction for a mismatch and handle a service failure separately from an invalid code. This is useful even when the submission contains no street address, for example when assigning leads to territories.
3. Verify a postal address when the workflow needs it
If you ship physical goods, use a postal address verification service such as Loqate where you need to match the street, city and postal code against address reference data. Decide how to handle ambiguous or unmatched results and apply carrier rules separately. See country and region fields for checkout for how to collect the inputs.
FAQ
Do I need a developer?
Server-side checks need someone to connect them to your submission handler and keep the private key in server configuration.
What if a country has no subdivision that applies to the address?
Allow an empty region where your business rules permit it. Check a region when supplied and require one only where the workflow needs it.
Is browser validation enough?
Treat submitted values as untrusted. Apply the country and region checks on the server before using those values for routing, shipping or reporting.
Does a postal match guarantee delivery?
It indicates a match against the provider's reference data. Carrier restrictions and conditions at delivery still matter.