Skip to main content

KYC Additional steps

Requirements
  • API key
  • Additional step credits
  • Additional step token generation via API enabled (done by iDenfy's staff)
  • Additional step type set in your environment (done by iDenfy's staff)
Image alt text

Customize your Address Verification to enhance user experience

  • A special note or secret phrase
  • Customer’s face while holding their ID document
  • Document of the vehicle
  • Vehicle's license plate numbe
  • Ownership of an item
Read more
Limitations
  • Utility Bill document selection step doesn't validate the user's choice against the upload; it only guides them on expected document types.
  • Utility Bill document selection step will be shown only when step's name is UTILITY_BILL, to skip it, any different step name should be set & used.
  • Any custom additional step texts (name & description) could be changed by request, from iDenfy's side of the application.

Generating token with Additional step​

UPLOAD Processing Type

Use this when you simply want to store the document file as part of the verification — without extracting or validating its contents.

When to use:

  • You only need to attach the document to the verification record.
  • No analysis, extraction, or validation is required.

What happens:

  • The document is saved with the verification.
  • No automated checks or manual review are triggered.
  • No data is extracted or returned.

Request​

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.

{
  "clientId": "123"
}

additionalSteps object value explanation:​

ALL (country selection)
Explanation:

Refers to including ALL countries. If specific countries are listed using their alpha2 codes, the additional steps apply only to those countries.

ALL (document type)
Explanation:

Includes ALL supported document types. If specific document types are listed, the additional steps apply only to those types. Values include: ID_CARD, PASSPORT, RESIDENCE_PERMIT, DRIVER_LICENSE, PAN_CARD, AADHAAR, etc.

fields
Explanation:

Defines the name of the field in the additionalData.

texts
Explanation:

Supported locales

canUpload
Explanation:

Boolean setting (true/false) to allow or disallow users from uploading a photo from their device.

canCapture
Explanation:

Boolean setting (true/false) to allow or disallow users from capturing a photo using their device's camera.

canUploadPDF
Explanation:

Boolean setting (true/false) to allow or disallow users from uploading a document in PDF format.

Response example​

{
  "message": "Token created successfully",
  "authToken": "cBqwefLQK6jEA20CJnq12r01cge00mlvPrjTGM4",
  "scanRef": "6a31253e-e10a-11eb-cc95-02cb49d118ed",
  "clientId": "2",
  "personScanRef": "2",
  "firstName": null,
  "lastName": null,
  "successUrl": null,
  "errorUrl": null,
  "unverifiedUrl": null,
  "callbackUrl": null,
  "locale": null,
  "country": null,
  "expiryTime": 3600,
  "sessionLength": 600,
  "documents": ["ID_CARD", "PASSPORT", "DRIVER_LICENSE", "RESIDENCE_PERMIT"],
  "dateOfBirth": null,
  "dateOfExpiry": null,
  "dateOfIssue": null,
  "nationality": null,
  "personalNumber": null,
  "documentNumber": null,
  "sex": null,
  "address": null,
  "showInstructions": true,
  "tokenType": "IDENTIFICATION",
  "utilityBill": true,
  "additionalSteps": {
    "ALL": {
      "ALL": {
        "UTILITY_BILL": {
          "type": "UPLOAD",
          "texts": {
            "en": {
              "name": "Please upload a proof of address document",
              "description": "Please make sure that the proof of address document is fully visible and is not older than 3 months. All information must be clearly visible including your full name, address, date of the document, and the document must be a legitimate utility bill or a bank statement, as handwritten papers are not accepted. Also, the utility bill must be in Latin alphabet. ID documents are not accepted as valid proof of address."
            },
            "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."
            },
            "es": {
              "name": "Cargue un comprobante de domicilio",
              "description": "Asegúrese de que el comprobante de domicilio esté completamente visible y no tenga más de 3 meses. Toda la información debe ser claramente visible, incluido su nombre completo, dirección, fecha del documento, y el documento debe ser una factura de servicios públicos legítima, un extracto bancario, no se aceptan documentos escritos a mano no se aceptan. También, la factura de servicios públicos debe estar en alfabeto latino. Los documentos de identidad no se aceptan como prueba válida de domicilio."
            }
          },
          "fields": [],
          "settings": {
            "canUpload": true,
            "canCapture": true,
            "canUploadPDF": true
          }
        }
      }
    }
  },
  "externalRef": null,
  "digitString": null
}
COMPARE Processing Type

Use this when you need to both extract data and compare it against values you provide.

When to use:

  • You want to verify if the data in the document matches what you supplied during token creation.
  • Example: Match the address on the document with additionalData sent during verification start.

What happens:

  • The system extracts data from the document.
  • That data is compared with the values you provided via the additionalData key.
  • The result of the comparison is returned.

Possible comparison results (in additionalData.status):

  • MATCH
  • NOT_MATCH
  • NOT_FOUND
  • NO_DATA

These will also be included in the webhook callback.

EXTRACT Processing Type

Use this when you need to extract address or data from the document — but don’t want to compare it to anything.

When to use:

  • You want to read and extract data (e.g., address) from the document.
  • You don’t need to validate it against pre-supplied data.

What happens:

  • The system (AI or manual team) reads and extracts data from the document.
  • The extracted data is available in:

Important:

  • Do not rely on the additionalData.status field for this type.
  • Since no matching is performed, the status field is not applicable.
  • Focus only on the raw extracted data.

Request structure​

You can optionally include the expected user address details within the additionalData object when generating an identification token.

How Provided Data Affects Verification

Submitting address data impacts the process based on the step's method:

  • COMPARE Steps: If you provide the address in additionalData, it will be automatically cross-referenced against the submitted document. Without it, this comparison is skipped.
  • EXTRACT Steps: Providing the address serves as helpful reference information for manual review, potentially improving efficiency.
Document Requirements for Address Proof

When users submit proof of address documents (like utility bills), they must adhere to these standards:

  • Age: No older than 3 months.
  • Clarity: All text clear and unobstructed.
  • Format: Official documents only (no handwritten notes), using Latin characters.

Request example​

{
  "clientId": "123",
  "additionalData": {
    // step name UTILITY_BILL must match w/ step name set at env. Custom Additional Step settings
    "UTILITY_BILL": {
      // address that is provided for comparison (COMPARE type) or easier extraction (EXTRACT type);
      "address": "1234, Drive/Street, City/State, postcode, etc."
    }
  }
}

Response example​

{
  "message": "Token created successfully",
  "authToken": "57K5hu3HSTOLCg4UFNpdwZqsC8tDG0PLnvgcY4sC",
  "scanRef": "10bb0ade-4784-11ec-a167-02476f3f1509",
  "clientId": "123",
  "personScanRef": "123",
  "firstName": null,
  "lastName": null,
  "successUrl": null,
  "errorUrl": null,
  "unverifiedUrl": null,
  "callbackUrl": null,
  "locale": "en",
  "country": null,
  "expiryTime": 3600,
  "sessionLength": 600,
  "documents": ["ID_CARD", "PASSPORT", "DRIVER_LICENSE", "RESIDENCE_PERMIT"],
  "dateOfBirth": null,
  "dateOfExpiry": null,
  "dateOfIssue": null,
  "nationality": null,
  "personalNumber": null,
  "documentNumber": null,
  "sex": null,
  "address": null,
  "showInstructions": true,
  "tokenType": "IDENTIFICATION",
  "utilityBill": null,
  "additionalSteps": {
    "ALL": {
      "ALL": {
        "UTILITY_BILL": {
          "type": "EXTRACT", // are set at your partner environment settings;
          "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."
            },
            "en": {
              "name": "Please upload a proof of address document",
              "description": "Please make sure that the proof of address document is fully visible and is not older than 3 months. All information must be clearly visible including your full name, address, date of the document, and the document must be a legitimate utility bill or a bank statement, as handwritten papers are not accepted. Also, the utility bill must be in Latin alphabet. ID documents are not accepted as valid proof of address."
            } // all available and/or set translation locales should be returned;
          },
          "fields": ["address"],
          "settings": {
            // could be changed at environment level by request;
            "canUpload": true,
            "canCapture": false,
            "canUploadPDF": true
          }
        }
      }
    }
  },
  "additionalData": {
    "UTILITY_BILL": {
      "address": "1234, Drive/Street, City/State, postcode, etc."
    }
  },
  "externalRef": null,
  "digitString": null
}

