Proof of Address

The Proof of Address (PoA) solution automates the verification of end-user addresses by capturing and extracting data from documents such as bank statements and utility bills, matching name data, and by checking the integrity of the document.

The core solution validates document type and issue date, extracts name and address information. It is possible to improve the solution further by enabling name matching and/or fraud validation to check document integrity.

All the extracted and checked data is provided via API or Veriff Customer Portal.

The automatic Proof of Address solution is available via API, web flow, and native SDKs. The flow is set up via Workflows in the Veriff Customer Portal.

Contact your solutions engineer for info and configuration.

Prerequisites

• You have an integration set up with Veriff

• The Proof of Address check is configured for that integration by your Solutions Engineer

• You have configured the decision webhook to get responses from Veriff  (see the how-to in webhooks’ Set up webhooks section)

• If using the API, you are ready to collect and send Veriff your end-user’s data and document images

• Veriff strongly recommends that you create and send us the endUserId or vendorData

Define acceptable document types

To add more flexibility to the solution, you can define which document types are accepted to perform the verification.

You can pass them when creating a session with POST /sessions, using the proofOfAddress.acceptableTypes array.

→ See the Supported document types article for a list of document types

Flow overview

The flow is a bit different, depending on the method you are using to verify your end-users with Veriff.

Proof of Address Extraction

In this case, data is extracted from the end-user’s document.

POST {baseURL}/v1/sessions
Type: object
Headers:
       X-AUTH-CLIENT: string (required) = API key
       Content-Type: application/json

curl -X POST \
  --url '/v1/sessions/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -d '{
    "verification": {
        "person": {
            "firstName": "John",
            "lastName": "Smith",
        },
        "proofOfAddress": {
            "acceptableTypes": [
                {"name": "UTILITY_BILL"},
                {"name": "TAX_DOCUMENT"},
                {"name": "PHONE_BILL"},
            ]
        },
        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
    }
}'

POST {baseURL}/v1/sessions/{sessionId}/media
Type: object
Headers:
       X-AUTH-CLIENT: string (required) = API key
       X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
       Content-Type: application/json

curl -X POST \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "image": {
        "context": "document-front",
        "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII="
    }
}'

PATCH {baseURL}/v1/sessions/{sessionId}
Type: object
Headers:
       X-AUTH-CLIENT: string (required) = API key
       X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
       Content-Type: application/json

curl -X PATCH \
  --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: dd994f70b1150ae012f9c1d6d20adf7ed69780044835d39de20b00ffae0660a0' \
  -d '{
    "verification": {
      "status": "submitted"
    }
}'

Find decision and/or session related info

You can get the data from three sources:

• Receive the decision webhook

• Query the results via GET sessions/{sessionId}/decision

• View the session in Veriff Customer Portal

Note about the fraud validation

