Metadata Database Verification

Metadata Database Verification validates end-user identity data (name, DOB, address, national ID, phone, document numbers, etc) against authoritative external government, consumer, credit bureau, utility, and phone registry databases across via the DataZoo aggregation platform. It returns field-level validation statuses for granular, programmable decision-making.

*This solution can be:

• an add-on to your document-based Identity Verification (IDV), or

• used separately as a stand-alone check. In this case a separate integration is needed, the whole flow is done over the API and you need to input all the data in initData.

All session-related info is returned via decision webhook and can be polled from different API endpoints. The results of the verification can also be viewed in the Veriff Customer Portal, in the Webhook tab.

Contact your solutions engineer for info and configuration.

Prerequisites

• You have an integration set up with Veriff

• The database 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

The data you need to send when creating a session depends on the database. Check regional databases' documentation for the exact list of fields.

Key terminology

End-user data sources

The "end-user data sources" refer to the origins from which the end-user's information can be collected for database verification. This solution is performed using initData.

InitData

This is data that you provide when creating a verification session, i.e. the parameters you specify in the POST /sessions request. Includes information like names, date of birth, address, phone number, ID number, gender etc.

General overview of the parameters sent via initData:

• person.firstName: string End-user's first name

• person.lastName: string End-user's last name

• person.fullName: string End-user’s first and last name

• person.dateOfBirth: string Date of birth in YYYY-MM-DD format

• person.middleName: string Middle name

• person.gender: string Gender (M/F)

• person.email: string Email address

• person.phoneNumber: string Mobile phone number

• person.landLinePhoneNumber: string Landline phone number

• person.idNumber: string National ID number

• person.partnerFirstName: string Partner’s first name

• person.partnerLastName: string Partner’s last name

• person.marriageDateOfEvent: string Marriage date

• person.secondLastName: string Second last name

• document.number: string Document number

• document.country: string Document issuing country (ISO 3166-1 alpha-2)

• document.validFrom: string Document issue/valid-from date

• document.validUntil: string Document expiry date

• document.cardNumber: string Physical card number

• document.cardType: string Card type

• document.stateOfIssue: string State of issue

• document.referenceNumber: string Reference number

• document.registrationNumber: string Registration number

• document.version: string Document version

• address.fullAddress: string Full address string

• address.street: string Street name

• address.neighbourhood: string Usually an unofficial neighbourhood name

• address.city: string City name

• address.state: string A first-level administrative division

• address.postcode: string Postcode number

• consents: array List of consent objects

  • type: string Consent type (general or dvs)

  • approved: boolean Whether consent was obtained

The data you need to send when creating a session depends on the database. Check regional databases' documentation for the exact list of fields.

Flow overview

Database flow

Step 1: you input end-user's data (initData) in POST /sessions API call

Step 2: system queries the appropriate database(s) based on country/region

Step 3: validation analysis, aka field-by-field comparison between input data and registry data, leading to validation of multiple data points (name, DOB, address, etc.)

Step 4: validation decision

Step 5: webhook is sent, containing:

• Validation conclusion per field sent and supported by registry

• Info about decision influence based on selected compared fields

Session flow

This solution is available only via API. You are responsible for gathering and passing all required initData.

Use via API

1. Generate a verification session using the API keys and the baseURL of your integration (see the API Documentation and API Reference[↗] how to find these)

   • Check each database's documentation to see which initData parameters are required and allowed to be sent.

2. Patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call

   • This endpoint requires endpoint level authentication via x-hmac-signature header. See HMAC Authentication and Endpoint Security article for general info about signature creation.

Sample request payload

curl -X PATCH 'https://stationapi.veriff.com/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: your-api-key' \
  -H 'x-hmac-signature: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
  "verification": {
    "status": "submitted"
  }
}'

3. Database checks are run

4. Check the decision data and/or session related info from the decision webhook and/or query the data from the GET /decisions endpoint. Check each database's documentation to see an example of the webhook and API response payload.

