Validate Address

Check the delivered customer addresses as well as a phonetic and associative identification of duplicates. Additionally, checks of client-specific negative or positive lists can be processed. Usually, the AddressCheck is used for the pure verification of the address data e.g. for registration processes.

Path

POST /api/v3/validate/address

Request Body

application/json

required

object

The person initiating the checkout, typically the buyer who places the order. May also receive the order.

identificationNumber

string

Max length: 20

National ID number (if the customer is a physical person). Registration number (if the customer is a company).

birthDate

required

string

yyyy-MM-dd

Date of birth. Not required if customerCategory is 'Company'.

object

Customer address

legalForm

string

Max length: 255

Type of business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.

object

existingCustomer

boolean

Is customer an existing customer for merchant

verifiedCustomerIdentification

boolean

This field signifies whether the customer's identification has been successfully verified.

marketingOptIn

boolean

Shows if merchant is allowed to send marketing information to customer

customerSince

string

yyyy-MM-ddTHH:mm:ss.fffffffzzz

Since when customer has been merchant's client

customerClassification

string

Max length: 255

Customer reputation (e.g. VIP client)

acquisitionChannel

string

Enum:

NotSet
Advertisment
SocialNetwork
Direct
SearchEngine
Other

Customer acquisition channel

hasCustomerCard

boolean

Shows if customer has loyalty card

customerCardSince

string

yyyy-MM-ddTHH:mm:ss.fffffffzzz

The date when the loyalty card was issued to the customer

customerCardClassification

string

Specifies the level of the loyalty card (e.g Gold member). For DE, AT, CH, this must be an integer from 1 to 5, where 5 is the highest VIP level.

profileTrackingId

string

Max length: 50

ipAddress

string

Max length: 39

Customer’s IP address

numberOfTransactions

integer

Total number of successful purchases that have been made by the specific consumer

customerIndividualScore

string

The customer's individual risk score provided by the merchant. Accepts a number from -10000 to 10000 (can be encased in quotation marks or not), or a single case-insensitive letter from 'a' to 'z'.

userAgent

string

Max length: 4096

UserAgent of this specific consumer

amountOfTransactions

number

Amount of paid orders last 12 months

otherPaymentMethods

boolean

Other payment method than MI in wallet

verifiedCustomerIdentificationType

string

Max length: 255

Specific method or category used to authenticate or verify a customer's identity

verifiedCustomerIdentificationDate

string

yyyy-MM-dd

Date on which a customer's identification details have been successfully confirmed or authenticated dateformat: yyyy-MM-dd

customerNumber

string

Max length: 100

Customer number has to be unique, if no customer number available please leave empty

salutation

string

Enum:

Mr
Mrs
Miss

Salutation

firstName

string

Max length: 50

First name. Everything over 50 characters will be truncated

lastName

string

Max length: 50

Last name. Everything over 50 characters will be truncated

companyName

string

Max length: 255

Purchasing company name. Everything over 255 characters will be truncated. This field is mandatory for processing B2B transactions in Austria, Belgium, Germany, the Netherlands and Switzerland.

string

Max length: 255

phone

string

Max length: 16

Customer’s fixed-line phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format. The resulting number can contain up to 16 characters, including the country code.

mobilePhone

string

Max length: 16

Customer’s mobile phone number. The number will be normalised by us, removing non-numeric characters and converting it to international format. The resulting number can contain up to 16 characters, including the country code.

customerCategory

required

string

Enum:

Company
Person

Customer category

conversationLanguage

string

Enum:

The language code used for client communication. If not provided, the system will default to the language configured for the client.

distributionType

string

Enum:

Paper
Email
Sms

How information (invoices, notices, etc.) will be distributed to customer.

vatId

string

Max length: 50

VAT registration number, the unique number that identifies a business. This field is mandatory for processing B2B transactions in Austria, Germany and Switzerland.

Responses

isValid

boolean

Is response valid
object

Customer address
careOf

string
Max length: 50

Care of. Intermediary who is responsible for transferring a piece of mail between the postal system and the final addressee. For example Jane c/o John (“Jane at John's address”). This field has to be used for company, authority and organization names as well - e. g. "Sportverein Blau-Weiß e.V.

street

string
Max length: 100

Name of street or packstation

streetNumber

string
Max length: 10

Street or packstation number

streetNumberAdditional

string
Max length: 10

Additional street number

postalCode

string
Max length: 10

Postal code

postalPlace

string
Max length: 100

Postal place
countryCode

string

Enum:
NO
SE
FI
DK
DE
AT
CH
NL
BE

Country code
array

Risk check messages
type

string

Enum:
BusinessError
TechnicalError
NotificationMessage

code

string
Max length: 100

Confirmation or error code

message

string
Max length: 4096

Message content

customerFacingMessage

string
Max length: 4096

Message to display to customer

actionCode

string

Enum:
Unavailable
AskConsumerToConfirm
AskConsumerToReEnterData
OfferSecurePaymentMethods
RequiresSsn
AskConsumerToIdentify
ManualReview

Action codes

fieldReference

string
Max length: 100

Reference to field that caused an error
type

string

Enum:
BusinessError
TechnicalError
NotificationMessage
code

string
Max length: 100

Confirmation or error code

message

string
Max length: 4096

Message content

customerFacingMessage

string
Max length: 4096

Message to display to customer
actionCode

string

Enum:
Unavailable
AskConsumerToConfirm
AskConsumerToReEnterData
OfferSecurePaymentMethods
RequiresSsn
AskConsumerToIdentify
ManualReview

Action codes
fieldReference

string
Max length: 100

Reference to field that caused an error
401 Authorization has been denied for this request.
413 Request body too large.
429 Too many requests.
500 Internal server error.

Successful Request

Request Example

    
        {
 "customer": {
  "email": "astrid.svensson@example.com",
  "address": {
   "street": "Gütersloher Straße",
   "postalCode": "33415",
   "countryCode": "DE",
   "postalPlace": "Berlin",
   "streetNumber": "123"
  },
  "lastName": "Svensson",
  "riskData": {
   "ipAddress": "123.123.123.123"
  },
  "birthDate": "1999-01-02",
  "firstName": "Astrid",
  "customerCategory": "Person"
 }
}

Response Example

    
        {
 "isValid": true,
 "correctedAddress": {
  "street": "Gütersloher Str.",
  "postalCode": "33415",
  "countryCode": "DE",
  "postalPlace": "Verl",
  "streetNumber": "123"
 }
}