API documentation Addresses

Contents

Address Data

The following describes the validations that are in place for address records, and the data sanitations that you will need to perform before sending the data to ViaEurope.

Addresses are currently used in the following contexts:

Data Sanitation

You will need to ensure to perform the following data sanitations on the address data that you submit to ViaEurope in order to ensure that the data can be processed without error. Failure to do so might result in the request being rejected with an error.

Key(s) Description
name1 , name2 , street , city
  • You need to make sure these fields contain only valid characters in the Extended Latin character set. Umlauts and characters with diacritics are allowed, but special characters such as curly quotes or non-printable characters are not.
  • This regular expression for Java matches valid strings: ^(?>(\p{IsLatin}|[\u0020-\u007E]))*$
  • Additionally you need to make sure the string does not include any newline or linebreak characters (such as \n or \r ). Each field may only be one line. See below for maximum lengths.
street , city , zip , email , phone
  • You must strip any and all double-quote characters ( "..." ) from these strings.
street
  • You need to ensure that the streed field contains only the street name and house number, and no other information such as floor or apartment number (these may be in name2 ).
  • You need to ensure that the street does not contain either the name of the city or the city's postal code ( zip ).
  • You need to make sure that the street does not contain any company names or buildings, these should be in name1 name2
zip
  • You need to ensure that the postal code is in the correct format. The specific format will depend on the country of the address.
city
  • The country code must be submitted as a 2-letter country code according to the ISO 3166-2 standard. For example NL or DE
phone
  • You need to ensure that the phone number contains only the plus + and minus - characters and the numbers 0-9 zero to nine. Whitespaces are not allowed. The maximum length for a phone number is 25 characters.
email
  • You need to ensure that the email is a valid email address. It needs to include at least one dot . and one at sign @ and match the following regular expression: /\A[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z/

Data Validation

We perform the validations on the various address fields which may produce the following errors. If you have performed the aforementioned sanitations, your data should be accepted; but keep in mind that there may be additional context-specific validations. This list is not exhaustive.

You may test your address data against our address validation API to see if it passes our validations.

Bear in mind that courier networks might perform their own checks and might reject a delivery even though it passed our validation. The delivery record will be set to state rejected_at_courier in this case. Your account manager can help you determine additional limitations that might apply to your choice of delivery network.

Key Description Datatype Constraints Errors
service Name String Optional. The name of the delivery service that is planned to be used with the submitted address. It will be used to check if that courier charges extra for delivering to the given address. 200 OK with an additional JSON payload of warnings (See example). The address is still considered valid and can be used in subsequent requests despite the warning.
  • Service not recognized
name1 Name String Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name1 can't be blank
  • Name1 is too long (maximum is 35 characters)
  • Name1 must only contain latin or printable ASCII characters
  • Name1 must not contain multiple lines
name2 Name (continued) String Optional. Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name2 must only contain latin or printable ASCII characters
  • Name2 is too long (maximum is 35 characters)
  • Name2 must not contain multiple lines
street Street String Maximum 70 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks. Must not contain zip code. Must not contain city.
  • Street can't be blank
  • Street is too long (maximum is 70 characters)
  • Street must not contain city, building, or company name
  • Street must only contain latin or printable ASCII characters
  • Street must not contain multiple lines
city City String 2-35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • City can't be blank
  • City is too short (minimum is 2 characters)
  • City is too long (maximum is 35 characters)
  • City must only contain latin or printable ASCII characters
  • City must not contain multiple lines
country Country String 2 character ISO 3166-Alpha 2 country code.
  • Country can't be blank
  • Country is unknown or not supported
  • Country is invalid
zip Zip String Zipcode associated with the address
  • ZIP can't be blank
  • ZIP has invalid format (country-specific)
email Email of recipient String Optional. Maximum 50 characters
  • Email can't be blank
  • Email is not a valid email address
  • Email is too long (maximum is 50 characters)
phone Phone number String Optional. Maximum 15 characters. Must only contain characters 0-9, plus and minus.
  • Phone can't be blank
  • Phone must only contain characters 0-9, plus and minus
  • Phone is too long (maximum is 25 characters)