Account Holders

Learn how to create an account holder object.

Account holders and accounts have a 1:1 relationship. When an account holder is successfully created, an associated account is also created.

To create an account holder object for an individual end-user, a Know Your Customer (KYC) process is run to verify the identity of the individual. We support three types of workflows for KYC:

  • Basic KYC offers identity verification with an immediate accepted or rejected decision, and no remediation opportunity
  • Advanced KYC [beta] offers identity verification with a remediation path if the initially submitted information was not successfully verified - either by resubmitting corrected information or uploading a document
  • BYO KYC allows an API user to bypass the Lithic KYC process and create an individual account (available only to users with KYC processes pre-approved by Lithic)

To create a business account holder, a Know Your Business (KYB) process is run to verify the identity of the business. We support two types of workflows for KYB:

  • Basic KYB [beta] offers identity verification with an immediate pending decision, with a final accepted or rejected decision provided via webhook within 2 business days
  • BYO KYB [beta] allows an API user to bypass the Lithic KYB process and create an individual account (available only to users with KYB processes pre-approved by Lithic)
  • KYC-Exempt [beta] allows certain programs to enroll users as KYC-exempt. This includes programs whose account holders do not require any KYC or KYB or programs that wish to supplement business account holder objects with representations of individual cardholders. You can use the KYC-exempt workflow to create account holders. KYC-exempt allows an API user to pass in a smaller set of PII to create an account holder (available only to users approved by Lithic on a program by program basis)

Create Account Holders (Enterprise)

This endpoint runs the entered individual or business's information (i.e., account holder) through a Customer Identification Program (CIP), and creates an account holder object.

If Lithic's KYC or KYB (i.e., not BYO) workflow is used and the account holder is successfully verified or requires further verification, an associated account_token will be returned in the response, which can then be used to issue cards once the workflow indicates an ACCEPTED status. If a BYO KYC, BYO KYB, or KYC-exempt (coming soon) workflow is used, as long as the required inputs are passed in, an associated account_token will be returned in the responses, which can then be used to issue cards.

In certain cases, responses from this endpoint may indicate the workflow is under review or further action is needed to complete the account creation process. If using a workflow with asynchronous responses (Advanced KYC or Basic KYB), we recommend first setting up webhooks to be notified of events (see Create Webhook for KYC/KYB Status) relating to the outcomes of the workflows.

šŸš§

As a reminder, while using this endpoint is an important part of ensuring your card program is compliant with relevant government and banking regulations, you are responsible for all financial activity on api.lithic.com associated with your API key. This endpoint is intended to be used for KYC/KYB compliance purposes, and not as a comprehensive fraud solution.

POST https://api.lithic.com/v1/account_holders

Sample KYC 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-13T00:00:00Z",
   "individual": {
      "first_name": "Johnny",
      "last_name": "AppleSeed",
      "dob": "1990-06-28",
      "phone_number": "+15555555555",
      "email": "[email protected]",
      "government_id": "000003333",
      "address": {
         "address1": "123 Main Street",
         "postal_code": "10128",
         "city": "New York", 
         "state":"NY",
         "country":"USA"
      }
   }
}
'

Sample KYC Response

{
    "data": {
        "account_token": "8dc88f3e-21ea-4d17-9a1c-00cea1a76cf9",
        "status": "ACCEPTED",
        "status_reasons": [],
        "token": "12345678-aa69-4cbc-a946-30d90181b621"
    }
}

Sample KYB 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": "New Coffee Shop",
      "government_id": "000003333",
      "address": {
          "address1": "456 Main Street",
          "city": "New York",
          "state": "NY",
          "postal_code": "10128",
          "country": "USA"
      },
      "phone_numbers": ["+15555555555"]
   },
   "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": "+15555555555",
      "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": "+15555555556",
         "email": "[email protected]",
         "government_id": "000004444",
         "address": {
            "address1": "789 Main Street",
            "postal_code": "10128", 
            "city": "New York",
            "state": "NY", 
            "country": "USA"
         }
      }    
   ]
}
'

