Identity verification (KBA)

Knowledge-Based Authentication (KBA) challenges a signer to answer identity questions before the document opens. Passing is a precondition to viewing and signing, not a step inside it.

Where the questions come from

Nobody sets them up — not the signer, not your organization, not Loyva. The signer enters identifying details, an identity-data provider matches them against credit-header and public-records data, and the questions are generated from what it holds, with plausible wrong answers mixed in:

Which of these streets have you previously lived on? A) Cedar Ln B) Willow Dr C) Pinecrest Ave D) Marigold St E) None of the above

This is what makes it meaningful: someone who has the emailed signing link — or the signer's inbox — still cannot answer questions about a life that isn't theirs.

Neither you nor Loyva can see the questions or the answers. Only the outcome is recorded.

Enabling it

KBA is set when a document template is created and cannot be changed afterwards.

That is not a UI restriction. KBA runs on a separate signing account, so the flag decides where the template is physically hosted, and there is no way to move a document between accounts. PATCH /api/v2/templates/{id} returns 409 if you try to change it.

POST /api/v2/templates
Content-Type: application/json

{
  "name": "Loan agreement",
  "kba_required": true
}

Templates report their setting on read:

{
  "template_id": "tmpl_...",
  "kba_required": true,
  "docuseal_instance": "cloud"
}

A document package inherits KBA from its members, and every member must use the same signing account — mixing a KBA template with a non-KBA one is rejected at create/update time, because the two cannot be merged into one document.

Sending

Nothing extra is required. POST /api/v2/envelopes/{id}/send reads the setting from the template or package and adds the verification step automatically. The envelope records it:

{ "envelope_id": "env_...", "kba_required": true, "docuseal_instance": "cloud" }

If the verification step cannot be added, the send fails rather than delivering a document that appears protected and isn't.

Limitations


In-person signing	Not available. A knowledge challenge the sender is standing over defeats its purpose. `send_email: false` returns 422.
Embed widget	Not available. `POST /api/v2/embed/token` returns 409 with `code: "kba_required"`. Signers use the emailed Loyva signing link.
Coverage	Depends on US public-record and credit-header data. Signers with little record history may not be challengeable; that outcome is recorded as `unavailable`, which is distinct from a failure.
Existing templates	Cannot be converted. Create a new template.

Results

GET /api/v2/envelopes/{id}/kba

{
  "data": [
    {
      "signer_email": "[email protected]",
      "status": "passed",
      "occurred_at": "2026-08-31T18:04:11Z",
      "docuseal_session_id": "4918a42d...",
      "ip_address": "203.0.113.7",
      "price_cents": 400
    }
  ]
}

status is one of passed, failed, or unavailable. Treat unavailable as "could not be checked", not as a failure — it means the provider had too little record history to build questions for that person.

The same outcome also appears on the envelope timeline (kba.verified), in the audit log (envelope.kba_verified), on the signer list in the Loyva app, and — once the document is vaulted — in both the vault custody record PDF and the identity_verification block of the UCC §9-105 certificate, alongside the signer, timestamp, IP and session id.

The certificate block is additive evidence: it records how each signer was identified and does not change the seven compliance checks or the score.

Pricing

$4.00 per signer verified, billed on your monthly usage invoice. There is no included allowance; every verification is charged. The count for the current month appears under Settings → Usage.

Where the questions come from​

Enabling it​

Sending​

Limitations​

Results​

Pricing​