How to add KBA authentication after sending a document?

BoldSign allows you to add knowledge-based authentication (KBA) to a signer after a document has been sent. Use the PATCH /v1/document/addAuthentication API, set authenticationType to KBA, and provide optional KBA settings in kbaSettings.

For an overview of KBA behavior and supported settings, refer to Knowledge-based authentication.

Request settings

To add KBA authentication after sending, provide the target signer and KBA settings.

Property	Type	Description
`emailId`	string	Email address of the signer to whom KBA should be added.
`order`	integer	Signer order. Use this when the same email address appears more than once in the document.
`authenticationType`	string	Set this value to `KBA`.
`kbaSettings`	object	KBA configuration for the signer.

The kbaSettings object supports:

Property	Type	Description
`type`	string	KBA frequency. Supported values are `EveryAccess`, `UntilSignCompleted`, and `OncePerDocument`.
`maximumRetryCount`	integer	Maximum number of KBA attempts. Supported values are `1` to `3`.
`nameMatcher`	string	Name-match tolerance level. Supported values are `None`, `Lenient`, `Moderate`, and `Strict`.

We recommend setting nameMatcher to Strict, Moderate, or Lenient to compare the signer name with the identity details provided during KBA. Use None only when name comparison is intentionally not required.

N> KBA is available only for U.S.-based recipients. KBA is not available for group signers or in-person signers.

Code snippet

The following examples add KBA authentication to one signer in an existing document.

curl -X PATCH "https://api.boldsign.com/v1/document/addAuthentication?documentId={Your document id}" \
  -H 'X-API-KEY: {Your API Key}' \
  -H "Content-Type: application/json" \
  -d '{
  "emailId": "[email protected]",
  "authenticationType": "KBA",
  "kbaSettings": {
    "type": "EveryAccess",
    "maximumRetryCount": 3,
    "nameMatcher": "Strict"
  }
}'

using BoldSign.Api;
using BoldSign.Api.Model;
using BoldSign.Api.Model.Kba;
using BoldSign.Model;

var apiClient = new ApiClient("https://api.boldsign.com", "{Your API Key}");
var documentClient = new DocumentClient(apiClient);

var kbaSettings = new KbaSettings
{
    Type = AuthenticationFrequency.EveryAccess,
    MaximumRetryCount = 3,
    NameMatcher = KbaNameMatchLevel.Strict,
};

await documentClient.AddAuthenticationAsync(
    documentId: "{Your document id}",
    emailId: "[email protected]",
    authenticationType: AuthenticationType.KBA,
    kbaSettings: kbaSettings).ConfigureAwait(false);

Replace {Your document id}, {Your API Key}, and signer email with your actual values.

After KBA is added, the signer must complete KBA before accessing the document, based on the configured KBA frequency.