Verify

POST/v1/intl_addver/verifications

Verify and standardize an international address.

Supports both structured and freeform address inputs.
Specify includeDetails=true to get additional details as per the IntlDetails schema.
Uses 1 lookup.

Query ParametersExpand Collapse

geoData: optional boolean

includeDetails: optional boolean

properCase: optional boolean

Body ParametersJSONExpand Collapse

body: object { address } or object { address }

Input model for structured international address verification.

One of the following:

StructuredAddressInput = object { address }

Input model for structured international address verification.

address: object { country, line1, postalOrZip, 5 more }

country: string

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

line1: string

The first line of the address (e.g., street address, building, etc.).

postalOrZip: string

The postal or ZIP code.

provinceOrState: string

The administrative area (e.g., state, province, region).

city: optional string

The city, town, or locality of the address.

line2: optional string

The second line of the address (e.g., apartment, suite, etc.).

line3: optional string

The third line of the address (e.g., additional locality or delivery info).

line4: optional string

The fourth line of the address (e.g., further address details).

FreeformAddressInput = object { address }

Input model for freeform international address verification.

address: string

The full address as a single string.

ReturnsExpand Collapse

data: object { city, country, line1, 13 more }

The result of a verified international address.

city: string

The city or locality.

country: string

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

line1: string

The first address line.

postalOrZip: string

The postal or ZIP code.

provinceOrState: string

The province or state.

countryName: optional string

The full country name.

details: optional object { building, buildingType, cityName, 30 more }

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

building: optional string

The building name or number.

buildingType: optional string

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

cityName: optional string

The full city name.

citySecondary: optional string

Secondary city information.

cityType: optional string

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

deliveryAddress: optional string

The full delivery address.

dependentLocality: optional string

The dependent locality (UK addresses).

doubleDependentLocality: optional string

The double dependent locality (UK addresses).

organization: optional string

The organization or company name.

postalOrZipPrimary: optional string

The primary part of the postal or ZIP code.

postalOrZipSecondary: optional string

The secondary part of the postal or ZIP code.

postBox: optional string

The post box number.

premise: optional string

The premise name or number.

premiseNumber: optional string

The premise number.

premiseSecondary: optional string

Secondary premise information.

premiseType: optional string

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

provinceOrStateName: optional string

The full name of the province or state.

provinceOrStateType: optional string

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

street: optional string

The street name.

streetPostDirection: optional string

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

streetPreDirection: optional string

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

streetType: optional string

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

subAdministrativeArea: optional string

The sub-administrative area.

subBuilding: optional string

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

SubBuildingFloor: optional string

The floor of the sub-building.

subBuildingNumber: optional string

The sub-building number.

subBuildingType: optional string

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

subStreet: optional string

The sub-street name.

subStreetPostDirection: optional string

The directional suffix for the sub-street.

subStreetPreDirection: optional string

The directional prefix for the sub-street.

subStreetType: optional string

The type of sub-street.

superAdministrativeArea: optional string

The super-administrative area.

telephone: optional string

The telephone number associated with the address.

errors: optional Errors { city, generic, line1, 2 more }

Errors encountered during address verification.

city: optional array of string

Errors related to the city.

generic: optional array of string

Generic errors not tied to a specific field.

line1: optional array of string

Errors related to the first address line.

line2: optional array of string

Errors related to the second address line.

provinceOrState: optional array of string

Errors related to the province or state.

firmName: optional string

The firm or company name, if available.

formattedAddress: optional string

The formatted address string.

geoData: optional object { geoAccuracy, latitude, longitude }

Geocoding result for the verified address.

geoAccuracy: optional string

The geocode accuracy.

latitude: optional string

The latitude of the address.

longitude: optional string

The longitude of the address.

line2: optional string

The second address line.

line3: optional string

The third address line, if available.

status: optional Status

The verification status of an address.

One of the following:

"verified"

"corrected"

"failed"

summary: optional object { contextIdentificationMatchLevel, lexiconIdentificationMatchLevel, matchScore, 6 more }

A summary of the verification process and match levels.

contextIdentificationMatchLevel: optional string

Context identification match level.

lexiconIdentificationMatchLevel: optional string

Lexicon identification match level.

matchScore: optional number

