Run a Document fetch check for GBG IDscan (GB built) using the API

Abstract

Learn how to run a Document fetch check using GBG IDscan in Maxsight API 4.0, including creating or selecting a profile, confirming required fields, sending the request, and retrieving results through webhooks.

Prerequisites

To run a Document fetch check in the Maxsight API 4.0, you must have:

Configured your smart policy to include the Document fetch check (DOCUMENT_FETCH), which is called ID verification (service collects documents) in the front end, using GBG IDscan (GB built) as the data provider.
Included this check as an acceptance check on the Verify identity (INDIVIDUAL_VERIFY_IDENTITY) or Verify address (INDIVIDUAL_VERIFY_ADDRESS) task.

This guide explains how to run a Document fetch check in the Maxsight API 4.0 when using GBG IDscan (GB built) as the data provider. In the portal, this check is called ID verification (service collects documents). It retrieves the results of an ID verification journey completed with GBG, and uses them to determine whether the check passes or fails in Maxsight.

This check can be run on the following tasks:

Verify identity task (INDIVIDUAL_VERIFY_IDENTITY)
Verify address task (INDIVIDUAL_VERIFY_ADDRESS)

Create or select a profile

This check is always run on profiles with the INDIVIDUAL entity type.

If you haven't created the profile yet, follow the steps to create a profile through the API. Note the profile id returned in the response, for example, a2c4393a-e219-67a4-5ab4-2186952e9038.

You can also create a profile through the portal. To get the profile id, view the profile in the portal and copy the string of letters and numbers after /profiles/ in the URL.

Confirm the profile has the required fields for the check

To see all data on the profile, make a request to the following endpoint.

Request endpoint:

GET https://{api_region}/4.0/profiles/{profile_id}

Replace {api_region} with the API URL specific to your region. Use api.us.maxsight.com for the US region, api.eu.maxsight.com for the EU region, or api.ae.maxsight.com for the UAE region.

In this example, data is returned for an individual profile named "Alex Wheeler." The profile has the Verify identity and Verify address tasks.

Sample response:

{
    "applications": [ … ],
    "category": "APPLICANT",
    "checks": [ ],
    "collected_data": {
        "entity_type": "INDIVIDUAL",
        "address_history": [
            {
                "address": {
                    "type": "STRUCTURED",
                    "country": "GBR",
                    "locality": "London",
                    "original_freeform_address": "Crown, 38, Street, London, W1 2ZT",
                    "original_structured_address": { … },
                    "postal_code": "W1 2ZT",
                    "route": "Street",
                    "street_number": "38",
                    "subpremise": "Crown"
                }
            }
        ],
        "contact_details": { },
        "personal_details": {
            "dob": "1975-04-19",
            "name": {
                "family_name": "Wheeler",
                "given_names": [
                    "Alex"
                ]
            },
            "national_identity_number": { },
            "nationality": "GBR"
        }
    },
    "collection_steps": [ ],
    "creation_date": "2025-10-03 13:48:16",
    "display_name": "Alex Wheeler",
    "document_images": [ ],
    "events": [ ],
    "has_associates": false,
    "has_collection_steps": false,
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "linked_to": [ ],
    "role": "INDIVIDUAL_CUSTOMER",
    "root_id": "6bba3592-d9de-1ee5-8e97-ba8d8d13c558",
    "status": "NORMAL",
    "tags": [ ],
    "task_progress": { … },
    "task_types": [
        "INDIVIDUAL_VERIFY_IDENTITY",
        "INDIVIDUAL_VERIFY_ADDRESS"
    ],
    "tasks": [
        {
            "check_ids": [ ],
            "creation_date": "2025-10-03 13:48:16",
            "form_instance_ids": [ ],
            "id": "3d7a333c-418d-72a1-007b-06854dbb28eb",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "INDIVIDUAL_VERIFY_IDENTITY",
            "variant": {
                "alias": "verify_identity",
                "id": "ddc72ea7-6e45-cc3b-dc52-30a94b9ec8c2",
                "name": "Verify identity",
                "task_type": "INDIVIDUAL_VERIFY_IDENTITY"
            }
        },
        {
            "check_ids": [ ],
            "creation_date": "2025-10-03 13:48:16",
            "form_instance_ids": [ ],
            "id": "72aadb55-8b02-8495-d6b0-e1627ec23612",
            "is_complete": false,
            "is_expired": false,
            "is_skipped": false,
            "state": "INCOMPLETE",
            "type": "INDIVIDUAL_VERIFY_ADDRESS",
            "variant": {
                "alias": "verify_address",
                "id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
                "name": "Verify address",
                "task_type": "INDIVIDUAL_VERIFY_ADDRESS"
            }
        }
    ],
    "unresolved_event_types": [ ]
}

Use the response to:

Confirm the profile has the type of task you want to run the check on. To run this check on the Verify address task, the profile must have a task with the INDIVIDUAL_VERIFY_ADDRESS type. To run this check on the Verify identity task, the profile must have a task with the INDIVIDUAL_VERIFY_IDENTITY type.
Take note of the corresponding task ID (tasks.id). Use the corresponding task alias (tasks.variant.alias) to confirm that you're looking at the right task. If there is more than one task with the same alias, which happens when a task has more than one version, use the task with "is_expired": "false". Note that the task variant ID (tasks.variant.id) won't be used to run this check, so you don't need to take note of it.
Confirm the profile has data for these required keys, which are stored in the collected_data object:
- personal_details.name.given_names: The individual's first and (if applicable) middle names.
- personal_details.name.family_name: The individual's surname.
- address_history: An array of objects containing the individual's addresses. Note that this field is only required when you're running the check on the Verify address task.

