API Documentation

Advanced KYC

Implementation guide for Advanced KYC.

Suggest Edits

🚧

Do I have to use Advanced KYC? If I'm an existing customer using Classic KYC, do I need to switch?

NO, if you are switching to our new banking partner, Priority, you are not required to switch.

We are requiring newly onboarding customers to use Advanced rather than Classic KYC.

While there is no current ETA, we do plan to eventually sunset the Classic system and only support Advanced KYC.

Building out Advanced KYC

This section is for onboarding customers who have not already built out Classic KYC. Jump to this section if you have already built out Classic KYC and are switching to Advanced.

Please note that the Advanced KYC system is NOT SDK compatible.

Endpoint Order

/check_handle

To ensure the user_handle you're wanting to assign is unique.

/register

Creates a new individual or business entity in the Sila ecosystem with associated PII. Does NOT begin KYC verification. Creates a Sila wallet for the user_handle if you are using ECDSA authentication. If you are using JWT authentication, make sure to create a Sila wallet.

NOTE: Prior to beginning KYC verification in the next step with /request_kyc, end users can update their information with /update.

/kyc

Kicks off KYC verification for a specific user_handle. Note this cannot be called until you have created a KYC Flow in the console.

/get_verifications/<verification_uuid> or /get_verifications

Return the verification status of a single KYC application with /get_verifications/<verification_uuid> or a full list of all verification records for a specific user_handle with /get_verifications.

📘

Do not poll /get_verifications or /get_verifications/<verification_uuid>

Just like how we advise against polling /check_kyc and using webhooks instead, please use our webooks instead of polling these endpoints.

Sila reserves the right to impose rate limits if deemed necessary.

🚧

Important! When end user doesn't pass KYC

If your end user receives a status of documents_required, you have five total tries to get the user to pass:

  1. The first try will always be to update end user PII using /update. Once updated, use /resume_verification to restart the verification process.
  2. If the end user still doesn't pass, the next try will be to upload a doc. Once uploaded, use /resume_verification to restart the verification process.
  3. You are given three more tries to upload that same doc - you cannot upload a different doc, so be sure the one that is uploaded is the correct one. Continue to use /resume_verification to restart the verification process.

Which action to take - PII update or doc upload - will be indicated in an action_needed field in the kyc_action webhook or the response to /get_verifications/<verification_uuid>. Values are either entity_data, doc_upload, or review. Note that review indicates no action needs to be taken as the verification is under manual review by Sila.

/resume_verification

If an end user fails verification, use this endpoint to restart the verification process after PII has been updated or after uploading a doc to /documents.

/documents

Upload end user documentation to this endpoint if necessary to verify their identity. Only one doc can be uploaded, so be sure to upload the correct one on the first try. Options are: driver's license, state ID, or passport.

🚧

KYB Doc Upload

Docs for business entities must be manually reviewed, and verification cannot be automatically resumed. Documents uploaded through /documents for business entities will be reviewed by our Banking Ops team. They will either ask for additional documentation if the first was insufficient, approve, or deny the verification record.

Webhooks

New kyc_status

  • Fires on the transition between pass/fail. Rely on kyc_action for all updates in between.
  • Not applicable to Classic KYC system.

New kyc_action

  • Fires on documents_required updates or review. Rely on kyc_status for pass/fail update.
  • Not applicable to Classic KYC system.

Testing

The triggers for Classic KYC do not apply. Please see the Advanced KYC Testing doc for the new triggers.

KYB

See our KYB docs for more.

  • There are no new endpoints if you are switching from Classic to Advanced, but business members are now required to be linked prior to calling /kyc on the business entity. This will run verifications on all the business members, and the business.
  • If there is a change in business members and you need to add a new one, you can link that member before or after they have passed KYC, but you should run KYC on just that individual entity rather than re-running the business through KYB.
    • In this scenario, if you are linking a new member that has not yet passed KYC, /link_business_member will kick off the verification process - no need to call /kyc. The verification_uuid will be returned in the /link_business_member response.
  • Docs for business entities must be manually reviewed, and verification cannot be automatically resumed. Documents uploaded through /documents for business entities will be reviewed by our Banking Ops team. They will either ask for additional documentation if the first was insufficient, approve, or deny the verification record.

Basic KYB Order

  1. Register business entity and all individual entities to be linked to the business as business members.
  2. Link individual entities to the business entity with /link_business_member.
  3. Run /kyc on the business entity - this will also run KYC on the individual entities.
  4. Once all entities have passed KYC, certify beneficial owners and business if necessary with /certify_beneficial_owner and /certify_business.

