API Documentation

/request_kyc

Starts KYC verification process on a registered user handle.

Suggest Edits

After having created a user and a handle with /register, you can start the KYC verification process on the user with this endpoint. The verification results for a handle are asynchronously returned at the /check_kyc endpoint, and further details on handling failures can be found in the documentation there.

Requests

The request body at this endpoint is the header_msg JSON object.

header.user_handle should have the registered handle to be verified.

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.

You also need to pass a kyc_level key into the request body if you have a specific KYC flow approved for your app, or to take advantage of our document verification functionality if KYC fails by using DOC_KYC. If your funds flow needs different KYC requirements, contact us!

Sila will restrict to re-requesting KYC after 2 failures. This will stop our customers to send updates & resubmissions for KYC data on failed KYC using /update endpoints. Previously, there was no limit to sending /request_kyc requests after failing KYC. This gives unlimited access to our end-users to send updated information and check KYC updates; We have put up this restriction so that bad actors not to send continually update end-user data and re-attempt 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/request_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

{
  "reference":"ref",
  "message":"user submitted for KYC review.",
  "success": true,
  "status":"SUCCESS",
  "response_time_ms": "171",
  "verification_uuid": "482d405f-2dc4-4cbc-9f37-13e0dfa8be5a"
}

***
For INSTANT-ACHV2:
***

POST /0.2/request_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, 
    "auth_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "ref"
  }, 
  "message": "header_msg",
  "kyc_level": "INSTANT-ACHV2"
}

HTTP/1.1 200 OK

{
  "reference":"ref",
  "message":"user submitted for KYC review.",
  "success": true,
  "status":"SUCCESS",
  "response_time_ms": "171",
  "verification_uuid": "482d405f-2dc4-4cbc-9f37-13e0dfa8be5a"
}

***
For custom user-onboarding flows:
***

POST /0.2/request_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, 
    "auth_handle": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "ref"
  }, 
  "message": "header_msg",
  "kyc_level": "CUSTOM_KYC_FLOW_NAME"
}

***

HTTP/1.1 200 OK

{
  "reference":"ref",
  "message":"user submitted for KYC review.",
  "success": true,
  "status":"SUCCESS",
  "response_time_ms": "171",
  "verification_uuid": "482d405f-2dc4-4cbc-9f37-13e0dfa8be5a"
}

// Normal flow - NOTE**, use 'DOC_KYC'.  This will result in a `DOCUMENTS REQUIRED` 
// verification status in /check_kyc instead of `FAILED` for entities that don't 
// automatically pass, but that could pass KYC by uploading a document.
const res = await Sila.requestKYC(userHandle, walletPrivateKey, 'DOC_KYC');

// Custom flow
const res = await Sila.requestKYC(userHandle, walletPrivateKey, 'flow_name');

// 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 submitted for KYC review
console.log(res.data.success);
console.log(res.data.verification_uuid);

### Default KYC Request - NOTE**, use 'DOC_KYC'.  This will result 
### in a `DOCUMENTS REQUIRED` verification status in /check_kyc instead of `FAILED`
### for entities that don't automatically pass, but that could pass KYC by uploading a document.

payload = {
    "user_handle": "user.silamoney.eth",    #Required
    "kyc_level": "DOC_KYC"
}

User.requestKyc(silaApp,payload,user_private_key, use_kyc_level=True)

### Custom KYC Request
payload = {
    "user_handle": "user.silamoney.eth",    #Required
    "kyc_level": "CUSTOM_KYC_FLOW_NAME"
}

User.requestKyc(silaApp,payload,user_private_key, use_kyc_level=True)

### Success Response Object
{
    status_code: 200,
    reference: 'ref',
    success: True,
    verification_uuid: '482d405f-2dc4-4cbc-9f37-13e0dfa8be5a',
    status: 'SUCCESS',
    message: 'user submitted for kyc',
}

### Failure Response Object
{
    status: 'FAILURE',
    message: 'error',
}

### ***SECURITY ALERT***
### ***This sdk never transmits private keys over the network,it is advised to use a secure way for managing user private keys***

//Default request - NOTE**, use 'DOC_KYC'.  This will result in a `DOCUMENTS REQUIRED` 
// verification status in /check_kyc instead of `FAILED` for entities that don't 
// automatically pass, but that could pass KYC by uploading a document.

ApiResponse response = api.requestKYC("user handle","DOC_KYC","user private key");

//Custom kyc flow
ApiResponse response = api.requestKYC("user handle","custom kyc flow name","user private key");

RequestKycResponse parsedResponse = (RequestKycResponse) response.getData();

parsedResponse.getStatus();
parsedResponse.getMessage();
parsedResponse.getReference();
parsedResponse.getVerificationUuid();
parsedResponse.getSuccess();

// Normal flow  - NOTE**, use 'DOC_KYC'.  This will result in a `DOCUMENTS REQUIRED` 
// verification status in /check_kyc instead of `FAILED` for entities that don't 
// automatically pass, but that could pass KYC by uploading a document.
$userHandle = 'user.silamoney.eth';
$userPrivateKey = 'some private key'; // Hex format
$kycLevel = 'DOC_KYC';
$response = $client->requestKYC($userHandle, $userPrivateKey, $kycLevel);

// Custom flow
$userHandle = 'user.silamoney.eth';
$userPrivateKey = 'some private key'; // Hex format
$kycLevel = 'CUSTOM_KYC_FLOW_NAME';
$response = $client->requestKYC($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 submitted for KYC review.
echo $response->getData()->success;
echo $response->getData()->verification_uuid;

ApiResponse<object> response = api.RequestKYC(userHandle, walletPrivateKey, "DOC_KYC");

// Custom flow
ApiResponse<object> response = api.RequestKYC(userHandle, walletPrivateKey, "flow_name");

// Success Response Object

Console.WriteLine(response.StatusCode); // 200
Console.WriteLine(((RequestKycResponse)response.Data).Reference); // Random reference number
Console.WriteLine(((RequestKycResponse)response.Data).Status); // SUCCESS
Console.WriteLine(((RequestKycResponse)response.Data).Message); // user submitted for KYC review.
Console.WriteLine(((RequestKycResponse)response.Data).VerificationUuid); // verification uuid.

📘

Mocking KYC Failures in Sandbox - The Unhappy Path

Please refer to the /request_kyc endpoint requirements doc for testing information.

🚧

KYB Levels

Unlike with KYC, with KYB the KYC_LEVEL does not need to be specified explicitly by your API request. Instead, KYB levels are applied to the business entity based on the business type.

Request Details

KeyTypeDescription
headerJSON objectRequired. 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.
kyc_levelStringOptional. The kyc_level field is used to request a specific verification flow for an entity.

See our section on KYC/KYB Levels for more details on KYC levels.

If left empty, DEFAULT will be used for backwards compatibility. This is not recommended. If you have not been approved for a custom level, you should specify DOC_KYC here in place of DEFAULT for any individual (eg. non-business) users.

DOC_KYC uses the DEFAULT flow but will provide a DOCUMENTS REQUIRED status in /check_kyc instead of FAILED for entities don't automatically pass, but that could pass KYC by uploading a document.

Responses

Status Codesuccess AttributeDescription
200trueThe verification process for the user registered under header.user_handle has been successfully started.
400falseBad request format - check validation_details for more information.
401falseauthsignature or usersignature header was absent or incorrect.
403falsekyc_level not configured/approved for auth_handle in current environment.
403falseEntity identity has returns for previous entity.

Updated about 3 years ago