Simulating Account Holder Creation

Simulate various pending or rejected statuses in KYC/KYB in sandbox.

Basic KYC

To simulate a KYC rejection in sandbox with Basic KYC (i.e., POST /account_holders calls with workflow = KYC_BASIC passed in), you can call the POST /account_holders endpoint with the following request body:

{
    "workflow": "KYC_BASIC",
    "tos_timestamp": ..., // any valid input
    "idempotency_token": ..., // any valid input
    "individual": {
    "first_name": "kyc",
        "last_name": "simulator",
        "dob": "2021-01-01",
        "government_id": "000-00-0001",
        "email": ..., // any valid input
        "phone_number": "+1234567890",
        "address": {
            "address1": ..., // any valid input
            "city": ..., // any valid input
            "state": ..., // any valid input
            "postal_code": ..., // any valid input
            "country": ... // any valid input
        }
    }
}

In order to simulate a KYC failure with a specific reason, below are the possible values for the government_id property:

# Note: any value not listed here results in an ACCEPTED result
"000-00-0001": "ADDRESS_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0002": "NAME_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0003": "DOB_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0004": "ID_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0005": "OTHER_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0006": "AGE_THRESHOLD_FAILURE" // status = "REJECTED"
"000-00-0007": "RISK_THRESHOLD_FAILURE" // status = "REJECTED"
"000-00-0008": "BLOCKLIST_ALERT_FAILURE" // status = "REJECTED"
"000-00-0009": "MULTIPLE_RECORDS_FAILURE" // status = "REJECTED"
"000-00-0010": "COMPLETE_VERIFICATION_FAILURE" // status = "REJECTED"

Sample Request

curl https://api.lithic.com/v1/account_holders
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "workflow": "KYC_BASIC",
   "tos_timestamp": "2022-01-13 00:00:00",
   "individual": {
      "first_name": "kyc",
      "last_name": "simulator",
      "dob":"2021-01-01",
      "phone_number": "+1234567890",
      "email": "[email protected]",
      "government_id": "000-00-0001", 
      "address": {
         "address1": "123 Main Street",
         "city": "New York",
         "state": "NY",
         "postal_code": "10128",
         "country": "USA"
      }
   }
}
'

Advanced KYC

To simulate a KYC rejection or pending status with Advanced KYC (i.e., POST /account_holders calls with workflow = KYC_ADVANCED passed in), you can call the POST /account_holders endpoint with the following request body:

{
    "workflow": "KYC_ADVANCED",
    "tos_timestamp": ..., // any valid input
    "idempotency_token": ..., // any valid input
    "individual": {
    "first_name": "kyc",
        "last_name": "simulator",
        "dob": "2021-01-01",
        "government_id": "000-00-0001",
        "email": ..., // any valid input
        "phone_number": "+1234567890",
        "address": {
            "address1": ..., // any valid input
            "city": ..., // any valid input
            "state": ..., // any valid input
            "postal_code": ..., // any valid input
            "country": ... // any valid input
        }
    }
}

In order to simulate various statuses and status reasons associated with them, below are the possible values for the government_id property:

# Note: any value not listed here results in an ACCEPTED result
"000-00-0001": "ADDRESS_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0002": "NAME_VERIFICATION_FAILURE" // status = "PENDING_RESUBMIT"
"000-00-0003": "DOB_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0004": "ID_VERIFICATION_FAILURE" // status = "PENDING_RESUBMIT"
"000-00-0005": "OTHER_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0006": "AGE_THRESHOLD_FAILURE" // status = "REJECTED"
"000-00-0007": "RISK_THRESHOLD_FAILURE" // status = "REJECTED"
"000-00-0008": "BLOCKLIST_ALERT_FAILURE" // status = "REJECTED"
"000-00-0009": "MULTIPLE_RECORDS_FAILURE" // status = "PENDING_DOCUMENT"
"000-00-0010": "COMPLETE_VERIFICATION_FAILURE" // status = "REJECTED"

Sample Request

curl https://api.lithic.com/v1/account_holders
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
      "workflow": "KYC_ADVANCED",
      "tos_timestamp": "2022-01-13 00:00:00",
      "individual": {
         "first_name": "kyc",
         "last_name": "simulator",
         "dob":"2021-01-01",
         "phone_number": "+1234567890",
         "email": "[email protected]",
         "government_id": "000-00-0001",
         "address": {
            "address1": "123 Main Street",
            "city": "New York",
            "state": "NY", 
            "postal_code": "10128",
            "country": "USA"
         }
     }
}
'

KYB Basic

KYB failure simulation cases coming soon!


Did this page help you?