API Reference
API ReferenceChangelogFAQDashboard

Submit applicant data for Non-Doc Verification

post https://api.sumsub.com/resources/applicants//ekyc/submit

Overview

Use this method to initiate a Non-Doc Verification based on the provided applicant data.

Request example

The following are request examples sorted by the Alpha-3 country code.

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "ARG",
         "idDocType": "ID_CARD",
         "number": <dni>,
         "gender": <M/F>
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "BGD", 
         "idDocType": "ID_CARD", 
         "number": <National ID>,
         "dob": <YYYY-MM-DD>
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "info": {
         "country": "BRA", 
         "tin": <cpf>
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "GBR", 
         "idDocType": "OTHER"
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "info": {
         "country": "IDN",
         "tin": <NIK>,
         "firstName": <Full name>,
      }
   }'

// Verification basis: AADHAAR
curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "IND", 
         "idDocType": "ID_CARD", 
         "number": <AADHAAR>
      }
   }'

// Verification basis: Digilocker
curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "IND", 
         "idDocType": "OTHER"
      }
   }'

// Verification basis: NID
curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "KEN", 
         "idDocType": "ID_CARD", 
         "number": <National ID>
      }
   }'
  
// Verification basis: Passport
curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "KEN", 
         "idDocType": "PASSPORT" 
         "number": <Passport number>
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "MEX",
         "idDocType": "ID_CARD",
         "number": <CURP>
      }
   }'

// Verification basis: BVN
curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "info": {
         "country": "NGA", 
         "tin": <bvn>
      }
   }'
  
// Verification basis: NIN
curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "NGA", 
         "idDocType": "ID_CARD", 
         "number": <NIN>
      }
   }'

// Verification basis: Driver’s License
curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "NGA", 
         "idDocType": "DRIVERS" 
         "number": <Driver License number>
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "NLD",
         "idDocType": "OTHER",
         "firstName": "John",
         "lastName": "Doe"
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "VNM", 
         "idDocType": "DRIVERS" 
         "number": <Driver License number>,
         "dob": <YYYY-MM-DD>
      }
   }'

curl -X POST \
  'https://api.sumsub.com/resources/applicants/631f268442d8290001e1eee9/ekyc/submit' \
  -H 'Content-Type: application/json' \
  -d '{
      "idDoc": {
         "country": "ZAF", 
         "idDocType": "ID_CARD" 
         "number": <National ID>
      }
   }'

Response explained

The following table describes the response structure.

NameTypeOptionalDescription
statusStringNoVerification status:
  • completed — submission completed.
  • skipped — submission skipped.
  • confirmationRequired — submission needs approval. See confirmationType.
  • rejected — submission rejected.
confirmationTypeStringYesConfirmation type:
  • otp — Submission should be confirmed via OTP code.
  • oAuth — Applicant should be directed to the external service to proceed with submission.
confirmationIdStringYesConfirmation ID.
confirmationStatusStringYesConfirmation flow status.
otpConfirmationObjectYesOTP confirmation details if confirmationType is otp.
oauthConfirmationObjectYesoAuth confirmation details if confirmationType is oAuth.

📘

Note

Access to the applicant data from some providers needs to be confirmed by the applicant. In that case, status will be set to confirmationRequired and confirmationStatus to created. The confirmation type will be provided in the confirmationType field. For details on how to confirm submission, see this article.

For example, for an Indian AADHAAR, the applicant receives an SMS with the OTP code on the phone number that is linked to that particular AADHAAR. The applicant should then provide the code to confirm access.

otpConfirmation attributes

NameTypeDescription
codeLengthNumberThe OTP code length.

oAuthConfirmation attributes

NameTypeDescription
urlStringAn external auth URL where applicant should be directed to pass authentication.
redirectUrlStringThe final URL address where the auth page will be redirected after the applicant finishes the journey.

📘

Mind the following:

  • Applicants should be redirected to the url where they can authenticate the external source. At the end of the auth journey, applicants will be redirected to the completeUrl consisting of redirectUrl enriched with queryParams with the auth result.
  • If url was opened in the child window, postMessage: {type: "ekycOauth", completeUrl: "<completeUrl>"} will be sent.
  • Several redirects can be performed during the auth flow. To detect the completion of the journey, redirect to the redirectUrl or subscribe to postMessages.
  • To complete the Non-Doc oAuth flow, pass the final full url as completeUrl to confirm the applicant data.

Response examples

Provided data is valid and no confirmation is required

{
  "status" : "completed"
}

Provided data is valid and OTP confirmation is required

{
    "status": "confirmationRequired",
    "confirmationId": "bzaPxnCpyxEqs0sJKASXxZIk",
    "confirmationStatus": "created",
    "confirmationType": "otp",
    "otpConfirmation": {
        "codeLength": "6",
    }
}

Provided data is valid and authentication through external services is required

{
  "status" : "confirmationRequired",
  "confirmationType" : "oAuth",
  "confirmationId" : "wXhl47RZeJfoOSTmUFT9j5On",
  "confirmationStatus" : "created",
  "oauthConfirmation" : {
    "url" : "https://ext.auth.service.com/oidc/authorize?param1=value1&param2=value2",
    "redirectUrl" : "https://api.sumsub.com/resources/ekyc/redirect"
  }
}
Language
Credentials
Header
Click Try It! to start a request and see the response here!