Console Setup Requirements

With Advanced KYC, you will create your own KYC Flows in the Console to be submitted to our Compliance team for approval. You are required to have one for KYC, but if you use KYB you will need two Flows - one for KYC and one for KYB.

Creating a New KYC Flow

  1. Navigate to the Applications tab

  2. Find the app you want to create a KYC Flow for and click the KYC Flow tab

  3. Click Add New

  4. After clicking Add New, fill out the information and choose KYC options for your new Flow

    1. Name: Required. Give your KYC Flow a name

    2. Version: Pre-populated. Once your Flow has been approved, you have the option to create a new version of the Flow with different options.

    3. Pre-Defined Option Set: Required. Choose between KYC, KYB with EIN, and KYB without EIN. This automatically selects a group of options.

  5. Once you've chosen a Pre-Defined Option Set, the Options section will appear. The pre-defined options are already selected, greyed out. These cannot be removed. Additional options can be added here if desired.

  6. Save your KYC Flow

    1. NOTE: After you save your KYC Flow, you will see the Flow UUID populated.

Editing an Existing KYC Flow

🚧

When editing is allowed

Editing is only allowed before you submit a KYC Flow to our Compliance team for approval. Once submitted, editing is no longer allowed.

The only exception is when a Flow is denied by the Compliance team - the status will change to Denied and you can make edits, then resubmit for approval.

Once you have an existing Flow populating the list at the bottom of the KYC Flows tab, click "View Details" (far right) then "Edit"

Submitting a KYC Flow for Approval

Once you have an existing Flow populating the list at the bottom of the KYC Flows tab and you are ready for Sila's Compliance team to review it, click "Submit for Approval" (far right). The status will change to Pending Approval, and no further edits can be made to this Flow.

📘

Sandbox Approval

In the Sandbox environment ONLY, approval is automatically granted once you click "Submit for Approval"

Creating a New Version

If you need to make changes to a KYC Flow after it's been approved, you can create a new version.

  1. Click "View Details," then "Add New Version"

  2. You CANNOT edit the Name or the Flow UUID. You CAN change the Pre-Defined Option Set and the Options.

  3. Once your changes have been made, click "Save" and this will add a new In Process Flow to the list, with a different Flow UUID. Make further edits as needed, then submit for approval.

Switching from Classic KYC to Advanced KYC

Start with this section of this implementation guide if you are switching from Classic to Advanced KYC to review endpoint changes, then continue through the rest of the full guide.

👍

If you do NOT have Classic built out, jump to this section.

Code Changes

Note that the below is an overview of changes to make. Please see the linked endpoint docs for more specifics on requirements, requests, and responses.

Existing Endpoints

/documents

  • New required verification_uuid field in request. The ID of the verification record the document is for must be provided.
  • New provider field in the request. Optional. Default is ALLOY (only valid option, currently).
  • New is_front field in the request. This is a boolean to designate the front and back of the document being uploaded. Default is true, so only required to set to false for the back of documents.
  • NOTE: You will only need to upload a single document for the Advanced KYC system. There will no longer be any need to upload multiple documents for a single review. The options are: driver's license, state ID, or passport.

🚧

KYB Doc Upload

Doc upload is not supported for business entities. Additional verification will be done manually by the Sila BankOps team.

New Endpoints

/kyc

  • The endpoint you'll use to kick off the KYC verification process after registering a new end user instead of /request_kyc.

/get_verifications/<verification_uuid>

  • Supply a verification UUID to return the full verification record. Use instead of /check_kyc.

/get_verifications

  • Returns the full list of verification records for a single user_handle. Use instead of /check_kyc.

📘

Do not poll /get_verifications or /get_verifications/<verification_uuid>

Just like how we advise against polling /check_kyc and using webhooks instead, please use our webooks instead of polling these endpoints.

Sila reserves the right to impose rate limits if deemed necessary.

/resume_verification

  • Resumes the verification process after updating end user PII or uploading a document.

Endpoints No Longer Needed

/request_kyc

  • Use /kyc.

/check_kyc

  • Use /get_verifications/<verification_uuid> or /get_verifications instead.

Webhooks

  • The KYC Status Event webhook will not fire with Advanced KYC. Please see the webhooks section below.

Updated 2 months ago