Knowledge-Based Authentication

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. SpitShake 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.

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
  }'

{
  "success": true,
  "message": "KBA configuration saved successfully",
  "provider": "lexisnexis"
}

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

curl -X GET "https://spitshake.io/api/kba/config" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

{
  "configured": true,
  "provider": "demo"
}

{
  "configured": false,
  "provider": null
}

Step 3: Initiate KBA Session

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

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"
  }'

{
  "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"
      ]
    }
  ]
}

{
  "error": "Missing required identity fields: date_of_birth, ssn_last_4"
}

{
  "error": "KBA provider is temporarily unavailable. Please try again shortly."
}

Step 4: Verify Answers

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

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"
  }'

{
  "passed": true,
  "score": 85
}

{
  "passed": false,
  "score": 40
}

{
  "error": "KBA session has expired or is invalid. Please initiate a new session."
}

Stored Verification Data

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

{
  "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

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Knowledge-Based Authentication

Overview

Step 1: Configure KBA Provider

Available Providers

Step 2: Check Configuration

Step 3: Initiate KBA Session

Step 4: Verify Answers

Stored Verification Data

Audit Events

Scoring

Complete Flow Diagram

​Overview

​Step 1: Configure KBA Provider

​Available Providers

​Step 2: Check Configuration

​Step 3: Initiate KBA Session

​Step 4: Verify Answers

​Stored Verification Data

​Audit Events

​Scoring

​Complete Flow Diagram

Overview

Step 1: Configure KBA Provider

Available Providers

Step 2: Check Configuration

Step 3: Initiate KBA Session

Step 4: Verify Answers

Stored Verification Data

Audit Events

Scoring

Complete Flow Diagram