Additional step upload or re-upload for existing verification​

Upload additional step

Authorization: API key pair
Method: POST
Endpoint: https://ivs.idenfy.com/api/v2/upload-additional-step

You can allow users to update or re-submit documents for custom additional steps after their initial verification attempt. This functionality addresses scenarios such as:

  • Correcting a previously uploaded document that was deemed invalid (e.g., a utility bill older than three months).
  • Providing a required additional document after the main identity verification flow has been completed.
warning

When a new document is submitted this way, it overrides any data previously uploaded for that specific additional step during the earlier verification attempt.

Request example​

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

Additional configurations​

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: alongside other mandatory key/value pairs so that new KYC token would be created without any custom additional steps.

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

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

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
Custom Additional Step Selection

Utility Bill Selection

Custom Additional Step Upload

Utility Bill Upload

Managing custom additional steps with each request individually​

Recommended Approach: Server-Side Configuration

Controlling custom additional steps by sending specific instructions with each API request is not the standard method and should only be used as a fallback.

We strongly recommend configuring your custom additional steps within your iDenfy account settings whenever possible. Only use the per-request control described below if the standard configuration approach doesn't meet your specific needs.

Controlling Additional Steps via API Request If necessary, you can define or override the behavior of custom additional steps for individual verification requests. This is done by including a specifically structured additionalSteps object when generating the verification token

Finances

If you will be using types of additional steps, you have to have sufficient credits for each type.

Request example​

{
  "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": {
            "en": {
              "name": "YOUR_PROVIDED_NAME_FOR_SECTION",
              "description": "YOUR_EXPLANATION_OF_THE_SECTION"
            }
          },
          "fields": ["address"],
          // option to change settings that are being passed
          "settings": {
            "canUpload": false,
            "canCapture": true,
            "canUploadPDF": false
          }
        }
      }
    }
  }
}