Verification Limit

In this guide, we’ll go through the necessary steps to set a Verification Limit on your program. The end result is a program configured to return errors when the defined limit is reached.

Overview

The Verification Limit feature is used to set a program’s policy on the number of successful verifications allowed for a particular individual over a period of time, for example, once per 180 days. An individual is defined by their First Name, Last Name and Date of Birth.

Once the limit is set on your program the API will refuse to process verification requests not allowed by the policy, returning an error code instead. By default no Verification Limit is defined.

Establish Verification Limit

To set a Verification Limit on your program, use the verificationLimit POST request. The schema is:

Request:

POST /rest/v2/program/<YOUR_PROGRAM_ID>/verificationLimit HTTP/1.1
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

{
    "quantity": 5,
    "days": 30
}

A successful request will return a 200 OK ressponse:

HTTP/1.1 200 OK
Content-Type: application/json

Request Parameters

quantity: integer, The number of verifications to allow in a given time period.
days: integer, The number of days for which the verification limit should be enacted.

Example:

Set a limit of 1 verification per person per 180 days:

POST /rest/v2/program/<YOUR_PROGRAM_ID>/verificationLimit HTTP/1.1
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

{
    "quantity": 1,
    "days": 180
}

Once set, the API will return a 429 Too Many Requests error, with a message indicating that the user has exceeded the program’s verification limit quantity for the defined period.

Remove and Change Verification Limit

Once a policy is set on a program you may not use the verificationLimit POST request to change a limit. Doing so will result in a 409 error code: Verification limit already exists.

To change the Verification Limit on your program, you must first remove the existing limit with the verificationLimit DELETE request to remove a limit.

Example:

DELETE /rest/v2/program/<YOUR_PROGRAM_ID>/verificationLimit HTTP/1.1
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

A successful request will return a 200 OK response:

HTTP/1.1 200 OK
Content-Type: application/json

Once the limit is deleted you can add a new Verification Limit using the verificationLimit POST request again.