The match score (0-100).

message: optional string

Additional message about the verification.

parsingStatus: optional string

The parsing status of the address.

postCodeStatus: optional string

The status of the postal code.

postProcessedVerificationMatchLevel: optional string

The match level after post-processing.

preProcessedVerificationMatchLevel: optional string

The match level before post-processing.

verificationStatus: optional string

The overall verification status.

zipPlus4: optional string

The ZIP+4 code (for US addresses).

message: string

status: "success" or "error"

One of the following:

"success"

"error"

Verify

curl https://api.postgrid.com/v1/intl_addver/verifications \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY" \
    -d '{
          "address": {
            "country": "country",
            "line1": "line1",
            "postalOrZip": "postalOrZip",
            "provinceOrState": "provinceOrState"
          }
        }'

{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Scarborough",
    "country": "CA",
    "details": {
      "premise": "31"
    },
    "formattedAddress": "31 Fl,scarborough On",
    "geoData": {
      "latitude": "43.761961",
      "longitude": "-79.245693",
      "geoAccuracy": "A2"
    },
    "line1": "31 Fl",
    "line2": "Scarborough On",
    "provinceOrState": "ON",
    "postalOrZip": "",
    "summary": {
      "verificationStatus": "partially_verified",
      "postProcessedVerificationMatchLevel": "city",
      "preProcessedVerificationMatchLevel": "city",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "city",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}

{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Reilingen",
    "country": "DE",
    "details": {
      "building": "Reilingen Baden Wurtemberg",
      "premise": "43"
    },
    "formattedAddress": "Reilingen Baden Wurtemberg,hockenheimer Str. 43,68799 Reilingen",
    "geoData": {
      "latitude": "49.297010",
      "longitude": "8.571100",
      "geoAccuracy": "P4"
    },
    "line1": "Reilingen Baden Wurtemberg",
    "line2": "Hockenheimer Str. 43",
    "line3": "68799 Reilingen",
    "postalOrZip": "68799",
    "provinceOrState": "Baden-Württemberg",
    "summary": {
      "verificationStatus": "verified",
      "postProcessedVerificationMatchLevel": "premise_or_building",
      "preProcessedVerificationMatchLevel": "premise_or_building",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "premise_or_building",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}

Returns Examples

{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Scarborough",
    "country": "CA",
    "details": {
      "premise": "31"
    },
    "formattedAddress": "31 Fl,scarborough On",
    "geoData": {
      "latitude": "43.761961",
      "longitude": "-79.245693",
      "geoAccuracy": "A2"
    },
    "line1": "31 Fl",
    "line2": "Scarborough On",
    "provinceOrState": "ON",
    "postalOrZip": "",
    "summary": {
      "verificationStatus": "partially_verified",
      "postProcessedVerificationMatchLevel": "city",
      "preProcessedVerificationMatchLevel": "city",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "city",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}

{
  "status": "success",
  "message": "International address verified successfully.",
  "data": {
    "city": "Reilingen",
    "country": "DE",
    "details": {
      "building": "Reilingen Baden Wurtemberg",
      "premise": "43"
    },
    "formattedAddress": "Reilingen Baden Wurtemberg,hockenheimer Str. 43,68799 Reilingen",
    "geoData": {
      "latitude": "49.297010",
      "longitude": "8.571100",
      "geoAccuracy": "P4"
    },
    "line1": "Reilingen Baden Wurtemberg",
    "line2": "Hockenheimer Str. 43",
    "line3": "68799 Reilingen",
    "postalOrZip": "68799",
    "provinceOrState": "Baden-Württemberg",
    "summary": {
      "verificationStatus": "verified",
      "postProcessedVerificationMatchLevel": "premise_or_building",
      "preProcessedVerificationMatchLevel": "premise_or_building",
      "parsingStatus": "unable_to_parse",
      "lexiconIdentificationMatchLevel": "premise_or_building",
      "contextIdentificationMatchLevel": "premise_or_building",
      "postCodeStatus": "postal_code_primary_empty",
      "matchScore": 100
    }
  }
}

Verify

Query ParametersExpand Collapse

Body ParametersJSONExpand Collapse

ReturnsExpand Collapse

Verify

Returns Examples

What can I help you with?

Suggestions