Sample KYB Response

{
    "data": {
        "account_token": "8dc88f3e-21ea-4d17-9a1c-00cea1a76cf9",
        "status": "PENDING",
        "status_reasons": [],
        "token": "12345678-aa69-4cbc-a946-30d90181b621"
    }
}

Fields used in all account creation calls:

idempotency-token (optional, header)Optional unique identifier of max length 36-characters to ensure idempotency in requests; this identifier will be checked to prevent repeated retries of the same request.
String. Permitted values: 1 to 36 characters.
workflow (required)Specifies the type of account creation workflow to run.
String. Permitted values:
- KYC_BASIC: Basic KYC
- KYC_ADVANCED: Advanced KYC [beta]
- KYC_BYO: Bring Your Own KYC
- KYB_BASIC: Basic KYB [beta]
- KYB_BYO: Bring Your Own KYB [beta]
- KYC_EXEMPT: KYC-Exempt (coming soon)
tos_timestamp (required)AnĀ ISO 8601Ā timestamp indicating when the account holder accepted the applicable legal agreements (e.g., cardholder terms) as agreed upon during API customer's implementation with Lithic.
String. Permitted values: ISO 8601 timestamp (yyyy-MM-ddThh:mm:ssZ).

Additional fields for KYC workflows:

individual (object, required)Information on individual for whom the account is being opened and KYC is being run. See Individual Schema.
Object. Permitted values: Valid individual object.
kyc_passed_timestamp (required only if workflow is KYC_BYO)AnĀ ISO 8601Ā timestamp indicating when pre-approved KYC was completed on the individual with a pass result.
String. Permitted values: ISO 8601 timestamp (yyyy-MM-ddThh:mm:ssZ).

Additional fields for KYB workflows:

business_entity (object, required)Information for business for which the account is being opened and KYB is being run. See Business Entity Schema.
Object. Permitted values: Valid business_entity object.
nature_of_business (required)Short description of the company's line of business (i.e., what does the company do?).
String.
website_url (required)Company website URL.
String.
business_owner_entities (list of objects, required if no business_owner_individual are provided)List of all entities with 25% or more ownership in the company.

If no entity or individual owns 25% or more of the company, and the largest shareholder is an entity, please identify them in this field. See FinCEN requirements (Section I) for more background on entities that should be included.

This field should be a list of one or more business entities. See Business Entity Schema. If no business owner is an entity, pass in an empty list. However, either this parameter or business_owner_individual must be populated.
List of objects. Permitted values: List of valid business_entity objects.
business_owner_individuals (list of objects, required if no business_owner_individuals are provided)List of all individuals with 25% or more ownership in the company.

If no entity or individual owns 25% or more of the company, and the largest shareholder is an individual, please identify them in this field. See FinCEN requirements (Section I) for more background on individuals that should be included.

This field should be a list of one or more individuals. See Individual Schema. If no business owner is an individual, pass in an empty list. However, either this parameter or business_owner_entity must be populated.
List of objects. Permitted values: List of valid individual objects.
control_person (object, required)An individual with significant responsibility for managing the legal entity (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer). This can be an executive, or someone who will have program-wide access to the cards that Lithic will provide. In some cases, this individual could also be a beneficial owner listed above. See FinCEN requirements (Section II) for more background.
Object. Permitted values: Valid individual object.
kyb_passed_timestamp (required only if workflow is KYB_BYO)AnĀ ISO 8601Ā timestamp indicating when pre-approved KYB was completed on the individual with a pass result.
String. Permitted values: ISO 8601 timestamp (yyyy-MM-ddThh:mm:ssZ).

Additional fields for KYC-exempt workflow:

