Sandbox mode

Sandbox Knowledge-Based Authentication (KBA) lets you test the KBA flow in a non-production environment. Any document sent using sandbox OAuth credentials or a sandbox API key is treated as a sandbox document for KBA. Sandbox KBA requests do not incur live KBA costs, so you can safely validate your integration before moving to production.

In sandbox mode, the signer still goes through the KBA flow. To successfully complete KBA during testing, provide the predefined sandbox identity details listed below.

Sandbox test data for KBA

Use the following values exactly as shown when completing KBA in sandbox mode.

Field	Sandbox value
First name	`JOHN`
Last name	`SMITH`
Address	`222333 PEACHTREE PLACE`
City	`ATLANTA`
State	`GEORIGA (GA)`
ZIP	`30318`
SSN last four	`3333`

If these values are entered as expected in sandbox mode, the signer can successfully complete the KBA test flow.

Name matching for KBA

Name matching for KBA is used to compare the signer's name in the document request with the predefined sandbox identity used during testing. This helps simulate how name-based verification behaves before moving your integration to production.

If you set NameMatcher to a value other than None, such as Lenient, Moderate, or Strict, the signer's name must be John Smith. This is because the sandbox KBA flow expects the signer's name to match the sandbox test identity, whose first name is JOHN and last name is SMITH.

To avoid validation issues during sandbox testing, make sure both the signer's name and the KBA answers align with the sandbox data. If name matching is enabled and the signer's name does not match John Smith, the sandbox KBA flow may not validate successfully.

We recommend always enabling NameMatcher, at a minimum of Lenient.

Code snippet

The following examples send a document with KBA enabled for one signer in sandbox mode.

curl -X 'POST' \
  'https://api.boldsign.com/v1/document/send' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {Your sandbox API key}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'Files=@{Your file path};type=application/pdf' \
  -F 'Title=Agreement' \
  -F 'Message=This document is sent for sandbox KBA testing.' \
  -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 sandbox 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",
    Message = "This document is sent for sandbox KBA testing.",
    Signers = new List<DocumentSigner> { signer },
    Files = filesToUpload,
};

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

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

Notes

Documents sent with sandbox OAuth credentials are treated as sandbox documents for KBA.
Documents sent with a sandbox API key are also treated as sandbox documents for KBA.
Sandbox KBA is intended only for testing and validation.
Sandbox KBA usage does not incur live KBA charges.