Find decision and/or session related info

You can get the data from three sources:

• Receive the decision webhook webhook (check each database's documentation to see an example)

• Query the results via GET sessions/{sessionId}/decision[↗] (payload is identical to webhook’s, check each database's documentation to see an example)

• View the session in Veriff Customer Portal > All Verifications > Webhooks tab

The data you see in the webhook / API response payload depends on the database. Check regional databases' documentation for the exact list of fields.

Note about object and field visibility

Some objects and fields within the registryValidations are optional.

You should expect that any key may be omitted from the payload or return a null value.

A field is included in the response only when it is not skipped. If a validation was configured but skipped, it is omitted from the webhook.

Because the response schema is dynamic and based on both your specific configuration and the quality of the initData provided, your application logic must account for omitted keys and null values as a standard part of the verification workflow.

Note on session outcomes

An approved session is identified by a verification.status of approved. Depending on your configuration, a "clean" result may also include:

• All configured validations returned success or not_applicable

If a validation is not enabled, it is omitted from the payload and do not impact the approved status.

Webhook/API response general structure

The example below uses placeholder data to show only the part that is relevant to Metadata Database Verification solution.

{
  "status": "success",
  "verification": {
    "registryValidations": {
      "<REGISTRY_KEY>": {
        "status": "success | failure | error",
        "data": { ... } | null,
        "error": null | {
          "code": "enum string",
          "message": "string"
        },
        "timestamp": "ISO-8601 string" | null,
        "validations": {
          "<validation_code>": {
            "result": "enum string",
            "reason": "string | null"
          }
        }
      }
    }
  }
}

Parameters explained

• verification : Parent container for verification results

  • registryValidations : Metadata Database Verification results container

    • <REGISTRY_KEY> : Combination of country code and registry name. Parent container for the specific registry results

      • status: string Overall result. Enum:success, failure, or error

      • data: object | null Data returned from the registry (e.g., visa details, person status). null if registry only performs matching without returning data

      • error: object | null Structured error when <REGISTRY_KEY>.status is error. null otherwise

        • code: Machine-readable error info, see more info below

        • message: Human-readable error info, see more info below

      • timestamp: string | null ISO-8601 timestamp of registry response, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset. null when validation could not be performed.

      • validations: object | null Map of <validation_code> to the validations matching outcome as shown in result. null when <REGISTRY_KEY>.status is error

        • <validation_code> : object See more info below for enum

          • result: Machine-readable result of validation. See more info below

          • reason: Machine-readable reason for the result value. See more info below

Available validation_code values

Note that only non-skipped validations appear in webhook.

• processing System-level execution status

• is_input_valid Whether end-user data passed format validation (Note: has details array on failure)

• consent_obtained Whether required consent was provided

• identity_is_valid Whether the person was found/verified in the registry

• first_name_match First name comparison result

• middle_name_match Middle name comparison result

• last_name_match Last name comparison result

• full_name_match Full name comparison result

• first_partner_name_match Partner’s first name comparison result

• last_partner_name_match Partner’s last name comparison result

• date_of_birth_match Date of birth comparison result

• gender_match Gender comparison result

• email_match Email comparison result

• phone_number_match Phone number comparison result

• land_line_phone_number_match Landline phone comparison result

• id_number_match National ID number comparison result

• marriage_date_of_event_matchMarriage date comparison result

• address_full_address_match Full address comparison result

• address_street_match Street comparison result

• address_city_match City comparison result

• address_state_match State comparison result

• address_postcode_match Postcode comparison result

• address_neighbourhood_match Neighbourhood comparison result

• document_number_match Document number comparison result

• document_card_number_match Card number comparison result

• document_version_match Document version comparison result

• document_reference_number_match Reference number comparison result

• document_valid_from_match Document valid-from date comparison result

validation_code.result statuses and meanings

• success The submitted value matches the registry record

• failure with reason: value_mismatch The submitted value does not match the registry record

• not_applicable with:

  • reason: input_not_provided The input value was not provided for this validation

  • reason: output_not_received The registry did not return data for this field

validation_code.reason values

• null On success

• value_mismatch Provided value does not match registry

• input_not_provided Input value was not provided

• output_not_received Registry didn't return the data point

• person_not_found Person not found in registry

• consent_not_obtained Required consent was not given

• input_invalid Input data failed format validation

• registry_unavailable Registry could not be reached

• technical_issues Internal error occurred

• validation_disabled Validation was not configured (these are omitted from webhook)

error.code and error.message values

Note that:

• These appear when status is error

• error is null when registry status is success or failure

Databases by regions

Australia and Oceania

• Australia Residential (AU_RESIDENTIAL)

• Australia Citizens (AU_CITIZENS)

• Australia Consumer (AU_CONSUMER)

• Australia ASIC Personal Name Register (AU_ASIC_PERSONAL_NAME_REGISTER)

• Australia TICA Tenancy Register (AU_TICA_TENANCY_REGISTER)

South America

• Chile National ID (CL_NATIONAL_ID)

• Chile Residential (CL_RESIDENTIAL)

EMEIA

• United Kingdom Residential (GB_RESIDENTIAL)

• United Kingdom Consumer (GB_CONSUMER)

Australia and Oceania

{
  "verification": {
    "person": {
      "firstName": "James",
      "lastName": "Wilson",
      "dateOfBirth": "1974-05-05"
      "email": "james.wilson@example.com",
      "gender": "M",
      "middleName": "Robert",
      "landLinePhoneNumber": "+61298765432",
      "phoneNumber": "+61412345678"
    }
  }
}

{
  "verification": {
    "person": {
      "firstName": "James",
      "lastName": "Wilson",
      "email": "james.wilson@example.com",
      "gender": "M",
      "middleName": "Robert",
      "landLinePhoneNumber": "+61298765432",
      "phoneNumber": "+61412345678"
    },
    "address": {
      "street": "42 George Street",
      "city": "Sydney",
      "postcode": "2000"
    }
  }
}

{
  "verification": {
    "person": {
      "firstName": "James",
      "lastName": "Wilson",
      "email": "james.wilson@example.com",
      "gender": "M",
      "middleName": "Robert",
      "landLinePhoneNumber": "+61298765432",
      "phoneNumber": "+61412345678"
    },
    "address": {
      "fullAddress": "42 George Street, Sydney NSW 2000"
    }
  }
}

{
  "AU_RESIDENTIAL": {
    "status": "success",
    "data": {
      "addressElement1": "42 George Street",
      "addressElement3": "Sydney",
      "addressElement4": "NSW",
      "addressElement5": "2000",
      "dataSourceScore": 0.95,
      "emailAddress": "james.wilson@example.com",
      "firstName": "James",
      "lastName": "Wilson",
      "middleName": "Robert"
    },
    "validations": {
      "processing": {"result": "success", "reason": null},
      "is_input_valid": {"result": "success", "reason": null},
      "identity_is_valid": {"result": "success", "reason": null},
      "first_name_match": {"result": "success", "reason": null},
      "last_name_match": {"result": "success", "reason": null},
      "middle_name_match": {"result": "success", "reason": null},
      "date_of_birth_match": {"result": "success", "reason": null},
      "address_full_address_match": {"result": "success", "reason": null},
      "email_match": {"result": "not_applicable", "reason": "output_not_received"},
      "phone_number_match": {"result": "not_applicable", "reason": "output_not_received"}
    },
    "error": null,
    "timestamp": "2026-04-01T10:00:00Z"
  }
}

{
  "verification": {
    "person": {
      "firstName": "Sarah",
      "lastName": "Thompson",
      "dateOfBirth": "1988-11-02",
      "email": "sarah.thompson@example.com.au",
      "gender": "F",
      "middleName": "Jane",
      "phoneNumber": "+61412345678"
    }
  }
}

{
  "verification": {
    "person": {
      "firstName": "Sarah",
      "lastName": "Thompson",
      "email": "sarah.thompson@example.com.au",
      "gender": "F",
      "middleName": "Jane",
      "phoneNumber": "+61412345678"
    },
    "address": {
      "street": "15 Queen Street"
      "postcode": "4000"
    }
  }
}

{
  "verification": {
    "person": {
      "firstName": "Sarah",
      "lastName": "Thompson",
      "email": "sarah.thompson@example.com.au",
      "gender": "F",
      "middleName": "Jane",
      "phoneNumber": "+61412345678"
    },
    "address": {
      "fullAddress": "15 Queen Street, 4000"
    }
  }
}

{
  "AU_CITIZENS": {
    "status": "success",
    "data": {
      "addressElement1": "15 Queen Street",
      "addressElement3": "Brisbane",
      "addressElement4": "QLD",
      "addressElement5": "4000",
      "dataSourceScore": 0.92,
      "documentNo": true,
      "firstName": "Sarah",
      "lastName": "Thompson",
      "middleName": "Jane"
    },
    "validations": {
      "processing": {"result": "success", "reason": null},
      "is_input_valid": {"result": "success", "reason": null},
      "identity_is_valid": {"result": "success", "reason": null},
      "first_name_match": {"result": "success", "reason": null},
      "last_name_match": {"result": "success", "reason": null},
      "date_of_birth_match": {"result": "success", "reason": null},
      "address_full_address_match": {"result": "success", "reason": null}
    },
    "error": null,
    "timestamp": "2026-04-01T10:10:00Z"
  }
}

{
  "verification": {
    "person": {
      "firstName": "Michael",
      "lastName": "Brown",
      "dateOfBirth": "1975-06-20",
      "email": "m.brown@example.com",
      "phoneNumber": "+61400123456"
    },
    "address": {
      "street": "8 Pitt Street",
      "neighbourhood": "Sydney CBD",
      "city": "Sydney",
      "state": "NSW",
      "postcode": "2000"
    }
  }
}

{
  "verification": {
    "person": {
      "firstName": "Michael",
      "lastName": "Brown",
      "dateOfBirth": "1975-06-20",
      "email": "m.brown@example.com",
      "phoneNumber": "+61400123456"
    },
    "address": {
      "fullAddress": "8 Pitt Street, Sydney CBD NSW 2000"
    }
  }
}

  "AU_CONSUMER": {
    "status": "success",
    "data": {
      "addressElement1": "8 Pitt Street",
      "addressElement3": "Sydney",
      "addressElement4": "NSW",
      "dateOfBirth": "1975-06-20",
      "emailAddress": "m.brown@example.com",
      "firstName": "Michael",
      "lastName": "Brown"
    },
    "validations": {
      "processing": {"result": "success", "reason": null},
      "is_input_valid": {"result": "success", "reason": null},
      "first_name_match": {"result": "success", "reason": null},
      "last_name_match": {"result": "success", "reason": null},
      "date_of_birth_match": {"result": "success", "reason": null}
    },
    "error": null,
    "timestamp": "2026-04-01T10:15:00Z"
  }
}

{
  "verification": {
    "person": {
      "firstName": "Jane",
      "lastName": "Thompson",
      "middleName": "Sarah",
      "dateOfBirth": "1985-07-14"
    }
  }
}

{
  "status": "success",
  "verification": {
    "registryValidations": {
      "AU_ASIC_PERSONAL_NAME_REGISTER": {
        "status": "success",
        "data": {
          "firstName": "Sarah",
          "lastName": "Thompson",
          "middleName": "Jane",
          "dateOfBirth": "1985-07-14"
        },
        "validations": {
          "processing": { "result": "success", "reason": null },
          "consent_obtained": { "result": "success", "reason": null },
          "is_input_valid": { "result": "success", "reason": null },
          "identity_is_valid": { "result": "success", "reason": null },
          "first_name_match": { "result": "success", "reason": null },
          "last_name_match": { "result": "success", "reason": null },
          "date_of_birth_match": { "result": "success", "reason": null },
          "middle_name_match": { "result": "not_applicable", "reason": "input_not_provided" }
        },
        "error": null,
        "timestamp": "2026-04-07T09:30:00.000Z"
      }
    }
  }
}

{
  "verification": {
    "person": {
      "firstName": "Tom",
      "lastName": "Evans",
      "middleName": "Michael",
      "dateOfBirth": "1984-02-24"
    }
  }
}

{
  "status": "success",
  "verification": {
    "registryValidations": {
      "AU_TICA_TENANCY_REGISTER": {
        "status": "success",
        "data": {
          "firstName": "Tom",
          "lastName": "Evans",
          "middleName": "Michael",
          "dateOfBirth": "1984-02-24"
        },
        "validations": {
          "processing": { "result": "success", "reason": null },
          "consent_obtained": { "result": "success", "reason": null },
          "is_input_valid": { "result": "success", "reason": null },
          "identity_is_valid": { "result": "success", "reason": null },
          "first_name_match": { "result": "success", "reason": null },
          "last_name_match": { "result": "success", "reason": null },
          "date_of_birth_match": { "result": "success", "reason": null },
          "middle_name_match": { "result": "not_applicable", "reason": "input_not_provided" }
        },
        "error": null,
        "timestamp": "2026-04-07T09:30:00.000Z"
      }
    }
  }
}

South America

{
  "verification": {
    "person": {
      "firstName": "Carlos",
      "lastName": "Gonzalez",
      "dateOfBirth": "1991-07-14",
      "idNumber": "12345678-9",
      "middleName": "Andrés"
    }
  }
}

  "CL_NATIONAL_ID": {
    "status": "success",
    "data": {
      "dateOfBirth": "1991-07-14",
      "firstName": "Carlos",
      "lastName": "Gonzalez",
      "middleName": "Andrés",
      "nationalIdNo": "12345678-9",
      "nationalIdNoStatus": "VALID"
    },
    "validations": {
      "processing": {"result": "success", "reason": null},
      "is_input_valid": {"result": "success", "reason": null},
      "identity_is_valid": {"result": "success", "reason": null},
      "first_name_match": {"result": "success", "reason": null},
      "last_name_match": {"result": "success", "reason": null},
      "date_of_birth_match": {"result": "success", "reason": null},
      "id_number_match": {"result": "success", "reason": null}
    },
    "error": null,
    "timestamp": "2026-04-01T11:00:00Z"
  }
}

{
  "verification": {
    "person": {
      "firstName": "Valentina",
      "lastName": "Muñoz",
      "middleName": "Isabel"
    },
    "address": {
      "street": "Avenida Libertador Bernardo O'Higgins 1234",
      "city": "Santiago"
    }
  }
}

{
  "CL_RESIDENTIAL": {
    "status": "failure",
    "data": {
      "addressElement1": "Av Libertador Bernardo O'Higgins 1234",
      "firstName": "Valentina",
      "lastName": "Muñoz",
      "middleName": "Isabel"
    },
    "validations": {
      "processing": {"result": "success", "reason": null},
      "is_input_valid": {"result": "success", "reason": null},
      "identity_is_valid": {"result": "failure", "reason": "person_not_found"},
      "first_name_match": {"result": "not_applicable", "reason": "output_not_received"},
      "last_name_match": {"result": "not_applicable", "reason": "output_not_received"}
    },
    "error": null,
    "timestamp": "2026-04-01T11:05:00Z"
  }
}

EMEIA

{
  "verification": {
    "person": {
      "firstName": "William",
      "lastName": "Davies",
      "dateOfBirth": "1982-01-30",
      "phoneNumber": "+447700900123",
      "landLinePhoneNumber": "+442071234567"
    },
    "document": {
      "version": "1"
    },
    "address": {
      "street": "10 Downing Street",
      "neighbourhood": "Westminster",
      "city": "London",
      "state": "England",
      "postcode": "SW1A 2AA"
    }
  }
}

