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
orREJECTED
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 anACCEPTED
orREJECTED
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": <RFC 3339 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_UPLOAD 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 |
Updated about 2 months ago