Skip to content
Stainless Stainless Stainless SDKs

Account Holders

Account Holders

Last updated: (timestamp)

Account Holders

account_holders
Methods
Create an individual or business account holder
post/v1/account_holders

Create an account holder and initiate the appropriate onboarding workflow. Account holders and accounts have a 1:1 relationship. When an account holder is successfully created an associated account is also created. All calls to this endpoint will return a synchronous response. The response time will depend on the workflow. In some cases, the response may indicate the workflow is under review or further action will be needed to complete the account creation process. This endpoint can only be used on accounts that are part of the program that the calling API key manages.

Get an individual or business account holder
get/v1/account_holders/{account_holder_token}

Get an Individual or Business Account Holder and/or their KYC or KYB evaluation status.

Update account holder information and possibly resubmit for evaluation
patch/v1/account_holders/{account_holder_token}

Update the information associated with a particular account holder (including business owners and control persons associated to a business account). If Lithic is performing KYB or KYC and additional verification is required we will run the individual's or business's updated information again and return whether the status is accepted or pending (i.e., further action required). All calls to this endpoint will return a synchronous response. The response time will depend on the workflow. In some cases, the response may indicate the workflow is under review or further action will be needed to complete the account creation process. This endpoint can only be used on existing accounts that are part of the program that the calling API key manages.

Get a list of individual or business account holders
get/v1/account_holders

Get a list of individual or business account holders and their KYC or KYB evaluation status.

Get account holder document uploads
get/v1/account_holders/{account_holder_token}/documents

Retrieve the status of account holder document uploads, or retrieve the upload URLs to process your image uploads.

Note that this is not equivalent to checking the status of the KYC evaluation overall (a document may be successfully uploaded but not be sufficient for KYC to pass).

In the event your upload URLs have expired, calling this endpoint will refresh them. Similarly, in the event a previous account holder document upload has failed, you can use this endpoint to get a new upload URL for the failed image upload.

When a new document upload is generated for a failed attempt, the response will show an additional entry in the required_document_uploads list in a PENDING state for the corresponding image_type.

Get account holder document upload status
get/v1/account_holders/{account_holder_token}/documents/{document_token}

Check the status of an account holder document upload, or retrieve the upload URLs to process your image uploads.

Note that this is not equivalent to checking the status of the KYC evaluation overall (a document may be successfully uploaded but not be sufficient for KYC to pass).

In the event your upload URLs have expired, calling this endpoint will refresh them. Similarly, in the event a document upload has failed, you can use this endpoint to get a new upload URL for the failed image upload.

When a new account holder document upload is generated for a failed attempt, the response will show an additional entry in the required_document_uploads array in a PENDING state for the corresponding image_type.

Simulate an account holder document upload's review
post/v1/simulate/account_holders/enrollment_document_review

Simulates a review for an account holder document upload.

Simulate an account holder's enrollment review
post/v1/simulate/account_holders/enrollment_review

Simulates an enrollment review for an account holder. This endpoint is only applicable for workflows that may required intervention such as KYB_BASIC.

Initiate account holder document upload
post/v1/account_holders/{account_holder_token}/documents

Use this endpoint to identify which type of supported government-issued documentation you will upload for further verification. It will return two URLs to upload your document images to - one for the front image and one for the back image.

This endpoint is only valid for evaluations in a PENDING_DOCUMENT state.

Uploaded images must either be a jpg or png file, and each must be less than 15 MiB. Once both required uploads have been successfully completed, your document will be run through KYC verification.

If you have registered a webhook, you will receive evaluation updates for any document submission evaluations, as well as for any failed document uploads.

Two document submission attempts are permitted via this endpoint before a REJECTED status is returned and the account creation process is ended. Currently only one type of account holder document is supported per KYC verification.

Domain Types
Account Holder
AccountHolderobject
ShowShow
tokenstring

Globally unique identifier for the account holder.

formatuuid
createdstring

Timestamp of when the account holder was created.

formatdate-time
account_tokenstring
optional

Globally unique identifier for the account.

formatuuid
beneficial_owner_entitiesarray of object
optional
deprecated

Deprecated.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Business's physical address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable.

dba_business_namestring

Any name that the business operates under that is not its legal business name (if applicable).

entity_tokenstring

Globally unique identifier for the entity.

formatuuid
government_idstring

Government-issued identification number. US Federal Employer Identification Numbers (EIN) are currently supported, entered as full nine-digits, with or without hyphens.

phone_numbersarray of string

One or more of the business's phone number(s), entered as a list in E.164 format.

parent_companystring
optional

Parent company name (if applicable).

beneficial_owner_individualsarray of object
optional

