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 https://sandbox.lithic.com/v1/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 https://sandbox.lithic.com/v1/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"
         }
     }
}
'

Basic KYB

To simulate creating an account holder in sandbox with the Basic KYB workflow (i.e., POST /account_holders calls with workflow = KYB_BASIC), you can call the POST https://sandbox.lithic.com/v1/account_holders endpoint with the following request body:

{
   "workflow": "KYB_BASIC",
   "tos_timestamp": ..., // any valid input
   "business_entity": {
      "legal_business_name": ..., // any valid input
      "government_id": "000-00-0001",
      "address": {
          "address1": ..., // any valid input
          "city": ..., // any valid input
          "state": ..., // any valid input
          "postal_code": ..., // any valid input
          "country": ... // any valid input
      },
      "phone_numbers": [...], // any valid input
   }
   "website_url": ..., // any valid input
   "nature_of_business": ..., // any valid input
   "control_person": {
      "first_name": ..., // any valid input
      "last_name": ..., // any valid input
      "dob": ..., // any valid input
      "phone_number": ..., // any valid input
      "email": ..., // any valid input
      "government_id": ..., // any valid input
      "address": {
         "address1": ..., // any valid input
         "postal_code": ..., // any valid input
         "city": ..., // any valid input
         "state": ..., // any valid input
         "country": ... // any valid input
        }
      },
   "beneficial_owner_individuals": [
      {
         "first_name": ..., // any valid input
         "last_name": ..., // any valid input
         "dob": ..., // any valid input
         "phone_number": ..., // any valid input
         "email": ..., // any valid input
         "government_id": ..., // any valid input
         "address": {
            "address1": ..., // any valid input
            "postal_code": ..., // any valid input
            "city": ..., // any valid input
            "state": ..., // any valid input 
            "country": ... // any valid input
         }
      }    
   ]
}

Sandbox will look for specific values for government_id within the business_entity object in your request in order to trigger either an ACCEPTED status or a REJECTED status with desired status_reasons. Other body parameters will be accepted as long as they are properly formatted. The test cases available are:

# Note: any value not listed here results in a PENDING_REVIEW result
"000-00-0001": // status = "ACCEPTED" with no associated "status_reasons"
"000-00-0002": "BENEFICIAL_OWNER_INDIVIDUAL_BLOCKLIST_ALERT_FAILURE" // status = "REJECTED"
"000-00-0003": "BENEFICIAL_OWNER_INDIVIDUAL_DOB_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0004": "BENEFICIAL_OWNER_INDIVIDUAL_ID_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0005": "BENEFICIAL_OWNER_INDIVIDUAL_NAME_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0006": "CONTROL_PERSON_BLOCKLIST_ALERT_FAILURE" // status = "REJECTED"
"000-00-0007": "CONTROL_PERSON_DOB_VERIFICATION_FAILURE " // status = "REJECTED"
"000-00-0008": "CONTROL_PERSON_ID_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0009": "CONTROL_PERSON_NAME_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0010": "PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILURE" // status = "REJECTED"
"000-00-0011": "PRIMARY_BUSINESS_ENTITY_ID_VERIFICATION_FAILURE " // status = "REJECTED"
"000-00-0012": "PRIMARY_BUSINESS_ENTITY_NAME_VERIFICATION_FAILURE   " // status = "REJECTED"
"000-00-0013": "OTHER_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": "KYB_BASIC",
   "tos_timestamp": "2022-01-13T00:00:00Z",
   "business_entity": {
      "legal_business_name": "KYB Simulator",
      "government_id": "000-00-0001",
      "address": {
          "address1": "456 Main Street",
          "city": "New York",
          "state": "NY",
          "postal_code": "10128",
          "country": "USA"
      },
      "phone_numbers": ["+11111111111"]
   },
   "website_url": "newcoffeeshop.com",
   "nature_of_business":"Retail store selling coffee and other food items",
   "control_person": {
      "first_name": "Johnny", 
      "last_name": "AppleSeed",
      "dob": "1990-06-28",
      "phone_number": "+22222222222",
      "email": "[email protected]",
      "government_id": "000003333",
      "address": {
         "address1": "123 Main Street",
         "postal_code": "10128", 
         "city": "New York",
         "state": "NY",
         "country": "USA"
        }
      },
   "beneficial_owner_individuals": [
      {
         "first_name": "Mary",
         "last_name": "AppleSeed",
         "dob": "1991-06-28",
         "phone_number": "+12312312341",
         "email": "[email protected]",
         "government_id": "000004444",
         "address": {
            "address1": "789 Main Street",
            "postal_code": "10128", 
            "city": "New York",
            "state": "NY", 
            "country": "USA"
         }
      }    
   ]
}
'

Once your request is successfully submitted, a PENDING_REVIEW status will be returned, followed by a webhook containing the final status (as determined by the test case submitted) with the below example body. The webhook will be sent to the URL configured via the POST https://sandbox.lithic.com/v1/webhooks/account_holders endpoint.

{
   "event_time": "2020-07-15T17:48:48Z",
   "account_token": "528215b6-ba72-429b-96b3-af0a2ea4431b",
   "type": "verification",
   "status": "ACCEPTED",
   "status_reasons": [],
   "token": "575e7b36-958f-4651-af5d-ceea8c72024a"
}