Account Holders (Businesses)
Learn how to create an account holder object for businesses.
Account holders and accounts have a 1:1 relationship. When an account holder is successfully created, an associated account is also created.
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)
Customers enrolling businesses may also need to enroll those businesses' authorized users using our KYC-exempt workflow. All customers enrolling businesses and issuing physical cards to those businesses' authorized users should enroll those authorized users using the KYC-exempt workflow.
Create Business 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 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
{
"account_token": "76100d29-b30f-4ede-a472-97455d64733b",
"status": "PENDING_REVIEW",
"status_reasons": [
"BENEFICIAL_OWNER_INDIVIDUAL_0_ID_VERIFICATION_FAILURE",
"BENEFICIAL_OWNER_INDIVIDUAL_0_NAME_VERIFICATION_FAILURE",
"CONTROL_PERSON_ID_VERIFICATION_FAILURE",
"CONTROL_PERSON_NAME_VERIFICATION_FAILURE"
],
"token": "24e2a5ce-c865-4419-a423-e2bf75791d61",
"created": "2023-09-27T14:55:02.731983"
}
Fields used in all account creation calls:
| 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 |
| tos_timestamp (required) | An RFC 3339 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: RFC 3339 format (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. |
beneficial_owner_entities (list of objects, required if no beneficial_owner_individuals 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. Please note that if the business has a beneficial owner entity, they will automatically be manually reviewed to avoid excessive Middesk charges for multiple business entity reviews. 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 beneficial_owner_individuals must be populated. List of objects. Permitted values: List of valid business_entity objects. |
beneficial_owner_individuals (list of objects, required if no beneficial_owner_entities 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 beneficial_owner_entities 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 RFC 3339 timestamp indicating when pre-approved KYB was completed on the individual with a pass result. String. Permitted values: RFC 3339 format (yyyy-MM-ddThh:mm:ssZ). |
| website_url (optional) | Company website URL. May enter N/A if business entity does not have a website. String. |
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. RFC 3339 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 #########). |
| 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. |
| phone_number (optional) | Individual's phone number. Optional for control person and beneficial owner individuals submitted for KYB. String. E.164 format without hyphens. For example, "+12124007676" for a US phone number. |
| email (optional) | Email address. Optional for individuals submitted for KYB. String. Permitted values: Valid email address. For example, "[email protected]". |
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
| Workflow | Potential status values returned via this endpoint |
|---|---|
| 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 |
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. This token should be passed in the business_account_token field for individuals enrolled using the KYC-exempt workflow. 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) |
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": "95e5f1b7-cfd5-4520-aa3c-2451bab8608d",
"account_token": "e87db14a-4abf-4901-adad-5d5c9f46aff2",
"business_account_token": "",
"external_id": "",
"created": "2023-03-14T21:09:24.186122",
"user_type": "BUSINESS",
"exemption_type": "",
"verification_application": {
"created": "2023-03-14T21:09:24.186122",
"updated": "2023-03-14T21:09:24.186122",
"status": "ACCEPTED",
"status_reasons": []
},
"business_entity": {
"address": {
"address1": "123 Old Forest Way",
"address2": "",
"city": "Omaha",
"state": "NE",
"postal_code": "68022",
"country": "US"
},
"dba_business_name": "Ozymandias",
"government_id": "114-123-1513",
"legal_business_name": "Agis Companies",
"parent_company": "",
"phone_numbers": [
"+12124007676"
]
},
"beneficial_owner_individuals": [
{
"address": {
"address1": "123 Old Forest Way",
"address2": "",
"city": "Omaha",
"state": "NE",
"postal_code": "68022",
"country": "US"
},
"dob": "1991-03-08 08:00:00",
"email": "[email protected]",
"first_name": "Tom",
"last_name": "Bombadil",
"phone_number": "+12124007676"
}
],
"beneficial_owner_entities": [],
"control_person": {
"address": {
"address1": "123 Old Forest Way",
"address2": "",
"city": "Omaha",
"state": "NE",
"postal_code": "68022",
"country": "US"
},
"dob": "1991-03-08 08:00:00",
"email": "[email protected]",
"first_name": "Tom",
"last_name": "Bombadil",
"phone_number": "12124007676"
},
"nature_of_business": "Software company selling solutions to the restaurant industry",
"website_url": "www.mybusiness.com",
"email": "[email protected]",
"phone_number": "12124007676",
"status": "ACCEPTED"
}
| account_holder_token (required, path parameter) | Token associated with the account holder to be 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. 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"
}
KYB Workflow Diagrams and Expected Response Times
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
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_FAILURE | One or more of the beneficial owner individual's appear on one or more government watch lists. |
| BENEFICIAL_OWNER_INDIVIDUAL_DOB_VERIFICATION_FAILURE | One or more of the beneficial owner individual's date of birth provided could not be verified. |
| BENEFICIAL_OWNER_INDIVIDUAL_ID_VERIFICATION_FAILURE | One or more of the business owner individual's government-issued identification number(s) provided could not be matched. |
| BENEFICIAL_OWNER_INDIVIDUAL_NAME_VERIFICATION_FAILURE | One or more of the business owner individual's name(s) provided could not be verified. |
| CONTROL_PERSON_BLOCKLIST_ALERT_FAILURE | The control person appeared on one or more government watch lists. |
| CONTROL_PERSON_DOB_VERIFICATION_FAILURE | The control person's date of birth provided could not be verified. |
| CONTROL_PERSON_ID_VERIFICATION_FAILURE | The control person's government-issued identification number provided could not be matched. |
| CONTROL_PERSON_NAME_VERIFICATION_FAILURE | The control peron's name provided could not be verified. |
| PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILURE | The address of the primary business entity provided could not be verified. |
| PRIMARY_BUSINESS_ENTITY_ID_VERIFICATION_FAILURE | The government-issued identification of the primary business entity provided could not be verified. |
| PRIMARY_BUSINESS_ENTITY_NAME_VERIFICATION_FAILURE | The name of the primary business entity provided could not be verified. |
| OTHER_VERIFICATION_FAILURE | The business entity could not be verified for other reasons. |
Simulating Account Holder Creation in Sandbox
See Simulating Account Holder Creation page for detail.
Updated about 1 month ago