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 four 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)
• KYC-Exempt 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 Individual Account Holders

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 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

{
  "workflow": "KYC_BYO",
  "individual": {
    "address": {
      "address1": "123 Old Forest Way",
      "city": "Omaha",
      "country": "USA",
      "postal_code": "68022",
      "state": "NE"
    },
    "dob": "1991-03-08 08:00:00",
    "email": "[email protected]",
    "first_name": "Tom",
    "government_id": "111-23-1411",
    "last_name": "Bombadil",
    "phone_number": "+12124007676"
  },
  "tos_timestamp": "2022-03-08 08:00:00",
  "kyc_passed_timestamp": "2022-03-08 08:00:00"
}
'

Sample KYC Response

{
  "account_token": "819993c6-2b89-4ebc-b5c4-d40ce637b640",
  "status": "ACCEPTED",
  "status_reasons": [],
  "token": "e7d26ae4-52f8-4a78-8eca-a1c078261f3f",
  "created": "2023-10-06T15:16:16.230770"
}

Fields used in all account creation calls:

Additional fields for KYC workflows:

Additional fields for KYC-exempt workflow:

Individual Schema

Address Schema

Potential Outcomes by Workflow Type

Update Individual Account Holder

API Reference: Update account holder information

PATCH https://api.lithic.com/v1/account_holders/{account_holder_token}

Sample Request

curl https://api.lithic.com/v1/account_holders/c8e9694e-625d-49cb-aca3-da82bf16d3de \
  -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
     "email": "[email protected]",
     "phone_number": "123456789",
     "business_account_token": "5e86d4eb-5114-433e-a812-a88293e62b69"
}
'

Sample Response

{
  "token": "c8e9694e-625d-49cb-aca3-da82bf16d3de",
  "email": "[email protected]",
  "phone_number": "123456789"
  "business_account_token": "5e86d4eb-5114-433e-a812-a88293e62b69"
}

Get Specific Account Holder

API Reference: Get account holder

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

Sample Request

curl --request GET \
     --url https://api.lithic.com/v1/account_holders/8fff015e-2697-4617-8a29-e57c37e39719 \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json'

Sample Response

{
  "token": "c8e9694e-625d-49cb-aca3-da82bf16d3de",
  "email": "[email protected]",
  "phone_number": "123456789"
  "business_account_token": "5e86d4eb-5114-433e-a812-a88293e62b69"
}

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"
    }
}

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...",
      }
  ]
}

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
    }
  ]
}

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. We send three types of events related to accountholders via our Events platform: account_holder.created, account_holder.updated, and account_holder.verification. You can also see examples of these three events in Sandbox using Send Example Event Types.

Sample Webhooks:

{
  "account_token": "00000000-0000-0000-0000-000000000001",
  "created": "2023-09-26T16:41:40.530938",
  "event_type": "account_holder.created",
  "status": "ACCEPTED",
  "status_reasons": [],
  "token": "00000000-0000-0000-0000-000000000001"
}

{
  "business_account_token": null,
  "created": "2023-09-26T16:41:40.530938",
  "email": "[email protected]",
  "event_type": "account_holder.updated",
  "external_id": null,
  "first_name": "John",
  "last_name": "Appleseed",
  "phone_number": 15555555555,
  "token": "00000000-0000-0000-0000-000000000001"
}

{
  "account_token": "00000000-0000-0000-0000-000000000001",
  "created": "2023-09-26T16:41:40.530938",
  "event_type": "account_holder.verification",
  "status": "ACCEPTED",
  "status_reasons": [],
  "token": "00000000-0000-0000-0000-000000000001"
}

KYC 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
• 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

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).

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).

Simulating Account Holder Creation in Sandbox

See Simulating Account Holder Creation page for detail.