Skip to content
PostGrid PostGrid
Get startedDashboardSupport
API Reference

Intl Address Verification

International Address Verification API.

Provides endpoints to verify and standardize international addresses, supporting both structured and freeform inputs.

Verify
intl_address_verification.verify(IntlAddressVerificationVerifyParams**kwargs) -> IntlAddressVerificationVerifyResponse
POST/v1/intl_addver/verifications
Batch Verification
intl_address_verification.batch_verification(IntlAddressVerificationBatchVerificationParams**kwargs) -> IntlAddressVerificationBatchVerificationResponse
POST/v1/intl_addver/verifications/batch
Get Autocomplete Previews
intl_address_verification.get_autocomplete_previews(IntlAddressVerificationGetAutocompletePreviewsParams**kwargs) -> IntlAddressVerificationGetAutocompletePreviewsResponse
GET/v1/intl_addver/completions
Get Autocomplete Advanced Previews
intl_address_verification.get_autocomplete_advanced_previews(IntlAddressVerificationGetAutocompleteAdvancedPreviewsParams**kwargs) -> IntlAddressVerificationGetAutocompleteAdvancedPreviewsResponse
GET/v1/intl_addver/completions
Autocomplete
intl_address_verification.autocomplete(IntlAddressVerificationAutocompleteParams**kwargs) -> IntlAddressVerificationAutocompleteResponse
POST/v1/intl_addver/completions
ModelsExpand Collapse
class IntlAddressVerificationVerifyResponse: …
data: Data

The result of a verified international address.

city: str

The city or locality.

country: str

The country code (ISO 3166-1 alpha-2).

line1: str

The first address line.

postal_or_zip: str

The postal or ZIP code.

province_or_state: str

The province or state.

country_name: Optional[str]

The full country name.

details: Optional[DataDetails]

Additional details about the verified address, such as premise, thoroughfare, and locality.

building: Optional[str]

The building name or number.

building_type: Optional[str]

The type of building (e.g., apartment, office).

city_name: Optional[str]

The full city name.

city_secondary: Optional[str]

Secondary city information.

city_type: Optional[str]

The type of city (e.g., city, town, village).

delivery_address: Optional[str]

The full delivery address.

dependent_locality: Optional[str]

The dependent locality (UK addresses).

double_dependent_locality: Optional[str]

The double dependent locality (UK addresses).

organization: Optional[str]

The organization or company name.

postal_or_zip_primary: Optional[str]

The primary part of the postal or ZIP code.

postal_or_zip_secondary: Optional[str]

The secondary part of the postal or ZIP code.

post_box: Optional[str]

The post box number.

premise: Optional[str]

The premise name or number.

premise_number: Optional[str]

The premise number.

premise_secondary: Optional[str]

Secondary premise information.

premise_type: Optional[str]

The type of premise (e.g., house, flat).

province_or_state_name: Optional[str]

The full name of the province or state.

province_or_state_type: Optional[str]

The type of province or state (e.g., province, state, region).

street: Optional[str]

The street name.

street_post_direction: Optional[str]

The directional suffix for the street (e.g., N, S, E, W).

street_pre_direction: Optional[str]

The directional prefix for the street (e.g., N, S, E, W).

street_type: Optional[str]

The type of street (e.g., St, Ave, Blvd).

sub_administrative_area: Optional[str]

The sub-administrative area.

sub_building: Optional[str]

The sub-building name or number (e.g., unit, suite).

sub_building_floor: Optional[str]

The floor of the sub-building.

sub_building_number: Optional[str]

The sub-building number.

sub_building_type: Optional[str]

The type of sub-building (e.g., floor, wing).

sub_street: Optional[str]

The sub-street name.

sub_street_post_direction: Optional[str]

The directional suffix for the sub-street.

sub_street_pre_direction: Optional[str]

The directional prefix for the sub-street.

sub_street_type: Optional[str]

The type of sub-street.

super_administrative_area: Optional[str]

The super-administrative area.

telephone: Optional[str]

The telephone number associated with the address.

errors: Optional[Errors]

Errors encountered during address verification.

city: Optional[List[str]]

Errors related to the city.

generic: Optional[List[str]]

Generic errors not tied to a specific field.

line1: Optional[List[str]]

Errors related to the first address line.

line2: Optional[List[str]]

Errors related to the second address line.