{
  "GB_RESIDENTIAL": {
    "status": "success",
    "data": {
      "addressElement1": "10 Downing Street",
      "addressElement2": "Westminster",
      "addressElement3": "London",
      "addressElement4": "England",
      "addressElement5": "SW1A 2AA",
      "dateOfBirth": "1982-01-30",
      "emailAddress": null,
      "firstName": "William",
      "landlineNumber": "+442071234567",
      "lastName": "Davies",
      "matchedAddress": "10 Downing Street"
    },
    "validations": {
      "processing": {"result": "success", "reason": null},
      "is_input_valid": {"result": "success", "reason": null},
      "identity_is_valid": {"result": "success", "reason": null},
      "first_name_match": {"result": "success", "reason": null},
      "last_name_match": {"result": "success", "reason": null},
      "date_of_birth_match": {"result": "success", "reason": null},
      "address_full_address_match": {"result": "success", "reason": null},
      "phone_number_match": {"result": "success", "reason": null},
      "land_line_phone_number_match": {"result": "success", "reason": null}
    },
    "error": null,
    "timestamp": "2026-04-01T11:10:00Z"
  }
}

{
  "verification": {
    "person": {
      "firstName": "Emma",
      "lastName": "Clark",
      "dateOfBirth": "1995-04-18",
      "email": "emma.clark@example.co.uk",
      "phoneNumber": "+447911123456"
    },
    "address": {
      "street": "25 Baker Street",
      "neighbourhood": "Marylebone",
      "city": "London",
      "state": "England",
      "postcode": "W1U 8EW"
    }
  }
}

{
  "GB_CONSUMER": {
    "status": "success",
    "data": {
      "addressElement1": "25 Baker Street",
      "addressElement3": "London",
      "addressElement4": "Greater London",
      "addressElement5": "W1U 8EW",
      "dateOfBirth": "1995-04-18",
      "emailAddress": "emma.clark@example.co.uk",
      "firstName": "Emma",
      "lastName": "Clark"
    },
    "validations": {
      "processing": {"result": "success", "reason": null},
      "is_input_valid": {"result": "success", "reason": null},
      "first_name_match": {"result": "success", "reason": null},
      "last_name_match": {"result": "success", "reason": null},
      "date_of_birth_match": {"result": "success", "reason": null}
    },
    "error": null,
    "timestamp": "2026-04-01T11:15:00Z"
  }
}

Status and reason codes

For info about the 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, expired, abandoned.

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

1. verification.reason for the reason why the verification failed.

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

The table above aims to list the most common reasons why you may see the decline or resubmission_requested reason for a Metadata Database Verification session. However, the session may be declined due to a reason that is not inherently related to this solution's flow (e.g. uploaded document's quality is low). In that case, to find info about the codes you are seeing, refer to:

• Granular reason codes (table)

• Verification session status codes (table)

• Verification session decision codes (table)

Additional data

Best practices

1. In API flow, ensure that initData is present, especially the mandatory fields.

2. Ensure correct data formats to reduce the possibility of session going to resubmission_requested.

3. Document image quality: ensure that end-user's document image is of good quality. This will reduce the possibility of session going to resubmission_requested.

4. Person's ID number is always sent in the document.number parameter (not person.idNumber).

5. Error handling: implement proper error handling for all possible validation results.

6. Session declined due to third-party provider issues: implement proper session handling flow when possibly legitimate end-user's session is declined due to the third-party service provider having issues, as indicated by session code registry_unavailable, technical_issue, or registry_timeout.

7. Webhook security: secure your webhook endpoint and verify request signatures.

8. User experience: provide clear feedback to users about validation results.

9. Ensure backwards compatibility for webhooks and API connections.

FAQ

Changelog