Skip to main content

Verifying proof of address - API only (v1)

Stable / GA

This is the current stable version of this step type.

Headless address document verification that extracts residential address data​

Verifies an address document using static evidence collected by your own front end and submitted to IDnow via API, with results delivered as a ResidentialAddress data block.

In Headless mode, your application is responsible for collecting and providing the document image. IDnow verifies the submitted document automatically and extracts the address data from it. There is no user-facing capture step; all evidence is provided directly by your system.

Step compatibility

This step, Verifying IBAN - API only (v1), and Verifying ID document - API only (IDC) (v2) steps each require a different document type and cannot be combined in the same flow.

In addition, the DocumentImages data block for this step must not come from an ID document capture step, such as Verifying ID document (IDC) (v2), Verifying ID document (IDC) (v3), Verifying ID document (v1) or Verifying ID document (v2). Those steps capture identity documents (passport, driving licence, etc.), which this step cannot process. Instead, send the address document images in input.documentImages when you create the session.

Key features​

  • Customer-managed evidence collection: The customer application captures and submits document images via API.
  • Residential address extraction: Full address, street, house number, city, postal code, and country are extracted from the document.
  • Optional identity cross-check: When compareIdentity is enabled, the given name and family name on the document are cross-checked against a BasicIdentity data block, which must come from an earlier step or from the session creation request
  • Unified Verification data block: A Verification result is produced on all output routes.
Supported countries and issuers

Address documents are supported for the following countries and issuers. Depending on the specific document model, analysis may be fully automated or involve a manual review step.

CountryISO codeIssuerCategory
AustriaAUTZMRAdministration
AustriaAUTWIEN_ENERGIEEnergy supplier
AustriaAUTA1_TELEKOMTelecom mobile
AustriaAUTDREI_AUSTRIATelecom mobile
BelgiumBELLUMINUSEnergy supplier
BelgiumBELTELENETTelecom
BelgiumBELVOOTelecom
GermanyDEUBERLINERWASSERWater supplier
GermanyDEUEONEnergy supplier
GermanyDEUO2Telecom
GermanyDEUTTELECOMTelecom
GermanyDEUVATTENFALLEnergy supplier
GermanyDEUVODAFONETelecom
GermanyDEUONE_AND_ONETelecom
FranceFRAEDFEnergy supplier
FranceFRAENGIEEnergy supplier
FranceFRATOTAL_DIRECT_ENERGIEEnergy supplier
FranceFRATOTAL_ENERGIESEnergy supplier
FranceFRADIRECT_ENERGIEEnergy supplier
FranceFRAENIEnergy supplier
FranceFRAVATTENFALLEnergy supplier
FranceFRAOCTOPUS_ENERGYEnergy supplier
FranceFRAILEKEnergy supplier
FranceFRAOHM_ENERGIEEnergy supplier
FranceFRASOWEEEnergy supplier
FranceFRAMINT_ENERGIEEnergy supplier
FranceFRAALPIQEnergy supplier
FranceFRAELMYEnergy supplier
FranceFRAEKWATEUREnergy supplier
FranceFRAGAZ_DE_BORDEAUXEnergy supplier
FranceFRAPLENITUDEEnergy supplier
FranceFRAPRIMEOEnergy supplier
FranceFRAENERGIE_STRASBOURGEnergy supplier
FranceFRADYNEFFEnergy supplier
FranceFRAENERCOOPEnergy supplier
FranceFRAANTARGAZEnergy supplier
FranceFRAALTERNAEnergy supplier
FranceFRALA_BELLENERGIEEnergy supplier
FranceFRAUEMEnergy supplier
FranceFRAURBAN_SOLAR_ENERGYEnergy supplier
FranceFRABUTAGAZEnergy supplier
FranceFRAHAPPEEnergy supplier
FranceFRAWEKIWIEnergy supplier
FranceFRAPAPERNESTEnergy supplier
FranceFRAENGIE_PROEnergy supplier
FranceFRAORANGETelecom
FranceFRASFRTelecom
FranceFRAFREETelecom
FranceFRANUMERICABLETelecom
FranceFRACANALBOXTelecom
FranceFRANORDNETTelecom
FranceFRABOUYGUESTelecom
FranceFRABOUYGUES_MOBILETelecom mobile
FranceFRASFR_MOBILETelecom mobile
FranceFRAFREE_MOBILETelecom mobile
FranceFRAORANGE_MOBILETelecom mobile
FranceFRALA_POSTE_MOBILETelecom mobile
FranceFRANRJ_MOBILETelecom mobile
FranceFRACIC_MOBILETelecom mobile
FranceFRACREDIT_MUTUEL_MOBILETelecom mobile
FranceFRAAUCHAN_TELECOMTelecom mobile
FranceFRAWIZZEETelecom mobile
FranceFRAPRIXTELTelecom mobile
FranceFRALEBARATelecom mobile
FranceFRASYMA_MOBILETelecom mobile
FranceFRAREGLO_MOBILETelecom mobile
FranceFRACORIOLISTelecom mobile
FranceFRAYOUPRICETelecom mobile
FranceFRACDISCOUNT_MOBILETelecom mobile
FranceFRAZEOPTelecom mobile
FranceFRASAURWater supplier
FranceFRASUEZWater supplier
FranceFRAVEOLIAWater supplier
FranceFRADIONEOWater supplier
FranceFRADGFIPFiscal administration
FranceFRACPAMAdministration
FranceFRAREVOLUTBank
FranceFRATWISPAYBank
FranceFRAMAIFInsurer
IrelandIRLBANK_OF_IRELANDBank
IrelandIRLELECTRIC_IRELANDEnergy supplier
IrelandIRLSKY_TVTelecom
ItalyITAENELEnergy supplier
ItalyITAFASTWEBTelecom
ItalyITATIMTelecom
LuxembourgLUXCTIEAdministration
MonacoMCOSMEGEnergy supplier
NetherlandsNLDABN_AMROBank
NetherlandsNLDZIGGOTelecom
NetherlandsNLDVANDEBRONEnergy supplier
NetherlandsNLDVITENSWater supplier
PortugalPRTEDPEnergy supplier
PortugalPRTNOSTelecom
PortugalPRTMEOTelecom
PortugalPRTEPALWater supplier
RomaniaROUDIGITelecom
RomaniaROUENELEnergy supplier
RomaniaROUENGIEEnergy supplier
RomaniaROUEONEnergy supplier
RomaniaROUGOLD_ENERGIEEnergy supplier
RomaniaROUENDESAEnergy supplier
RomaniaROUORANGETelecom
RomaniaROUINGBank
RomaniaROURAIFFEISEN_BANKBank
SpainESPIBERDROLAEnergy supplier
SpainESPJAZZTELTelecom
SpainESPMOVISTARTelecom