kyc_exemption_type (required)Specifies the type of KYC exemption under which this account holder is being created.
String. Permitted values:
- AUTHORIZED_USER: Authorized user account holder
- PREPAID_CARD_USER: Prepaid card user account holder
first_name (required)Individual's first name, as it appears on government-issued identity documents.
String.
last_name (required)Individual's last name, as it appears on government-issued identity documents.
String.
email (required)Email address.
String. Permitted values: Valid email address. For example, "[email protected]".
phone_number (required)Individual's phone number.
String. E.164 format without hyphens. For example, "+12124007676" for a US phone number.
address (object, optional)Individual's current address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable. Only USA addresses are currently supported. See Address Schema.
Object. Valid address object.

Individual Schema

first_name (required)Individual's first name, as it appears on government-issued identity documents.
String.
last_name (required)Individual's last name, as it appears on government-issued identity documents.
String.
dob (required)Date of birth.
String. ISO 8601 format (yyyy-MM-dd).
government_id (required)Government-issued identification number (required for identity verification and compliance with banking regulations). Social Security Numbers (SSN) and Individual Taxpayer Identification Numbers (ITIN) are currently supported, entered as full nine-digits, with or without hyphens.
String. Permitted values: Full nine-digits, with or without hyphens (###-##-#### or #########).
email (required)Email address.
String. Permitted values: Valid email address. For example, "[email protected]".
phone_number (required)Individual's phone number.
String. E.164 format without hyphens. For example, "+12124007676" for a US phone number.
address (object, required)Individual's current address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable. Only USA addresses are currently supported. See Address Schema.
Object. Valid address object.

Address Schema

address1 (required)Valid deliverable address (no PO boxes).
String.
address2 (optional)Unit or apartment number (if applicable).
String.
city (required)City name.
String.
state (required)Valid state code. Only USA state codes are currently supported.
String. Permitted values: Uppercase ISO 3166-2 two-character abbreviation for USA addresses. For example, "CA" for California.
postal_code (required)Valid postal code. Only USA ZIP codes are currently supported.
String. Permitted values: 5 or 10 characters. For US addresses, either five-digit zipcode or nine-digit "ZIP+4".
country (required)Country name. Only USA is currently supported.
String. Permitted values: Uppercase ISO 3166-1 alpha-3 three-character abbreviation. For example, USA.

Business Entity Schema

legal_business_name (required)Legal (formal) business name.
String.
dba_business_name (optional)Any name that the business operates under that is not its legal business name (if applicable).
String.
parent_company (optional)Parent company name (if applicable).
String.
government_id (required)Government-issued identification number. US Federal Employer Identification Numbers (EIN) are currently supported, entered as full nine-digits, with or without hyphens.
String. Permitted values: Full nine-digit EIN, with or without hyphens (##-####### or #########).
address (object, required)Business's physical address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable. See Address Schema.
Object. Permitted values: Valid address object.
phone_numbers (list, required)One or more of the business's phone number(s), entered as a list in E.164 format. For example, "+12124007676" for US phone numbers.
List. Permitted values: List of phone numbers, entered in E.164 format without hyphens. For example, "+12124007676" for US phone numbers.

Potential Outcomes by Workflow Type

WorkflowPotential status values returned via this endpoint
Basic KYC- ACCEPTED: account holder creation was successful and both account_holder_token and account_token are returned
- REJECTED: account holder creation was unsuccessful
Advanced KYC- ACCEPTED: account holder creation was successful and both account_holder_token and account_token are returned
- REJECTED: account holder creation was unsuccessful
- PENDING_RESUBMIT: one or more critical KYC fields may have been mis-entered and both account_holder_token and account_token are returned, but account is not yet in ACTIVE state; see Resubmit Information to proceed
- PENDING_DOCUMENT: government-issued document is required to verify identity and both account_holder_token and account_token are returned, but account is not yet in ACTIVE state; see Submit Document to proceed
BYO KYC- ACCEPTED: account holder creation was successful and both account_holder_token and account_token are returned
KYC-Exempt beta- ACCEPTED: account holder creation was successful
Basic KYB- PENDING: submitted information is under review and both account_holder_token and account_token are returned, but account is not yet in ACTIVE state; final APPROVED or REJECTED status to be provided via webhook
BYO KYB- ACCEPTED: account holder creation was successful

Resubmit Information [beta]

This endpoint is used in cases where a KYC submission returned a PENDING_RESUBMIT result. This step must be completed in order to proceed with the KYC evaluation.

The required parameters for creating an individual account should be checked and resubmitted. Potential statuses returned from this endpoint are ACCEPTED, REJECTED PENDING_RESUBMIT, or PENDING_DOCUMENT.

Two resubmission attempts are permitted via this endpoint before a REJECTED status is returned and the account creation process is terminated.

POST https://api.lithic.com/v1/account_holders/{token}/resubmit

Sample Request

curl https://api.lithic.com/v1/account_holders/12345678-aa69-4cbc-a946-30d90181b621/resubmit \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "individual": {
      "first_name": "Johnny",
      "last_name": "AppleSeed", 
      "dob":"1990-06-29",
      "phone_number":"+15555555555",
      "email":"[email protected]",
      "government_id":"000003333",
      "address": {
         "address1": "124 Main Street", 
         "postal_code": "10128",
         "city": "New York", 
         "state": "NY",
         "country": "USA"
      }
   },
   "tos_timestamp": "2022-01-13T00:00:00Z"
}
'

