Additional Steps

Requirements:

API key pair
Additional step credits
Additional step session creation via API enabled (configured by iDenfy staff)
Additional step type set in your environment (configured by iDenfy staff)

Limitations:

The Utility Bill document selection step does not validate the user’s choice against the upload — it only guides them on expected document types.
The Utility Bill document selection step is shown only when the step name is UTILITY_BILL. To skip it, use any different step name.
Contact iDenfy to change custom additional step texts (name and description).

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 system saves the document with the verification.
No automated checks or manual review are triggered.
No data is extracted or returned.

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 API returns the comparison result.

Possible comparison results (in additionalData.status):

MATCH
NOT_MATCH
NOT_FOUND
NO_DATA

These are also included in the webhook callback.

EXTRACT Processing Type

Use this when you need to extract address or data from the document but do not want to compare it to anything. When to use:

You want to read and extract data (e.g., address) from the document.
You do not 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 the verification UI and the webhook callback.

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

Session Creation Request

To create a session with a utility bill step, you do not need to pass anything extra. The custom additional step is included by default if configured in your environment settings.

Minimal Request

{
  "clientId": "123"
}

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

Request with Address Data

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

How provided data affects verification:

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": {
    "UTILITY_BILL": {
      "address": "1234, Drive/Street, City/State, postcode, etc."
    }
  }
}

The step name UTILITY_BILL in additionalData must match the step name configured in your environment’s Custom Additional Step settings.

Response

The response structure is identical to the minimal request response above, with these key differences:

"type" is set to "EXTRACT" (or whichever processing type you configured) instead of "UPLOAD"
"fields" contains the fields you requested (e.g., ["address"])
An "additionalData" object is included, echoing the address data you provided

Upload or Re-Upload for Existing Verification

POST https://ivs.idenfy.com/api/v2/upload-additional-step
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

You can allow users to update or re-submit documents for custom additional steps after their initial verification attempt. This 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.

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

Verification Without Custom Additional Step

If a custom additional step is pre-configured on iDenfy’s side but you need to create some tokens without it, pass an empty object for the step:

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

Multiple Custom Additional Steps

If multiple custom additional steps are configured at the environment level, token creation includes all of them by default. To use only a specific step, specify it explicitly. For example, if UTILITY_BILL and ADDITIONAL_DOCUMENT are configured and you want only the latter:

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

Customization Options

The default UTILITY_BILL step always includes a selection step from the user’s perspective. This step is configurable on the partner environment level (if permissions are granted). Find it at Settings > Configuration > Customisation > Allowed POA Documents or contact iDenfy’s tech support team to edit it.

Possible POA document types

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

Managing Custom Additional Steps Per Request

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.

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 creating the verification session.

If you use different types of additional steps, you must have sufficient credits for each type.

Request Example

{
  "clientId": "1",
  "additionalSteps": {
    "ALL": {
      "ALL": {
        "UTILITY_BILL": {
          "type": "COMPARE",
          "texts": {
            "en": {
              "name": "YOUR_PROVIDED_NAME_FOR_SECTION",
              "description": "YOUR_EXPLANATION_OF_THE_SECTION"
            }
          },
          "fields": ["address"],
          "settings": {
            "canUpload": false,
            "canCapture": true,
            "canUploadPDF": false
          }
        }
      }
    }
  }
}

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Fraud Prevention

Bank Verification

Going Live

Reference

Generating Token with Additional Step

UPLOAD Processing Type

COMPARE Processing Type

EXTRACT Processing Type

Session Creation Request

Minimal Request

Response Example

Request with Address Data

Request Example

Response

Upload or Re-Upload for Existing Verification

Request Example

Additional Configurations

Verification Without Custom Additional Step

Multiple Custom Additional Steps

Customization Options

Managing Custom Additional Steps Per Request

Request Example

​Generating Token with Additional Step

​UPLOAD Processing Type

​COMPARE Processing Type

​EXTRACT Processing Type

​Session Creation Request

​Minimal Request

​Response Example

​Request with Address Data

​Request Example

​Response

​Upload or Re-Upload for Existing Verification

​Request Example

​Additional Configurations

​Verification Without Custom Additional Step

​Multiple Custom Additional Steps

​Customization Options

​Managing Custom Additional Steps Per Request

​Request Example

Generating Token with Additional Step

UPLOAD Processing Type

COMPARE Processing Type

EXTRACT Processing Type

Session Creation Request

Minimal Request

Response Example

Request with Address Data

Request Example

Response

Upload or Re-Upload for Existing Verification

Request Example

Additional Configurations

Verification Without Custom Additional Step

Multiple Custom Additional Steps

Customization Options

Managing Custom Additional Steps Per Request

Request Example