Retrieve granular check result data

This guide demonstrates how to retrieve granular result data for a check using our API. This is currently supported for Photo ID checks and for identity checks carried out by Experian. By accessing detailed information via the Retrieve a Check endpoint, you can build more advanced automation or decisioning flows based on specific check outcomes.

WARNING

Check responses are still in beta. Available data may be incomplete or differ from the specification. Contact developers@amiqus.co to report inconsistencies.

Prerequisites

• Amiqus API credentials: Ensure you have valid credentials to authenticate your requests.
• Check type support: Granular data is returned for Photo ID checks and Experian identity checks. Experian identity checks may not be enabled for all teams. Other check types return a placeholder response for now (see Handling the response).
• Valid record ID: You will need a valid record ID associated with a supported check.

Overview of the flow

Below is a sequence diagram illustrating the process:

Step-by-step guide

1. List all steps for a record

Begin by calling the List all steps for a client record endpoint, using the record ID you wish to inspect. The response will include an array of step objects. Identify the step with a type of check.photo_id or check.identity, which will contain either the check object or a reference to the check ID.

2. Retrieve the check

Once you have the relevant check ID (either directly from the step object or via its embedded check), call the Retrieve a check endpoint using that ID. Make sure to include the expand=response query parameter to retrieve the detailed result data.

https://id.amiqus.co/api/v2/checks/123?expand=response

Without expand=response, the response property is true when a response is available to expand, and null when there is none yet (for example, while the check is still pending).

Handling the response

The shape of the expanded response depends on the check. Use response.object to tell them apart:

response.object	Check	Contents
check_response.photo_id	Photo ID	Reports and their breakdowns
check_response.identity	Identity	Provider-specific verdicts, identified by provider
check_response.other	Any other check	No granular data yet

Photo ID

A Photo ID response has an overall status and result (clear or consider), and a list of reports. Depending on how the check was configured, these can include:

• Document reports: document type and issuing country, data comparison and consistency, expiry dates and extracted fields
• Facial similarity reports: match outcomes and liveness detection (if applicable)
• eVisa reports for right to work checks: the eVisa details, with a breakdown of name and image match, conditions, restrictions, and start and expiry dates. eVisa reports may not be enabled for all teams. The eVisa report is for a person to review. It doesn't affect the check's overall status, which comes from the document and facial similarity reports.

Each report has its own result, and if any breakdown is not clear, the report's result is consider.

Identity

Identity checks can be carried out by more than one provider, and each provider returns a different shape. Check provider before reading the rest of the response. Currently, the only identity provider with a granular response is experian.

An Experian response contains a verdicts object with up to two verdicts, depending on your team's workflow:

• identity: whether Experian matched the person against its records
• warnings: whether Experian holds anything that counts against the person (contra-indicators)

Each verdict has:

• decision: continue, refer or stop
• reason: Experian's one-line summary, such as Identity verified, or null when none was returned
• rules: the rules that fired, each with an id and Experian's text, or null when none did

The two verdicts are independent, and either can refer or stop the check. For example, a person can be fully verified under identity while warnings refers because a contra-indicator was raised. verdicts is null when Experian returned neither.

{
  "object": "check_response.identity",
  "provider": "experian",
  "verdicts": {
    "identity": {
      "decision": "continue",
      "reason": "Identity verified",
      "rules": [
        {
          "id": "5200",
          "text": "Two or more Primary or Secondary Data Sources with a name and address and DoB"
        }
      ]
    },
    "warnings": {
      "decision": "continue",
      "reason": "No Contra-indicator alerts",
      "rules": null
    }
  }
}

The rules under a continue identity verdict are the evidence Experian matched on, not findings against the person. Under a stop verdict, they record what was missing.

Other check types

Checks whose response is not yet available from the API return { "object": "check_response.other" }. Your integration should handle this, and any object or provider value it does not recognise, without failing, as support for more checks and providers is added over time.

What happens next?

After retrieving the check data:

• Log and audit: Store the granular results as needed for audit trails or compliance evidence.
• Automate decisions: Use result fields to update internal systems, trigger workflows, or flag checks for manual review.
• Prepare for future automation: In future releases, we aim to add granular data for more check types and providers, and enable status automation for clients and records based on check outcomes.

By following this guide, you can make full use of the granular data available for Photo ID and identity checks, enhancing your automation capabilities and improving the transparency of your verification flows.