What are synchronous and asynchronous checks?

Checks have two modes:

Synchronous: When the check is run, the results are returned from the data provider immediately. You can see the result in the response from the call to run the check.
Asynchronous: The results are not returned from the data provider immediately. The response from the call to run the check will return PENDING or RUNNING as the state. Listen to the Check completed webhook to find out when the result has been returned, and make a call to Get the results of a specific check.

This only applies to checks you're running via the API. It does not apply to checks run by the smart policy.

How do you set the check mode to be synchronous or asynchronous?

To specify whether the check should run synchronously or asynchronously, send the mode query parameter when you make the request to run the check.

To run the check synchronously, send the mode as sync.
To run the check asynchronously, send the mode as async.

If you do not send the mode parameter, Identity checks will run synchronously and all other checks will run asynchronously.

If you run a check synchronously but a response is not received from the data provider within 120 seconds, the mode will switch to asynchronous automatically. This means you should support asynchronous checks, even if you intend to run checks synchronously.

Not all data providers guarantee a check response with 120 seconds. For example, idvcheck assigns specialists to verify documents manually, which takes longer. To learn more about guaranteed response times, speak to your data provider. To learn more about running a check, see Run a check in the developer resources.

Example: Synchronous check

Below is an example of an Identity check run synchronously.

We can see in the response that the check has finished running because the state is COMPLETE.

The response also contains the check result. In this case, the check passed and an overall result of 2+2 was achieved.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/checks?mode=sync

Sample request body:

{
    "check_type": "IDENTITY_CHECK",
    "task_ids": [
        "3d7a333c-418d-72a1-007b-06854dbb28eb"
    ],
    "variant": {
        "alias": "provider"
    }
}

Sample response:

{
    "check_type": "IDENTITY_CHECK",
    "completed_on": "2020-03-18 14:33:23",
    "decision": "PASS",
    "errors": [ ],
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "input_data": { … },
    "instructed_on": "2020-03-18 14:33:23",
    "output_data": { … },
    "performed_on": "2020-03-18 14:33:23",
    "providers": [ … ],
    "result": "2+2",
    "started_on": "2020-03-18 14:33:23",
    "state": "COMPLETE",
    "task_ids": [ … ],
    "variant": { … }
}

Example: Asynchronous check

Below is an example of the same check run asynchronously.

We can see in the response that the check has not been instructed yet because the state is PENDING. Note that if the check has been instructed, the state will be RUNNING.

To find out when a check has finished running, listen to the Check completed webhook.

If a check is PENDING, it will be instructed automatically. After the Check completed webhook has sent a payload to say the check is finished running, you can get more information about the check results by making a call to get the results of Get the results of a specific check.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/checks?mode=async

Sample request body:

{
    "check_type": "IDENTITY_CHECK",
    "task_ids": [
        "3d7a333c-418d-72a1-007b-06854dbb28eb"
    ],
    "variant": {
        "alias": "provider"
    }
}

Sample response:

{
    "check_type": "IDENTITY_CHECK",
    "id": "ea565b55-47d9-1858-4588-3a22a3838707",
    "instructed_on": "2020-03-18 14:33:23",
    "performed_on": "2020-03-18 14:33:23",
    "providers": [ ],
    "state": "PENDING",
    "started_on": "2020-03-18 14:33:23",
    "task_ids": [ … ],
    "variant": { … }
}

In this section:

Using Passfort