🚧
Classic KYC ONLY
Only use this endpoint if you are utilizing Classic KYC. 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.

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.

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.

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": "app_handle", 
    "user_handle":"user_handle", 
    "version": "0.2", 
    "reference": "<your unique id>"
  }, 
  "message": "header_msg",
  "kyc_level": "KYC-STANDARD" //optional
}

***

HTTP/1.1 200 OK

{
  "success": true,
  "status": "SUCCESS",
  "message": "user has passed ID verification!",
  "response_time_ms": "171",
  "reference": "<your unique id>",
  "sila_reference_id": "sila_assigned_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
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": "app_handl",
    "user_handle": "business_user_handle"
  }
}

***

{
    "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, ...]

Request Attributes

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 handle `user_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
kyc_level	String	Optional. Use to filter for verifications which only match the specified KYC level. When left out, the overall top-level verification status reflects the last non-pending verification status for the current user, regardless of KYC level. You don't need to use this if you only ever use one KYC level in your application or per user.

Responses

Individual Entities

Understanding the verification_history array

Field	Description
`verification_id`	UUID identifying verification run for the 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 "KYC-STANDARD" for individuals.
`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. -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`	Will be null.
`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.

Business Entities

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	SuccessAttribute	`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.

/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

🚧Classic KYC ONLY

Request

Authorization / Authentication

Apps using Access Token Authorization

Apps using ECDSA Authentication

Request Attributes

Responses

Individual Entities

Business Entities

Each object in the certification_history array has keys like so:

Each object in the members array has keys like so:

Verification Statuses

/check_kyc response tags for failures

Indviduals:

Businesses:

🚧
Classic KYC ONLY

Each object in the `certification_history` array has keys like so:

Each object in the `members` array has keys like so: