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

# Knowledge-Based Authentication

> Verify signer identity with knowledge-based authentication (KBA) questions powered by LexisNexis or Experian.

## Overview

Knowledge-Based Authentication (KBA) verifies a signer's identity by asking them questions derived from public and credit records that only the real person would know. DocuTrust integrates with LexisNexis and Experian, and also provides a demo provider for testing.

## Step 1: Configure KBA Provider

Set up your KBA provider credentials. Only one provider can be active at a time.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/kba/update_config" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "kba_provider": "lexisnexis",
      "lexisnexis_api_key": "lx-prod-a1b2c3d4e5f6a7b8c9d0e1f2",
      "experian_api_key": null
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "KBA configuration saved successfully",
    "provider": "lexisnexis"
  }
  ```
</ResponseExample>

### Available Providers

| Provider   | Value        | Description                                                       |
| ---------- | ------------ | ----------------------------------------------------------------- |
| LexisNexis | `lexisnexis` | Production identity verification via LexisNexis InstantID         |
| Experian   | `experian`   | Production identity verification via Experian Precise ID          |
| Demo       | `demo`       | Test provider that returns sample questions (no real data lookup) |

## Step 2: Check Configuration

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://spitshake.io/api/kba/config" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "configured": true,
    "provider": "demo"
  }
  ```

  ```json 200 — Not Configured theme={null}
  {
    "configured": false,
    "provider": null
  }
  ```
</ResponseExample>

## Step 3: Initiate KBA Session

Submit the signer's identity information to generate a set of multiple-choice questions. All identity fields are required.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/kba/{submission_id}/initiate" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1985-06-15",
      "ssn_last_4": "6789",
      "address": "742 Evergreen Terrace",
      "city": "Springfield",
      "state": "IL",
      "zip": "62704"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "session_id": "kba_sess_abc123",
    "questions": [
      {
        "id": "q1",
        "text": "Which of the following addresses have you been associated with?",
        "choices": [
          "742 Evergreen Terrace, Springfield, IL",
          "123 Elm Street, Shelbyville, IL",
          "456 Oak Avenue, Capital City, IL",
          "None of the above"
        ]
      },
      {
        "id": "q2",
        "text": "Which of the following counties have you lived in?",
        "choices": [
          "Sangamon County",
          "Cook County",
          "DuPage County",
          "None of the above"
        ]
      },
      {
        "id": "q3",
        "text": "Which of the following phone numbers is associated with you?",
        "choices": [
          "(217) 555-0134",
          "(312) 555-0198",
          "(630) 555-0172",
          "None of the above"
        ]
      },
      {
        "id": "q4",
        "text": "In which year did you first open a credit account?",
        "choices": [
          "2003",
          "2005",
          "2007",
          "None of the above"
        ]
      }
    ]
  }
  ```

  ```json 422 — Missing Fields theme={null}
  {
    "error": "Missing required identity fields: date_of_birth, ssn_last_4"
  }
  ```

  ```json 503 — Provider Error theme={null}
  {
    "error": "KBA provider is temporarily unavailable. Please try again shortly."
  }
  ```
</ResponseExample>

## Step 4: Verify Answers

Submit the signer's answers to the KBA questions. The provider scores the responses and returns a pass/fail result.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/kba/{submission_id}/verify" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "session_id": "kba_sess_abc123",
      "answers": [
        { "question_id": "q1", "answer": "742 Evergreen Terrace, Springfield, IL" },
        { "question_id": "q2", "answer": "Sangamon County" },
        { "question_id": "q3", "answer": "(217) 555-0134" },
        { "question_id": "q4", "answer": "2005" }
      ],
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Passed theme={null}
  {
    "passed": true,
    "score": 85
  }
  ```

  ```json 200 — Failed theme={null}
  {
    "passed": false,
    "score": 40
  }
  ```

  ```json 422 — Invalid Session theme={null}
  {
    "error": "KBA session has expired or is invalid. Please initiate a new session."
  }
  ```
</ResponseExample>

### Stored Verification Data

After verification (pass or fail), the result is saved to the submitter's `values` hash under the corresponding field UUID:

```json theme={null}
{
  "session_id": "kba_sess_abc123",
  "passed": true,
  "score": 85,
  "verified_at": "2026-04-09T14:45:00Z",
  "method": "kba"
}
```

## Audit Events

Every KBA interaction is recorded in the immutable audit log:

| Event                     | Description                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `kba_session_initiated`   | A KBA session was started for a submitter. Logs the submission ID and submitter role. |
| `kba_verification_passed` | The signer answered enough questions correctly. Logs the score.                       |
| `kba_verification_failed` | The signer did not meet the score threshold. Logs the score.                          |

## Scoring

The KBA score is a percentage from 0 to 100 representing how many questions the signer answered correctly, weighted by question difficulty. The passing threshold is determined by the provider:

* **LexisNexis**: Default passing score of 70
* **Experian**: Default passing score of 75
* **Demo**: Always returns a score of 85 for correct answers, 40 for incorrect

## Complete Flow Diagram

```
┌──────────────────┐
│  Signer reaches  │
│  KBA field       │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Signer enters   │
│  identity info   │
│  (name, DOB,     │
│   SSN last 4,    │
│   address)       │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────┐
│  POST initiate   │─────▶│  Provider returns│
│  identity fields │      │  4 questions     │
└────────┬─────────┘      └──────────────────┘
         │
         ▼
┌──────────────────┐
│  Signer answers  │
│  questions       │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐      ┌──────────────────┐
│  POST verify     │─────▶│  Score recorded  │
│  answers array   │      │  in audit log    │
└────────┬─────────┘      └──────────────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 ┌──────┐  ┌──────┐
 │ Pass │  │ Fail │
 │ ≥70  │  │ <70  │
 └──┬───┘  └──┬───┘
    │         │
    ▼         ▼
 Continue   Signing
 signing    blocked
```