Validate an address

Article
04/11/2024

Applies to: Partner Center | Partner Center operated by 21Vianet | Partner Center for Microsoft Cloud for US Government

This article explains how to validate an address using the address validation API.

The address validation API should only be used for prevalidation of customer profile updates. Based on the API response status, the caller should choose the most appropriate address for the customer.

Prerequisites

Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.

C#

To validate an address, first instantiate a new Address object and populate it with the address to validate. Then, retrieve an interface to Validations operations from the IAggregatePartner.Validations property, and call the IsAddressValid method with the address object.

IAggregatePartner partnerOperations;

// Create an address to validate.
Address address = new Address()
{
    AddressLine1 = "One Microsoft Way",
    City = "Redmond",
    State = "WA",
    PostalCode = "98052",
    Country = "US"
};

// Validate the address.
AddressValidationResponse result = partnerOperations.Validations.IsAddressValid(address);

// If the request completes successfully, you can inspect the response object.

// See the status of the validation.
Console.WriteLine($"Status: {addressValidationResult.Status}");

// See the validation message returned.
Console.WriteLine($"Validation Message Returned: {addressValidationResult.ValidationMessage ?? "No message returned."}");

// See the original address submitted for validation.
Console.WriteLine($"Original Address:\n{this.DisplayAddress(addressValidationResult.OriginalAddress)}");

// See the suggested addresses returned by the API, if any exist.
Console.WriteLine($"Suggested Addresses Returned: {addressValidationResult.SuggestedAddresses?.Count ?? "None."}");

if (addressValidationResult.SuggestedAddresses != null && addressValidationResult.SuggestedAddresses.Any())
{
    addressValidationResult.SuggestedAddresses.ForEach(a => Console.WriteLine(this.DisplayAddress(a)));
}

// Helper method to pretty-print an Address object.
private string DisplayAddress(Address address)
{
    StringBuilder sb = new StringBuilder();

    foreach (var property in address.GetType().GetProperties())
    {
        sb.AppendLine($"{property.Name}: {property.GetValue(address) ?? "None to Display."}");
    }

    return sb.ToString();
}

REST request

Request syntax

Method	Request URI
POST	{baseURL}/v1/validations/address HTTP/1.1

Request headers

For more information, see Partner Center REST headers.

Request body

This table describes the required properties in the request body.

Name	Type	Required*	Description
addressline1	string	Y	The first line of the address.
addressline2	string	N	The second line of the address. This property is optional.
city	string	Y	The city.
state	string	Y	The state.
postalcode	string	Y	The postal code.
country	string	Y	The two-character ISO alpha-2 country code.

* Required properties may change based on the country or region.

Response details

The response returns one of the following status messages. If status response is not Verified or VerifiedShippable, review your entered address and/or suggested address. It's up to the caller to choose the most appropriate address for the customer.

Status	Description	Number of suggested addresses returned	Status response recommendation
Verified shippable	Address is verified and can be shipped to.	Single	Proceed with verified address.
Verified	Address is verified.	Single	Proceed with verified address.
Interaction required	Suggested address is significantly changed and needs user confirmation.	Single	Proceed with user confirmed address.
Street partial	The given street in the address is partial and needs more info.	Multiple—maximum of three	Proceed with user confirmed address.
Premises partial	The given premises (building number, suite number, and others) are partial and need more info.	Multiple—maximum of three	Proceed with user confirmed address.
Multiple	There are multiple fields that are partial in the address (potentially also including street partial and premises partial).	Multiple—maximum of three	Proceed with user confirmed address.
None	Address is incorrect.	None	Proceed with user confirmed address.
Not validated	Address wasn't able to be sent through the validation process.	None	Proceed with user confirmed address.

Request example

# "VerifiedShippable" Request Example

POST https://api.partnercenter.microsoft.com/v1/validations/address HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
MS-CorrelationId: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
MS-RequestId: eb55c2b8-6f4b-4b44-9557-f76df624b8c0
Host: api.partnercenter.microsoft.com
Content-Length: 137
X-Locale: en-US

{
    "AddressLine1": "1 Microsoft Way",
    "City": "Redmond",
    "State": "WA",
    "PostalCode": "98052",
    "Country": "US"
}

# "StreetPartial" Request Example

POST https://api.partnercenter.microsoft.com/v1/validations/address HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
MS-CorrelationId: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
MS-RequestId: ee6cf74c-3ab5-48d6-9269-4a4b75bd59dc
Host: api.partnercenter.microsoft.com
Content-Length: 135
X-Locale: en-US

{
    "AddressLine1": "Microsoft Way",
    "City": "Redmond",
    "State": "WA",
    "PostalCode": "98052",
    "Country": "US"
}

REST response

If successful, the method returns an AddressValidationResponse object in the response body, with a HTTP 200 status code. An example follows.

Response success and error codes

Each response comes with an HTTP status code that indicates success or failure and debugging information. Use a network trace tool to read this code, error type, and other parameters. For the full list, see Partner Center REST error codes.

Response example

# "VerifiedShippable" Response Example

HTTP/1.1 200 OK
Date: Mon, 17 May 2021 23:19:19 GMT
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
MS-RequestId: eb55c2b8-6f4b-4b44-9557-f76df624b8c0
X-Locale: en-US
 
{
    "originalAddress": {
        "country": "US",
        "city": "Redmond",
        "state": "WA",
        "addressLine1": "1 Microsoft Way",
        "postalCode": "98052"
    },
    "suggestedAddresses": [
        {
            "country": "US",
            "city": "Redmond",
            "state": "WA",
            "addressLine1": "1 Microsoft Way",
            "postalCode": "98052-8300"
        }
    ],
    "status": "VerifiedShippable"
}

# "StreetPartial" Response Example

HTTP/1.1 200 OK
Date: Mon, 17 May 2021 23:34:08 GMT
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
MS-RequestId: ee6cf74c-3ab5-48d6-9269-4a4b75bd59dc
X-Locale: en-US
 
{
    "originalAddress": {
        "country": "US",
        "city": "Redmond",
        "state": "WA",
        "addressLine1": "Microsoft Way",
        "postalCode": "98052"
    },
    "suggestedAddresses": [
        {
            "country": "US",
            "city": "Redmond",
            "state": "WA",
            "addressLine1": "1 Microsoft Way",
            "postalCode": "98052-6399"
        }
    ],
    "status": "StreetPartial",
    "validationMessage": "Address field invalid for property: 'Region', 'PostalCode', 'City'"
}