postal_or_zip: Optional[List[str]]

Errors related to the postal or ZIP code.

province_or_state: Optional[List[str]]

Errors related to the province or state.

firm_name: Optional[str]

The firm or company name, if available.

formatted_address: Optional[str]

The formatted address string.

geo_data: Optional[DataGeoData]

Geocoding result for the verified address.

geo_accuracy: Optional[str]

The geocode accuracy.

latitude: Optional[str]

The latitude of the address.

longitude: Optional[str]

The longitude of the address.

line2: Optional[str]

The second address line.

line3: Optional[str]

The third address line, if available.

status: Optional[Status]

The verification status of an address.

One of the following:
"verified"
"corrected"
"failed"
summary: Optional[DataSummary]

A summary of the verification process and match levels.

context_identification_match_level: Optional[str]

Context identification match level.

lexicon_identification_match_level: Optional[str]

Lexicon identification match level.

match_score: Optional[float]

The match score (0-100).

message: Optional[str]

Additional message about the verification.

parsing_status: Optional[str]

The parsing status of the address.

post_code_status: Optional[str]

The status of the postal code.

post_processed_verification_match_level: Optional[str]

The match level after post-processing.

pre_processed_verification_match_level: Optional[str]

The match level before post-processing.

verification_status: Optional[str]

The overall verification status.

zip_plus4: Optional[str]

The ZIP+4 code (for US addresses).

message: str
status: Literal["success", "error"]
One of the following:
"success"
"error"
class IntlAddressVerificationBatchVerificationResponse: …
data: Data
results: List[DataResult]
error: Optional[str]

An error message for this address. Present when verification failed.

verified_address: Optional[DataResultVerifiedAddress]

The result of a verified international address.

city: str

The city or locality.

country: str

The country code (ISO 3166-1 alpha-2).

line1: str

The first address line.

postal_or_zip: str

The postal or ZIP code.

province_or_state: str

The province or state.

country_name: Optional[str]

The full country name.

details: Optional[DataResultVerifiedAddressDetails]

Additional details about the verified address, such as premise, thoroughfare, and locality.

building: Optional[str]

The building name or number.

building_type: Optional[str]

The type of building (e.g., apartment, office).

city_name: Optional[str]

The full city name.

city_secondary: Optional[str]

Secondary city information.

city_type: Optional[str]

The type of city (e.g., city, town, village).

delivery_address: Optional[str]

The full delivery address.

dependent_locality: Optional[str]

The dependent locality (UK addresses).

double_dependent_locality: Optional[str]

The double dependent locality (UK addresses).

organization: Optional[str]

The organization or company name.

postal_or_zip_primary: Optional[str]

The primary part of the postal or ZIP code.

postal_or_zip_secondary: Optional[str]

The secondary part of the postal or ZIP code.

post_box: Optional[str]

The post box number.

premise: Optional[str]

The premise name or number.

premise_number: Optional[str]

The premise number.

premise_secondary: Optional[str]

Secondary premise information.

premise_type: Optional[str]

The type of premise (e.g., house, flat).

province_or_state_name: Optional[str]

The full name of the province or state.

province_or_state_type: Optional[str]

The type of province or state (e.g., province, state, region).

street: Optional[str]

The street name.

street_post_direction: Optional[str]

The directional suffix for the street (e.g., N, S, E, W).

street_pre_direction: Optional[str]

The directional prefix for the street (e.g., N, S, E, W).

street_type: Optional[str]

The type of street (e.g., St, Ave, Blvd).

sub_administrative_area: Optional[str]

The sub-administrative area.

sub_building: Optional[str]

The sub-building name or number (e.g., unit, suite).

sub_building_floor: Optional[str]

The floor of the sub-building.

sub_building_number: Optional[str]

The sub-building number.

sub_building_type: Optional[str]

The type of sub-building (e.g., floor, wing).

sub_street: Optional[str]

The sub-street name.

sub_street_post_direction: Optional[str]

The directional suffix for the sub-street.

sub_street_pre_direction: Optional[str]

The directional prefix for the sub-street.

sub_street_type: Optional[str]

The type of sub-street.

super_administrative_area: Optional[str]

The super-administrative area.

telephone: Optional[str]

The telephone number associated with the address.

errors: Optional[Errors]

Errors encountered during address verification.

city: Optional[List[str]]

Errors related to the city.

generic: Optional[List[str]]

