# Address APIs

The Address APIs provide capabilities to validate, standardize, and suggest addresses to improve delivery accuracy and reduce shipment failures. These APIs help ensure that addresses used in shipment processing are complete, correctly formatted, and aligned with postal standards.
The APIs support:
  - Address Validation (domestic and international) to verify and correct address data
  - Address Suggestion to provide alternatives when validation fails
  - Address Autocomplete to assist in capturing accurate addresses from partial input


Version: 1.0.0

## Servers

```
https://api-dev.sendpro360.pitneycloud.com/shipping
```

```
https://api-qa.sendpro360.pitneycloud.com/shipping
```

Sandbox Server
```
https://api-sandbox.sendpro360.pitneybowes.com/shipping
```

Production Server (uses live data)
```
https://api.sendpro360.pitneybowes.com/shipping
```

## Security

### bearerAuth

Type: http
Scheme: bearer

## Download OpenAPI description

[Address APIs](https://docs.sendpro360.pitneycloud.com/_bundle/openapi/address.yaml)

## 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


### Address Validate

 - [POST /api/v1/address/verify](https://docs.sendpro360.pitneycloud.com/openapi/address/address/addressvalidate.md): 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.

### Address Suggest

 - [POST /api/v1/address/suggest](https://docs.sendpro360.pitneycloud.com/openapi/address/address/addresssuggest.md): The Address Suggest API returns address suggestions. Use this API only if the Address Validate API fails to validate an address and returns a 400 error. This API itself does not validate addresses; it returns suggestions based on the information submitted in the request. 

Important Notes

  - In response, the address object outside the suggestions object, including the status field, must be ignored as it does not provide valid address data.

  - Only the addresses listed under the suggestions.addresses array should be considered for further action.

  Key Considerations

  - Some suggestions, especially for range suggestions, might not be valid delivery points may not guarantee delivery.
    For example, if the suggested valid range for a street is 1-100, the API may suggest and validate all numbers in the range, even if only 12, 24, and 36 are actual deliverable addresses.

  - The API returns a maximum of 20 suggestions.

  - The suggestions are not sorted by best match.

  - Some requests might return no suggestions.

  - If no suggestions are available, the suggestions object is not included in the response.

### Address Autocomplete

 - [GET /api/v2/address/suggest](https://docs.sendpro360.pitneycloud.com/openapi/address/address/addressautocomplete.md): The Address Autocomplete API provides intelligent address suggestions for U.S. addresses based on partial input submitted in the searchText query parameter. It returns a structured list of up to 15 suggested addresses, including unit-level details (e.g., apartments or suites) and geographic coordinates when available.
Use Address Validate API to validate the address. 


Key Capabilities:
- Returns full, structured addresses based on searchText
- Accepts partial address details such as a street name, city, state, or ZIP code.
- Autocompletes partial addresses and place names, prioritizing results by relevance and proximity.
- Suggests unit-level suggestions when available (e.g., apartments, suites)
- Provides geographic coordinates (latitude and longitude) for mapping use cases. 
- Returns up to 15 relevant address suggestions per request

> Note: This API only suggests addresses matches. It does not validate them. To verify address accuracy, use the Address Validation API.

### International Address Validate

 - [POST /api/v1/address/verify/intl](https://docs.sendpro360.pitneycloud.com/openapi/address/address/addressvalidateintl.md): This operation validates international addresses to improve postal accuracy within that country. This ensure that parcels are rated correctly and shipments reach their final destination on time. The International Address Validate 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.