onboard/v2/customer

[POST] /onboard/v2/customer

Onboard a new customer

The onboard section of Avenu's API is used for creating a customer. Onboard requests are sent through Avenu's know-your-customer (KYC) checks. The onboarding endpoint does not support batch processing. If you have an existing customer base please talk to a Sales associate for information on importing existing customers into the Avenu platform.

To onboard a new customer, provide at least two accepted IDs to the governmentIds array. One of which must be a social security number (SSN).

Device identification is optional, but it is passed to Hummingbird for help with case management (refunds, fraud, etc.).

A customer attempting to onboard with the Avenu platform that fails during the eKYC process can retry the onboarding process again. We recommend sending their information to the /onboard/v2/customer endpoint to re-start the onboarding process from the start.

Example [POST] Request

{{avenu_base_url}}/onboard/v2/customer
{ "firstName" : "", "middleInitial" : "", "lastName" : "", "dateOfBirth" : "", "address" : "", "city" : "", "state" : "", "zipCode" : "", "country" : "", "citizenship" : "", "email" : "", "mobilePhone" : "", "governmentIds": [ { "idType": "", "idNumber": "", "idIssuedBy" : "", "idIssueDate" : "", "idExpirationDate" : "", }, { "idType": "", "idNumber": "", "idIssuedBy" : "", "idIssueDate" : "", "idExpirationDate" : "", } ], "deviceIdentity": { "deviceId": "", "deviceType": "", "deviceName": "", "deviceOperatingSystem": "", "deviceIPAddress": "", "deviceLocation": "", "deviceLongitude": "", "deviceLatitude": "", "deviceUser": "", "deviceIMEINumber" : "", "deviceTorEnabled" : "", "deviceFirstSeen" : "", "deviceLastSeen" : "" } }

Input Parameters

Parameter

Format

Length Restriction

Required

Explanation

"firstName"

String - may not contain special characters except dashes -, apostrophes ', and spaces.

50

Y

The Avenu customer's first name.

"middleInitial"

String - may not contain special characters.

1

N

The Avenu customer's middle initial. Avenu will not accept a full middle name, only an initial

"lastName"

String - may not contain special characters except dashes -, apostrophes ', and spaces.

50

Y

The Avenu customer's last name.

"dateOfBirth"

String; ISO 8601 YYYY-MM-DD

10

Y

The Avenu customer's date of birth.

"address"