Only present when user_type == "BUSINESS". You must submit a list of all direct and indirect individuals with 25% or more ownership in the company. A maximum of 4 beneficial owners can be submitted. If no individual owns 25% of the company you do not need to send beneficial owner information. See FinCEN requirements (Section I) for more background on individuals that should be included.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Individual's current address

dobstring

Individual's date of birth, as an RFC 3339 date.

emailstring

Individual's email address.

entity_tokenstring

Globally unique identifier for the entity.

formatuuid
first_namestring

Individual's first name, as it appears on government-issued identity documents.

last_namestring

Individual's last name, as it appears on government-issued identity documents.

phone_numberstring

Individual's phone number, entered in E.164 format.

business_account_tokenstring
optional

Only applicable for customers using the KYC-Exempt workflow to enroll authorized users of businesses. Pass the account_token of the enrolled business associated with the AUTHORIZED_USER in this field.

formatuuid
business_entityobject
optional

Only present when user_type == "BUSINESS". Information about the business for which the account is being opened and KYB is being run.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Business's physical address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable.

dba_business_namestring

Any name that the business operates under that is not its legal business name (if applicable).

entity_tokenstring

Globally unique identifier for the entity.

formatuuid
government_idstring

Government-issued identification number. US Federal Employer Identification Numbers (EIN) are currently supported, entered as full nine-digits, with or without hyphens.

phone_numbersarray of string

One or more of the business's phone number(s), entered as a list in E.164 format.

parent_companystring
optional

Parent company name (if applicable).

control_personobject
optional

Only present when user_type == "BUSINESS". 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.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Individual's current address

dobstring

Individual's date of birth, as an RFC 3339 date.

emailstring

Individual's email address.

entity_tokenstring

Globally unique identifier for the entity.

formatuuid
first_namestring

Individual's first name, as it appears on government-issued identity documents.

last_namestring

Individual's last name, as it appears on government-issued identity documents.

phone_numberstring

Individual's phone number, entered in E.164 format.

emailstring
optional

< Deprecated. Use control_person.email when user_type == "BUSINESS". Use individual.phone_number when user_type == "INDIVIDUAL".

Primary email of Account Holder.

exemption_typeenum
optional
Accepts one of the following: "AUTHORIZED_USER", "PREPAID_CARD_USER"

The type of KYC exemption for a KYC-Exempt Account Holder.

Hide ParametersShow Parameters
"AUTHORIZED_USER"
"PREPAID_CARD_USER"
external_idstring
optional

Customer-provided token that indicates a relationship with an object outside of the Lithic ecosystem.

formatstring
individualobject
optional

Only present when user_type == "INDIVIDUAL". Information about the individual for which the account is being opened and KYC is being run.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Individual's current address

dobstring

Individual's date of birth, as an RFC 3339 date.

emailstring

Individual's email address.

entity_tokenstring

Globally unique identifier for the entity.

formatuuid
first_namestring

Individual's first name, as it appears on government-issued identity documents.

last_namestring

Individual's last name, as it appears on government-issued identity documents.

phone_numberstring

Individual's phone number, entered in E.164 format.

nature_of_businessstring
optional

Only present when user_type == "BUSINESS". User-submitted description of the business.

formatstring
phone_numberstring
optional

< Deprecated. Use control_person.phone_number when user_type == "BUSINESS". Use individual.phone_number when user_type == "INDIVIDUAL".

Primary phone of Account Holder, entered in E.164 format.

required_documentsarray of entity_tokenstringstatus_reasonsarray of stringvalid_documentsarray of stringRequiredDocument
optional

Only present for "KYB_BASIC" workflow. A list of documents required for the account holder to be approved.

statusenum
optional
Accepts one of the following: "ACCEPTED", "PENDING_REVIEW", "PENDING_DOCUMENT", 2 more

<Deprecated. Use verification_application.status instead>

KYC and KYB evaluation states.

Note:

  • PENDING_REVIEW is only applicable for the KYB_BASIC workflow.
Hide ParametersShow Parameters
"ACCEPTED"
"PENDING_REVIEW"
"PENDING_DOCUMENT"
"PENDING_RESUBMIT"
"REJECTED"
status_reasonsarray of enum
optional

<Deprecated. Use verification_application.status_reasons> Reason for the evaluation status.

Hide ParametersShow Parameters
"ADDRESS_VERIFICATION_FAILURE"
"AGE_THRESHOLD_FAILURE"
"COMPLETE_VERIFICATION_FAILURE"
"DOB_VERIFICATION_FAILURE"
"ID_VERIFICATION_FAILURE"
"MAX_DOCUMENT_ATTEMPTS"
"MAX_RESUBMISSION_ATTEMPTS"
"NAME_VERIFICATION_FAILURE"
"OTHER_VERIFICATION_FAILURE"
"RISK_THRESHOLD_FAILURE"
"WATCHLIST_ALERT_FAILURE"
user_typeenum
optional
Accepts one of the following: "BUSINESS", "INDIVIDUAL"

