GBG Developers

Guides   |   Verify Document

Verify Document

Our Verify Document service gives you the ability to enhance the experience of your users by accepting images of documents and using them to perform validations as part of your collection of verification checks.

What does verify document do?

Verify document allows you to submit images of the identifying documents of your end users, check them for tampering and other fraudulent activities and extract the data contained within them.

Where a document has multiple pages, or multiple sides containing required information you can submit multiple images and create a collection of images to verify against. Additional pages can be appended to a document up to seven days after the initial load, using the document-id returned from the first call.

You can then view images outlining the analysis of these documents within your audit trail records.


How does verify document work?


The Request

The verify document service allows you to specify a level of tolerance in the 'tolerance' header of the request. The tolerance options are 'DEFAULT', 'MEDIUM', and 'STRICT'. The stricter you are with the tolerance level the more likely a document is to be rejected by the service.

Images are submitted to the service using a POST request, supplying your image as multipart/form-data.

The Person Id

If this is the first request you are making in a series of verification requests that relate to a single user, you do not need to supply a person-id, and one will be created for you by IDAAS and returned in the response headers with the key 'person-id'. You should use this id for each subsequent request you make to any of the verification services. This will allow IDAAS to combine these verifications into a single record and perform actions such as combined scoring

If you have already performed other verification checks and already have a person-id, this should be supplied in a header with the name 'person-id'. For more information on where and how to supply a person-id, see our API Reference Documentation.

The Response

Identifiers for this specific verification request, and your submitted documents are returned in response headers, named 'verification-id' and 'document-id'. These can be used with the verification history API to retrieve your submitted requests at a later date. Your document-id will be required for performing further checks that rely on the document such as facematch. The address returned in a Verify Document response will have been cleansed, so subsequent requests (such as Verify Person) should set the cleanse-address header to false.

A successful response will contain the following schema:

  "verificationID": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
  "timestamp": "2019-01-04T14:38:25Z",
  "customerReference": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
  "verification": {
    "derivedData": {
      "isRecognised": true,
      "person": {
        "title": "Mr",
        "firstName": "David",
        "middlenames": [
        "lastnames": [
        "gender": "MALE",
        "birthdate": "2000-01-01",
        "address": {
          "extracted": "string",
          "enrichment": {
            "cleansed": {
              "lines": [
              "address": "string",
              "premise": "128",
              "building": "string",
              "subBuilding": "string",
              "thoroughfare": "Queen Victoria Street",
              "dependentThoroughfare": "string",
              "locality": "London",
              "dependentLocality": "string",
              "doubleDependentLocality": "string",
              "postalCode": "EC4V 4BJ",
              "postBox": "string",
              "country": "GBR",
              "superAdministrativeArea": "string",
              "administrativeArea": "string",
              "subAdministrativeArea": "string",
              "organization": "GB Group",
              "quality": {
                "avc": "string",
                "aqi": "string"
              "location": {
                "latitude": "string",
                "longitude": "string",
                "geoAccuracy": "string"
      "fields": [
          "id": "string",
          "name": "string",
          "type": "string",
          "description": "string",
          "value": "string"
      "images": [
          "type": "DIGITAL_TAMPERING_HEAT_MAP",
          "imageUrl": "string",
          "imageID": "string",
          "base64Image": "string"
      "classification": {
        "type": "string",
        "category": "string",
        "name": "string",
        "issue": "string",
        "issuingAuthority": "string"
    "result": {
      "function": "VERIFY-PERSON",
      "state": "string",
      "score": 0
  "triangulation": {
    "response": {
      "resultCode": 20,
      "resultDescription": "20 - same address and same person (independent of address)"
  "combined": {
    "decision": "string"
  "action": "string",
  "links": [
      "href": "string",
      "rel": "string"

What next?

To implement the verify person API, find detailed API information in our API Reference.