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