Generic errors not tied to a specific field.

line1: Optional[List[str]]

Errors related to the first address line.

line2: Optional[List[str]]

Errors related to the second address line.

postal_or_zip: Optional[List[str]]

Errors related to the postal or ZIP code.

province_or_state: Optional[List[str]]

Errors related to the province or state.

firm_name: Optional[str]

The firm or company name, if available.

formatted_address: Optional[str]

The formatted address string.

geo_data: Optional[DataResultVerifiedAddressGeoData]

Geocoding result for the verified address.

geo_accuracy: Optional[str]

The geocode accuracy.

latitude: Optional[str]

The latitude of the address.

longitude: Optional[str]

The longitude of the address.

line2: Optional[str]

The second address line.

line3: Optional[str]

The third address line, if available.

status: Optional[Status]

The verification status of an address.

One of the following:
"verified"
"corrected"
"failed"
summary: Optional[DataResultVerifiedAddressSummary]

A summary of the verification process and match levels.

context_identification_match_level: Optional[str]

Context identification match level.

lexicon_identification_match_level: Optional[str]

Lexicon identification match level.

match_score: Optional[float]

The match score (0-100).

message: Optional[str]

Additional message about the verification.

parsing_status: Optional[str]

The parsing status of the address.

post_code_status: Optional[str]

The status of the postal code.

post_processed_verification_match_level: Optional[str]

The match level after post-processing.

pre_processed_verification_match_level: Optional[str]

The match level before post-processing.

verification_status: Optional[str]

The overall verification status.

zip_plus4: Optional[str]

The ZIP+4 code (for US addresses).

message: str
status: Literal["success", "error"]
One of the following:
"success"
"error"
class IntlAddressVerificationGetAutocompletePreviewsResponse: …
data: List[Data]
id: Optional[str]

The unique identifier for this result. If the result is a fully resolvable address (type is Address), pass this to POST /completions to retrieve the full address. Otherwise, pass it as the container query parameter to GET /completions to drill down further.

description: Optional[str]

A secondary description of the result (e.g. city and country).

error: Optional[str]

An error message if the lookup failed for this result.

highlight: Optional[str]

Character ranges within text that match the search input, for bolding in UI.

text: Optional[str]

The human-readable address suggestion text.

type: Optional[str]

The type of result. Address means this can be resolved directly via POST /completions. Container means the result represents a building or complex — perform another GET /completions with this id as container to get individual unit addresses.

message: str
status: Literal["success", "error"]
One of the following:
"success"
"error"
class IntlAddressVerificationGetAutocompleteAdvancedPreviewsResponse: …
data: List[Data]
id: Optional[str]

The unique identifier for this result. If the result is a fully resolvable address (type is Address), pass this to POST /completions to retrieve the full address. Otherwise, pass it as the container query parameter to GET /completions to drill down further.

description: Optional[str]

A secondary description of the result (e.g. city and country).

error: Optional[str]

An error message if the lookup failed for this result.

highlight: Optional[str]

Character ranges within text that match the search input, for bolding in UI.

text: Optional[str]

The human-readable address suggestion text.

type: Optional[str]

The type of result. Address means this can be resolved directly via POST /completions. Container means the result represents a building or complex — perform another GET /completions with this id as container to get individual unit addresses.

message: str
status: Literal["success", "error"]
One of the following:
"success"
"error"
class IntlAddressVerificationAutocompleteResponse: …
data: Data

A fully resolved international address returned by POST /completions.

One of the following:
class DataIntlAddressCompletion: …

A fully resolved international address returned by POST /completions.

building: Optional[str]

The building name, if applicable.

city: Optional[str]

The city or locality.

company: Optional[str]

The company or organization name, if applicable.

country: Optional[str]

The country name.

country_code: Optional[str]

The ISO 2-letter country code.

department: Optional[str]

The department or floor, if applicable.

error: Optional[str]

An error message if resolution failed.

formatted_address: Optional[str]

The full formatted address string.

line1: Optional[str]

The first address line.

line2: Optional[str]

The second address line.

line3: Optional[str]

The third address line.

line4: Optional[str]

The fourth address line.

postal_or_zip: Optional[str]

The postal or ZIP code.

province_code: Optional[str]

The province or state code.

province_or_state: Optional[str]

The province or state name.

class DataVerifiedAddress: …

