Skip to main content

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.

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

ProviderValueDescription
LexisNexislexisnexisProduction identity verification via LexisNexis InstantID
ExperianexperianProduction identity verification via Experian Precise ID
DemodemoTest 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"
}

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

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

​
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:
EventDescription
kba_session_initiatedA KBA session was started for a submitter. Logs the submission ID and submitter role.
kba_verification_passedThe signer answered enough questions correctly. Logs the score.
kba_verification_failedThe 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