Skip to content
Stainless Stainless Stainless SDKs

Create

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.

Body Parameters
bodyunion
One of the following 3 object variants:
Hide ParametersShow Parameters
beneficial_owner_individualsarray of objectbusiness_entityobjectcontrol_personobjectnature_of_businessstringtos_timestampstringworkflowenumbeneficial_owner_entitiesarray of objectexternal_idstringkyb_passed_timestampstringwebsite_urlstringKYB
individualobjecttos_timestampstringworkflowenumexternal_idstringkyc_passed_timestampstringKYC
addressAddressemailstringfirst_namestringkyc_exemption_typeenumlast_namestringphone_numberstringworkflowenumbusiness_account_tokenstringexternal_idstringKYCExempt
Returns
tokenstring

Globally unique identifier for the account holder.

formatuuid
account_tokenstring

Globally unique identifier for the account.

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

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"
"PRIMARY_BUSINESS_ENTITY_ID_VERIFICATION_FAILURE"
"PRIMARY_BUSINESS_ENTITY_ADDRESS_VERIFICATION_FAILURE"
"PRIMARY_BUSINESS_ENTITY_NAME_VERIFICATION_FAILURE"
"PRIMARY_BUSINESS_ENTITY_BUSINESS_OFFICERS_NOT_MATCHED"
"PRIMARY_BUSINESS_ENTITY_SOS_FILING_INACTIVE"
"PRIMARY_BUSINESS_ENTITY_SOS_NOT_MATCHED"
"PRIMARY_BUSINESS_ENTITY_CMRA_FAILURE"
"PRIMARY_BUSINESS_ENTITY_WATCHLIST_FAILURE"
"PRIMARY_BUSINESS_ENTITY_REGISTERED_AGENT_FAILURE"
"CONTROL_PERSON_BLOCKLIST_ALERT_FAILURE"
"CONTROL_PERSON_ID_VERIFICATION_FAILURE"
"CONTROL_PERSON_DOB_VERIFICATION_FAILURE"
"CONTROL_PERSON_NAME_VERIFICATION_FAILURE"
createdstring
optional

Timestamp of when the account holder was created.

formatdate-time
external_idstring
optional

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

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

Request example Request
curl https://api.lithic.com/v1/account_holders \
    -H 'Content-Type: application/json' \
    -H "Authorization: $LITHIC_API_KEY" \
    -d '{
      "beneficial_owner_individuals": [
        {
          "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"
        }
      ],
      "business_entity": {
        "address": {
          "address1": "123 Old Forest Way",
          "city": "Omaha",
          "country": "USA",
          "postal_code": "68022",
          "state": "NE"
        },
        "government_id": "114-123-1513",
        "legal_business_name": "Acme, Inc.",
        "phone_numbers": [
          "+15555555555"
        ]
      },
      "control_person": {
        "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"
      },
      "nature_of_business": "Software company selling solutions to the restaurant industry",
      "tos_timestamp": "2018-05-29T21:16:05Z",
      "workflow": "KYB_BASIC",
      "kyb_passed_timestamp": "2018-05-29T21:16:05Z",
      "website_url": "www.mybusiness.com"
    }'
200 Example
{
  "token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "account_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "status": "ACCEPTED",
  "status_reasons": [
    "ADDRESS_VERIFICATION_FAILURE"
  ],
  "created": "2019-12-27T18:11:19.117Z",
  "external_id": "external_id",
  "required_documents": [
    {
      "entity_token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "status_reasons": [
        "string"
      ],
      "valid_documents": [
        "string"
      ]
    }
  ]
}