Skip to main content

Validate Address

GET /api/3pl/{company}/address

Validate the customer address before requesting rates. The endpoint returns the accepted address or a recommended correction.

Address line 1 has a maximum of 70 characters and address line 2 a maximum of 50 characters, including spaces. Validate the final address before collecting payment or burning a token, and validate again if it changes. Shorten long addresses or split them across the two lines; addresses are never truncated automatically. /rates and /order also enforce these limits.

Recipient names and address fields must use printable English/ASCII characters. Non-English characters are rejected before any carrier request.

curl --get "https://www.dyli.io/api/3pl/$DYLI_3PL_COMPANY/address" \
-H "x-api-key: $DYLI_3PL_API_KEY" \
--data-urlencode "name=Jamie Doe" \
--data-urlencode "email=jamie@example.com" \
--data-urlencode "phone=+1 212 555 0100" \
--data-urlencode "address_line_1=123 Main Street" \
--data-urlencode "address_line_2=Suite 4" \
--data-urlencode "city_locality=New York" \
--data-urlencode "state_province=NY" \
--data-urlencode "postal_code=10001" \
--data-urlencode "country_code=US"

Query Parameters​

NameRequiredDescription
nameYesRecipient name.
emailYesValid recipient email.
phoneYesRecipient phone number, including country code when applicable.
address_line_1YesStreet address. Maximum 70 characters, including spaces.
address_line_2NoApartment, suite, or unit. Maximum 50 characters, including spaces.
city_localityYesCity or locality.
state_provinceYesState, province, or region. Use a two-letter code for US addresses.
postal_codeYesPostal or ZIP code.
country_codeYesTwo-letter country code.

Valid Address​

{
"valid": true,
"address": {
"address_line_1": "123 Main St",
"address_line_2": "Suite 4",
"city_locality": "New York",
"state_province": "NY",
"postal_code": "10001",
"country_code": "US"
},
"original_address": {
"address_line_1": "123 Main St",
"address_line_2": "Suite 4",
"city_locality": "New York",
"state_province": "NY",
"postal_code": "10001",
"country_code": "US"
}
}

Suggested Correction​

An address that can be corrected returns 200 with valid: false and corrected: true.

{
"valid": false,
"corrected": true,
"recommended_address": {
"address_line_1": "123 MAIN ST",
"address_line_2": "SUITE 4",
"city_locality": "NEW YORK",
"state_province": "NY",
"postal_code": "10001-0001",
"country_code": "US"
},
"errors": []
}

Show the recommendation to the customer and use the confirmed address in /rates and /order. Shipping to Canada is available. Shipping to Russia is temporarily unavailable and returns unsupported_country with the message "Shipping to Russia is temporarily unavailable." Address validation, rates, and order creation all enforce this pause.

Address Line Too Long​

An address exceeding 70 characters on line 1 or 50 characters on line 2 returns 400 with the affected fields. The error message gives the limit for each affected line. The same error is returned by /rates and /order, even when address validation is skipped.

{
"valid": false,
"code": "SHIPPING_ADDRESS_TOO_LONG",
"error": "Address line 1 must be 70 characters or fewer, including spaces. Shorten the address or split it across both lines.",
"fields": ["address_line_1"]
}

Unsupported Characters​

Non-English characters return 400 and identify the fields that need to be corrected. This is a validation response and is not logged as a carrier or server failure.

{
"valid": false,
"code": "NON_ASCII_SHIPPING_ADDRESS",
"error": "Use English characters only for the recipient name and shipping address.",
"fields": ["name", "city_locality"]
}