The result of a verified international address.

city: str

The city or locality.

country: str

The country code (ISO 3166-1 alpha-2).

line1: str

The first address line.

postal_or_zip: str

The postal or ZIP code.

province_or_state: str

The province or state.

country_name: Optional[str]

The full country name.

details: Optional[DataVerifiedAddressDetails]

Additional details about the verified address, such as premise, thoroughfare, and locality.

building: Optional[str]

The building name or number.

building_type: Optional[str]

The type of building (e.g., apartment, office).

city_name: Optional[str]

The full city name.

city_secondary: Optional[str]

Secondary city information.

city_type: Optional[str]

The type of city (e.g., city, town, village).

delivery_address: Optional[str]

The full delivery address.

dependent_locality: Optional[str]

The dependent locality (UK addresses).

double_dependent_locality: Optional[str]

The double dependent locality (UK addresses).

organization: Optional[str]

The organization or company name.

postal_or_zip_primary: Optional[str]

The primary part of the postal or ZIP code.

postal_or_zip_secondary: Optional[str]

The secondary part of the postal or ZIP code.

post_box: Optional[str]

The post box number.

premise: Optional[str]

The premise name or number.

premise_number: Optional[str]

The premise number.

premise_secondary: Optional[str]

Secondary premise information.

premise_type: Optional[str]

The type of premise (e.g., house, flat).

province_or_state_name: Optional[str]

The full name of the province or state.

province_or_state_type: Optional[str]

The type of province or state (e.g., province, state, region).

street: Optional[str]

The street name.

street_post_direction: Optional[str]

The directional suffix for the street (e.g., N, S, E, W).

street_pre_direction: Optional[str]

The directional prefix for the street (e.g., N, S, E, W).

street_type: Optional[str]

The type of street (e.g., St, Ave, Blvd).

sub_administrative_area: Optional[str]

The sub-administrative area.

sub_building: Optional[str]

The sub-building name or number (e.g., unit, suite).

sub_building_floor: Optional[str]

The floor of the sub-building.

sub_building_number: Optional[str]

The sub-building number.

sub_building_type: Optional[str]

The type of sub-building (e.g., floor, wing).

sub_street: Optional[str]

The sub-street name.

sub_street_post_direction: Optional[str]

The directional suffix for the sub-street.

sub_street_pre_direction: Optional[str]

The directional prefix for the sub-street.

sub_street_type: Optional[str]

The type of sub-street.

super_administrative_area: Optional[str]

The super-administrative area.

telephone: Optional[str]

The telephone number associated with the address.

errors: Optional[Errors]

Errors encountered during address verification.

city: Optional[List[str]]

Errors related to the city.

generic: Optional[List[str]]

Generic errors not tied to a specific field.

line1: Optional[List[str]]

Errors related to the first address line.

line2: Optional[List[str]]

Errors related to the second address line.

postal_or_zip: Optional[List[str]]

Errors related to the postal or ZIP code.

province_or_state: Optional[List[str]]

Errors related to the province or state.

firm_name: Optional[str]

The firm or company name, if available.

formatted_address: Optional[str]

The formatted address string.

geo_data: Optional[DataVerifiedAddressGeoData]

Geocoding result for the verified address.

geo_accuracy: Optional[str]

The geocode accuracy.

latitude: Optional[str]

The latitude of the address.

longitude: Optional[str]

The longitude of the address.

line2: Optional[str]

The second address line.

line3: Optional[str]

The third address line, if available.

status: Optional[Status]

The verification status of an address.

One of the following:
"verified"
"corrected"
"failed"
summary: Optional[DataVerifiedAddressSummary]

A summary of the verification process and match levels.

context_identification_match_level: Optional[str]

Context identification match level.

lexicon_identification_match_level: Optional[str]

Lexicon identification match level.

match_score: Optional[float]

The match score (0-100).

message: Optional[str]

Additional message about the verification.

parsing_status: Optional[str]

The parsing status of the address.

post_code_status: Optional[str]

The status of the postal code.

post_processed_verification_match_level: Optional[str]

The match level after post-processing.

pre_processed_verification_match_level: Optional[str]

The match level before post-processing.

verification_status: Optional[str]

The overall verification status.

zip_plus4: Optional[str]

The ZIP+4 code (for US addresses).

message: str
status: Literal["success", "error"]
One of the following:
"success"
"error"