String - does not allow the following special characters ^[a-zA-Z0-9&@.,:-=+#%_ ]$

200

Y

The customer's physical street address.

"city"

String

100

Y

The customer's city.

"state"

String - US standard 2 letter state codes.

2

Y

The customer's state.

"zipCode"

Number - may not contain dashes or hyphens and should be numbers only.

5 or 9 digits

N

The customer's zip code.

"country"

String; ISO 3166 Alpha-3 country code

3

Y

The address' country.

"citizenship"

String; ISO 3166 Alpha-3 country code

3

Y

The customer's citizenship.

"email"

String; Excluding most special characters (!"#$%'*+:;<=>?[]^_`{|}~)

  • Except dashes, periods, and the "at" sign (@) directly preceding the domain name. The @ symbol must be followed by most common top level domains. Accepted domains: .com/.co/.net/.org/.edu/.gov/.us Example:\
    first.last@gmail.com
    firstlast123@gmail.com
    first-last123@gmail.com

320

Y

The customer's email.

"mobilePhone"

Number - should be numbers only and may not contain dashes or hyphens.

10

Y

The customer's mobile phone.

"idType"

String - see ID Types ) table below for acceptable values

20

Y

Government ID type. See types table below.

"idNumber"

String - may not contain special characters except dashes '-'

20

Y - see ID Types

Number on government id.

"idIssuedBy"

String - ISO 3166-2 "US" prefix with the 2 letter state code or just the 2 letter state code. ("US-XX" or just "XX".) Use "USA" for SSN idType.

5

Y - see ID Types

Government entity issuing id. Use USA for SSN. Use "US-AL" as an example for United States Alabama. US plus two letter state code.

"idIssueDate"

String; ISO 8601 YYYY-MM-DD

10

N (Y - for some ID Types)

Government entity issue date.

"idExpirationDate"

String; ISO 8601 YYYY-MM-DD

10

N (Y - for some ID Types )

Government entity expiration date.

"deviceId"

String - may not contain special characters except dashes/hyphens.

100

N

The user's unique device identifier.

"deviceType"

String - may not contain special characters.

50

N

The type of the user's device

"deviceName"

String - may not contain special characters.

100

N

The name given to the user's device.

"deviceOperatingSystem"

String - may not contain special characters.

100

N

The OS of the user's device.

"deviceIPAddress"

String - Has to be IPv4, should follow the dot-decimal notation, consisting of four decimal numbers, each ranging from 0 to 255, separated by dots.
Example: 192.168.7.138

15

N

Current IP Address for the device.

"deviceLocation"

String - may not contain special characters.

100

N

Current location for the device.

"deviceLongitude"

String - should conform to the ISO 6709:2022 standard for longitudes and latitudes.

50

N

Device's location longitude.

"deviceLatitude"

String - should conform to the ISO 6709:2022 standard for longitudes and latitudes.

50

N

Device's location latitude.

"deviceUser"

String - may not contain special characters.

50

N

The name of the user of the device.

"deviceIMEINumber"

String - may not contain special characters.

15

N

Mobile device unique equipment identifier.

"deviceTorEnabled"

Boolean - can only be Y/N

1

N

Device is/is not using Tor browser.

"deviceFirstSeen"

String; ISO 8601 yyyy-mm-dd

10

N

Date the device was first used to access Avenu.

"deviceLastSeen"

String; ISO 8601 yyyy-mm-dd

10

N

Date the device was last used to access Avenu.

Example Response

{ "customer": { "firstName" : "", "middleInitial" : "", "lastName" : "", "dateOfBirth" : "", "address" : "", "city" : "", "state" : "", "zipCode" : "", "country" : "", "citizenship" : "", "email" : "", "mobilePhone" : "", "governmentIds": [ { "idType" : "", "idNumber" : "", "idIssuedBy" : "", "idIssueDate" : "", "idExpirationDate" : "", }, { "idType": "", "idNumber": "", "idIssuedBy" : "", "idIssueDate" : "", "idExpirationDate" : "", } ], "deviceIdentity": { "deviceId": "", "deviceType": "", "deviceName": "", "deviceOperatingSystem": "", "deviceIPAddress": "", "deviceLocation": "", "deviceLongitude": "", "deviceLatitude": "", "deviceUser": "", "deviceIMEINumber" : "", "deviceTorEnabled" : "", "deviceFirstSeen" : "", "deviceLastSeen" : "" } }, "status": "", "statusInfo": "" }

Response Elements

(In addition to the original input parameters)

ElementDetails
statusThe customer's status code
statusInfoAdditional information associated with the status code

ID Type

ID TypeDescriptionRequired Fields
SSNSocial security Number; This is a required identifieridType, idNumber, idIssuedBy
DRIVER_LICENSEDrivers License; Requires ID front and back scansidType, idNumber, idIssuedBy, idIssueDate, idExpirationDate
ID_CARDGovernment ID card; Requires ID front and back scansidType, idNumber, idIssuedBy, idIssueDate, idExpirationDate
PASSPORTPassport; Requires Passport first-page scanidType, idNumber, idIssuedBy, idIssueDate, idExpirationDate

Error Codes

For Required, Size, and Format restrictions an error code may be returned for each field. Only one error code is returned per field each time in that order. For example, if firstName is >50 characters and has special characters, only the size restriction error code and message will be sent back first as:

{ "code": "CA3107", "message": "firstName: Invalid Length" }
CategoryResponse CodeResponse Error Message
RequiredCA3000{Field Name} : Missing Required Field
SizeCA3107{Field Name} : Invalid Length
FormatCA3107{Field Name} : Invalid Format
RequiredCA3104Invalid Data
FormatAA8006{Email} : Invalid Format
RequiredAA8006Invalid Data
RequiredAA8004GovID Issue Date - Missing Required Field
RequiredAA8004GovID Expiration Date - Missing Required Field
RequiredAA8007Invalid Data
RequiredAA8008Invalid Data

Did this page help you?