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.

Credentials

Before utilizing the integration, you will need a developer account with Pitney Bowes. After you have signed in to the account, follow these instructions to obtain your API key and secret.

Note

Production access is not granted by default. You will need contact Pitney Bowes to enable Production.

Tip

Service providers should read up on Merchant Accounts should you wish to provide other services to clients. You may continue to use your own Developer ID for this integration as 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

At application startup, you will need to register the integration with the Microsoft DI container:

builder.Services.AddPitneyBowesAddressValidation();
Important

HybridCache is required for authentication caching. Please 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

ApiKey and ApiSecret should be stored encrypted at rest. See the Security for additional details.

Standard Example

The following example demonstrates a standard address validation request. For situations where the validation has failed or the address being provided is incomplete, consider making 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

The isResidential value returned should be treated as a suggestion and not a guarantee.

Suggestion Example

The following example demonstrates an address suggestion request. Scenarios in which such requests are made include:

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

In order 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 values returned in the Suggestions collection are not guaranteed to be valid. Items within the collection should be iterated through and validated manually.

Warning

The isResidential value returned should be treated as a suggestion and not a guarantee.

Note

AddressValidation runs an internal validation engine under the covers to validate both the request and the response. You will find these results in the Warnings and Errors collections from the IAddressValidationResponse object.

Items within the Suggestion collection are not processed by the internal validator.

Edit this page