Lithic API Documentation | Account Holders › Simulate An Account Holder S Enrollment Review

API Reference

Account Holders

account_holders

Methods

Create An Individual Or Business Account Holder -> { token, account_token, status, 4 more... }

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.

Update Account Holder Information And Possibly Resubmit For Evaluation -> { token, account_token, beneficial_owner_entities, 17 more... } | { token, address, business_account_token, 5 more... }

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 An Individual Or Business Account Holder ->

AccountHolder

get/v1/account_holders/{account_holder_token}

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

Initiate Account Holder Document Upload ->

Document

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.

Get Account Holder Document Uploads -> { data }

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

Document

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.

Get A List Of Individual Or Business Account Holders -> SinglePage<

AccountHolder

get/v1/account_holders

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

Simulate An Account Holder S Enrollment Review -> { token, account_token, beneficial_owner_entities, 17 more... }

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.

Response fields

token: string

Optional

(format: uuid)

Globally unique identifier for the account holder.

account_token: string

Optional

(format: uuid)

Globally unique identifier for the account.

beneficial_owner_entities: Array<

KYBBusinessEntity

Optional

Deprecated.

beneficial_owner_individuals: Array<{ address, dob, email, 4 more... }>

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.

business_account_token: string

Optional

Nullable

(format: uuid)

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.

business_entity:

KYBBusinessEntity

Optional

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

control_person: { address, dob, email, 4 more... }

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.

created: string

Optional

(format: date-time)

Timestamp of when the account holder was created.

email: string

Optional

(Deprecated. Use control_person.email when user_type == "BUSINESS". Use individual.phone_number when user_type == "INDIVIDUAL".) Primary email of Account Holder.

exemption_type: "AUTHORIZED_USER" | "PREPAID_CARD_USER"

Optional

The type of KYC exemption for a KYC-Exempt Account Holder. "None" if the account holder is not KYC-Exempt.

external_id: string

Optional

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

individual: { address, dob, email, 4 more... }

Optional

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

nature_of_business: string

Optional

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

phone_number: string

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_documents: Array<

RequiredDocument

Optional

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

status: "ACCEPTED" | "PENDING_DOCUMENT" | "PENDING_RESUBMIT" | 1 more...

Optional

(Deprecated. Use verification_application.status instead) KYC and KYB evaluation states.

Note: PENDING_RESUBMIT and PENDING_DOCUMENT are only applicable for the ADVANCED workflow.

status_reasons: Array<"ADDRESS_VERIFICATION_FAILURE" | "AGE_THRESHOLD_FAILURE" | "COMPLETE_VERIFICATION_FAILURE" | 21 more...>

Optional

(Deprecated. Use verification_application.status_reasons) Reason for the evaluation status.

user_type: "BUSINESS" | "INDIVIDUAL"

Optional

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.

verification_application: { created, status, status_reasons, 2 more... }

Optional

Information about the most recent identity verification attempt

website_url: string

Optional

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

Request example

curl https://api.lithic.com/v1/simulate/account_holders/enrollment_review \
    -H 'Content-Type: application/json' \
    -H "Authorization: $LITHIC_API_KEY" \
    -d '{}'

200Example

{
  "token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "account_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "beneficial_owner_entities": [
    {
      "address": {
        "address1": "123 Old Forest Way",
        "city": "Omaha",
        "country": "USA",
        "postal_code": "68022",
        "state": "NE",
        "address2": "address2"
      },
      "government_id": "114-123-1513",
      "legal_business_name": "Acme, Inc.",
      "phone_numbers": [
        "+15555555555"
      ],
      "dba_business_name": "dba_business_name",
      "parent_company": "parent_company"
    }
  ],
  "beneficial_owner_individuals": [
    {
      "address": {
        "address1": "123 Old Forest Way",
        "city": "Omaha",
        "country": "USA",
        "postal_code": "68022",
        "state": "NE",
        "address2": "address2"
      },
      "dob": "1991-03-08 08:00:00",
      "email": "[email protected]",
      "first_name": "Tom",
      "last_name": "Bombadil",
      "phone_number": "+15555555555"
    }
  ],
  "business_account_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "business_entity": {
    "address": {
      "address1": "123 Old Forest Way",
      "city": "Omaha",
      "country": "USA",
      "postal_code": "68022",
      "state": "NE",
      "address2": "address2"
    },
    "government_id": "114-123-1513",
    "legal_business_name": "Acme, Inc.",
    "phone_numbers": [
      "+15555555555"
    ],
    "dba_business_name": "dba_business_name",
    "parent_company": "parent_company"
  },
  "control_person": {
    "address": {
      "address1": "123 Old Forest Way",
      "city": "Omaha",
      "country": "USA",
      "postal_code": "68022",
      "state": "NE",
      "address2": "address2"
    },
    "dob": "1991-03-08 08:00:00",
    "email": "[email protected]",
    "first_name": "Tom",
    "last_name": "Bombadil",
    "phone_number": "+15555555555"
  },
  "created": "2019-12-27T18:11:19.117Z",
  "email": "email",
  "exemption_type": "AUTHORIZED_USER",
  "external_id": "external_id",
  "individual": {
    "address": {
      "address1": "123 Old Forest Way",
      "city": "Omaha",
      "country": "USA",
      "postal_code": "68022",
      "state": "NE",
      "address2": "address2"
    },
    "dob": "1991-03-08 08:00:00",
    "email": "[email protected]",
    "first_name": "Tom",
    "last_name": "Bombadil",
    "phone_number": "+15555555555"
  },
  "nature_of_business": "nature_of_business",
  "phone_number": "phone_number",
  "required_documents": [
    {
      "entity_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "status_reasons": [
        "string"
      ],
      "valid_documents": [
        "string"
      ]
    }
  ],
  "status": "ACCEPTED",
  "status_reasons": [
    "ADDRESS_VERIFICATION_FAILURE"
  ],
  "user_type": "BUSINESS",
  "verification_application": {
    "created": "2019-12-27T18:11:19.117Z",
    "status": "ACCEPTED",
    "status_reasons": [
      "ADDRESS_VERIFICATION_FAILURE"
    ],
    "updated": "2019-12-27T18:11:19.117Z",
    "ky_passed_at": "2019-12-27T18:11:19.117Z"
  },
  "website_url": "website_url"
}

Simulate An Account Holder Document Upload S Review ->

Document

post/v1/simulate/account_holders/enrollment_document_review

Simulates a review for an account holder document upload.

Domain types

AccountHolder = { token, created, account_token, 17 more... }

AddressUpdate = { address1, address2, city, 3 more... }

KYB = { beneficial_owner_individuals, business_entity, control_person, 7 more... }

KYBBusinessEntity = { address, government_id, legal_business_name, 3 more... }

KYC = { individual, tos_timestamp, workflow, 2 more... }

KYCExempt = { address, email, first_name, 6 more... }

RequiredDocument = { entity_token, status_reasons, valid_documents }