Proof of Address

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 | null* 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

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

Sample response

Below are an example and explanation of the Address Validation related payload. Depending on your solution, the payload may contain additional parameters. To find more info about it, see the decision webhook documentation.

...
"additionalVerifiedData": {
  "proofOfAddress": {
    "documentType": "ELECTRICITY_BILL",
    "nameMatch": null,
    "nameMatchPercentage": null,
    "addressValidationResult": {
      "components": {
          "plausibleFullAddress": "23 Willowbrook Lane, Ashford, Kent CT19 8NP, UK",
          "city": "Ashford",
          "unit": null,
          "state": null,
          "street": "Willowbrook Lane",
          "country": "UK",
          "postcode": "CT19 8NP",
          "houseNumber": "23"
        },
      "addressType": "residential"
      "validations": {
        "countryExists": {
          "result": "skipped"
        }
      }
    }
  }
}
...

Request properties explained

• additionalVerifiedData: object Data that has been optionally verified for the session

  • proofOfAddress: object Proof of address data

    • • documentType: string | null 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.

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

      • addressValidationResult: object Contains data that has been found about the extracted address

        • components: object

          • plausibleFullAddress: string | null Full address as a string, containing extracted and found data

          • city: string | null Any human settlement, including cities, towns, villages, hamlets, localities, etc.

          • unit: string | null An apartment, unit, office, lot, or other secondary unit designator

          • state: string | null A first-level administrative division

          • street: string | null Street name

          • country: string | null Sovereign nations and their dependent territories (ISO 3166)

          • postcode: string | null Postal codes used for mail sorting

          • houseNumber: string | null External (street-facing) building number

        • addressType: string | null Indicates if the address is of a residential or business premise, or it is a PO box. One of residential , business , poBox. null if the address validation feature was has not been enabled, or if no data was sent.

        • validations: object Contains country validation result data

          • countryExists: object Indicates if the validation was able to verify the country

            • result:  string | null Indicates the result of country validation, or if it was skipped. One of success, failure, skipped

Sample response

Below are an example and explanation of the Address Validation related payload. Depending on your solution, the payload may contain additional parameters. To find more info about it, see the GET sessions/{sessionId}/decision[↗] documentation.

...
"additionalVerifiedData": {
  "proofOfAddress": {
    "documentType": "ELECTRICITY_BILL",
    "nameMatch": null,
    "nameMatchPercentage": null,
    "addressValidationResult": {
      "components": {
          "plausibleFullAddress": "23 Willowbrook Lane, Ashford, Kent CT19 8NP, UK",
          "city": "Ashford",
          "unit": null,
          "state": null,
          "street": "Willowbrook Lane",
          "country": "UK",
          "postcode": "CT19 8NP",
          "houseNumber": "23"
        },
      "addressType": "residential"
      "validations": {
        "countryExists": {
          "result": "skipped"
        }
      }
    }
  }
}
...

Request properties explained

• additionalVerifiedData: object Data that has been optionally verified for the session

  • proofOfAddress: object Proof of address data

    • • documentType: string | null 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.

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

      • addressValidationResult: object Contains data that has been found about the extracted address

        • components: object

          • plausibleFullAddress: string | null Full address as a string, containing extracted and found data

          • city: string | null Any human settlement, including cities, towns, villages, hamlets, localities, etc.

          • unit: string | null An apartment, unit, office, lot, or other secondary unit designator

          • state: string | null A first-level administrative division

          • street: string | null Street name

          • country: string | null Sovereign nations and their dependent territories (ISO 3166)

          • postcode: string | null Postal codes used for mail sorting

          • houseNumber: string | null External (street-facing) building number

        • addressType: string | null Indicates if the address is of a residential or business premise, or it is a PO box. One of residential , business , poBox. null if the address validation feature was has not been enabled, or if no data was sent.

        • validations: object Contains country validation result data

          • countryExists: object Indicates if the validation was able to verify the country

            • result:  string | null Indicates the result of country validation, or if it was skipped. One of success, failure, skipped

Sample response

Below are an example and explanation of the Address Matching related payload. Depending on your solution, the payload may contain additional parameters. To find more info about it, see the decision webhook documentation.

...,
    "additionalVerifiedData": {
      "proofOfAddress": {
        "documentType": "UTILITY_BILL",
        "fullName": "John Smith",
        "fullAddress": "123 Main Street, New York, NY 10001, USA",
        "issueDate": "2025-09-01",
        "nameMatch": null,
        "nameMatchPercentage": null
      },
      "addressMatching": {
        "addresses": [
          {
            "fullAddress": "123 Main Street, New York, NY 10001, USA",
            "parsedAddress": {
              "city": "New York",
              "unit": null,
              "state": "NY", 
              "street": "Main Street",
              "country": "USA",
              "postcode": "10001",
              "houseNumber": "123"
            }
          },
          {
            "fullAddress": "123 Main St, New York, New York 10001, United States",
            "parsedAddress": {
              "city": "New York",
              "unit": null,
              "state": "New York",
              "street": "Main St", 
              "country": "United States",
              "postcode": "10001",
              "houseNumber": "123"
            }
          }
        ],
        "result": true,
        "matchThreshold": 80,
        "matchPercentage": 90
      }
    },
...

Request properties explained

• additionalVerifiedData: object Data that has been optionally verified for the session

  • proofOfAddress: object Proof of address data

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

    • fullName:  string Person’s name as a single string

    • fullAddress: string Full address as a single string

    • issueDate: string PoA document issue date, in YYYY-MM-DD format

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

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

  • addressMatching: object Contains all address matching validation results

    • addresses: array Array of exactly 2 address objects - first from initData, second from PoA document

      • fullAddress: string Original full address string as provided/extracted

      • parsedAddress: object Google Maps API parsed address components

        • city: string | null Parsed city name

        • unit: string | null Parsed partment/unit number

        • state: string | null Parsed state/province

        • street: string | null Parsed street name (premise)

        • country: string | null Parsed country name

        • postcode: string | null Parsed postal/ZIP code

        • houseNumber: string | null Parsed house/building number

    • result: boolean Indicates whether addresses match based on threshold

    • matchThreshold: integer Configured matching percentage threshold

    • matchPercentage: integer Indicates matching percentage

Sample response

Below are an example and explanation of the Address Matching related payload. Depending on your solution, the payload may contain additional parameters. To find more info about it, see the GET sessions/{sessionId}/decision[↗] documentation.

...,
    "additionalVerifiedData": {
      "proofOfAddress": {
        "documentType": "UTILITY_BILL",
        "fullName": "John Smith",
        "fullAddress": "123 Main Street, New York, NY 10001, USA",
        "issueDate": "2025-09-01",
        "nameMatch": null,
        "nameMatchPercentage": null
      },
      "addressMatching": {
        "addresses": [
          {
            "fullAddress": "123 Main Street, New York, NY 10001, USA",
            "parsedAddress": {
              "city": "New York",
              "unit": null,
              "state": "NY", 
              "street": "Main Street",
              "country": "USA",
              "postcode": "10001",
              "houseNumber": "123"
            }
          },
          {
            "fullAddress": "123 Main St, New York, New York 10001, United States",
            "parsedAddress": {
              "city": "New York",
              "unit": null,
              "state": "New York",
              "street": "Main St", 
              "country": "United States",
              "postcode": "10001",
              "houseNumber": "123"
            }
          }
        ],
        "result": true,
        "matchThreshold": 80,
        "matchPercentage": 90
      }
    },
...

Request properties explained

• additionalVerifiedData: object Data that has been optionally verified for the session

  • proofOfAddress: object Proof of address data

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

    • fullName:  string Person’s name as a single string

    • fullAddress: string Full address as a single string

    • issueDate: string PoA document issue date, in YYYY-MM-DD format

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

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

  • addressMatching: object Contains all address matching validation results

    • addresses: array Array of exactly 2 address objects - first from initData, second from PoA document

      • fullAddress: string Original full address string as provided/extracted

      • parsedAddress: object Google Maps API parsed address components

        • city: string | null Parsed city name

        • unit: string | null Parsed partment/unit number

        • state: string | null Parsed state/province

        • street: string | null Parsed street name (premise)

        • country: string | null Parsed country name

        • postcode: string | null Parsed postal/ZIP code

        • houseNumber: string | null Parsed house/building number

    • result: boolean Indicates whether addresses match based on threshold

    • matchThreshold: integer Configured matching percentage threshold

    • matchPercentage: integer Indicates matching percentage