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 brand-new document that is not based on a template makes the same choice at POST /api/v2/esign/builder-session, by passing kba_required: true with no template_id or package_id. That is the last point at which it can be chosen: the builder opens against one account, and the document exists there from then on.

Packages

A document package derives KBA from its members: if any member requires it, the whole package does, and the combined document is sent through the Cloud signing account. There is no package-level flag to set — a package is one merged document and one envelope, so it cannot be half verified.

Mixing a KBA template with non-KBA ones is supported. On save, Loyva copies each non-Cloud member onto the Cloud signing account and merges from those copies; the original templates are left untouched and stay the source of truth. A copy is rebuilt automatically when its source template changes.

The copy reproduces the template's documents, field placements and signer roles. Settings DocuSeal keeps outside a template's fields do not carry across. Word-sourced templates cannot be part of a package at all, so they are never copied.

Packages report the derived answer on read:

{
  "package_id": "pkg_...",
  "kba_required": true,
  "docuseal_instance": "cloud"
}

POST and PATCH /api/v2/document-packages return 502 if a member cannot be copied to the Cloud account — for example when that account is not configured. Each entry in items also reports its own kba_required and docuseal_instance.

Sending part of a package

A single send can leave some of a package's documents out. Pass the member template ids to keep as package_template_ids alongside package_id on POST /api/v2/esign/builder-session. Omit it to send the whole package. The documents stay in package order whatever order you list them in, and at least one is required. If only one is kept, it is copied rather than merged.

KBA is then worked out from the kept documents alone. If you leave out the only member that requires it, that send is not verified. The package's stored answer is unchanged.

{
  "envelope_id": "env_...",
  "package_id": "pkg_...",
  "package_template_ids": ["tmpl_a", "tmpl_c"]
}

package_template_ids returns 400 if an id is not a member of the package, if the template has been deleted, or if it is used on a bulk-send batch (batch_id).

Sending several templates without a package

To combine templates on the fly, pass two to twenty template ids as template_ids on POST /api/v2/esign/builder-session, instead of template_id or package_id. They are merged into one document in the order given, and KBA follows the same rule as a package: if any of them requires it, the whole document is verified on the Cloud signing account.

{
  "envelope_id": "env_...",
  "template_ids": ["tmpl_c", "tmpl_a"]
}

template_ids returns 400 if it is combined with template_id or package_id, if an id is listed twice, if a template has been deleted, or if it is used on a bulk-send batch.

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

Signing links

Verified documents are signed on the Cloud signing account, which serves its forms from a Loyva-branded domain (cloud.sign.loyva.io) rather than the provider's own. Every signing URL Loyva hands back — signing_url from GET /api/v2/envelopes/{id}/signing-links, the embed_url on an embed token, and the link in a signing email — already points at the right host for the environment you are calling. Treat these URLs as opaque: read them from the response rather than assembling one from a slug.

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": "jane@example.com",
      "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.

Your own organization's users are never challenged. When the sender adds themselves as a signer ("Add me as a signer"), the KBA step is applied to the client-side signers only — the sender is already authenticated to Loyva — and no verification is billed for them.