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

ParameterFormatLength RestrictionRequiredExplanation
"firstName"String - may not contain special characters except dashes -, apostrophes ', and spaces.50YThe Avenu customer's first name.
"middleInitial"String - may not contain special characters.1NThe 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.50YThe Avenu customer's last name.
"dateOfBirth"String; ISO 8601 YYYY-MM-DD10YThe Avenu customer's date of birth.
"address"String200YThe customer's physical street address.
"city"String100YThe customer's city.
"state"String - US standard 2 letter state codes.2YThe customer's state.
"zipCode"Number - may not contain dashes or hyphens and should be numbers only.5 or 9 digitsNThe customer's zip code.
"country"String; ISO 3166 Alpha-3 country code3YThe address' country.
"citizenship"String; ISO 3166 Alpha-3 country code3YThe 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]
320YThe customer's email.
"mobilePhone"Number - should be numbers only and may not contain dashes or hyphens.10YThe customer's mobile phone.
"idType"String - see ID Types ) table below for acceptable values20YGovernment ID type. See types table below.
"idNumber"String - may not contain special characters except dashes '-'20Y - 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.5Y - 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-DD10N (Y - for some ID Types)Government entity issue date.
"idExpirationDate"String; ISO 8601 YYYY-MM-DD10N (Y - for some ID Types )Government entity expiration date.
"deviceId"String - may not contain special characters except dashes/hyphens.100NThe user's unique device identifier.
"deviceType"String - may not contain special characters.50NThe type of the user's device
"deviceName"String - may not contain special characters.100NThe name given to the user's device.
"deviceOperatingSystem"String - may not contain special characters.100NThe 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
15NCurrent IP Address for the device.
"deviceLocation"String - may not contain special characters.100NCurrent location for the device.
"deviceLongitude"String - should conform to the ISO 6709:2022 standard for longitudes and latitudes.50NDevice's location longitude.
"deviceLatitude"String - should conform to the ISO 6709:2022 standard for longitudes and latitudes.50NDevice's location latitude.
"deviceUser"String - may not contain special characters.50NThe name of the user of the device.
"deviceIMEINumber"String - may not contain special characters.15NMobile device unique equipment identifier.
"deviceTorEnabled"Boolean - can only be Y/N1NDevice is/is not using Tor browser.
"deviceFirstSeen"String; ISO 8601 yyyy-mm-dd10NDate the device was first used to access Avenu.
"deviceLastSeen"String; ISO 8601 yyyy-mm-dd10NDate 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