Skip to main content
Requirements:
  • API key pair
  • Additional step credits
  • Additional step token generation 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.
  • Custom additional step texts (name and description) can be changed by request from iDenfy’s side.

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

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

​
Token generation request

To generate a token with a utility bill step, there is no need to pass anything extra since the custom additional step is taken into account by default if it is set 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 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
}

​
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 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",
          "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."
            }
          },
          "fields": ["address"],
          "settings": {
            "canUpload": true,
            "canCapture": false,
            "canUploadPDF": true
          }
        }
      }
    }
  },
  "additionalData": {
    "UTILITY_BILL": {
      "address": "1234, Drive/Street, City/State, postcode, etc."
    }
  },
  "externalRef": null,
  "digitString": null
}

​
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). It can be found at Settings > Configuration > Customisation > Allowed POA Documents or edited by iDenfy’s tech support team.
  • 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 generating the verification token.
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
          }
        }
      }
    }
  }
}