Suggest Addresses

HTTP Request

POST /v1/addresses/verify-suggest?returnSuggestions=true

Summary

This operation returns suggested addresses. Use this if the Address Validation API call has returned an error.

Considerations

  1. The suggested addresses are not validated. To validate a suggested address, use the Address Validation API.

  2. Some suggestions might not be valid delivery points.

    This is especially true for range suggestions. For example, if the suggested valid range for a street is 1-100, the Suggest Addresses API call will consider all numbers in the range to be valid, even if the only valid delivery points are numbers 12, 24, and 36.

  3. For a given request, the API returns suggestions for one part of the address, as specified in the suggestions.suggestionType field.

    The suggestions will be for one of the following parts of the address:

    • Primary number range (e.g., street number, PO Box number)

    • Secondary number range (e.g., suite number, apartment number)

    • Street Name

    • City Name

    • Company Name

    • Puerto Rican Urbanization

  4. The API returns a maximum of 20 suggestions.

  5. The suggestions are not sorted by best match.

  6. Some requests might return no suggestions. If there are no suggestions, the suggestions object is not returned.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/addresses/verify-suggest?returnSuggestions=true
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/addresses/verify-suggest?returnSuggestions=true

Query Parameter

Name

Description

returnSuggestions

Required. To return suggested addresses, set this to true.

Valid values:

  • true

  • false

Request Headers

Name

Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

Content-Type

Required. The media type of the request entity. Set this to application/json.

Accept-Language

Language and country code. Default: en-US

X-PB-UnifiedErrorStructure

Recommended. Set this to true to use the standard error object if an error occurs.

Request Elements

Name

Data Type

Description

address

Address Object

Required. The address for which to retrieve suggestions.

Address Object for the Suggest Addresses API

Name

Data Type

Description

addressLines

Array[String]

Required. Street address or P.O. Box. Include apartment number, if applicable. You can specify up to 3 address lines. For domestic shipments: ensure that the street address is specified as the last of the 3 address lines per USPS® label guidelines.

cityTown

String

The city or town.

stateProvince

String

The state or province. For a US or Canadian address, use the 2-letter state or province code.

postalCode

String

Required. The postal code or ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code in one of the following formats:

  • 12345

  • 12345-6789

If you use a different format, such as 12345- or 123451234, you will receive an error.

countryCode

String

Required. Two-character country code from the ISO country list.

company

String

The name of the company.

name

String

The first and last name.

phone

String

The phone number. Enter the digits with or without spaces or hyphens. When used for Pickups, the maximum is 10 digits.

email

String

The email address.

residential

Boolean

Indicates whether this is a residential address. Pitney Bowes recommends including this parameter to improve address verification.

deliveryPoint

String

The 2-digit USPS domestic delivery point, when available.

carrierRoute

String

The last four characters of the USPS domestic carrier route code. The carrier route is the area served by a particular USPS mail carrier. The full carrier route code is a nine-character string comprising the five-digit postal code appended by these four characters.

taxId

String

Pickup Request Only. Tax identification number. This is optional for pickup requests.

status

String

RESPONSE ONLY. This field applies to the Validate Address and Suggest Addresses APIs. The field indicates whether the submitted address is valid and whether the API made changes to the address.

Possible values are:

  • VALIDATED_CHANGED: The address is valid, but the API made changes to improve the address. For example, if an address has a valid street number and street name (e.g. “100 Elm”) but is missing the street suffix (e.g. “St”), the API would add the suffix.

  • VALIDATED_AND_NOT_CHANGED: The address is valid. The API made no changes.

  • NOT_CHANGED: The address could not be validated. The API made no changes.

Response Elements

Name

Data Type

Description

address

Address Object

The original address. This might contain changes made for address validation. The Address Object’s status field indicates if changes have been made.

suggestions

Object

Suggested changes for a specific part of the address. The suggested changes are not validated. To validate a suggested change, use the Address Validation API.

suggestions.suggestionType

String

The part of the address that is changed in the accompanying suggestions. Possible values are:

  • street

  • streetPrimaryRange (e.g., street number, PO Box number)

  • secondaryRange (e.g., suite number, apartment number)

  • poBoxPrimaryRange

  • ruralRouteUnitRange

  • highwayContractUnitRange

  • city

  • company

  • puertoricanUrbanization

suggestions.address

Array[Address Object]

The suggestions. Each object in the array provides a suggested change to the returned address.

Sample Requests

This section provides the following examples:

Returned Address is Validated and Not Changed

Sample Request
curl -X POST ".../v1/addresses/verify-suggest?returnSuggestions=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "address": {
        "addressLines": [
            "3 1st Ave NW"
        ],
        "cityTown": "Litz",
        "stateProvince": "FL",
        "postalCode": "33549",
        "countryCode": "US",
        "name": "Jane Wilson",
        "residential": true
    }
}'
Sample Response
{
    "address": {
        "addressLines": [
            "3 1st Ave NW"
        ],
        "cityTown": "Litz",
        "stateProvince": "FL",
        "postalCode": "33549",
        "countryCode": "US",
        "name": "Jane Wilson",
        "residential": true,
        "status": "VALIDATED_AND_NOT_CHANGED"
    },
    "suggestions": {
        "suggestionType": "street",
        "address": [ {
            "addressLines": [
                "3 1ST AVE NE"
            ],
            "cityTown": "Litz",
            "stateProvince": "FL",
            "postalCode": "33549",
            "name": "Jane Wilson"
        },
        {
            "addressLines": [
                "3 1ST AVE SE"
            ],
            "cityTown": "Litz",
            "stateProvince": "FL",
            "postalCode": "33549",
            "name": "Jane Wilson"
        },
        ...
        ]
    }
}

Returned Address is Validated and Changed

Sample Request
curl -X POST ".../v1/addresses/verify-suggest?returnSuggestions=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "address": {
        "addressLines": [
            "27 Watervw Dr",
            "",
            ""
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "name": "John Smith",
        "residential": true
    }
}'
Sample Request
{
    "address": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484-4301",
        "countryCode": "US",
        "name": "John Smith",
        "residential": false,
        "deliveryPoint": "27",
        "carrierRoute": "C010",
        "status": "VALIDATED_CHANGED"
    },
    "suggestions": {
        "suggestionType": "company",
        "address": [
            {
                "addressLines": [
                    "27 Waterview Dr"
                ],
                "cityTown": "Shelton",
                "stateProvince": "CT",
                "postalCode": "06484-4301",
                "company": "PITNEY BOWES CREDIT CORP",
                "name": "John Smith"
            }
        ]
    }
}

Error Codes

Error codes specific to address validation are seven-digits long and start with 10. See the address-specific errors in 10-Prefix Error Codes.

For a list of all error codes returned by the PB Shipping APIs, please see Error Codes.