Sample Response

{
    "data": {
        "account_token": "8dc88f3e-21ea-4d17-9a1c-00cea1a76cf9",
        "status": "ACCEPTED",
        "status_reasons": [],
        "token": "12345678-aa69-4cbc-a946-30d90181b621"
    }
}
idempotency-token (optional, header)Optional unique identifier of max length 36-characters to ensure idempotency in requests; this identifier will be checked to prevent repeated retries of the same request.
String. Permitted values: 1 to 36 characters.
token (required, path parameter)Token associated with the account holder for which information is being resubmitted.
String. Permitted values: 36-digit version 4 UUID (including hyphens).
individual (object, required)Information on individual for whom the account is being opened and KYC is being re-run. See Individual Schema.
Object. Permitted values: Valid individual object.
tos_timestamp (required)AnĀ ISO 8601Ā timestamp indicating when Lithic's terms of service were accepted by the API customer.
String. Permitted values: ISO 8601 timestamp (yyyy-MM-ddThh:mm:ssZ).

Submit Document [beta]

These instructions are used in cases where a KYC attempt has returned the result PENDING_DOCUMENT. Before initiating these steps, we recommend setting up webhooks to be notified of events (see Create Webhook for KYC/KYB Status) relating to the document submission process. There are three steps involved in submitting documentation for verification:

  1. Use the Initiate Document Upload endpoint to identify the type of supported document you will be uploading; this will return two URLs to which you will upload a front image and back image of the document
  2. Upload the two document images directly to the provided URLs
  3. Use the Get Document Upload Status at any time to check the status of the document upload or to retrieve the URLs needed to proceed with verification

Initiate Document Upload

This endpoint is used to identify which type of supported government-issued documentation you will upload for further verification. It will return two URLs - one for the front image and one for the back image - with the status of each shown in a PENDING state.

POST https://api.lithic.com/v1/account_holders/{token}/documents

Sample Request

curl https://api.lithic.com/v1/account_holders/12345678-aa69-4cbc-a946-30d90181b621/documents \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "document_type": "drivers_license"
}
'

Sample Response