The type of Account Holder. If the type is "INDIVIDUAL", the "individual" attribute will be present. If the type is "BUSINESS" then the "business_entity", "control_person", "beneficial_owner_individuals", "nature_of_business", and "website_url" attributes will be present.

Hide ParametersShow Parameters
"BUSINESS"
"INDIVIDUAL"
verification_applicationobject
optional

Information about the most recent identity verification attempt

Hide ParametersShow Parameters
createdstring
optional

Timestamp of when the application was created.

formatdate-time
statusenum
optional
Accepts one of the following: "ACCEPTED", "PENDING_REVIEW", "PENDING_DOCUMENT", 2 more

KYC and KYB evaluation states.

Note:

  • PENDING_REVIEW is only applicable for the KYB_BASIC workflow.
Hide ParametersShow Parameters
"ACCEPTED"
"PENDING_REVIEW"
"PENDING_DOCUMENT"
"PENDING_RESUBMIT"
"REJECTED"
status_reasonsarray of enum
optional

Reason for the evaluation status.

Hide ParametersShow Parameters
"ADDRESS_VERIFICATION_FAILURE"
"AGE_THRESHOLD_FAILURE"
"COMPLETE_VERIFICATION_FAILURE"
"DOB_VERIFICATION_FAILURE"
"ID_VERIFICATION_FAILURE"
"MAX_DOCUMENT_ATTEMPTS"
"MAX_RESUBMISSION_ATTEMPTS"
"NAME_VERIFICATION_FAILURE"
"OTHER_VERIFICATION_FAILURE"
"RISK_THRESHOLD_FAILURE"
"WATCHLIST_ALERT_FAILURE"
updatedstring
optional

Timestamp of when the application was last updated.

formatdate-time
website_urlstring
optional

Only present when user_type == "BUSINESS". Business's primary website.

formatstring
Address Update
AddressUpdateobject
ShowShow
address1string
optional

Valid deliverable address (no PO boxes).

address2string
optional

Unit or apartment number (if applicable).

citystring
optional

Name of city.

countrystring
optional

Valid country code. Only USA is currently supported, entered in uppercase ISO 3166-1 alpha-3 three-character format.

postal_codestring
optional

Valid postal code. Only USA ZIP codes are currently supported, entered as a five-digit ZIP or nine-digit ZIP+4.

statestring
optional

Valid state code. Only USA state codes are currently supported, entered in uppercase ISO 3166-2 two-character format.

KYB
KYBobject
ShowShow
beneficial_owner_individualsarray of object

You must submit a list of all direct and indirect individuals with 25% or more ownership in the company. A maximum of 4 beneficial owners can be submitted. If no individual owns 25% of the company you do not need to send beneficial owner information. See FinCEN requirements (Section I) for more background on individuals that should be included.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Individual's current address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable. Only USA addresses are currently supported.

dobstring

Individual's date of birth, as an RFC 3339 date.

emailstring

Individual's email address. If utilizing Lithic for chargeback processing, this customer email address may be used to communicate dispute status and resolution.

first_namestring

Individual's first name, as it appears on government-issued identity documents.

government_idstring

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

last_namestring

Individual's last name, as it appears on government-issued identity documents.

phone_numberstring
optional

Individual's phone number, entered in E.164 format.

business_entityobject

Information for business for which the account is being opened and KYB is being run.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Business's physical address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable.

government_idstring

Government-issued identification number. US Federal Employer Identification Numbers (EIN) are currently supported, entered as full nine-digits, with or without hyphens.

phone_numbersarray of string

One or more of the business's phone number(s), entered as a list in E.164 format.

dba_business_namestring
optional

Any name that the business operates under that is not its legal business name (if applicable).

parent_companystring
optional

Parent company name (if applicable).

control_personobject

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.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Individual's current address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable. Only USA addresses are currently supported.

dobstring

Individual's date of birth, as an RFC 3339 date.

emailstring

Individual's email address. If utilizing Lithic for chargeback processing, this customer email address may be used to communicate dispute status and resolution.

first_namestring

Individual's first name, as it appears on government-issued identity documents.

government_idstring

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

last_namestring

Individual's last name, as it appears on government-issued identity documents.

phone_numberstring
optional

Individual's phone number, entered in E.164 format.

nature_of_businessstring

Short description of the company's line of business (i.e., what does the company do?).

tos_timestampstring

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.

workflowenum
Accepts one of the following: "KYB_BASIC", "KYB_BYO"

