/kyc

Advanced KYC system endpoint to kick off the KYC verification process for a registered user_handle.

👍

This doc has been updated with Priority specifications.

🚧

Advanced KYC ONLY

Only use this endpoint if you are utilizing the new Advanced KYC. Otherwise, use /request_kyc.

After creating a user_handle with /register, begin the KYC verification process with this endpoint. Check results with /get_verifications or /get_verifications/<verification_uuid>. This endpoint supports both ECDSA and JWT, but we recommend using JWT. This endpoint is not SDK-supported.

Note that if a verification record goes into a status of documents_required, the verification status will automatically transition to failed after 30 days if documents are not uploaded. Upload a doc to this verification record to restart the process in this scenario.

CONSOLE KYC FLOW REQUIRED

You must have set up a KYC Flow in the Sila console to hit this endpoint. See this section of our implementation guide.

Creation of Sila Wallet / Priority Remote Ledger Account

  • This endpoint creates the Sila wallet / Priority remote ledger account. This happens upon a successful /kyc call.
  • If you are using an app that uses JWT authentication that the remote ledger account will be frozen until KYC is passed. If you are using ECDSA authentication, the payment instrument will not be frozen, but you will not be able to transact with it until KYC is passed.
  • While this payment instrument is created at this point, the payment instrument UUID is not returned in the /kyc response. Instead, it will be returned with the kyc_status webhook when KYC is passed. You can also call /get_wallets or /get_payment_methods to retrieve it before then.
    • Additional line to kyc_status webhook will look like: "wallet_id": "wallet_uuid_string"

Request

Authorization / Authentication

Apps using Access Token Authorization

Use a valid access token in an Authorization: Bearer request header.

See Auth Token Overview for more details.

NOTE: Though we recommend using JWT, you can use this endpoint with ECDSA.

POST /0.2/kyc HTTP/1.1
sandbox.silamoney.com
Content-Type: application/json
Authorization: Bearer [GENERATED JWT TOKEN HERE]

{
  "header": {
    "created": 1234567890, //required
    "app_handle": "<your app_handle>", //required
    "user_handle":"user_handle", //required
    "version": "0.2", 
    "reference": "<your unique id>"
  }, 
  "flow": "<uuid of KYC flow>", //required
	"kyc_level": "KYC-PRIORITY" // required
}

***

HTTP/1.1 202 OK

{
  "success": true,
  "reference": "1753312417",
  "message": "KYC successfully requested using flow c9bed594-9368-4fd8-8094-b78df7850ba0.",
  "verification_ids": [
      {
        "entity": "test_user",
        "verification_id": "28772779-f411-46eb-8f2d-c7dea439a303"
      }
  ],
  "flow_requested": "c9bed594-9368-4fd8-8094-b78df7850ba0",
  "checks_requested": [
      "priority_kyc"
  ],
  "status": "SUCCESS",
  "sila_reference_id": "req_whdbvhx1nusaacx3c3wtcoi3ki",
  "response_time_ms": "407"
}

Request Attributes

KeyTypeDescription
headerJSON objectRequired.

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 - the user_handle to go through KYC

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
flowstringRequired.

UUID of the desired KYC Flow to use. Can be found in the KYC Flow details in the Console.
kyc_levelstringRequired.

Valid options:
KYC-PRIORITY - use for individual entities
KYB-PRIORITY - use for business entities

Responses

Status CodeSuccess AttributeDescriptionerror_code
202true
400falseEnd user data has not been entered into Sila's system.

"Missing required verification data: []"
400falseIDV for this entity has failed twice within the past 30 days.

"{user_handle} has reached the maximum number of attempts for ID verification. Further attempts are not allowed at this time."
KYC_ATTEMPTS_EXCEEDED
403falseWhen a KYC Flow exists but hasn't been approved by Compliance.

"KYC Flow <request_uuid> is not yet approved for use."
KYC_FLOW_NOT_APPROVED
403falseA KYC application has already been submitted for an entity, within the past 15 min.

"There has already been a pending KYC request submitted within the last 15 min for the entity."
KYC_REQUEST_DUPLICATE_PENDING
403falseThere is already a passed identity verification within the last 30 days.

"There has already ben a passed identity verification within the last {window}."
RECENTLY_PASSED_ID_VERIFICATION
404falseA non-existent KYC Flow UUID was entered.

"KYC flow <request_uuid> not found."
KYC_FLOW_DNE