{
  "account_holder_token": "12345678-aa69-4cbc-a946-30d90181b621",
  "token": "bf47c70c-70eb-43ab-b278-4ff59a70bcc4",
  "document_type": "drivers_license",
  "required_document_uploads": [
    {
      "image_type": "front",
      "status": "PENDING",
      "status_reasons": [],
      "upload_url": "https://lithic-document-verification-uploads...",
      },
    {
      "image_type": "back",
      "status": "PENDING",
      "status_reasons": [],
      "upload_url": "https://lithic-document-verification-uploads...",
      }
  ]
}
account_holder_token (required, path parameter)Token associated with the account holder for which information is being submitted.
String. Permitted values: 36-digit version 4 UUID (including hyphens).
document_type (required)Type of documentation to be submitted for verification. The following types of documentation, issued by these government entities, are currently supported:
- commercial_license: Commercial driverā€™s license (United States only)
- drivers_license: Driverā€™s license (United States only)
- passport: Passport (Argentina, Australia, Bahrain, Belarus, Bermuda, Brazil, Cameroon, Canada, China, Colombia, CĆ“te d'Ivoire, Denmark, Finland, France, Germany, Ghana, Haiti, Honduras, Hong Kong, Hungary, Iceland, India, Indonesia, Iraq, Ireland, Israel, Italy, Jamaica, Japan, Korea, Republic of, Latvia, Macao, Malaysia, Malta, Mexico, Myanmar, Netherlands, New Zealand, Nigeria, Pakistan, Peru, Philippines, Poland, Russian Federation, Singapore, South Africa, Sri Lanka, Switzerland, Syrian Arab Republic, Thailand, Uganda, Ukraine, United Kingdom, United States, Vietnam)
- passport_card: Passport Card (United States only)
- visa: Visa (United States only)

Upload Document Images

Once front and back image of the individual's supported document are received, upload the images to the provided URLs with the below payload:

curl \
-X PUT \
--upload-file "/path/to/file" \
"https://lithic-document-verification-uploads..."

A few notes about uploading the document images:

  • Acceptable image types are JPG, JPEG, and PNG; other image types uploaded will return a FAILED document status with INVALID_FILE_TYPE as the status_reason (which you can see via the Get Document Upload Status endpoint)
  • Maximum file size allowed per upload is 15 MiB
  • Both URLs are linked to the account_token submitted through the Initiate Document Upload endpoint, and are unique to the image type (i.e., the front image must be uploaded to the URL tied to the front image; back image must be uploaded to the URL tied to the back image)
  • If document verification results in an ACCEPTED KYC status for the individual, the document images uploaded will be retained by Lithic for compliance records; if document verification results in KYC statuses of REJECTED or PENDING_DOCUMENT (i.e., document image needs to be submitted again), the document images uploaded will be deleted
  • If you need to retrieve the upload links at any point or obtain new links (they expire after 7 days), use the Get Document Upload Status endpoint

Get Document Upload Status

After uploading document images to the provided URLs, this endpoint can be used to check the status of the document upload. Note that this is a separate process from checking the status of the KYC evaluation overall (a document may be successfully uploaded but the KYC evaluation can still be rejected) - use the Check KYC/KYB Status endpoint for that purpose.

A status will be returned for each image (front and back), with these possible status values:

  • PENDING: Document image has not yet been received
  • UPLOADED: Document has been successfully uploaded but verification has not yet been run (typically because the second image has not yet been successfully uploaded)
  • COMPLETED: Verification has been run on the document
  • FAILED: Document image was not successfully uploaded - this may be due to an incorrect file format, or the uploaded image was blurry or contains glare (which will be reflected in status_reasons)

Once both images are in UPLOADED status, the document is run through KYC verification. This will generate either an ACCEPTED or REJECTED status for the KYC evaluation, which you can check via the Check KYC/KYB Status endpoint or be notified via webhook.

If a document upload fails, a new URL will be generated that can be retrieved via this endpoint. The response structure will be modified with an additional object under required_document_uploads with a status of PENDING. If no document upload is attempted within 7 days of the original link being generated, the link will be refreshed when this endpoint is called.

GET https://api.lithic.com/v1/account_holders/{account_holder_token}/documents/{token}

Sample Request

curl https://api.lithic.com/v1/account_holders/12345678-aa69-4cbc-a946-30d90181b621/documents/bf47c70c-70eb-43ab-b278-4ff59a70bcc4 \
  -X GET \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \

Sample Response

{
  "account_holder_token": "12345678-aa69-4cbc-a946-30d90181b621",
  "token": "bf47c70c-70eb-43ab-b278-4ff59a70bcc4",
  "document_type": "drivers_license",
  "required_document_uploads": [
    {
      "image_type": "front",
      "status": "PENDING",
      "status_reasons": null,
      "upload_url": "https://lithic-document-verification-uploads..."
    },
    {
      "image_type": "back",
      "status": "COMPLETED",
      "status_reasons": null,
      "upload_url": null
    }
  ]
}
account_holder_token (required, path parameter)Token associated with the account holder for which document upload status is being retrieved.
String. Permitted values: 36-digit version 4 UUID (including hyphens).
token (required, path parameter)Token associated with the document for which an upload status is being retrieved.
String. Permitted values: 36-digit version 4 UUID (including hyphens).

Check KYC/KYB Status

This endpoint is used to check the status of a KYC or KYB evaluation.

GET https://api.lithic.com/v1/account_holders/{token}

Sample Request

curl https://api.lithic.com/v1/account_holders/12345678-aa69-4cbc-a946-30d90181b621 \
  -X GET \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \

Sample Response

{
      "token": "12345678-aa69-4cbc-a946-30d90181b621",
      "phone_number": "15555555555",
      "email": "[email protected]",
      "status": "ACCEPTED"
}
token (required, path parameter)Token identifying the account holder for which KYC or KYB status is being retrieved.
String. Permitted values: 36-digit version 4 UUID (including hyphens).

Create Webhook for KYC/KYB Status

You can create a webhook to be notified of updates to the status of any in-process KYC or KYB evaluation. Calling this endpoint with a different URL will re-register the new URL and rotate the HMAC token. Since HMAC verification is available, the IP addresses from which KYC/KYB webhooks are sent are subject to change.

Two specific use cases where we recommend the use of webhook updates are:

  • KYC workflows: In the case where documents need to be submitted for verification, a webhook will notify you once the document upload status changes, or an ACCEPTED or REJECTED status for the KYC evaluation is available
  • KYB workflows: All Basic KYB workflows will initially return a PENDING_REVIEW status, and a webhook will notify you once an ACCEPTED or REJECTED status is available
POST https://api.lithic.com/v1/webhooks/account_holders

Sample Request

{
  "url": "https://mywebhook.com/incoming"
}

Sample Response

{
  "data": {
    "hmac_token": "52969474-5dc5-42f7-927a-2e3b45b3d7d2"
  }
}

The webhook payload will have the following structure:

{
  "event_time": <ISO 8601 timestamp>,
  "account_token": <token>,
  "type": <type>,
  "status": <status>,
  "status_reasons": list<status_reasons>,
  "token": <token>,  
}
Webhook type (type)Potential status values returned
verification: Webhook content relates to the verification status of a KYC or KYB evaluation (i.e., the account was successfully or unsuccessfully created)- ACCEPTED: Status of a verification has been updated from PENDING_DOCUMENT to ACCEPTED (KYC use case) or PENDING to ACCEPTED (KYB use case)
- REJECTED: Status of a verification has been updated from PENDING_DOCUMENT to REJECTED (KYC use case) or PENDING to REJECTED (KYB use case)
document_upload_front or document_upload_back: Webhook content relates to the upload status of the front or back image of an identity document- FAILED: Uploaded document has failed

KYC/KYB Workflow Diagrams and Expected Response Times

Expected Response Times:

  • Steps 1 + 2 - Customer submits required PII and receives response containing status for the account holder: Up to 5 seconds

Expected Response Times:

  • Initial Call - Steps 1 + 2 - Customer makes initial call with required PII and receives response containing status for the account holder: Up to 5 seconds
  • Pending Resubmit - Steps 1 + 2 - Customer resubmits required PII and receives response containing status for the account holder: Up to 5 seconds
  • Pending Document - Steps 1 + 2 - Customer initiates document upload and receives upload links: Up to 2 seconds
  • Pending Document - Steps 3 + 4 - Customer uploads document images to provided links and receives webhook containing status for the account holder: Up to 35 seconds

Expected Response Times:

  • Steps 1 + 2 - Customer makes call with required PII and receives response containing status for the account holder: Up to 3 seconds

Expected Response Times:

  • Steps 1 + 2 - Customer makes call with required business data and PII, and receives a pending review status for the account holder: Up to 15 seconds
  • Steps 2 + 3 - Customer receives pending review status from the initial call, then subsequently receives a webhook containing final status for the account holder: Up to 48 business hours

Expected Response Times:

  • Steps 1 + 2 - Customer makes call with required business data and PII, and receives response containing status for the account holder: Up to 3 seconds

Failure Reasons

KYC Failure Reasons

When a KYC evaluation fails, one or more of the following reasons will be returned in the response (contained in status_reasons).

ADDRESS_VERIFICATION_FAILUREThe address provided could not be verified.
AGE_THRESHOLD_FAILUREThe individualā€™s provided age did not fall within an acceptable age range. This can include a COPPA-related failure.
BLOCKLIST_ALERT_FAILUREThe individual appeared on one or more government watch lists.
COMPLETE_VERIFICATION_FAILUREThe individualā€™s identity could not be verified based on information available in searched records.
DOB_VERIFICATION_FAILUREThe date of birth provided could not be verified.
ID_VERIFICATION_FAILUREThe government-issued identification number provided could not be matched.
NAME_VERIFICATION_FAILUREThe name provided could not be verified.
OTHER_VERIFICATION_FAILUREThe individual was rejected for a reason other than one specified above. Contact Lithic support for more information.
RISK_THRESHOLD_FAILUREThe user was flagged for high risk of fraud.

KYB Failure Reasons

When a KYB evaluation fails, one or more of the following reasons will be returned in the response (contained in status_reasons).

BENEFICIAL_OWNER_INDIVIDUAL_BLOCKLIST_ALERT_FAILUREOne or more of the beneficial owner individual's appear on one or more government watch lists.
BENEFICIAL_OWNER_INDIVIDUAL_DOB_VERIFICATION_FAILUREOne or more of the beneficial owner individual's date of birth provided could not be verified.
BENEFICIAL_OWNER_INDIVIDUAL_ID_VERIFICATION_FAILUREOne or more of the business owner individual's government-issued identification number(s) provided could not be matched.
BENEFICIAL_OWNER_INDIVIDUAL_NAME_VERIFICATION_FAILUREOne or more of the business owner individual's name(s) provided could not be verified.
CONTROL_PERSON_BLOCKLIST_ALERT_FAILUREThe control person appeared on one or more government watch lists.
CONTROL_PERSON_DOB_VERIFICATION_FAILUREThe control person's date of birth provided could not be verified.
CONTROL_PERSON_ID_VERIFICATION_FAILUREThe control person's government-issued identification number provided could not be matched.
CONTROL_PERSON_NAME_VERIFICATION_FAILUREThe control peron's name provided could not be verified.
PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILUREThe address of the primary business entity provided could not be verified.
PRIMARY_BUSINESS_ENTITY_ID_VERIFICATION_FAILUREThe government-issued identification of the primary business entity provided could not be verified.
PRIMARY_BUSINESS_ENTITY_NAME_VERIFICATION_FAILUREThe name of the primary business entity provided could not be verified.
OTHER_VERIFICATION_FAILUREThe business entity could not be verified for other reasons.

Document Upload Failure Reasons

When a document upload fails, one or more of the following reasons will be returned in the response (contained in status_reasons).

FRONT_IMAGE_BLURRYFront image of document is blurry and cannot be processed.
FRONT_IMAGE_GLAREFront image of document contains glare and cannot be processed.
BACK_IMAGE_BLURRYBack image of document is blurry and cannot be processed.
BACK_IMAGE_GLAREBack image of document contains glare and cannot be processed.
INVALID_DOCUMENT_TYPEDocument uploaded is not supported. Refer to supported document types listed.
INVALID_DOCUMENT_UPLOADDocument upload failed for other or unknown reasons.

Simulating Account Holder Creation in Sandbox

See Simulating Account Holder Creation page for detail.