If the required fields don't exist or contain invalid data, running the check returns an error.

Run the check

To run the check, send a request to the following endpoint.

Request endpoint:

POST https://{api_region}/4.0/profiles/{profile_id}/checks

Replace {api_region} with the API URL specific to your region. Use api.us.maxsight.com for the US region, api.eu.maxsight.com for the EU region, or api.ae.maxsight.com for the UAE region.

By default, the check will run asynchronously. You can also send mode as a query parameter to run the check synchronously.

Note that if a response is not received from GBG IDscan within 120 seconds, the mode will switch to asynchronous automatically, so you should always support asynchronous checks.

Body parameters:

When you make the POST request, include the following parameters in the body.

Key	Value	Description
`check_type` *Required string	`DOCUMENT_FETCH`	The type of check that's being run.
`source` *Required string	`GENERIC`	Identifies the data provider source.
`reference` *Required string	Sample value: `7c77bff5-a4b3-42d8-b39f-e0d2d8213497`	The Journey ID, provided by GBG IDscan upon completion of the individual's ID verification journey through the GBG SDK interface. The GBG professional services team can advise on obtaining this value.
`category` Optional string	`PROOF_OF_ADDRESS` or `PROOF_OF_IDENTITY`	The category of the document. You should send `PROOF_OF_ADDRESS` when the check is run on the Verify address task and `PROOF_OF_IDENTITY` when the check is run on the Verify identity task. When the category is `PROOF_OF_ADDRESS`, part of the pass criteria of the check is that the address extracted from the document must match the address in the profile. If you do not send this key, Maxsight uses the `PROOF_OF_IDENTITY` category.
`task_ids` Optional string	Sample value: `72aadb55-8b02-8495-d6b0-e1627ec23612`	Array of strings where each string is a unique identifier for a task the check will run on. While this key is optional, we strongly recommend including it in your request. If you do not send this key, Maxsight runs the check on the Verify identity task.
`variant` *Required object	For a sample value, see the following sample request body.	Object to indicate which variant of the check will run.

Sample request body:

{
    "check_type": "DOCUMENT_FETCH",
    "source": "GENERIC",
    "reference": "7c77bff5-a4b3-42d8-b39f-e0d2d8213497",
    "category": "PROOF_OF_IDENTITY",
    "task_ids": [
        "72aadb55-8b02-8495-d6b0-e1627ec23612"
    ],
    "variant": {
        "alias": "GBG_verification"
    }
}

Sample response:

{
    "check_type": "DOCUMENT_FETCH",
    "source": "GENERIC",
    "id": "a2c4393a-e219-67a4-5ab4-2186952e9038",
    "reference": "7c77bff5-a4b3-42d8-b39f-e0d2d8213497",
    "category": "PROOF_OF_IDENTITY",
    "input_data": {
        "address_history": [ … ],
        "entity_type": "INDIVIDUAL",
        "personal_details": { … },
        "nationality": "GBR"
    },
    "instructed_on": "2025-11-05 17:01:13",
    "performed_on": "2025-11-05 17:01:13",
    "started_on": "2025-11-05 17:01:13",
    "deadline": "2025-11-08",
    "providers": [ … ],
    "state": "RUNNING",
    "task_ids": [
        "72aadb55-8b02-8495-d6b0-e1627ec23612"
    ],
    "variant": { … }
}

Get the check result

Listen to the Check completed webhook to get a notification when the check is finished running and to learn what the result is.

This webhook sends a payload whenever results are returned from any check.

Payloads from this webhook have several important keys:

secret: Authenticate the request by ensuring this secret matches your secret.
id: The check ID. Use it to confirm the payload is for your check by matching it to the check ID you captured earlier.
check_type: The type of check that was run.
variant.alias: The alias for the check variant. You can use it for additional confirmation that the payload is for your check by matching it to the check variant alias you captured earlier.
result: The value for this key indicates the result of the check. To learn more about the results, see About GBG IDscan (GB built).

Sample payload:

{
    "id": "33bae6b8-5689-b96b-143c-06e93ab8527e",
    "event": "CHECK_COMPLETED",
    "secret": "yourSecret",
    "timestamp": 1573048450,
    "data": {
        "check": {
            "check_type": "DOCUMENT_FETCH",
            "id": "ea565b55-47d9-1858-4588-3a22a3838707",
            "result": "Pass",
            "variant": {
                "alias": "GBG_verification",
                "id": "ea70ade9-3de3-1785-203b-68044cd3ecbb",
                "name": "GBG IDscan"
            }
        },
        "customer_ref": null,
        "profile_id": "a2c4393a-e219-67a4-5ab4-2186952e9038"
    }
}

The check returns one of three results:

Pass: data.check.result is Pass. GBG IDscan returns a pass result and the extracted details match the entity details in Maxsight.
Fail: data.check.result is Fail. GBG IDscan returns a refer, expired, not accepted, not supported, or undefined result, or the extracted details don't match the entity details in Maxsight.
Error: data.check.result is Error. Required fields are missing from the Maxsight entity data, or an issue occurs with the integration.

Additional information

In this section: