Address Validation API

Try Now

POST https://api.piyovi.io/v1/shipment/address_validation

Overview

The Address Validation API allows you to verify and standardize addresses before creating a shipment. This helps reduce delivery issues and shipping costs by ensuring address data is accurate and properly formatted.

Authentication

This API requires authentication using one of the following methods:

• Bearer Token: Include JWT with Bearer prefix in the Authorization header
• API Key: Include X-API-KEY header with your API key

For more details, see Authentication Guide.

Request Format

POST /v1/shipment/address_validation
Content-Type: application/json
Authorization: Bearer {token}

Request Body

{
  "address": {
    "companyName": "Acme Corp",
    "contactName": "John Smith",
    "emailAddress": "john@example.com",
    "phoneNumber1": "555-123-4567",
    "address1": "123 Main St",
    "address2": "Suite 200",
    "area": "Downtown",
    "city": "San Francisco",
    "stateProvince": "CA",
    "country": "US",
    "zipPostalCode": "94105",
    "vatorTax": "12345",
    "vatorTaxType": "EIN",
    "vatorTaxTypeCountryCode": "US",
    "addressType": "Commercial"
  }
}

Response Format

Success Response (200 OK)

{
  "success": true,
  "validatedAddress": [
    {
      "addressId": "addr-12345",
      "companyName": "Acme Corp",
      "contactName": "John Smith",
      "emailAddress": "john@example.com",
      "phoneNumber1": "555-123-4567",
      "address1": "123 MAIN ST",
      "address2": "STE 200",
      "city": "SAN FRANCISCO",
      "stateProvince": "CA",
      "country": "US",
      "zipPostalCode": "94105-1234",
      "verified": true
    }
  ],
  "status": "Valid",
  "addressType": "Commercial",
  "validationOptions": [
    {
      "key": "StandardizedAddress",
      "value": "123 MAIN ST STE 200, SAN FRANCISCO CA 94105-1234",
      "message": "Address has been standardized",
      "messageType": "Info"
    }
  ]
}

Error Response (400 Bad Request)

{
  "success": false,
  "errors": [
    {
      "code": "InvalidAddress",
      "message": "Unable to validate address",
      "type": "ValidationError"
    }
  ]
}

Field Reference

Request Fields

Field	Type	Required	Description
address	object	Yes	Container for address information

Address Object Fields

Field	Type	Required	Description
companyName	string	No	Company name
contactName	string	No	Contact person's name
emailAddress	string	No	Email address for communications
phoneNumber1	string	No	Primary phone number
address1	string	Yes	Primary address line (street number and name)
address2	string	No	Secondary address information (apt, suite, unit)
area	string	No	Area or district within city
city	string	Yes	City name
stateProvince	string	Yes	State, province, or region
country	string	Yes	Country code (2-letter ISO code recommended)
zipPostalCode	string	Yes	Postal or ZIP code
vatorTax	string	No	VAT number or tax ID
vatorTaxType	string	No	Type of tax identifier (e.g., EIN, VAT)
vatorTaxTypeCountryCode	string	No	Country code for tax purposes
addressType	string	No	Type of address (e.g., Commercial, Residential)

Response Fields

Field	Type	Description
success	boolean	Indicates if validation was successful
errors	array	Error details if validation failed
warnings	array	Warning messages about potential issues
validatedAddress	array	Array of validated address objects
status	string	Overall validation status (Valid, Invalid, Partial)
addressType	string	Detected address type (Commercial, Residential)
remarks	object	Additional information about address validation
validationOptions	array	Alternative address suggestions or corrections

Validated Address Object Fields

Field	Type	Description
addressId	string	Unique identifier for the address
companyName	string	Standardized company name
contactName	string	Contact person's name
emailAddress	string	Email address
phoneNumber1	string	Primary phone number
address1	string	Standardized street address line 1
address2	string	Standardized street address line 2
city	string	Standardized city name
stateProvince	string	Standardized state or province
country	string	Standardized country
zipPostalCode	string	Standardized postal or ZIP code
fullAddress	string	Complete formatted address
verified	boolean	Indicates if address is verified

Validation Option Fields

Field	Type	Description
key	string	Type of validation option
value	string	Suggested value or correction
message	string	Description of the suggestion
messageType	string	Type of message (Info, Warning, Error)

Examples

US Address Validation

{
  "address": {
    "companyName": "Tech Solutions Inc",
    "contactName": "Sarah Johnson",
    "address1": "1 Market St",
    "address2": "Floor 23",
    "city": "San Francisco",
    "stateProvince": "CA",
    "country": "US",
    "zipPostalCode": "94105"
  }
}

International Address Validation

{
  "address": {
    "companyName": "Global Imports GmbH",
    "contactName": "Hans Schmidt",
    "address1": "Friedrichstrasse 123",
    "city": "Berlin",
    "stateProvince": "Berlin",
    "country": "DE",
    "zipPostalCode": "10117"
  }
}

Residential Address Validation

{
  "address": {
    "contactName": "Maria Garcia",
    "address1": "742 Evergreen Terrace",
    "city": "Springfield",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "62701",
    "addressType": "Residential"
  }
}

Address Validation with Incomplete Information

{
  "address": {
    "companyName": "Widgets Co",
    "address1": "123 Main",
    "city": "Chicago",
    "stateProvince": "IL",
    "country": "US",
    "zipPostalCode": "60601"
  }
}

Notes

• Always validate addresses before creating shipments to avoid delivery issues and additional charges.
• The API will attempt to standardize and correct addresses, adding any missing information when possible.
• Address validation is particularly important for international shipments to ensure customs compliance.
• The response may include multiple suggestions if the address could not be fully validated.
• Address type detection (Commercial vs. Residential) helps avoid carrier surcharges for incorrect address type classification.
• Standardized addresses conform to the postal authority format for the specified country.