Skip to content
Shared APIs
/
/Address

Address

APIs for validating, suggesting, and autocompleting addresses.

  • Standardizes address formats based on postal data
  • Enhances delivery accuracy by correcting address components
  • Provides fallback mechanisms (suggestions) when validation fails
  • Supports user-friendly address capture through autocomplete
Operations

Address Validate

Request

This operation validates addresses to improve postal accuracy within the country (e.g., United States). This ensure that parcels are rated correctly and shipments reach their final destination on time. The validate address operation sends an address for verification, and the response indicates whether the address is valid.
Key Considerations:

  • Validation results include VALIDATED_AND_NOT_CHANGED or VALIDATED_CHANGED for valid addresses. Invalid addresses result in HTTP status 400 with an Error Code of Invalid Address.
  • Only U.S. domestic addresses are validated.
  • Pitney Bowes verifies addresses for accuracy against current USPS® data and makes corrections to delivery lines and last lines when possible.
  • The minimalAddressValidation query parameter can be used to limit the extent of corrections to the address.
  • If validation fails, you can use the Suggest Addresses API call to provide suggestions that could result in the address passing verification in a subsequent Address Validation API call.
Security
bearerAuth
Bodyapplication/jsonrequired
addressLine1stringrequired

The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).

Example:"27 Watervw Dr"
addressLine2string

The addressLine2 contains Street address or Landmark (if any).

Example:"near abc street"
addressLine3string

The addressLine3 contains P.O.Box (if any) near the address.

Example:"near xyz street"
cityTownstring

The name of the city or town to where the address belongs.

Example:"Shelton"
countryCodestringrequired

This indicates the two-character ISO code of the country from the ISO country list.

Example:"US"
namestring

Name of the person to which this address points.

Example:"John Smith"
postalCodestringrequired

The postal code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.

Example:"06484"
stateProvincestring

The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code.

Example:"CT"
curl -i -X POST \
  https://api-sandbox.sendpro360.pitneybowes.com/shipping/api/v1/address/verify \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "addressLine1": "27 Watervw Dr",
    "addressLine2": "near abc street",
    "addressLine3": "near xyz street",
    "cityTown": "Shelton",
    "countryCode": "US",
    "name": "John Smith",
    "postalCode": "06484",
    "stateProvince": "CT"
  }'

Responses

The address has been verified.

Bodyapplication/json
addressLine1string

The addressLine1 can contain the Flat number, Building or Apartment Name/number (if any) or company name (if not residential).

Example:"27 Watervw Dr"
addressLine2string

The addressLine2 contains Street address or Landmark (if any).

Example:"near abc street"
addressLine3string

The addressLine3 contains P.O.Box (if any) near the address.

Example:"near xyz street"
cityTownstring

The name of the city or town to where the address belongs.

Example:"Shelton"
countryCodestring

This indicates the two-character ISO code of the country from the ISO country list.

Example:"US"
namestring

Name of the person to which this address points.

Example:"John Smith"
postalCodestring

The postal code or ZIP code of the address. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.

Example:"06484"
residentialboolean

The specified adress can be Residential or Official. In case if the adress is Residential, the boolean value will be 'true', else it will take 'false'.

Example:true
stateProvincestring

The State or Province of the address. For a US or Canadian address, it is the 2-letter state or province code.

Example:"CT"
deliveryPointstring

The 2-digit USPS delivery point code for the address. It is used to specify delivery locations within a postal route.

  • Supported Carrier: USPS domestic shipments only.
Example:"57"
carrierRoutestring

The 4-character alphanumeric carrier route code. It is used to specify delivery route for a specific mail carrier.

  • Full carrier route codes include the 5-digit ZIP Code followed by the 4-character carrierRoute (e.g., 12345C005).
  • Supported Carrier: USPS domestic shipments only.
Example:"C005"
statusstring
  • This field applies only to the Validate Address API. It indicates whether the submitted address is valid and whether the API made significant changes to the address. Possible values are:
    -VALIDATED_CHANGED: The address is valid, but the API made significant changes to improve it. For example, if an address includes a valid street number and street name (e.g., 100 Elm) but is missing a street suffix (e.g., St), the API would add the suffix. Adding or changing the Zip+4, suite or unit number, residential flag, or making formatting changes are not considered significant changes.
    -VALIDATED_AND_NOT_CHANGED: The address is valid, and the API made no significant changes.
Enum:"VALIDATED_CHANGED""VALIDATED_AND_NOT_CHANGED"
Example:"VALIDATED_CHANGED"
Response
{
  "addressLine1": "27 Waterview Drive",
  "addressLine2": "near abc street",
  "addressLine3": "near xyz street",
  "cityTown": "Shelton",
  "countryCode": "US",
  "name": "John Smith",
  "postalCode": "06484-5841",
  "residential": true,
  "stateProvince": "CT",
  "status": "VALIDATED_AND_NOT_CHANGED",
  "deliveryPoint": "57",
  "carrierRoute": "C005"
}