If the fraud validation has been enabled for your solution, then you will see the additionalVerifiedData.proofOfAddress.fraud object in the payload.

        "additionalVerifiedData": {
            "proofOfAddress": {
                ...
                "fraud": {
                    "riskLevel": "HIGH_RISK",
                    "reason": "PDF_PROCESSED_BY_EDITOR",
                    "reasonDescription": "Document was processed using editing software",
                    "indicators": []
                }
            },

The fraud object shows the document's risk level and gives additional details about the factors that influenced this risk assessment. Veriff passes the data unaltered in webhooks and API payloads.

Veriff recommends you do not build any logic on top of the proofOfAddress.fraud.indicators array, as possible values may be altered without prior notice to provide better insights. However, structure of entries will stay backwards compatible.

The decision webhook and API examples below contain limited info about the possible values of the keys in the fraud object.

Webhook payload

Below are a sample and an explanation of a decision webhook payload for a minimal Proof of Address Verification.

Depending on your solution, the payload may contain additional parameters. To find more info about it, see the decision webhook documentation.

Sample request

{
    "status": "success",
    "verification": {
        "id": "ab1c2345-678d-4e3b-98a3-a75b00b715kj",
        "attemptId": "c6cab5b0-c506-47a6-922d-6ae3b72ca172",
        "code": 9001,
        "person": {
            "gender": null,
            "idNumber": null,
            "lastName": null,
            "addresses": [
                {
                    "fullAddress": "Jaan Koorti 777,
                     99999 Tallinn, Estonia"
                }
            ],
            "firstName": "Jane Doe",
            "citizenship": null,
            "dateOfBirth": null,
            "nationality": null,
            "yearOfBirth": null,
            "placeOfBirth": null,
            "pepSanctionMatch": null
        },
        "reason": null,
        "status": "approved",
        "comments": [],
        "document": {
            "type": null,
            "number": null,
            "country": null,
            "validFrom": "2023-11-25",
            "validUntil": null
        },
        "reasonCode": null,
        "vendorData": null,
        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
        "decisionTime": "2024-01-23T10:31:05.293000Z",
        "acceptanceTime": "2024-01-23T10:25:40.026Z",
        "additionalVerifiedData": {
            "proofOfAddress": {
                "documentType": "UTILITY_BILL",
                "nameMatch": true,
                "nameMatcPercentage": 100.00,
                "fraud": {
                    "riskLevel": "HIGH_RISK",
                    "reason": "PDF_PROCESSED_BY_EDITOR",
                    "reasonDescription": "Document was processed using editing software",
                    "indicators": []
                }
            },
         },
    }
    "technicalData": {
        "ip": null
}

Request properties explained

*Required field

• status: string* Status of the response

• verification: object* Verification request decision object. null if decision is not available yet

  • id: string* UUID v4 which identifies the verification session

  • attemptId: string* UUID v4 of the attempt which received a status (as shown in verification.status field)

  • vendorData: string | null* The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null* The UUID that you created for your end-user. null if not specified

  • status: string* Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

  • code: integer* Verification session decision code, one of 9001, 9102, 9103, 9104, 9121. For more info, see the verification session decision codes

  • reason: string | null Reason why the verification failed, only sent when the verification failed

  • reasonCode: integer | null Reason code of the failed verification, only sent when the verification failed. For more info, see the possible codes for a failed verification

  • decisionTime: string* Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • acceptanceTime: string* Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • person: object* Data about the verified person

    • gender: string | null* Person’s gender, represented as M or F, or null if not present

    • idNumber: string | null* National identification number

    • lastName: string | null* null, unless prefilled by the customer

    • addresses: array* Array of person's addresses

      • fullAddress: string Address as a single string

    • firstName: string | null* Person's first name as written on the document, if available

    • dateOfBirth: string* Person’s date of birth, represented as YYYY-MM-DD

    • nationality: string | null* Person's nationality

    • yearOfBirth: string | null* Person’s year of birth, represented as YYYY

    • placeOfBirth: string | null* Person's place of birth

    • pepSanctionMatch: string | null* Legacy field, may return incorrect result, should be ignored

    • citizenship: string | null* Deprecated, always returns null

  • document: object* Verified document

    • type: string | null Document type

    • number: string | null Document number, [a-zA-Z0-9] characters only

    • country: string | null Document issuing country, represented as ISO 3166 alpha-2 code

    • validUntil: string | null Document is valid until date, represented as YYYY-MM-DD. Optional, must be configured for your integration by the Solutions Engineer

    • validFrom: string | null* Document is valid from date, represented as YYYY-MM-DD

  • additionalVerifiedData: object* Data which has been optionally verified for session

    • proofOfAddress: object* Proof of address data. Optional, available only if the name match check has been enabled for the integration

      • documentType : string* Indicates the type of the proof of address document. null if the check could not be completed.

      • nameMatch: boolean | null Indicates if the name on the proof of address document matches the name from the initial request data. null if the check could not be completed. Sent only when the name match check was enabled.

      • nameMatchPercentage: float| null Indicates the level of similarity the matched names have, in the range of 0.00-100.00. null if the check could not be completed. Sent only when the name match check was enabled.

      • fraud: object Returns data about document integrity. Available only if the fraud validation check has been enabled for your integration.

        • riskLevel: string | null Indicates the risk level, possible values LOW_RISK, MEDIUM_RISK, HIGH_RISK . null if the check was not executed or failed.

        • reason: string | null Short description indicating the reason behind the risk level. null if the check was not executed or failed.

        • reasonDescription: string | null Human readable explanation of the data in the reason field. null if the check was not executed or failed.

        • indicators: array Array strings listing the factors that influenced the risk assessment. Empty if the check was not executed or failed.

  • comments: array* (Deprecated)

• technicalData: object* Technical data

  • ip: string | null IP of the device from which the verification was made

API call

Below are a sample and an explanation of a API call payload for a minimal Proof of Address Verification.

Depending on your solution, the payload may contain additional parameters. To find more info about it, see the GET sessions/{sessionId}/decision[↗] documentation.

Sample response

{
    "status": "success",
    "verification": {
        "id": "ab1c2345-678d-4e3b-98a3-a75b00b715kj",
        "attemptId": "c6cab5b0-c506-47a6-922d-6ae3b72ca172",
        "code": 9001,
        "person": {
            "gender": null,
            "idNumber": null,
            "lastName": null,
            "addresses": [
                {
                    "fullAddress": "Jaan Koorti 777,
                     99999 Tallinn, Estonia"
                }
            ],
            "firstName": "Jane Doe",
            "citizenship": null,
            "dateOfBirth": null,
            "nationality": null,
            "yearOfBirth": null,
            "placeOfBirth": null,
            "pepSanctionMatch": null
        },
        "reason": null,
        "status": "approved",
        "comments": [],
        "document": {
            "type": null,
            "number": null,
            "country": null,
            "validFrom": "2023-11-25",
            "validUntil": null
        },
        "reasonCode": null,
        "vendorData": null,
        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
        "decisionTime": "2024-01-23T10:31:05.293000Z",
        "acceptanceTime": "2024-01-23T10:25:40.026Z",
        "additionalVerifiedData": {
            "proofOfAddress": {
                "documentType": "UTILITY_BILL",
                "nameMatch": true,
                "nameMatcPercentage": 100.00,
                "fraud": {
                    "riskLevel": "HIGH_RISK",
                    "reason": "PDF_PROCESSED_BY_EDITOR",
                    "reasonDescription": "Document was processed using editing software",
                    "indicators": []
                }
            },
         },
    }
    "technicalData": {
        "ip": null
}

Response properties explained

• status: string Status of the response

• verification: object Verification request decision object. null if decision is not available yet

  • id: string UUID v4 which identifies the verification session

  • attemptId: string UUID v4 of the attempt which received a status (as shown in verification.status field)

  • vendorData: string | null The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null The UUID that you created for your end-user. null if not specified

  • status: string Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

  • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104, 9121. For more info, see the verification session decision codes

  • reason: string | null Reason why the verification failed, only sent when the verification failed

  • reasonCode: integer | null Reason code of the failed verification, only sent when the verification failed. For more info, see the possible codes for a failed verification

  • decisionTime: string Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • acceptanceTime: string Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • person: object Data about the verified person

    • gender: string | null Person’s gender, represented as M or F, or null if not present

    • idNumber: string | null National identification number

    • lastName: string | null null, unless prefilled by the customer

    • addresses: array Array of person's addresses

      • fullAddress: string Address as a single string

    • firstName: string | null Person's first name as written on the document, if available

    • dateOfBirth: string Person’s date of birth, represented as YYYY-MM-DD

    • nationality: string | null Person's nationality

    • yearOfBirth: string | null Person’s year of birth, represented as YYYY

    • placeOfBirth: string | null Person's place of birth

    • pepSanctionMatch: string | null Legacy field, may return incorrect result, should be ignored

    • citizenship: string | null Deprecated, always returns null

  • document: object Verified document

    • type: string | null Document type

    • number: string | null Document number, [a-zA-Z0-9] characters only

    • country: string | null Document issuing country, represented as ISO 3166 alpha-2 code

    • validUntil: string | null Document is valid until date, represented as YYYY-MM-DD. Optional, must be configured for your integration by the Solutions Engineer

    • validFrom: string | null Document is valid from date, represented as YYYY-MM-DD

  • additionalVerifiedData: object Data which has been optionally verified for session

    • proofOfAddress: object Proof of address data. Optional, available only if the name match check has been enabled for the integration

      • documentType : string Indicates the type of the proof of address document. null if the check could not be completed.

      • nameMatch: boolean | null Indicates if the name on the proof of address document matches the name from the initial request data. null if the check could not be completed. Sent only when the name match check was enabled.

      • nameMatchPercentage: float| null Indicates the level of similarity the matched names have, in the range of 0.00-100.00. null if the check could not be completed. Sent only when the name match check was enabled.

      • fraud: object Returns data about document integrity. Available only if the fraud validation check has been enabled for your integration.

        • riskLevel: string | null Indicates the risk level, possible values LOW_RISK, MEDIUM_RISK, HIGH_RISK . null if the check was not executed or failed.

        • reason: string | null Short description indicating the reason behind the risk level. null if the check was not executed or failed.

        • reasonDescription: string | null Human readable explanation of the data in the reason field. null if the check was not executed or failed.

        • indicators: array Array strings listing the factors that influenced the risk assessment. Empty if the check was not executed or failed.

  • comments: array (Deprecated)

• technicalData: object Technical data

  • ip: string | null IP of the device from which the verification was made

Veriff Customer Portal

You can find the verification session related info, including the decision, in the Veriff Customer Portal, under the All Verifications tab.

Proof of Address Capture

This is a separate solution which is used to just capture end-user’s document. No further analysis is done.

Refer to the Proof of Address Capture documentation.

Non-document Proof of Address

It is possible to perform Proof of Address verification without sending document data. This, however, is not part of the classic Proof of Address solution. Instead, it can be done by passing the end-user’s name and address data when creating a session with Veriff, and configuring the integration to include a registry check. Veriff passes the data to the database verification service provider, who verifies the name and address data, and returns relevant info.

Currently, the solution is available only for US Database Verification check.

Status and reason codes

For an approved session, see:

• verification.code about verification session decision code, one of 9001, 9102, 9103, 9104, 9121

• verification.status about verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

If the session was declined or resubmission_requested, you can find additional information by checking:

• verification.reason for the reason why the verification failed

verification.reasonCode for reason code of the failed verification and cross-reference it with Granular reason codes (table)

Most common decline reasons for the Proof of Address solution

For more info about the codes you are seeing, refer to:

• Verification session status codes (table)

• Verification session decision codes (table)

• Granular reason codes (table)

Changelog