KYC/KYB Status

Learn how to check the status of a KYC or KYB evaluation.

After a KYC or KYB evaluation is submitted, you can either request the status of the submission or listen for the status of your submission via webhook.

Check KYC/KYB Status

This endpoint is used to check the status of a KYC or KYB evaluation.

GET https://api.lithic.com/v1/account_holders/{account_holder_token}

Sample Request

curl https://api.lithic.com/v1/account_holders/12345678-aa69-4cbc-a946-30d90181b621 \
  -X GET \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Sample Response

{
    "token": "12345678-aa69-4cbc-a946-30d90181b621",
    "phone_number": "15555555555",
    "email": "[email protected]",
    "status": "ACCEPTED"
}
token (required, path parameter)Token identifying the account holder for which KYC or KYB status is being 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. Calling this endpoint with a different URL will re-register the new URL and rotate the HMAC token.

Two specific use cases where we recommend the use of webhook updates are:

  • KYC workflows: In the case where documents need to be submitted for verification, a webhook will notify you once the document upload status changes, or an ACCEPTED or REJECTED status for the KYC evaluation is available
  • KYB workflows: All Basic KYB workflows will initially return a PENDING_REVIEW status, and a webhook will notify you once an ACCEPTED or REJECTED status is available
POST https://api.lithic.com/v1/webhooks/account_holders

Sample Request

{
  "url": "https://mywebhook.com/incoming"
}

Sample Response

{
  "data": {
    "hmac_token": "52969474-5dc5-42f7-927a-2e3b45b3d7d2"
  }
}

The webhook payload will have the following structure:

{
  "event_time": <ISO 8601 timestamp>,
  "account_token": <token>,
  "type": <type>,
  "status": <status>,
  "status_reasons": list<status_reasons>,
  "token": <token>,  
}
Webhook type (type)Potential status values returned
verification: Webhook content relates to the verification status of a KYC or KYB evaluation (i.e., the account was successfully or unsuccessfully created)- ACCEPTED: Status of a verification has been updated from PENDING_DOCUMENT to ACCEPTED (KYC use case) or PENDING to ACCEPTED (KYB use case)
- REJECTED: Status of a verification has been updated from PENDING_DOCUMENT to REJECTED (KYC use case) or PENDING to REJECTED (KYB use case)
document_upload_front or document_upload_back: Webhook content relates to the upload status of the front or back image of an identity document- FAILED: Uploaded document has failed