Table of Contents

Pitney Bowes Integration

AddressValidation offers a complete integration to the Pitney Bowes Address Validation API to provide validation for the United States and Puerto Rico.

Note

This integration does not yet support batch validation.

Credentials

Get a developer account with Pitney Bowes before you use this integration. After you sign in, follow these instructions to get your API key and secret.

Note

Production access is not granted by default. Contact Pitney Bowes to enable Production.

Tip

If you provide other services to clients, read about Merchant Accounts. You can still use your own Developer ID for this integration — the Address Validation API does not require a Shipper ID.

Installation

The easiest way to install the integration into a project is through NuGet:

dotnet package add VisusIO.AddressValidation.Integration.PitneyBowes

Register the integration with the Microsoft DI container at application startup:

builder.Services.AddPitneyBowesAddressValidation();
Important

HybridCache caches access tokens. See the Caching section for details.

Configuration

Configuration is bound from the AddressValidationSettings:PitneyBowes section.

{
  "AddressValidationSettings": {
    "PitneyBowes": {
      "DeveloperId": "<your developer id>",
      "ApiKey": "<your api key>",
      "ApiSecret": "<your api secret>",
      "ClientEnvironment": "PRODUCTION"
    }
  }
}
Property Required Description
DeveloperId Yes Developer ID associated with your registered application
ApiKey Yes API key issued by Pitney Bowes for your registered application
ApiSecret Yes API secret issued by Pitney Bowes for your registered application
ClientEnvironment No Accepted values: PRODUCTION, DEVELOPMENT, SANDBOX. Defaults to DEVELOPMENT
EndpointUriOverride SANDBOX only Custom endpoint URI; required when ClientEnvironment is SANDBOX
Note

DeveloperId is only used to construct the cache key for the authentication cache.

Important

Store ApiKey and ApiSecret encrypted at rest. See Security for more details.

Standard Example

This example shows a standard address validation request. If validation fails, or the address is incomplete, make an address suggestion request instead.

public class ValidateController
{
    private readonly IAddressValidationService<PitneyBowesAddressValidationRequest> _validationService;

    public ValidateController(IAddressValidationService<PitneyBowesAddressValidationRequest> validationService)
    {
        _validationService = validationService ?? throw new ArgumentNullException(nameof(validationService));
    }

    [HttpPost]
    public async Task<IActionResult> Post([FromBody] PitneyBowesAddressValidationRequest request, CancellationToken cancellationToken = default)
    {
        IAddressValidationResponse? response = await _validationService.ValidateAsync(request, cancellationToken);
        
        return response is null
            ? new NotFoundResult()
            : response.Errors.Count > 0
                ? new UnprocessableEntityObjectResult(response)
                : new OkObjectResult(response);
    }
}

{
  "addressLines": [
    "350 5th Ave"
  ],
  "cityTown": "New York",
  "stateProvince": "NY",
  "postalCode": "10118",
  "countryCode": "US"
}
Warning

Treat the returned isResidential value as a suggestion, not a guarantee.

Suggestion Example

This example shows an address suggestion request. Make this request in these scenarios:

  • Standard request returned a validation failure in the Errors collection.
  • Provided address is incomplete or ambiguous.

To trigger an address suggestion request, set the IncludeSuggestions property to true.

{
  "addressLines": [
    "30 Rockefeller Plz"
  ],
  "cityTown": "New York",
  "stateProvince": "NY",
  "postalCode": "10112",
  "countryCode": "US"
}
Warning

The Suggestions collection does not guarantee valid values. Validate each item manually.

Warning

Treat the returned isResidential value as a suggestion, not a guarantee.

Note

AddressValidation runs an internal validation engine under the covers to validate both the request and the response. These results appear in the Warnings and Errors collections on the IAddressValidationResponse object.

The internal validator does not process items in the Suggestions collection.

Edit this page