# With KBA Quiz

## AgeMatch5.0.KBA

<mark style="color:green;">`POST`</mark> `https://production.idresponse.com/process/comprehensive/gateway`

Make an **HTTPS POST** request with the following body parameters to find out if the target has provided valid identity attributes and to receive the quiz to present. You will receive a synchronous response in 2-3 seconds with a **result** object that includes an **action, detail** and **issues object**. If any of the provided identity attributes provided did not match you will know during this initial call. \
\
Then present the quiz to the user and take their answers and populate them in the **template** object provided and make a second POST request to get the final result with quiz score.&#x20;

#### Request Body

| Name                                      | Type   | Description                                                        |
| ----------------------------------------- | ------ | ------------------------------------------------------------------ |
| user<mark style="color:red;">\*</mark>    | string | Your account's API username                                        |
| pass<mark style="color:red;">\*</mark>    | string | Your account's API password                                        |
| service<mark style="color:red;">\*</mark> | string | The service name (IDMatchPLUS5.0.MULTI)                            |
| reference                                 | string | A unique identifier for your customer                              |
| target<mark style="color:red;">\*</mark>  | object | The individual being sent for verification                         |
| fn<mark style="color:red;">\*</mark>      | string | The target's first name                                            |
| ln<mark style="color:red;">\*</mark>      | object | The target's last name                                             |
| addr<mark style="color:red;">\*</mark>    | string | The target's street address (line 1 and line 2)                    |
| city                                      | string | the target's city                                                  |
| state                                     | string | The target's state                                                 |
| zip<mark style="color:red;">\*</mark>     | string | The target's zip                                                   |
| dob                                       | string | The target's Date of Birth (YYYYMMDD format)                       |
| ssn                                       | string | The target's SSN (either 4 or 9)                                   |
| phone                                     | string | The target's phone number                                          |
| email                                     | string | The target's email address                                         |
| age<mark style="color:red;">\*</mark>     | string | The age to check (must be sent like "age+" i.e. "18+", "21+" etc.) |
| test\_key                                 | string | The test key value that you are using to test                      |

{% tabs %}
{% tab title="200 Transaction processed and result returned" %}

```javascript
{
  "output": {
    "questions": {
      "questions": [
        {
          "prompt": "With which of the following states are you or have you been associated?",
          "type": "state",
          "id": "state1",
          "answers": [
            {
              "text": "VERMONT"
            },
            {
              "text": "NORTH DAKOTA"
            },
            {
              "text": "SOUTH DAKOTA"
            },
            {
              "text": "WISCONSIN"
            },
            {
              "text": "None of the above"
            }
          ]
        },
        {
          "prompt": "Which of the following addresses are in Green Bay?",
          "type": "address",
          "id": "address3",
          "answers": [
            {
              "text": "11 157 STREET"
            },
            {
              "text": "170 WEAVER ST"
            },
            {
              "text": "87 EAST BROADWAY BLVD"
            },
            {
              "text": "6 PRICE ROAD"
            },
            {
              "text": "None of the above"
            }
          ]
        },
        {
          "prompt": "With which of the following zip codes are you or have you been associated?",
          "type": "zip5",
          "id": "zip52",
          "answers": [
            {
              "text": "54420"
            },
            {
              "text": "54155"
            },
            {
              "text": "54551"
            },
            {
              "text": "54807"
            },
            {
              "text": "None of the above"
            }
          ]
        },
        {
          "prompt": "With which of the following cities are you or have you been associated?",
          "type": "city",
          "id": "city0",
          "answers": [
            {
              "text": "STREETSBORO"
            },
            {
              "text": "SAINT JOHN"
            },
            {
              "text": "FORT MORGAN"
            },
            {
              "text": "WEST ALLIS"
            },
            {
              "text": "None of the above"
            }
          ]
        }
      ]
    }
  },
  "meta": {
    "confirmation": 21185214,
    "reference": "12345",
    "service": "AgeMatch5.0.KBA",
    "timestamp": "2017-08-08 14:25:02",
    "company": "Veratad Technologies, LLC",
    "user": "user@veratad.com"
  },
  "result": {
    "action": "PENDING",
    "detail": "MORE INFORMATION IS REQUIRED",
    "issues": []
  },
  "continuations": {
    "questions": {
      "url": "/process/continue",
      "template": {
        "token": "2nypwsj51mzhjvm7cr1hbyaabqm67qcc",
        "answers": {
          "zip52": [],
          "state1": [],
          "address3": [],
          "city0": []
        }
      },
      "instructions": "Add the text of the answers into the empty list for the appropriate question (case sensitive)."
    }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Use the test\_key attribute to test the service. When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. The below sample request is one of the available test cases. To access more click the link below.
{% endhint %}

{% content-ref url="../testing-1/additional-test-cases" %}
[additional-test-cases](https://api.veratad.com/testing-1/additional-test-cases)
{% endcontent-ref %}

## Sample Request Body

{% hint style="info" %}
This is the initial query to get the quiz. See below example of how to submit the answers for final scoring and evaluation.&#x20;
{% endhint %}

```javascript
{
      "user": "USERNAME",
      "pass": "PASSWORD",
      "service": "AgeMatch5.0.KBA",
      "rules": "A_RULESET_ID",
      "reference": "12345 {A UNIQUE ID}",
      "target":{
            "fn":"Barbara",
            "ln": "Miller",
            "addr": "123 Main St",
            "city": "Stratford",
            "state": "CT",
            "zip": "06614",
            "dob": "19740821",
            "ssn": "854125698",
            "phone": "2015106000",
            "email": "bmiller@veratad.com",
            "age": "21+",
            "test_key": "general_identity"
          }
  }
