Policy Decision in /slverify

In a verification workflow, the output of any /slverify request will include a policyDecision attribute.

The policyDecision attribute should be used to determine the next steps for a user in the flow. This is covered in detail here.

Policy Decision in API

In addition to the general guidance on the Policy Decision overview page, there are a few details to consider in the API representation of Policy Decision.

Obligation details

In the Verify API, if you receive a policy decision of obligation, you will also receive details on what to do next. This is through 2 attributes: policyObligation and forwardApiKey.

Example:

{
    //IDW API Output
  "forwardApiKey": "123456",
    "policyObligation": true,
    "policyDecision": "obligation"
}

In the above example:

  • policyDecision is set to obligation. This means additional steps are required in this workflow.
  • policyObligation is set to true. This means there is a registered next step configured for this service.
  • forwardApiKey is set to the value of the next API key in the workflow.

Your software should use this as a trigger to determine how to proceed with this user.

For example - API Key 123456 above may be for an additional PII verification step, in which case your app should load the appropriate UI and next step for the user. Once the additional data is collected, you should submit the required data back to the ID DataWeb API, and add map the value of forwardApiKey from the response to the apikey value in the input, as described here.

Retries

If the following are true:

  • user did not pass verification
  • your policy is set to to allow retires
  • there are retry attempts available

Then the Verify API will respond with an obligation to the same API key which was just processed. This means - your service has an obligation to retry this particular API key.

{
    //IDW API Output
  "forwardApiKey": "123456", //same API key as you are currently on. 
    "policyObligation": true,
    "policyDecision": "obligation"
}

Once the user runs out of retry attempts, the API will respond with the appropriate next step, for example "deny" or "obligation" to a different API key. Your app should interpret this, and follow the next steps accordingly.