For the full list of supported document models, contact your account manager.

Configuration​

OptionTypeRequiredDefaultDescription
configobjectYes—Environment-specific configuration.
config.live.realmstringYes—The IDCheck.io realm for the proof-of-address service in this environment. Provided by IDnow during onboarding. (live)
config.staging.realmstringYes—The IDCheck.io realm for the proof-of-address service in this environment. Provided by IDnow during onboarding. (staging)
compareIdentitybooleanNofalseWhen true, requires a prior BasicIdentity step for identity cross-check.

Example configuration​

{
  "config": {
    "live": { "realm": "your-live-realm" },
    "staging": { "realm": "your-staging-realm" }
  }
}

Input data blocks​

Data blockRequiredDescription
DocumentImagesYesAddress document images submitted as binary files via multipart/form-data. Front side is required; back side is optional. Accepted formats: JPEG, PNG. The DocumentImages data block supplied to this step must not come from an identity document capture step.
BasicIdentityConditionalIdentity data used for cross-check against the document holder. Present only when compareIdentity is true.
File size limit

Each file referenced in DocumentImages is subject to a per-file size limit of 4 MB.

Routes​

RouteDescription
verifiedDocument was successfully processed and address data was extracted.
not_verifiedDocument was rejected or analysis flagged the document as invalid.
fraud_detectedFraudulent identity suspicion detected. Takes precedence over other failure conditions.

Output data blocks​

RouteData blocks produced
verifiedResidentialAddress, Verification
conditionally:
BasicIdentity (only when compareIdentity is true)
not_verifiedVerification
fraud_detectedVerification

Example payloads​

ResidentialAddress — verified
{
  "residentAddress": "24 RUE DANTON 35700 RENNES FRANCE",
  "residentStreet": "RUE DANTON",
  "residentHouseNumber": "24",
  "residentCity": "RENNES",
  "residentPostalCode": "35700",
  "residentCountry": "FR",
  "residentState": null
}
BasicIdentity — verified (when compareIdentity: true)
{
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": null,
  "birthPlace": null
}
Verification — verified
{
  "status": "verified",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [],
      "evidence": []
    }
  ],
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-03-15T10:22:45.000Z",
  "verificationProcessId": "txn-poa-7f3a2c91"
}
Verification — fraud_detected
{
  "status": "fraudDetected",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        {
          "technique": "documentValidity",
          "sources": [],
          "outcome": "failed",
          "issues": [
            {
              "code": "BACKEND_ANALYSIS",
              "severity": "error",
              "message": "No document found"
            }
          ],
          "performedBy": null,
          "performedAt": null
        }
      ],
      "evidence": [
        {
          "type": "analysisReport",
          "ref": {
            "$ref": "vault",
            "$id": "6b514db8-55f0-4618-98b5-1e42845d053e"
          }
        }
      ]
    }
  ],
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-03-15T10:22:45.000Z",
  "verificationProcessId": "txn-poa-7f3a2c91"
}
Verification — not_verified (when compareIdentity: true)
{
  "status": "rejected",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        {
          "technique": "documentValidity",
          "sources": [],
          "outcome": "passed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        },
        {
          "technique": "electronicRecord",
          "sources": [
            {
              "type": "thirdPartyRegister",
              "id": null
            }
          ],
          "outcome": "passed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        },
        {
          "technique": "dataCrosscheck",
          "sources": [
            {
              "type": "signedBarcode",
              "id": null
            },
            {
              "type": "inputData",
              "id": null
            }
          ],
          "outcome": "failed",
          "issues": [
            {
              "code": "FIRST_NAME_MATCH",
              "severity": "error",
              "message": "Firstnames do not match the identity"
            }
          ],
          "performedBy": null,
          "performedAt": null
        },
        {
          "technique": "securityFeatures",
          "sources": [],
          "outcome": "passed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        }
      ],
      "evidence": [
        {
          "type": "analysisReport",
          "ref": {
            "$ref": "vault",
            "$id": "e243e571-e63e-4c21-8668-1b0fc07f6c03"
          }
        }
      ]
    }
  ],
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-03-15T10:22:45.000Z",
  "verificationProcessId": "txn-poa-7f3a2c91"
}