How to send a document with KBA using BoldSign API?

Knowledge-based authentication (KBA) verifies a U.S.-based signer using legal identity information and security questions before the signer can access the document. To send a document with KBA, set the signer's authenticationType to KBA and provide optional KBA settings in kbaSettings.

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

KBA request settings

Use the kbaSettings object to configure KBA for the signer.

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 send a document with KBA enabled for one signer.

curl -X 'POST' \
  'https://api.boldsign.com/v1/document/send' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {Your API Key}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'Files=@{Your file path};type=application/pdf' \
  -F 'Title=Agreement' \
  -F 'Signers={
  "name": "Alex Gayle",
  "emailAddress": "[email protected]",
  "authenticationType": "KBA",
  "kbaSettings": {
    "type": "EveryAccess",
    "maximumRetryCount": 3,
    "nameMatcher": "Strict"
  },
  "signerType": "Signer",
  "formFields": [
    {
      "id": "signature1",
      "name": "signature1",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 100,
        "y": 100,
        "width": 100,
        "height": 50
      },
      "isRequired": true
    }
  ]
}'

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 documentFilePath = new DocumentFilePath
{
    ContentType = "application/pdf",
    FilePath = "{Your File Path}",
};

var filesToUpload = new List<IDocumentFile>
{
    documentFilePath,
};

var signatureField = new FormField(
    id: "signature1",
    isRequired: true,
    type: FieldType.Signature,
    pageNumber: 1,
    bounds: new Rectangle(x: 100, y: 100, width: 100, height: 50));

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

var signer = new DocumentSigner(
    signerName: "Alex Gayle",
    signerType: SignerType.Signer,
    signerEmail: "[email protected]",
    authenticationType: AuthenticationType.KBA,
    formFields: new List<FormField> { signatureField },
    locale: Locales.EN)
{
    KbaSettings = kbaSettings,
};

var sendForSign = new SendForSign
{
    Title = "Agreement",
    Signers = new List<DocumentSigner> { signer },
    Files = filesToUpload,
};

var documentCreated = documentClient.SendDocument(sendForSign);
Console.WriteLine(documentCreated.DocumentId);

Replace the placeholder values such as {Your API Key}, {Your file path}, signer name, and signer email with your actual values.

After the document is sent, the signer must complete KBA before accessing the document. If the signer fails KBA, the signer can retry until the configured maximumRetryCount is reached.