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 an ACCEPTED result
"000-00-0001": "BENEFICIAL_OWNER_INDIVIDUAL_NAME_VERIFICATION_FAILURE" // status = "PENDING_REVIEW"
"000-00-0002": "BENEFICIAL_OWNER_INDIVIDUAL_DOB_VERIFICATION_FAILURE" // status = "PENDING_REVIEW"
"000-00-0003": "BENEFICIAL_OWNER_INDIVIDUAL_ID_VERIFICATION_FAILURE" // status = "PENDING_REVIEW"
"000-00-0004": "BENEFICIAL_OWNER_INDIVIDUAL_BLOCKLIST_ALERT_FAILURE" // status = "PENDING_REVIEW"
"000-00-0001": "CONTROL_PERSON_NAME_VERIFICATION_FAILURE" // status = "PENDING_REVIEW"
"000-00-0002": "CONTROL_PERSON_DOB_VERIFICATION_FAILURE " // status = "PENDING_REVIEW"
"000-00-0003": "CONTROL_PERSON_ID_VERIFICATION_FAILURE" // status = "PENDING_REVIEW"
"000-00-0004": "CONTROL_PERSON_BLOCKLIST_ALERT_FAILURE" // status = "PENDING_REVIEW"
"000-00-0001": "PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILURE" // status = "PENDING_REVIEW"
"000-00-0002": "PRIMARY_BUSINESS_ENTITY_ID_VERIFICATION_FAILURE " // status = "PENDING_REVIEW"
"000-00-0003": "PRIMARY_BUSINESS_ENTITY_NAME_VERIFICATION_FAILURE " // status = "PENDING_REVIEW"
"000-00-0004": "OTHER_VERIFICATION_FAILURE " // status = "PENDING_REVIEW"
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"
}
Updated 11 months ago