```

## Request with Quiz Answers

Once your user has answered the questions, send those answers back to the system for scoring and a final evaluation.&#x20;

## Submit Answers

<mark style="color:green;">`POST`</mark> `https://production.idresponse.com/process/continue`

Sending a POST request with the below body will give you the final evaluation of the quiz and other identity attributes.&#x20;

#### Request Body

| Name    | Type   | Description                                                                             |
| ------- | ------ | --------------------------------------------------------------------------------------- |
| token   | string | The token that was returned in the initial response that relates to this specific quiz. |
| answers | object | The answers object should include each question asked and the user's answer.            |

{% tabs %}
{% tab title="200 The result of the question and identity evaluation. " %}

```javascript
{
  "final": {
    "template": {
      "token": "euwd6q5a8b4c0vwc0zy0s6ms1mjh5p0s"
    },
    "url": "/process/status"
  },
  "output": {
    "answers": {
      "asked": 4,
      "correct": 0
    }
  },
  "result": {
    "action": "REVIEW",
    "detail": "TRANSACTION REQUIRES FURTHER ATTENTION",
    "issues": [
      "QUESTION CHECK FAILED"
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Sample Request Body - Quiz Score

```javascript
{
  "answers": {
    "state3": ["NEW YORK"],
    "mothers_maiden0": ["None of the above"],
    "phone1": ["(206) 393-4478"],
    "county2": ["FAIRFIELD"]
  },
  "token": "1bauxkpczhdiyy3vqm15ais8ue12u7zw"
}
```

## Action and Detail Responses

{% hint style="info" %}
The following are all values that will be returned in the result object of the response.
{% endhint %}

| Action  | Detail                       | Description                                                                                              |
| ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| FAIL    | NO MATCH                     | No matching identity found in the data sources                                                           |
| FAIL    | AGE NOT VERIFIED             | Target found, but no DOB information available                                                           |
| FAIL    | TARGET IS DECEASED           | Target found as a deceased identity                                                                      |
| FAIL    | POSSIBLE MINOR               | Target found, but a minor age detected                                                                   |
| FAIL    | QUESTION CHECK FAILED        | The user did not answers at least 3/4 questions correct.                                                 |
| FAIL    | QUIZ NOT GENERABLE           | The target did not have enough data to generate a quiz.                                                  |
| PENDING | MORE INFORMATION IS REQUIRED | Target was found is not deceased and meets the age requirement, but they have not yet answered the quiz. |
| PASS    | ALL CHECKS PASSED            | Target was found is not deceased, passed the verification quiz and meets the age requirement             |

## Rules

AgeMatch with KBA will process with the default base ruleset:

{% hint style="success" %}
The base ruleset will return a PASS when:

* A match is found
* The target is not deceased
* The target meets the age requirement
* The user has answered at least 3/4 questions correct
  {% endhint %}

{% hint style="info" %}
The base ruleset will return a PENDING when:&#x20;

* A match found&#x20;
* The target is not deceased&#x20;
* The age requirement is met&#x20;
* Questions are returned, but not answered yet
  {% endhint %}

{% hint style="danger" %}
The base ruleset will return a FAIL when:

* A match is not found or
* The target is deceased or
* The target does not meet the minimum age requirement&#x20;

In this case no questions will be provided.&#x20;
{% endhint %}

## API Processing Error Returns

{% hint style="info" %}
Each token is only valid for 300 seconds with this service. See the error responses to get information on what happens if a token is bad or expired.&#x20;
{% endhint %}

{% content-ref url="../api-processing-errors/error-returns" %}
[error-returns](https://api.veratad.com/api-processing-errors/error-returns)
{% endcontent-ref %}