/check_kyc

Returns whether entity attached to user handle is verified, not valid, or still pending.

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 an alternative, /check_kyc can be polled, but we do not recommend this approach.

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

  

Requests

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.

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 authentication section for more details on how to generate this signature.

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": "DOC_KYC"

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
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", 
    "crypto": "ETH", 
    "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": "ref",
  "entity_type": "individual",
  "verification_status": "passed",
  "verification_history": [
    {
      "verification_id": "616e7d20-1f65-4318-8f1c-880f191cefab",
      "verification_status": "passed",
      "kyc_level": "DEFAULT",
      "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": [
      "DEFAULT"
  ]
}

---

{
  "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": [
    "DEFAULT"
  ]
}

---

{
    "success": false,
    "status": "FAILURE",
    "message": "user is pending ID verification.",
    "reference": "ref",
    "entity_type": "individual",
    "verification_status": "pending",
    "verification_history": [
        {
            "verification_id": "9137dc67-978f-48cb-a44b-f6805f6954c4",
            "verification_status": "pending",
            "kyc_level": "DEFAULT",
            "requested_at": 1592338961,
            "updated_at": 1592338961,
            "reasons": [],
            "tags": [],
            "score": null,
            "parent_verification": null
        }
    ],
    "valid_kyc_levels": [
        "DEFAULT"
    ]
}

---

{
    "success": false,
    "status": "FAILURE",
    "message": "user has failed ID verification.",
    "reference": "",
    "entity_type": "individual",
    "verification_status": "failed",
    "verification_history": [
        {
            "verification_id": "2f5dc7de-5268-40e3-b39e-ac50535ef879",
            "verification_status": "failed",
            "kyc_level": "DEFAULT",
            "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"
            ],
            "score": 0.10,
            "parent_verification": null
        }
    ],
    "valid_kyc_levels": [
        "DEFAULT"
    ]
}
***
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", 
    "crypto": "ETH", 
    "reference": "<your unique id>"
  }, 
  "message": "header_msg",
  "kyc_level": "DOC_KYC"
}

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",
    "verification_history": [
        {
            "verification_id": "2881d961-66c8-43a7-8319-03b06e21fb82",
            "verification_status": "passed",
            "kyc_level": "DOC_KYC",
            "requested_at": 1637140009,
            "updated_at": 1637140009,
            "reasons": [],
            "tags": [],
            "score": null,
            "parent_verification": null
        }
    ],
    "valid_kyc_levels": [
        "DOC_KYC",
        "RECEIVE_ONLY"
    ],
    "status": "SUCCESS"
}
***
***
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", 
    "crypto": "ETH", 
    "reference": "<your unique id>"
  }, 
  "message": "header_msg",
  "kyc_level": "INSTANT-ACH"
}

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",
    "verification_history": [],
    "valid_kyc_levels": [
        "DEFAULT",
        "DOC_KYC",
        "INSTANT-ACH",
        "KYC-LITE",
        "RECEIVE_ONLY"
    ],
    "status": "FAILURE"
}
POST /0.2/check_kyc HTTP/1.1
Host: sandbox.silamoney.com
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]
Content-Type: application/json

{
  "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' //Optional field. Adding new additional value for kyc_level:  INSTANT-ACHV2

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="INSTANT-ACHV2"; // Optional
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 = 'INSTANT-ACHV2'; // Optional
$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 = "INSTANT-ACHV2"; // optional field
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. Requires these keys in JSON format: created, app_handle, user_handle. See the /check_handle endpoint for the complete list of fields in this object.

entity_type

String

Optional. The optional entity_type field is used to filter. Choose 'individual' or 'business' only. Example: individual

kyc_level

String

Optional. The kyc_level field is used to filter for verifications which only match the specified KYC level.

  

Responses

There are several new 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.
  • 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.
    • 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.

Indviduals:

Businesses:

See Triaging KYC Failures for more details

📘

In sandbox only, you can register a user that will always fail KYC by passing in a "first_name", "last_name", or "full_name" field with a value of "FAIL" (case-insensitive). For example, values of "fail", "Fail", and "fAiL" will all result in failures, but values like "FAILURE" and "fail1" will pass sandbox KYC.

  • When Register user with first_name, OR last_name, OR full_name = “documents_required” then it will return documents_required status.
  • When Register user with first_name, OR last_name, OR full_name = “Fraud” then it will return "failed" status with tags: "fraud warning" and "denied fraud .
  • When Register user with first_name, OR last_name, OR full_name = “Review” then it will return "review" status .

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'

documents are required to verify the entity. More likely to be fraud

'member_unverified'

business member(s) has user has not had a KYC evaluation

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

documents are required to verify the entity. Only applies to kyc_levels: DOC_KYC, INSTANT-ACH

'documents_received'

documents were received but not reviewed. Only applies to kyc_levels: DOC_KYC, INSTANT-ACH

'webhook_pending'

a webhook has not been received for an in-progress KYC evaluation

  

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.


Did this page help you?