onboard/v1/customer
[POST] /onboard/v1/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/v1/customer endpoint to re-start the onboarding process from the start.
Example [POST] Request
{{avenu_base_url}}/onboard/v1/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 | 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: [email protected] [email protected] [email protected] | 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)
Element | Details |
---|---|
status | The customer's status code |
statusInfo | Additional information associated with the status code |
ID Type
ID Type | Description | Required Fields |
---|---|---|
SSN | Social security Number; This is a required identifier | idType, idNumber, idIssuedBy |
DRIVER_LICENSE | Drivers License; Requires ID front and back scans | idType, idNumber, idIssuedBy, idIssueDate, idExpirationDate |
ID_CARD | Government ID card; Requires ID front and back scans | idType, idNumber, idIssuedBy, idIssueDate, idExpirationDate |
PASSPORT | Passport; Requires Passport first-page scan | idType, 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"
}
Category | Response Code | Response Error Message |
---|---|---|
Required | CA3000 | {Field Name} : Missing Required Field |
Size | CA3107 | {Field Name} : Invalid Length |
Format | CA3107 | {Field Name} : Invalid Format |
Required | CA3104 | Invalid Data |
Updated 23 days ago