/check_kyc
Returns whether entity attached to user handle is verified, not valid, or still pending.
Classic KYC ONLY
Only use this endpoint if you are utilizing Classic KYC (not Advanced). If you are using Advanced KYC, use /get_verification or /get_verifications.
This endpoint should be run after successfully completing /register and /request_kyc calls.
Since ID verification can take some time (on average it takes 33 seconds, but occasionally it can take longer), /request_kyc will never confirm in its response that an entity was verified. We recommend configuring a webhook in the developer console to be notified of state changes, as the /check_kyc endpoint should never be polled.
For more information about how to take advantage Sila's webhooks, visit KYC Status Update Event.
Triaging KYC Failures
Some users will fail their KYC or KYB evaluation. If you intend to help these users become transactional on your platform you will need to implement a KYC or KYB flow that enables you and them to triage the failures. For more details on that see Triaging KYC Failures
Request
The request body at this endpoint is the header_msg JSON object.
The handle for which KYC confirmation is being checked should be in the header.user_handle field.
The optional kyc_level field is used to filter for verifications which only match the specified KYC level. When this filter is not present in /check_kyc, the overall top-level verification status reflects the last non-pending verification status for the current user, regardless of KYC level. If your application is approved for multiple KYC levels, you can check overall KYC results for a single level of KYC with:
"kyc_level": "YOUR_KYC_LEVEL_NAME"
as an optional key in your request. You don't need to use this if you only ever use one KYC level in your application or per user.
To view a user's full KYC verifications flow, you can request:
"kyc_level": "KYC-STANDARD"
Authorization / Authentication
Apps using Access Token Authorization
Use a valid access token in a Authorization: Bearer request header.
See Auth Token Overview for more details.
Apps using ECDSA Authentication
Both authsignature and usersignature headers are required for this request. The usersignature header should be generated with a keypair registered to the user (either registered from the /register endpoint or the /register_wallet endpoint).
See our ECDSA overview for more.
Note - We recently renamed the field auth_handle to app_handle. For backward compatibility, auth_handle is still valid but has been removed from our documentation.
POST /0.2/check_kyc HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
{
"header": {
"created": 1234567890,
"app_handle": "handle.silamoney.eth",
"user_handle":"user.silamoney.eth",
"version": "0.2",
"reference": "<your unique id>"
},
"message": "header_msg"
}
***
HTTP/1.1 200 OK
{
"success": true,
"status": "SUCCESS",
"message": "user has passed ID verification!",
"response_time_ms": "171",
"reference": "<your unique id>",
"entity_type": "individual",
"verification_status": "passed",
"documents_required_verification_ids": [
"616e7d20-1f65-4318-8f1c-880f191cefab",
"616e7d20-1f65-4318-8f1c-880f191cefac",
],
"verification_history": [
{
"verification_id": "616e7d20-1f65-4318-8f1c-880f191cefab",
"verification_status": "passed",
"kyc_level": "KYC-STANDARD",
"requested_at": 1592339985,
"updated_at": 1592340016,
"reasons": [],
"tags": [
"KYC Name Match",
"KYC SSN Match",
"KYC DOB Match",
"Phone Match",
"KYC Address Match"
],
"score": 0.99,
"parent_verification": null
}
],
"valid_kyc_levels": [
"KYC-STANDARD"
]
}
---
{
"success": false,
"status": "FAILURE",
"message": "ID verification was not requested for user.",
"reference": "ref",
"entity_type": "individual",
"verification_status": "unverified",
"verification_history": [],
"valid_kyc_levels": [
"KYC-STANDARD"
]
}
---
{
"success": false,
"status": "FAILURE",
"message": "user is pending ID verification.",
"reference": "ref",
"entity_type": "individual",
"verification_status": "pending",
"documents_required_verification_ids": [],
"verification_history": [
{
"verification_id": "9137dc67-978f-48cb-a44b-f6805f6954c4",
"verification_status": "pending",
"kyc_level": "KYC-STANDARD",
"requested_at": 1592338961,
"updated_at": 1592338961,
"reasons": [],
"tags": [],
"documents_required_details_url": null,
"score": null,
"parent_verification": null
}
],
"valid_kyc_levels": [
"KYC-STANDARD"
]
}
---
{
"success": false,
"status": "FAILURE",
"message": "user has failed ID verification.",
"reference": "",
"entity_type": "individual",
"verification_status": "failed",
"documents_required_verification_ids": ["2f5dc7de-5268-40e3-b39e-ac50535ef879"],
"verification_history": [
{
"verification_id": "2f5dc7de-5268-40e3-b39e-ac50535ef879",
"verification_status": "failed",
"kyc_level": "KYC-STANDARD",
"requested_at": 1592341803,
"updated_at": 1592341815,
"reasons": [],
"tags": [
"Address Not Matched", "Address Not Verified",
"Name Mismatch","Name Not Verified",
"DOB Miskey", "DOB Not Verified",
"SSN Miskey", "SSN Not Verified"
],
"documents_required_details_url": "https://api.silamoney.com/0.2/check_kyc/2f5dc7de-5268-40e3-b39e-ac50535ef879/required_document_types",
"score": 0.10,
"parent_verification": null
}
],
"valid_kyc_levels": [
"KYC-STANDARD"
]
}
***
POST /0.2/check_kyc HTTP/1.1
Host: sandbox.silamoney.com
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
Content-Type: application/json
{
"header": {
"created": 1234567890,
"app_handle": "handle.silamoney.eth",
"user_handle":"user.silamoney.eth",
"version": "0.2",
"reference": "<your unique id>"
},
"message": "header_msg",
"kyc_level": "KYC-STANDARD"
}
HTTP/1.1 200 OK
***
{
"success": true,
"message": "user has passed ID verification!",
"reference": "23e74fa4-9419-429d-9365-85a4d27d0406",
"entity_type": "individual",
"verification_status": "passed",
"documents_required_verification_ids": [],
"verification_history": [
{
"verification_id": "2881d961-66c8-43a7-8319-03b06e21fb82",
"verification_status": "passed",
"kyc_level": "KYC-STANDARD",
"requested_at": 1637140009,
"updated_at": 1637140009,
"reasons": [],
"tags": [],
"documents_required_details_url": null,
"score": null,
"parent_verification": null
}
],
"valid_kyc_levels": [
"KYC-STANDARD"
],
"status": "SUCCESS"
}
***
HTTP/1.1 200 OK
***
{
"success": false,
"message": "ID verification was not requested for user.",
"reference": "fedb0464-5a66-4ceb-a789-bd5e3833943d",
"entity_type": "individual",
"verification_status": "unverified",
"documents_required_verification_ids": [],
"verification_history": [],
"valid_kyc_levels": [
"KYC-STANDARD",
"KYB-STANDARD",
],
"status": "FAILURE"
}
POST /0.2/check_kyc HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
usersignature: [GENERATED USERSIGNATURE HEX STRING HERE]
{
"header": {
"created": 1234567890,
"auth_handle": "your_app_handle.silamoney.eth",
"user_handle": "your_business_user.silamoney.eth"
}
}
***
{
"status": "FAILURE",
"message": "your_business_user is pending ID verification.",
"reference": "ref",
"entity_type": "business",
"verification_status": "pending",
"verification_history": [
{
"verification_id": "1802c2a5-1d1e-48a3-9af4-d7189934de9e",
"verification_status": "pending",
"kyc_level": "KYB-STANDARD",
"requested_at": 1592946326,
"updated_at": 1592946334,
"reasons": [],
"tags": [
"Address Matched",
"FEIN Found",
"Company Name Verified",
"Phone Matched",
"Representative Match"
],
"score": 0.9,
"parent_verification": null
}
],
"valid_kyc_levels": [
"KYB-STANDARD"
],
"certification_status": "certification_pending",
"certification_history": [],
"members": [
{
"user_handle": "your_individual_user",
"first_name": "Individual",
"last_name": "User",
"role": "controlling_officer",
"details": "CEO",
"ownership_stake": null,
"verification_status": "passed",
"verification_required": true,
"verification_id": "e72e7961-5924-4534-98d7-09d89f804762",
"beneficial_owner_certification_status": "certification_not_required",
"business_certification_status": "certification_not_required"
},
{
"user_handle": "your_individual_user",
"first_name": "Individual",
"last_name": "User",
"role": "beneficial_owner",
"details": "Private investor",
"ownership_stake": 66.7,
"verification_status": "passed",
"verification_required": true,
"verification_id": "e72e7961-5924-4534-98d7-09d89f804762",
"beneficial_owner_certification_status": "certification_pending",
"business_certification_status": "certification_pending"
}
]
}
---
{
"status": "SUCCESS",
"message": "your_business_user has passed ID verification!",
"reference": "",
"entity_type": "business",
"verification_status": "passed",
"verification_history": [
{
"verification_id": "1802c2a5-1d1e-48a3-9af4-d7189934de9e",
"verification_status": "passed",
"kyc_level": "KYB-STANDARD",
"requested_at": 1592946326,
"updated_at": 1592949479,
"reasons": [],
"tags": [
"Address Matched",
"FEIN Found",
"Company Name Verified",
"Phone Matched",
"Representative Match"
],
"score": 0.9,
"parent_verification": null
}
],
"valid_kyc_levels": [
"KYB-STANDARD"
],
"certification_status": "certified",
"certification_history": [
{
"administrator_user_handle": "your_individual_user",
"created": "2020-06-23T21:57:59.322388+00:00",
"created_epoch": 1592949479.322388,
"expires_after": null,
"expires_after_epoch": null,
"beneficial_owner_certifications": [
"kyb-test-1-individual"
]
}
],
"members": [
{
"user_handle": "your_individual_user",
"first_name": "Individual",
"last_name": "User",
"role": "controlling_officer",
"details": null,
"ownership_stake": null,
"verification_status": "passed",
"verification_required": true,
"verification_id": "e72e7961-5924-4534-98d7-09d89f804762",
"beneficial_owner_certification_status": "certification_not_required",
"business_certification_status": "certification_not_required"
},
{
"user_handle": "your_individual_user",
"first_name": "Individual",
"last_name": "User",
"role": "beneficial_owner",
"details": "Private investor",
"ownership_stake": 66.7,
"verification_status": "passed",
"verification_required": true,
"verification_id": "e72e7961-5924-4534-98d7-09d89f804762",
"beneficial_owner_certification_status": "certified",
"business_certification_status": "certified"
}
]
}
const kycLevel = 'DOC_KYC' //Alternative kyc_leve if approved for iACH product: INSTANT-ACHV2 - see KYC/KYB level docs
const res = await Sila.checkKYC(userHandle, walletPrivateKey, kycLevel);
// Success Response Object
console.log(res.statusCode); // 200
console.log(res.data.reference); // Random reference number
console.log(res.data.status); // SUCCESS
console.log(res.data.message); // User has passed ID verification
payload={
"user_handle": "user.silamoney.eth" #Required
}
User.checkKyc(silaApp,payload,user_private_key)
### Success Response Object
{
status: 'SUCCESS',
message: 'Kyc passed for user.silamoney.eth',
}
### Failure Response Object
{
status: 'FAILURE',
message: 'error',
}
String kycLevel="DOC_KYC"; //Alternative kyc_leve if approved for iACH product: INSTANT-ACHV2 - see KYC/KYB level docs
ApiResponse response = api.checkKYC("user handle", "user private key",kycLevel);
CheckKycResponse parsedResponse = (CheckKycResponse) response.getData();
parsedResponse.getStatus();
parsedResponse.getEntityType();
parsedResponse.getVerificationStatus();
parsedResponse.getVerificationHistory();
parsedResponse.getCertificationStatus();
parsedResponse.getCertificationHistory();
parsedResponse.getMembers();
$userHandle = 'user.silamoney.eth';
$userPrivateKey = 'some private key'; // Hex format
$kycLevel = 'DOC_KYC'; // Alternative kyc_leve if approved for iACH product: INSTANT-ACHV2 - see KYC/KYB level docs
$response = $client->checkKYC($userHandle, $userPrivateKey);
//or with $kycLevel
$response = $client->checkKYC($userHandle, $userPrivateKey, $kycLevel);
// Success 200
echo $response->getStatusCode(); // 200
echo $response->getData()->reference; // Random reference number
echo $response->getData()->status; // SUCCESS
echo $response->getData()->message; // User has passed ID verification!
echo $response->getData()->entity_type; // individual
echo $response->getData()->verification_status; // passed
echo $response->getData()->verification_history; // An array of all the verifications executed for the user (verification status, kyc level...)
echo $response->getData()->valid_kyc_levels; // An array of kyc levels valid for the user
// Additional business values
echo $response->getData()->certification_status; // certified
echo $response->getData()->certification_history; // An array of all the certifications executed for the business (administrator user handle, created, expires after...)
echo $response->getData()->members; // An array of users linked to the business and their verification and certification status (user handle, role, beneficial owner certification status...)
string kycLevel = "DOC_KYC"; // Alternative kyc_leve if approved for iACH product: INSTANT-ACHV2 - see KYC/KYB level docs
ApiResponse<object> response = api.CheckKYC(userHandle, walletPrivateKey, kycLevel);
// Success Response Object
Console.WriteLine(response.StatusCode); // 200
var parsedResponse = (CheckKYCResponse)response.Data;
Console.WriteLine(parsedResponse.Reference); // Random reference number
Console.WriteLine(parsedResponse.Status); // SUCCESS
Console.WriteLine(parsedResponse.Message); // user has passed ID verification!
Console.WriteLine(parsedResponse.EntityType); // individual|business
Console.WriteLine(parsedResponse.VerificationStatus); // passed
Console.WriteLine(parsedResponse.VerificationHistory); // A list of verification results
Console.WriteLine(parsedResponse.VerificationHistory[0].KYCLevel); // INSTANT-ACHv2
Console.WriteLine(parsedResponse.ValidKYCLevels); // List of KYC levels [DEFAULT, ...]
| Key | Type | Description |
|---|---|---|
| header | JSON object | Required. Required keys: created - Unix epoch timestamp in seconds. Must not be future-dated and must not be dated more than 5 minutes in the past.app_handle - your app handleuser_handle - user_handle to check KYC verification status for.Optional keys: reference: Can be any value for your own reference. If not provided, one will be assigned.version: Cannot be null if key is present. Valid values: 0.2, v0.2, V0.2 |
Responses
Keys in the /check_kyc response:
entity_type: Value will always be "individual" for individual users.verification_status: Describes the current state of an entities KYC evaluation. For instance, "passed" or "review". There are descriptions of these statuses in the table below. NOTE: More verification statuses than these may be added in the future, so please implement accordingly.documents_required_verification_ids: A list of verification ids of records that need documents submitted to pass KYC/KYB.verification_history: The value at this key is an array of 0 or more verification objects. All objects in this array have the following keys:verification_id: A UUID identifying the verification run for this user.verification_status: The same values are allowed here as in the overall verification status, which aggregates results from 0 or more verifications. (The overall top-level verification status reflects the last non-pending verification status for the current user.)kyc_level: The level of verification used. By default, this is "DEFAULT" for individuals; if a custom KYC level was requested, that value will be here instead.requested_at: An epoch timestamp (integer value in seconds) describing when this verification was requested.updated_at: An epoch timestamp (integer in seconds) describing when this verification was last updated with new data or a new status.reasons: An array of reason codes (strings) for failing a verification; this is usually empty if the user has passed.tags: An array of descriptive tags (strings) about the verification results.documents_required_details_url: The URL to which a request can be sent to get a list of documents needed for submission to pass KYC/KYB.- Note - For SDK users, please use the makeRequest() method to point to the returned url value for the response.
- This url points to a separate endpoint which can be used independently:
url:/check_kyc/<validation_id>/required_document_types
score: A nullable float value between 0 and 1. If null, no score has yet been computed.parent_verification: Always null for now; reserved for future use.valid_kyc_levels: An array of KYC level names that can be requested for this user. All verifications with any of these KYC levels for the current user will be included in the verification history and used to compute the overall verification status.
/check_kyc response tags for failures
When entities fail KYC some portion of the identity needs to be verified (so-called IDV). Below are links to which documents your users must provide in order to verify their identity based on the failure response attribute,
tags.
See Triaging KYC Failures for more details.
Indviduals:
- Individual Address Verification:
Address Not Matched,Address Not Verified- Name Verification:
Name Mismatch,Name Not Verified- Date of Birth Verification:
DOB Miskey,DOB Not Verified- Social Security Number Verification:
SSN Miskey,SSN Not Verified- General Identity Verification:
Fraud Warning,Denied Fraud,Fraud Risk,Fraud Review,Age Verification- Terminal Failures:
Foreign Device
Businesses:
- Entity Name:
Company Name Not Matched- EIN Verification:
FEIN Unmatched,FEIN Document Required- Business Address Verification:
Address Not Matched
Testing the triaging KYC failures flow in SANDBOX
In sandbox only, you can test out the triaging KYC failure flow by registering a user with specific mock KYC data that will trigger a certain KYC failure tag. See the the testing docs for more information.
The /check_kyc response for business end-users has additional keys when compared to the response for individual end-users: certification_status, certification_history, and members.
certification_status: A string; value can be any of [“certified”, “certification_not_required”, “certification_pending”].certification_history: An array of certification objects.members: An array of members objects.
Each object in the certification_history array has keys like so:
| Key | Type | Description |
|---|---|---|
administrator_user_handle | string | The handle of the linked administrator business member that requested the business certification. |
created | string (RFC3339-formatted timestamp) | Timestamp of when business certification was created. |
created_epoch | float | Epoch timestamp of when business certification was created. |
expires_after | string (RFC3339-formatted timestamp, nullable) | Timestamp of when business certification will expire. To be able to continue to transact, all linked beneficial owners need to be certified (/certify_beneficial_owner) and a new business certification will need to be created (/certify_business). |
expires_after_epoch | float | Epoch timestamp of when business certification will expire. To be able to continue to transact, all linked beneficial owners need to be certified (/certify_beneficial_owner) and a new business certification will need to be created (/certify_business). |
beneficial_owner_certifications | array of strings | Array of handles of beneficial owners that were individually certified and included in the latest business certification. |
Each object in the members array has keys like so:
| Key | Type | Description |
|---|---|---|
user_handle | string | The handle of the linked business member. |
first_name | string | The first name of the linked business member as registered. |
last_name | string | The last name of the linked business member as registered. |
role | string | The machine-readable business role name of this member. (If one member has multiple roles, then the same user will be in multiple objects in the members array). |
details | string (nullable) | The optional details string as sent in the original /link_business_member request. |
ownership_stake | float (nullable) | The ownership stake (valid value 0 < value <= 100) as registered in the original /link_business_member request. This will only be non-null for beneficial owners. |
verification_status | string | Verification status for individual, can be any one of [“passed”, “pending”, “unverified”, "review", or “failed”] for KYC Level STANDARD and [“passed”, “pending”, “unverified”, "documents_required", or "documents_received"] for KYC Level DOC_KYC. |
verification_required | boolean | True if individual verification must be “passed” for the business to transition to “passed” (if not already “passed”), false otherwise. Verification is not required for users that only have the “administrator” role. |
verification_id | string (UUID4) | Unique identifier of the linked individual verification. |
beneficial_owner_certification_status | string | Can be any one of [“certified”, “certification_pending”, “certification_not_required”]. Indicates that /certify_beneficial_owner has been successfully requested for this user. |
business_certification_status | string | Can be any one of [“certified”, “certification_pending”, “certification_not_required”]. Indicates that the business certification generated in /certify_business includes the individual certification generated from /certify_beneficial_owner. |
Verification Statuses
| Verification Status | Description |
|---|---|
| 'unverified' | Entity has not had a KYC evaluation |
| 'passed' | Entity has passed KYC |
| 'pending' | An entity's KYC evaluation is in progress |
| 'review' | Documents are required to verify the entity |
| 'failed' | Entity has failed KYC |
| 'member_failed' | Documents are required to verify business members. More likely to be fraud |
| 'member_review' | Documents are required to verify business members |
| 'member_pending' | A business member's KYC evaluation is in progress |
| 'documents_required' | Entity PII needs to be reviewed, and possibly documents uploaded |
| 'documents_received' | Documents were received but not reviewed |
| 'webhook_pending' | Waiting for a webhook response from a KYC provider |
| Status Code | success Attribute | verification_status Attribute | Description |
|---|---|---|---|
| 200 | true | "passed" | The user handle has successfully passed KYC verification. |
| 200 | false | "unverified" | Verification has not been requested for this user. |
| 200 | false | "pending" | The user is still pending KYC verification. |
| 200 | false | "failed" | The user has failed KYC verification. |
| 200 | false | "documents_required" | We require documents to be approved before passing verification. |
| 200 | false | "webhook_pending" | Awaiting additional verification. |
| 400 | false | N/A | Bad request - check message and/or validation_details keys for more information. |
| 401 | false | N/A | authsignature or usersignature header was absent or incorrect. |
Updated 3 months ago