> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge-based Authentication

Authenticates a US subject by asking questions drawn from their identity records, one question at a time, and returns PASSED, FAILED or NOT\_FOUND. Needs the subject's name and full US address; date of birth improves the match.

This page documents the **Knowledge-based Authentication** module, including its variants, capabilities, and the result values it returns.

## Knowledge-based Authentication: Knowledge-based Authentication

Performs Knowledge-Based Authentication

### Capabilities

The module returns the following capabilities.

#### Authentication result

Result of the KBA quiz

| Code | Label | Description |
| - | - | - |
| `PASSED` | Passed | Questions answered correctly |
| `FAILED` | Failed | Questions answered incorrectly |
| `NOT_FOUND` | Not Found | No match found for the provided identity |

#### Number of rounds

How many rounds of questions were asked

| Detail | Description |
| - | - |
| Type | Integer |
| Range | 0–2 |
| Default | `0` |

### Default outcomes

The following default outcomes are available for evaluation and routing in the Journey builder.

| Outcome | Condition | Description |
| - | - | - |
| `Pass` | Authentication Result is `PASSED` | — |
| `Not Found` | Authentication Result is `NOT_FOUND` | — |
| `Fail` | Default, when no conditions matched | — |
| `Error` | An error occurs during processing | — |

### Input payload

The following is a sample payload used to submit data to the **Knowledge-based Authentication** module for processing.

```json JSON theme={null}
{
  "context": {
    "config": {
      "delivery": "api"
    },
    "subject": {
      "identity": {
        "currentAddress": {
          "administrativeArea": "MN",
          "country": "US",
          "lines": [
            "1 SAMPLE STREET"
          ],
          "locality": "SAMPLETOWN",
          "postalCode": "12345"
        },
        "dateOfBirth": "1959-01-01",
        "firstName": "JANE",
        "lastNames": [
          "DOE"
        ]
      },
      "kba": {
        "answers": [
          {
            "choices": [
              "E"
            ],
            "id": 1
          },
          {
            "choices": [
              "E"
            ],
            "id": 2
          },
          {
            "choices": [
              "E"
            ],
            "id": 3
          },
          {
            "choices": [
              "E"
            ],
            "id": 4
          },
          {
            "choices": [
              "E"
            ],
            "id": 5
          },
          {
            "choices": [
              "E"
            ],
            "id": 6
          },
          {
            "choices": [
              "E"
            ],
            "id": 7
          },
          {
            "choices": [
              "E"
            ],
            "id": 8
          },
          {
            "choices": [
              "E"
            ],
            "id": 9
          },
          {
            "choices": [
              "E"
            ],
            "id": 10
          }
        ],
        "questions": []
      }
    }
  }
}
```

| Field | Required | Description |
| - | - | - |
| `FullName/firstName` | Yes | The subject's first name. |
| `FullName/lastNames` | Yes | The subject's last name or names. |
| `CurrentAddress/country` | Yes | The country of the current address. |
| `CurrentAddress/postalCode` | Yes | The postal or ZIP code of the current address. |
| `CurrentAddress/lines` | No | The full address as one or more free-form lines, used when structured address components aren't available. |
| `CurrentAddress/building` | No | The building name or number of the current address. |
| `CurrentAddress/subBuilding` | No | The flat, unit, or other sub-building of the current address. |
| `CurrentAddress/thoroughfare` | No | The street or thoroughfare of the current address. |
| `CurrentAddress/locality` | No | The town or city of the current address. |
| `CurrentAddress/administrativeArea` | No | The state, province, or county of the current address. |
| `CurrentAddress/premise` | No | The premise name or number of the current address. |
| `SSN` | No | The subject's Social Security Number. |
| `DateOfBirth` | No | The subject's date of birth. |
| `Kba/answer1` | No | The subject's answer to quiz question 1. |
| `Kba/answer2` | No | The subject's answer to quiz question 2. |
| `Kba/answer3` | No | The subject's answer to quiz question 3. |
| `Kba/answer4` | No | The subject's answer to quiz question 4. |
| `Kba/answer5` | No | The subject's answer to quiz question 5. |
| `Kba/answer6` | No | The subject's answer to quiz question 6. |
| `Kba/answer7` | No | The subject's answer to quiz question 7. |
| `Kba/answer8` | No | The subject's answer to quiz question 8. |
| `Kba/answer9` | No | The subject's answer to quiz question 9. |
| `Kba/answer10` | No | The subject's answer to quiz question 10. |

### Sample response

The following is a sample response returned by the module.

```json JSON theme={null}
{
  "response": {
    "advice": {
      "authenticationResult": "NOT_FOUND",
      "questionSetsUsed": 0
    },
    "outcome": "Not Found"
  }
}
```