Specifies the type of KYB workflow to run.

Hide ParametersShow Parameters
"KYB_BASIC"
"KYB_BYO"
beneficial_owner_entitiesarray of object
optional
deprecated

Deprecated.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Business's physical address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable.

government_idstring

Government-issued identification number. US Federal Employer Identification Numbers (EIN) are currently supported, entered as full nine-digits, with or without hyphens.

phone_numbersarray of string

One or more of the business's phone number(s), entered as a list in E.164 format.

dba_business_namestring
optional

Any name that the business operates under that is not its legal business name (if applicable).

parent_companystring
optional

Parent company name (if applicable).

external_idstring
optional

A user provided id that can be used to link an account holder with an external system

kyb_passed_timestampstring
optional

An RFC 3339 timestamp indicating when precomputed KYC was completed on the business with a pass result.

This field is required only if workflow type is KYB_BYO.

website_urlstring
optional

Company website URL.

KYB Business Entity
KYBBusinessEntityobject
ShowShow
addressobject

Business''s physical address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable.

Hide ParametersShow Parameters
address1string

Valid deliverable address (no PO boxes).

citystring

Name of city.

countrystring

Valid country code. Only USA is currently supported, entered in uppercase ISO 3166-1 alpha-3 three-character format.

postal_codestring

Valid postal code. Only USA ZIP codes are currently supported, entered as a five-digit ZIP or nine-digit ZIP+4.

statestring

Valid state code. Only USA state codes are currently supported, entered in uppercase ISO 3166-2 two-character format.

address2string
optional

Unit or apartment number (if applicable).

government_idstring

Government-issued identification number. US Federal Employer Identification Numbers (EIN) are currently supported, entered as full nine-digits, with or without hyphens.

phone_numbersarray of string

One or more of the business's phone number(s), entered as a list in E.164 format.

dba_business_namestring
optional

Any name that the business operates under that is not its legal business name (if applicable).

parent_companystring
optional

Parent company name (if applicable).

KYC
KYCobject
ShowShow
individualobject

Information on individual for whom the account is being opened and KYC is being run.

Hide ParametersShow Parameters
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

Individual's current address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable. Only USA addresses are currently supported.

dobstring

Individual's date of birth, as an RFC 3339 date.

emailstring

Individual's email address. If utilizing Lithic for chargeback processing, this customer email address may be used to communicate dispute status and resolution.

first_namestring

Individual's first name, as it appears on government-issued identity documents.

government_idstring

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

last_namestring

Individual's last name, as it appears on government-issued identity documents.

phone_numberstring

Individual's phone number, entered in E.164 format.

tos_timestampstring

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.

workflowenum
Accepts one of the following: "KYC_BASIC", "KYC_BYO"

Specifies the type of KYC workflow to run.

Hide ParametersShow Parameters
"KYC_BASIC"
"KYC_BYO"
external_idstring
optional

A user provided id that can be used to link an account holder with an external system

kyc_passed_timestampstring
optional

An RFC 3339 timestamp indicating when precomputed KYC was completed on the individual with a pass result.

This field is required only if workflow type is KYC_BYO.

KYC Exempt
KYCExemptobject
ShowShow
addressaddress1stringcitystringcountrystringpostal_codestringstatestringaddress2stringAddress

KYC Exempt user's current address - PO boxes, UPS drops, and FedEx drops are not acceptable; APO/FPO are acceptable.

emailstring

The KYC Exempt user's email

first_namestring

The KYC Exempt user's first name

kyc_exemption_typeenum
Accepts one of the following: "AUTHORIZED_USER", "PREPAID_CARD_USER"

Specifies the type of KYC Exempt user

Hide ParametersShow Parameters
"AUTHORIZED_USER"
"PREPAID_CARD_USER"
last_namestring

The KYC Exempt user's last name

phone_numberstring

The KYC Exempt user's phone number, entered in E.164 format.

workflowenum
Accepts one of the following: "KYC_EXEMPT"

Specifies the workflow type. This must be 'KYC_EXEMPT'

Hide ParametersShow Parameters
"KYC_EXEMPT"
business_account_tokenstring
optional

Only applicable for customers using the KYC-Exempt workflow to enroll authorized users of businesses. Pass the account_token of the enrolled business associated with the AUTHORIZED_USER in this field.

external_idstring
optional

A user provided id that can be used to link an account holder with an external system

Required Document
RequiredDocumentobject
ShowShow
entity_tokenstring

Globally unique identifier for an entity.

formatuuid
status_reasonsarray of string

Provides the status reasons that will be satisfied by providing one of the valid documents.

valid_documentsarray of string

A list of valid documents that will satisfy the KYC requirements for the specified entity.