Table of Contents

UPS® Integration

AddressValidation offers a complete integration to the UPS® 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 and an active UPS account before you use this integration. After you sign in, follow these instructions to get your credentials.

Installation

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

dotnet package add VisusIO.AddressValidation.Integration.Ups

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

builder.Services.AddUpsAddressValidation();
Important

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

Configuration

Configuration is bound from the AddressValidationSettings:Ups section.

{
  "AddressValidationSettings": {
    "Ups": {
      "AccountNumber": "<your account number>",
      "ClientId": "<your client id>",
      "ClientSecret": "<your client secret>",
      "ClientEnvironment": "PRODUCTION"
    }
  }
}
Property Required Description
AccountNumber Yes Your UPS account number
ClientId Yes OAuth 2.0 client ID issued by UPS for your registered application
ClientSecret Yes OAuth 2.0 client secret issued by UPS 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
Important

Store ClientId and ClientSecret encrypted at rest. See Security for more details.

Standard Example

The following example demonstrates a standard address validation request.

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

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

    [HttpPost]
    public async Task<IActionResult> Post([FromBody] UpsAddressValidationRequest 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);
    }
}
Note

When ClientEnvironment is set to DEVELOPMENT only addresses in New York (NY) and California (CA) are supported.

{
  "XAVRequest": {
    "Request": {
      "RequestOption": "3"
    },
    "AddressKeyFormat": {
      "AddressLine": [
        "1 Infinite Loop"
      ],
      "PoliticalDivision2": "Cupertino",
      "PoliticalDivision1": "CA",
      "PostcodePrimaryLow": "95014",
      "CountryCode": "US"
    }
  }
}

Suggestion Example

For an incomplete or ambiguous request, the response may include a potential match with suggestions.

Note

When ClientEnvironment is set to DEVELOPMENT only addresses in New York (NY) and California (CA) are supported.

{
  "XAVRequest": {
    "Request": {
      "RequestOption": "3"
    },
    "AddressKeyFormat": {
      "AddressLine": [
        "1 Infinite Lp"
      ],
      "PoliticalDivision2": "Cupertino",
      "PoliticalDivision1": "CA",
      "PostcodePrimaryLow": "95014",
      "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