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);

import boldsign

configuration = boldsign.Configuration(host="https://api.boldsign.com", api_key="{Your API Key}")

with boldsign.ApiClient(configuration) as api_client:

    document_api = boldsign.DocumentApi(api_client)

    kba_settings = boldsign.KbaSettings(
        type="EveryAccess",
        maximumRetryCount=3,
        nameMatcher="Strict")

    access_code_detail = boldsign.AccessCodeDetail(
        authenticationType="KBA",
        emailId="[email protected]",
        kbaSettings=kba_settings)

    document_api.add_authentication(document_id="{Your document id}", access_code_detail=access_code_detail)

<?php require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\DocumentApi;
use BoldSign\Model\AccessCodeDetail;
use BoldSign\Model\KbaSettings;

$config = new Configuration();
$config->setHost('https://api.boldsign.com');
$config->setApiKey('{Your API Key}');

$document_api = new DocumentApi($config);

$kba_settings = new KbaSettings();
$kba_settings->setType('EveryAccess');
$kba_settings->setMaximumRetryCount(3);
$kba_settings->setNameMatcher('Strict');

$access_code_detail = new AccessCodeDetail();
$access_code_detail->setAuthenticationType('KBA');
$access_code_detail->setEmailId('[email protected]');
$access_code_detail->setKbaSettings($kba_settings);

$document_api->addAuthentication($document_id = '{Your document id}', $access_code_detail);

import com.boldsign.ApiClient;
import com.boldsign.Configuration;
import com.boldsign.api.DocumentApi;
import com.boldsign.model.AccessCodeDetail;
import com.boldsign.model.KbaSettings;

ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.boldsign.com");
client.setApiKey("{Your API Key}");

DocumentApi documentApi = new DocumentApi(client);

KbaSettings kbaSettings = new KbaSettings();
kbaSettings.setType(KbaSettings.TypeEnum.EVERY_ACCESS);
kbaSettings.setMaximumRetryCount(3);
kbaSettings.setNameMatcher(KbaSettings.NameMatcherEnum.STRICT);

AccessCodeDetail accessCodeDetail = new AccessCodeDetail();
accessCodeDetail.setAuthenticationType(AccessCodeDetail.AuthenticationTypeEnum.KBA);
accessCodeDetail.setEmailId("[email protected]");
accessCodeDetail.setKbaSettings(kbaSettings);

documentApi.addAuthentication("{Your document id}", accessCodeDetail);

import { AccessCodeDetail, DocumentApi, KbaSettings } from "boldsign";

const baseUrl:string = "https://api.boldsign.com";
const documentApi = new DocumentApi(baseUrl);
documentApi.setApiKey("{Your API Key}");

const kbaSettings = new KbaSettings();
kbaSettings.type = KbaSettings.TypeEnum.EveryAccess;
kbaSettings.maximumRetryCount = 3;
kbaSettings.nameMatcher = KbaSettings.NameMatcherEnum.Strict;

const accessCodeDetail = new AccessCodeDetail();
accessCodeDetail.authenticationType = AccessCodeDetail.AuthenticationTypeEnum.Kba;
accessCodeDetail.emailId = "[email protected]";
accessCodeDetail.kbaSettings = kbaSettings;

documentApi.addAuthentication("{Your document id}", accessCodeDetail);

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.