GBG Developers

Guides   |   How Identity Solution APIs work: Decision Handling

How Identity Solution APIs work: Decision Handling


The Identity Solution API returns decisions in detailed and summary form. These results are available per API call, and also in a combined form from multiple API calls. For ease of use, the three overall PASS, FAIL and REFER outcomes can be used to indicate to the application the branch of logic that should be taken to handle the customer. The REFER decision indicates that more checks are needed to verify the customer.

In summary, your application generally just needs to examine the combined field in the returned content, and look to see if it contains a PASS, FAIL or REFER decision. In some cases an UNDETERMINED response may arrive, generally that happens when only one API call has been made so far.

The combined field provides a decision that can only be a pass if all previous API calls related to the individual being verified passed too. The Identity Solution will combine results in this manner whenever a person identifier field is passed to subsequent API calls. The first API call will always return a person identifier that can be used in subsequent API calls. If you have verified a document then a returned document verification identifier also may need to be passed to subsequent API calls.

If the decision is REFER, then you can get the customer to scan additional documents or provide more information to achieve a pass decision, or you may choose for an agent to handle the interaction if the customer is missing documentation, if it proves impossible to achieve the pass decision.

There is also a score field which can be useful during troubleshooting or for providing a verification strength indicator beyond the configured pass/fail/refer setting in the Identity Solution configuration that you are using. The field indicates the cumulative score based on the configuration being used. When used for troubleshooting, the score can sometimes reveal the underlying verification mechanism if certain score results are seen.

Note that these examples may change; refer to the API documentation for the precise format for the API version that you’re using. These examples are for informational purposes only.

  1. Combined decision on first API call
    The result shown here is typical for a first API call when handling a customer. Since only one API call has been made, no pass or fail combined result can occur yet, and instead the REFER decision indicates that further API calls will need to be made if the combined decision is required.

    "decision": {
        "current": "REFER"
        "combined": "UNDETERMINED"

    Earlier API versions returned the decision in this format:

    "combined": {
        "decision": "REFER"

  2. Combined decision after multiple API calls
    The combined object below can only indicate a pass result if at least two API calls were made, all with pass results, and the person identifier that was returned from the first call was used on the subsequent calls for verifying additional data or documents belonging to the customer. Here a successful PASS decision has been made, and the application can now move the customer forward successfully.

    "decision": {
        "current": "PASS"
        "combined": "PASS"

    Earlier API example response:

    "combined": {
        "decision": "PASS"