Skip to main content

Additional steps

Using this functionality will let you add additional steps for your users to complete in the verification process. These steps could include utility bill upload or an extra photo of your client. The text can be fully customizable.

All custom additional steps should be set in advance from iDenfy side of the application - both settings and finances should be in place so that new tokens would be created successfully.

note

To make this functionality available, please contact sales@idenfy.com if your contract does not include additional steps. For technical questions please contact our support team using dashboard.

Utility bill - default custom additional step​

A default custom additional step with UTILITY_BILL name and UPLOAD type/method is being taken into account, if your environment has sufficient/available credits and UTILITY_BILL is set at your environment settings from iDenfy's side.

Sending a request for utility bill​

To generate a token with utility bill step, there's no need to pass anything, since custom additional step will be taken into account by default, if it is set at your environment settings.

Standard request with provided mandatory key/value pair:

{
  "clientId": "123"
}
note

Any custom additional step texts (name & description) could be changed by request, from iDenfy's side of the application.

Additional options​

Additional step upload or re-upload for existing verification​

If a user uploaded an invalid additional step, for example, a utility bill that is older than 3 months, there is a possibility to reupload the file without the need of undergoing the verification process again.

If a user should upload a new document after verification is completed. This additional step should be set on the account and can be used.

These two cases can be done by sending an HTTP request to this endpoint https://ivs.idenfy.com/api/v2/upload-additional-step

The request must contain basic auth headers where username is API key and password is API secret. Please note that any data from the previous verification will be overridden by the new request.

Example request:​

{
  "scanRef": "3f2d0e6a-0a37-11ec-a45b-025ad99a18e7",
  "image": "{{Base64 image}}",
  "step": "UTILITY_BILL",
  "additionalData": {}
}
note

Requests sent to the https://ivs.idenfy.com/api/v2/upload-additional-step endpoint will only work if a custom additional step exists in your account settings.

KYC verification without custom additional step​

If a custom additional step is pre-configured on iDenfy's side but there is a need to create some KYC tokens without it, it is possible to pass:

   "additionalSteps": {
        "ALL": {
            "ALL": {}
        }
    }

alongside other mandatory key/value pairs so that new KYC token would be created without any custom additional steps.

Multiple custom additional steps​

If multiple custom additional steps are configured at the environment level, new KYC token creation will include all of them by default. To use only a specific step, you can specify it explicitly.

For example, if UTILITY_BILL and ADDITIONAL_DOCUMENT are set at the environment level, and you want to create a new KYC token with only the latter, pass:

    "additionalSteps": {
        "ALL": {
            "ALL": ["ADDITIONAL_DOCUMENT"]
        }
    }

Customisation options​

Default UTILITY_BILL step always include selection step (from user perspective). This step is configurable on partner environment level (if permissions granted) , it could be found on Settings -> Configuration -> Customisation -> Allowed POA Documents or edited by iDenfy's techsupport team.

Custom Additional Step Selection

Utility Bill Selection

Custom Additional Step Upload

Utility Bill Upload

Toggle to open list of possible values
  • Bank Statement
  • Electricity Bill
  • Water Bill
  • Credit Card Bill or Statement
  • Gas Bill
  • Telephone Bill
  • Bank Reference Letter
  • Internet Bill
  • Mortgage Statement or Contract
  • Company Payslip
  • Car or Home Insurance Policy
  • Municipality Bill or Government Tax Letter
  • Driver's License
  • Residence Permit
  • Official Letter from an Educational Institution
  • Lease Agreement for Your Residence
  • Letter of Employment
  • Authorized Change of Address Form
  • Car Registration
  • Other
  • Letter Issued by a Public Authority
warning

Utility Bill Selection step is not being validated - user can select one type but actually upload another - this list is dedicated for reference of what files are expected to be provided/uploaded. Requirements for valid files are mentioned in the note Utility bill with EXTRACT/COMPARE type

Utility Bill Selection step will be shown only with custom additional step UTILITY_BILL, to skip it, any different step name should be set & used.

