Lithic Account Holder API
The Account Holder API from Lithic — 8 operation(s) for account holder.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@lithic.com
description: 'The Lithic Developer API is designed to provide a predictable programmatic interface for accessing your Lithic account through an API and transaction webhooks.
Note that your API key is a secret and should be treated as such. Don''t share it with anyone, including us. We will never ask you for it.
'
termsOfService: https://lithic.com/legal/terms
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.txt
title: Lithic Developer 3DS Account Holder API
version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: Account Holder
paths:
/v1/account_holders:
get:
description: Get a list of individual or business account holders and their KYC or KYB evaluation status.
operationId: getAccountHolders
parameters:
- description: If applicable, represents the external_id associated with the account_holder.
example: 00000000-0000-0000-0000-000000000001
in: query
name: external_id
schema:
format: uuid
type: string
- description: The number of account_holders to limit the response to.
example: 10
in: query
name: limit
schema:
type: integer
- description: (Individual Account Holders only) The first name of the account holder. The query is case insensitive and supports partial matches.
example: John
in: query
name: first_name
schema:
type: string
- description: (Individual Account Holders only) The last name of the account holder. The query is case insensitive and supports partial matches.
example: Appleseed
in: query
name: last_name
schema:
type: string
- description: (Business Account Holders only) The legal business name of the account holder. The query is case insensitive and supports partial matches.
example: Busy Business, Inc.
in: query
name: legal_business_name
schema:
type: string
- description: Phone number of the account holder. The query must be an exact match.
example: '+15555555555'
in: query
name: phone_number
schema:
type: string
- description: Email address of the account holder. The query must be an exact match, case insensitive.
example: example@domain.com
in: query
name: email
schema:
type: string
- $ref: '#/components/parameters/endingBefore'
- $ref: '#/components/parameters/startingAfter'
- $ref: '#/components/parameters/beginTime'
- $ref: '#/components/parameters/endTime'
responses:
'200':
content:
application/json:
examples:
getAccountHoldersResponse:
value:
data:
- account_token: 6b67b340-ed11-4463-a33d-0d7f7fdcd28c
business_account_token: 00000000-0000-0000-0000-000000000000
created: '2024-01-11T19:50:36.105448'
email: john@appleseed.com
exemption_type: AUTHORIZED_USER
external_id: '+15555555555'
individual:
address:
address1: 123 Main Street
city: New York
country: USA
postal_code: '10128'
state: NY
dob: '2000-01-01'
email: john@appleseed.com
first_name: John
last_name: Appleseed
phone_number: '+15555555555'
entity_token: 49c978db-20c4-46d8-9db4-b0ef28c03533
phone_number: '+15555555555'
status: ACCEPTED
token: b68b7424-aa69-4cbc-a946-30d90181b621
user_type: INDIVIDUAL
verification_application:
created: '2024-01-11T19:58:24.821848'
status: ACCEPTED
status_reasons: []
updated: '2024-01-11T19:58:24.821848'
- account_token: 732f7328-a2d7-4281-a264-e8cb5af8d392
business_account_token: 00000000-0000-0000-0000-000000000000
business_entity:
address:
address1: 22 Street North
city: New York
country: USA
postal_code: '10004'
state: NY
dba_business_name: Busy Business, Inc.
government_id: 98-7654321
legal_business_name: Busy Business, Inc.
parent_company: Example company
phone_numbers:
- '+15555555555'
entity_token: f360a3c0-24e6-4852-ae82-27916a5c4e86
control_person:
address:
address1: 451 New Forest Way
city: Springfield
country: USA
postal_code: '68022'
state: IL
dob: '1991-03-08T08:00:00Z'
email: john@busybusiness.com
first_name: John
last_name: Appleseed
phone_number: '+15555555555'
entity_token: 9d657ba0-7c8a-4946-a596-f99d978a4137
created: '2024-01-11T19:50:36.105449'
exemption_type: AUTHORIZED_USER
external_id: 851030f1-9b7b-4939-8ac9-161bd972d26f
naics_code: '541512'
token: fa68ed76-9d02-4d45-8a3f-782f3b6a8b3f
user_type: BUSINESS
verification_application:
created: '2024-01-11T19:50:36.105449'
status: PENDING_REVIEW
status_reasons: []
updated: '2024-01-11T19:50:36.105449'
has_more: false
schema:
properties:
data:
items:
$ref: '#/components/schemas/AccountHolder'
type: array
has_more:
description: Whether there are more accounts to be retrieved.
type: boolean
required:
- data
- has_more
type: object
description: OK
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get a list of individual or business account holders
tags:
- Account Holder
post:
description: '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.'
operationId: postAccountHolders
requestBody:
content:
application/json:
examples:
kybRequest:
summary: Create an account holder with KYB workflow
value:
beneficial_owner_individuals:
- address:
address1: 300 Normal Forest Way
city: Portland
country: USA
postal_code: '90210'
state: OR
dob: '1991-03-08T08:00:00Z'
email: tim@left-earth.com
first_name: Timmy
government_id: 211-23-1412
last_name: Turner
phone_number: '+15555555555'
business_entity:
address:
address1: 123 Old Forest Way
city: Omaha
country: USA
postal_code: '61022'
state: NE
dba_business_name: Example Business Solutions
government_id: 12-3456789
legal_business_name: Busy Business, Inc.
phone_numbers:
- '+15555555555'
control_person:
address:
address1: 451 New Forest Way
city: Springfield
country: USA
postal_code: '68022'
state: IL
birthdate: '1980-04-12'
dob: '1991-03-08T08:00:00Z'
email: tom@middle-pluto.com
first_name: Tom
government_id: 111-23-1412
last_name: Timothy
phone_number: '+15555555555'
kyb_passed_timestamp: '2022-03-08T08:00:00Z'
naics_code: '541512'
nature_of_business: Software company selling solutions to the restaurant industry
tos_timestamp: '2022-03-08T08:00:00Z'
website_url: https://www.mybusiness.com
workflow: KYB_BYO
kybDelegatedRequest:
summary: Create an account holder with KYB_DELEGATED workflow
value:
business_entity:
address:
address1: 123 Old Forest Way
city: Omaha
country: USA
postal_code: '61022'
state: NE
legal_business_name: Busy Business, Inc.
kycExemptRequest:
summary: Create an account holder with KYC Exempt workflow
value:
address:
address1: 123 Old Forest Way
city: Omaha
country: USA
postal_code: '68022'
state: NE
business_account_token: e87db14a-4abf-4901-adad-5d5c9f46aff2
email: tom@middle-earth.com
first_name: Tom
kyc_exemption_type: AUTHORIZED_USER
last_name: Bombadil
phone_number: '+15555555555'
workflow: KYC_EXEMPT
kycRequest:
summary: Create an account holder with KYC workflow
value:
individual:
address:
address1: 123 Old Forest Way
city: Omaha
country: USA
postal_code: '68022'
state: NE
dob: '1991-03-08 08:00:00'
email: tom@middle-earth.com
first_name: Tom
government_id: 111-23-1412
last_name: Bombadil
phone_number: '+15555555555'
tos_timestamp: '2022-03-08T08:00:00Z'
workflow: KYC_BASIC
schema:
oneOf:
- $ref: '#/components/schemas/Kyb'
- $ref: '#/components/schemas/KybDelegated'
- $ref: '#/components/schemas/Kyc'
- $ref: '#/components/schemas/KycExempt'
required: true
responses:
'200':
content:
application/json:
examples:
acceptedEvaluationResponse:
summary: Accepted KYC/KYB evaluation response
value:
account_token: b68b7424-aa69-4cbc-a946-30d90181b621
status: ACCEPTED
status_reasons: []
token: 12345678-aa69-4cbc-a946-30d90181b621
created: '2024-09-16T20:13:41.865274'
pendingResubmitResponse:
summary: Pending resubmit KYC evaluation response
value:
account_token: b68b7424-aa69-4cbc-a946-30d90181b621
status: PENDING_RESUBMIT
status_reasons:
- NAME_VERIFICATION_FAILURE
token: 12345678-aa69-4cbc-a946-30d90181b621
created: '2024-09-16T20:13:41.865274'
pendingKYBReviewResponse:
summary: Pending review response for a KYB_BASIC request
value:
account_token: 6016af53-87d4-42aa-b021-0170644d6458
status: PENDING_REVIEW
status_reasons:
- PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILURE
token: 12345678-aa69-4cbc-a946-30d90181b621
created: '2024-09-16T20:13:41.865274'
required_documents:
- entity_token: 48afea0a-38b0-44e4-aaa7-c2b5413da9d3
valid_documents:
- EIN_LETTER
- TAX_RETURN
- CERTIFICATE_OF_GOOD_STANDING
- ARTICLES_OF_INCORPORATION
- ARTICLES_OF_ORGANIZATION
- CERTIFICATE_OF_FORMATION
- BYLAWS
- GOVERNMENT_BUSINESS_LICENSE
- PARTNERSHIP_AGREEMENT
- BANK_STATEMENT
- UTILITY_BILL_STATEMENT
status_reasons:
- PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILURE
schema:
properties:
account_token:
description: Globally unique identifier for the account.
format: uuid
type: string
created:
description: Timestamp of when the account holder was created.
format: date-time
type: string
external_id:
description: Customer-provided token that indicates a relationship with an object outside of the Lithic ecosystem.
type: string
status:
description: 'KYC and KYB evaluation states.
Note:
* `PENDING_REVIEW` is only applicable for the `KYB_BASIC` workflow.
'
enum:
- ACCEPTED
- PENDING_REVIEW
- PENDING_DOCUMENT
- PENDING_RESUBMIT
- REJECTED
type: string
status_reasons:
description: Reason for the evaluation status.
items:
$ref: '#/components/schemas/status-reasons'
type: array
required_documents:
description: Only present for "KYB_BASIC" workflow. A list of documents required for the account holder to be approved.
type: array
items:
$ref: '#/components/schemas/required-document'
token:
description: Globally unique identifier for the account holder.
format: uuid
type: string
required:
- account_token
- status
- status_reasons
- token
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Create an individual or business account holder
tags:
- Account Holder
/v1/account_holders/{account_holder_token}:
get:
description: Get an Individual or Business Account Holder and/or their KYC or KYB evaluation status.
operationId: getAccountHolder
parameters:
- $ref: '#/components/parameters/accountHolderTokenPath'
responses:
'200':
content:
application/json:
examples:
kycAcceptedReview:
summary: Accepted KYC evaluation response
value:
token: b68b7424-aa69-4cbc-a946-30d90181b621
account_token: 6b67b340-ed11-4463-a33d-0d7f7fdcd28c
business_account_token: 5310469f-3a16-44ce-89f8-cdc4446fcfdf
external_id: ''
created: '2024-01-11T19:50:36.105449'
user_type: INDIVIDUAL
verification_application:
created: '2024-01-11T19:50:36.105449'
updated: '2024-01-11T19:50:36.105449'
status: ACCEPTED
status_reasons: []
individual:
address:
address1: 451 New Forest Way
city: Springfield
state: IL
postal_code: '68022'
country: USA
dob: '1991-03-08T08:00:00Z'
email: john@appleseed.com
first_name: John
last_name: Appleseed
phone_number: '+15555555555'
entity_token: fd771a07-c5c2-42f3-a53c-a6c79c6c0d07
email: john@appleseed.com
phone_number: '+15555555555'
status: ACCEPTED
kybBasicPendingReview:
summary: Pending review submission for a KYB_BASIC account_holder
value:
token: fa68ed76-9d02-4d45-8a3f-782f3b6a8b3f
account_token: 732f7328-a2d7-4281-a264-e8cb5af8d392
business_account_token: 00000000-0000-0000-0000-000000000000
external_id: ''
created: '2024-01-11T19:50:36.105449'
user_type: BUSINESS
verification_application:
created: '2024-01-11T19:50:36.105449'
updated: '2024-01-11T19:50:36.105449'
status: PENDING_REVIEW
status_reasons:
- ADDRESS_VERIFICATION_FAILURE
required_documents:
- entity_token: 83cf25ae-c14f-4d10-9fa2-0119f36c7286
status_reasons:
- PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILURE
valid_documents:
- EIN_LETTER
- TAX_RETURN
- CERTIFICATE_OF_GOOD_STANDING
- ARTICLES_OF_INCORPORATION
- ARTICLES_OF_ORGANIZATION
- CERTIFICATE_OF_FORMATION
- BYLAWS
- GOVERNMENT_BUSINESS_LICENSE
- PARTNERSHIP_AGREEMENT
- BANK_STATEMENT
- UTILITY_BILL_STATEMENT
business_entity:
address:
address1: 22 Street North
city: New York
state: NY
postal_code: '10004'
country: USA
dba_business_name: Busy Business, Inc.
government_id: 98-7654321
legal_business_name: Busy Business, Inc.
parent_company: Example company
phone_numbers:
- '+15555555555'
entity_token: 05cc03c9-dea6-4d17-a11e-0f3ea57d51a5
control_person:
address:
address1: 451 New Forest Way
city: Springfield
state: IL
postal_code: '68022'
country: USA
dob: '1991-03-08T08:00:00Z'
email: john@appleseed.com
first_name: John
last_name: Appleseed
phone_number: '+15555555555'
entity_token: fd771a07-c5c2-42f3-a53c-a6c79c6c0d07
schema:
$ref: '#/components/schemas/AccountHolder'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get an individual or business account holder
tags:
- Account Holder
patch:
description: '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.'
operationId: patchAccountHolder
parameters:
- $ref: '#/components/parameters/accountHolderToken'
requestBody:
content:
application/json:
examples:
kybRequest:
summary: Update a business account holder with KYB workflow
value:
business_entity:
entity_token: 83cf25ae-c14f-4d10-9fa2-0119f36c7286
address:
postal_code: '61023'
control_person:
entity_token: fd771a07-c5c2-42f3-a53c-a6c79c6c0d07
address:
postal_code: '68023'
naics_code: '541512'
website_url: https://www.mynewbusiness.com
kycExemptRequest:
summary: Update an individual account holder with KYC workflow
value:
individual:
entity_token: fd771a07-c5c2-42f3-a53c-a6c79c6c0d07
address:
postal_code: '68023'
phone_number: '+15555555555'
kycRequest:
summary: Update an individual account holder with KYC workflow
value:
individual:
entity_token: fd771a07-c5c2-42f3-a53c-a6c79c6c0d07
address:
postal_code: '68023'
government_id: 111-23-1413
schema:
anyOf:
- $ref: '#/components/schemas/kyb-patch-request'
- $ref: '#/components/schemas/kyc-patch-request'
- $ref: '#/components/schemas/patch-request'
required: true
responses:
'200':
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/kyb-kyc-patch-response'
- $ref: '#/components/schemas/patch-response'
description: OK
'404':
$ref: '#/components/responses/NotFound'
summary: Update account holder information and possibly resubmit for evaluation
tags:
- Account Holder
/v1/account_holders/{account_holder_token}/documents:
get:
description: '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`.
'
operationId: getAccountHolderDocuments
parameters:
- $ref: '#/components/parameters/accountHolderTokenPath'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/document'
type: array
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get account holder document uploads
tags:
- Account Holder
post:
description: '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.
Supported file types include `jpg`, `png`, and `pdf`. Each file 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.
'
operationId: postAccountHolderDocuments
parameters:
- $ref: '#/components/parameters/accountHolderTokenPath'
requestBody:
content:
application/json:
examples:
recieveLinkForDriversLicense:
summary: Initiate account holder document upload
value:
entity_token: 83cf25ae-c14f-4d10-9fa2-0119f36c7286
document_type: EIN_LETTER
schema:
properties:
document_type:
description: The type of document to upload
enum:
- EIN_LETTER
- TAX_RETURN
- OPERATING_AGREEMENT
- CERTIFICATE_OF_FORMATION
- DRIVERS_LICENSE
- PASSPORT
- PASSPORT_CARD
- CERTIFICATE_OF_GOOD_STANDING
- ARTICLES_OF_INCORPORATION
- ARTICLES_OF_ORGANIZATION
- BYLAWS
- GOVERNMENT_BUSINESS_LICENSE
- PARTNERSHIP_AGREEMENT
- SS4_FORM
- BANK_STATEMENT
- UTILITY_BILL_STATEMENT
- SSN_CARD
- ITIN_LETTER
- FINCEN_BOI_REPORT
type: string
entity_token:
description: Globally unique identifier for the entity.
type: string
format: uuid
required:
- document_type
- entity_token
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/document'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Initiate account holder document upload
tags:
- Account Holder
/v1/account_holders/{account_holder_token}/documents/{document_token}:
get:
description: '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`.
'
operationId: getAccountHolderDocumentByToken
parameters:
- $ref: '#/components/parameters/accountHolderTokenPath'
- $ref: '#/components/parameters/documentToken'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/document'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get account holder document upload status
tags:
- Account Holder
/v1/account_holders/{account_holder_token}/entities:
post:
description: 'Create a new beneficial owner individual or replace the control person entity on an existing KYB account holder. This endpoint is only applicable for account holders enrolled through a KYB workflow with the Persona KYB provider.
A new control person can only replace the existing one. A maximum of 4 beneficial owners can be associated with an account holder.'
operationId: postAccountHolderEntities
parameters:
- $ref: '#/components/parameters/accountHolderTokenPath'
requestBody:
content:
application/json:
examples:
createBeneficialOwner:
summary: Create a new beneficial owner individual
value:
type: BENEFICIAL_OWNER_INDIVIDUAL
first_name: Timmy
last_name: Turner
dob: '1991-03-08T08:00:00Z'
email: tim@left-earth.com
phone_number: '+15555555555'
government_id: 211-23-1412
address:
address1: 300 Normal Forest Way
city: Portland
country: USA
postal_code: '90210'
state: OR
replaceControlPerson:
summary: Replace the existing control person entity
value:
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lithic/refs/heads/main/openapi/lithic-account-holder-api-openapi.yml