API ReferenceChangelogFAQDashboard

Sample verification flow

❗️

Important

Contact us in advance before using this type of integration. The verification flow can be difficult to implement since it may have lots of tricky cases that our WebSDK handles for you.

Also, we may decide to charge additionally for support when you chose this type of integration. The pricing model may change to charge per transaction, not per user.

The following scenario provides a verification flow example to help you understand the overall process and how you can handle common verification procedures:

  1. Generate an app token to start working with the Sumsub API.
  2. Create an applicant.
    1. Set up the steps that your applicants must go through to complete verification by creating a verification level. For more information about the supported types of documents, see this article.
    2. Provide as much information about your applicants as you have, e.g. email, phone, etc. — it helps us with our anti-fraud checks.
  3. Upload documents.
    1. Make sure to upload all the documents that you require. If a document is double-sided, submit two images and set the idDocSubType properly (FRONT_SIDE and BACK_SIDE). Make sure to send BACK_SIDE if FRONT_SIDE was already sent; otherwise, the verification step will not be completed, and you will not be able to initiate the check.
    2. If you have changed the list of restricted countries, we suggest rewriting it for applicants created before the change with this method.
  4. Request a check. Once all required documents are uploaded, you must let us know that the applicant is ready to be reviewed by moving them to the Pending status. if you do not submit documents correctly, the applicant will be rejected (or will not be checked at all). Make sure to check all the cases on your side to avoid having incomplete applicants.
  5. Set up webhooks and get verification results. The results are delivered by the applicantReviewed webhook that contains the reviewResult object that includes the reviewAnswer field indicating the verification status:
    1. If you received a GREEN response, all is fine; the applicant has been verified. If needed, you can also fetch the applicant data in a separate API call.
    2. If you got a RED response and rejectType is FINAL, block the applicant and let them resolve the issue via support. There are only 1-2% of such cases, and it can happen when, for example, there is a fake account or forged documents were used.
    3. If you got a RED response and rejectType is RETRY, the applicant has some issues with their documents that can potentially be solved. Refer to Resubmit problematic documents to learn how to fix them.

Resubmit problematic documents

There is no need to ask the applicant to resubmit all the documents all over again after receiving a RED response with rejectType set to RETRY; only those that have issues:

  1. Read the problematic images using this method and show the message from the moderationComment field to inform the applicant about the problem. For example: "The text on your identity document is not clearly visible. Upload a new photo".
  2. Re-upload documents from the problematic step to the same applicant, move the applicant to the Pending status, and wait for verification results.

👍

Consider the following for successful verification:

  • If you send the applicant data to us and want it to be cross-checked with the data recognized from the documents, make sure that you allow the applicant to fix the data on your side. We will send you a PROBLEMATIC_APPLICANT_DATA reject label in this case.
  • If you do not have any complex rules for documents, we recommend to send just one image for passports, and two sides for ID cards, driving licenses, and residence permits.
  • For selfies, make sure that the applicant is aware that the ID document should be uploaded with a selfie and be clearly readable.
  • Verifications statuses are handled correctly:
    • FINAL reject does not allow applicants to submit new documents. Each applicant is notified about that.
    • You should be able to react on status change. For example, we approved an applicant, but a week later, they appeared on the blocklist. We will send a RED result in this case to your webhook endpoint, and you should react on the status change accordingly.