Value explanation​

  • The first ALL value refers to country selection in alpha2 format. If you include specific countries in this value, the additional steps will only be added to these countries. ALL is used to include all countries.

  • The second ALL value refers to document type used for that additional step. Supported values: ID_CARD, PASSPORT, RESIDENCE_PERMIT, DRIVER_LICENSE, PAN_CARD, AADHAAR, OTHER. ALL is used to include all supported documents in your environment.

  • ADDITIONAL_PHOTO this is a variable that can be changed according to the step you're going to use.

  • type There can be 3 different types/methods and only 1 type/method can be enabled in your environment, depending on your contract:

  • UPLOAD - This type only allows the upload of the file. The file will not be processed or evaluated, either by automatic check or by our manual review team.

  • COMPARE - this type allows manual review team to compare the data that was provided with additionalData key during token generation with the data visible in the client's uploaded file. After the comparison, the possible values are: MATCH, NOT_MATCH, NOT_FOUND, NO_DATA. These statuses will be included in the webhook callback additionalData key.

  • EXTRACT - this type allows our manual review team to type in the information from the document that user uploaded/captured. That information will be visible in the verification pop-up or webhook callback. Values from additionalData -> status shouldn't be evaluated, since manual review team only extracts the address/data but not comparing.

  • fields name of the field in the additionalData

  • texts support multiple locales that you can use for your name and description. Supported values are - lt, en, ru, pl, lv, et, ro, it, de, fr, sv, es, hu, ja, bg, cs, nl, pt, uk, vi, sk, th, hi, id

  • Both name and description can be changed by your own text for each language.

  • The settings canUpload,canCapture,canUploadPDF only accepts boolean true or false.

  • canUpload setting will allow/disallow user to upload the photo from their device.

  • canCapture setting will allow/disallow user to capture the photo in their verification window.

  • canUploadPDF setting will allow/disallow user to upload the file in PDF format.

After generating a token using the example above, your user will see additional step window with the text we indicated.

Additional Steps

note

Our tech support team can add these additional steps to your environment's settings so these steps will have to be done by all users that go through verification process without the need to include them in the request each time. Please contact our support team via dashboard and we'll gladly assist.

Managing custom additional steps with each request individually​

danger

Use this option only if it is not possible to manage custom additional steps through the instructions provided above. We recommend setting up custom additional steps on our side and only overriding or providing additionalSteps with each request when no other solution is available.

In case you find need to control and pass custom additional steps object with each request individually and control everything regarding them with each request, check examples below.

Worth mentioning that your environment still must be eligible for the changes, e.g.:

  • sufficient credits must be present in case different custom additional step method/type is used;
  • sufficient credits must be present in case different custom additional step name is used;

Sending request for custom additional steps​

To generate a token with a custom additional step, add additionalSteps with a valid JSON to your request and send a HTTP POST request to: https://ivs.idenfy.com/api/v2/token

note

Use token additional steps setting and sufficient finances should be set in order to use this functionality. For example, if you'd like to change type/method with each request individually, both methods/types of that particular step name, should have sufficient credits.

The request must contain basic auth headers where username is API key and password is API secret.

{
  "clientId": "1",
  "additionalSteps": {
    "ALL": {
      "ALL": {
        "UTILITY_BILL": {
          "type": "COMPARE", // option to change method/type of custom additional step
          // option to add translations for different locales on each request individually
          "texts": {
            "de": {
              "name": "Bitte laden Sie einen Adressnachweis hoch",
              "description": "Bitte achten Sie darauf, dass der Adressnachweis vollständig sichtbar und nicht älter als 3 Monate ist. Alle Informationen müssen deutlich sichtbar sein, einschließlich Ihres vollständigen Namens, Ihrer Adresse und des Datums des Dokuments, und das Dokument muss eine gültige Stromrechnung sein, ein Kontoauszug, da handschriftliche Papiere nicht akzeptiert werden. Außerdem muss die Stromrechnung im lateinischen Alphabet sein. Ausweisdokumente werden nicht als gültiger Adressnachweis akzeptiert."
            }
          },
          "fields": ["address"],
          // option to change settings that are being passed
          "settings": {
            "canUpload": false,
            "canCapture": true,
            "canUploadPDF": false
          }
        }
      }
    }
  }
}