Skip to content
  1. Blog
  2. API

How to Require Signer Authentication for eSignature Requests via API

TL;DR: Set the authenticationType field on a signer in the send document request, and that signer must pass a check before the document opens. The API accepts email one-time passcodes, SMS codes, access codes, knowledge-based authentication (KBA) questions and ID checks. Our signer authentication methods guide compares them.

Your app sends a loan agreement to a customer by email. Anyone who gets into that inbox, or gets a forwarded link, could open the document and sign it.

Signer authentication closes that gap. This guide shows how to turn on each method with one request, with a client URL (cURL) sample for each.

What is signer authentication?

Signer authentication is a check the signer must pass before they can see or sign a document. It proves the person opening the link is the person you meant to sign.

Think of a hotel desk handing over a room key. The clerk asks for your name, and sometimes your ID, before the key leaves the counter. Each method sets a different bar for that check.

Which authentication methods can you set through the API?

The API accepts five values for authenticationType, and you set one per signer. Each value asks the signer to prove something different.

Value What the signer must do
EmailOTP Enter a one-time passcode (OTP) we email to them
SMSOTP Enter a one-time passcode we text to their phone
AccessCode Type a code you share with them yourself
KBA Answer KBA questions drawn from public records
IdVerification Photograph a government ID and take a selfie

KBA works only for signers based in the US. Our knowledge-based authentication and signer identity verification pages show what the signer sees.

How do developers handle authentication and security in eSignature APIs?

There are two layers, and each one protects a different thing. Your app proves itself to the API with an API key or OAuth, and each signer proves themselves to the document.

Every sample below sends the X-API-KEY header for the first layer. Keep that key on your server, never in browser code. Our guide to API keys vs OAuth authentication explains when to pick each.

The second layer is the authenticationType field on each signer. You pick the lightest check that still fits the risk of the document.

How do you send a document with SMS authentication?

Set authenticationType to SMSOTP and add the signer’s phoneNumber object. We text a code to that number, and the signer enters it to open the document.

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 'Signers={
  "name": "Alex",
  "emailAddress": "alex@example.com",
  "signerType": "Signer",
  "authenticationType": "SMSOTP",
  "phoneNumber": {
    "countryCode": "{Signer country code}",
    "number": "{Signer phone number}"
  },
  "formFields": [
    {
      "id": "signature",
      "name": "signature",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 100,
        "y": 100,
        "width": 200,
        "height": 25
      },
      "isRequired": true
    }
  ],
  "locale": "EN"
}' \
  -F 'Files=@{your file path}' \
  -F 'Title={title}'

Replace the placeholders in countryCode and number with the signer’s country code and phone number. Then send it.

How do you send a document with access code authentication?

Set authenticationType to AccessCode and put your code in authenticationCode. Share the code with the signer outside the email, such as in a phone call.

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 'Title="Sample Document"' \
  -F 'Signers={
  "name": "Alex",
  "emailAddress": "alex@example.com",
  "signerType": "Signer",
  "authenticationType": "AccessCode",
  "authenticationCode": "1234",
  "formFields": [
    {
      "id": "signature",
      "name": "signature",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 100,
        "y": 100,
        "width": 200,
        "height": 25
      },
      "isRequired": true
    }
  ],
  "locale": "EN"
}' \
  -F 'Files=@{your file path}'

The sample uses 1234 to keep it short. Pick a code that is hard to guess for real documents.

How do you send a document with email code authentication?

Set authenticationType to EmailOTP, with no extra fields. We email the signer a code when they open the link, and they enter it to see the document.

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 'Signers={
  "name": "Alex",
  "emailAddress": "alex@example.com",
  "signerType": "Signer",
  "authenticationType": "EmailOTP",
  "formFields": [
    {
      "id": "signature",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 50,
        "y": 100,
        "width": 200,
        "height": 25
      },
      "isRequired": true
    }
  ]
}' \
  -F 'Title="Sample Document"' \
  -F 'Files=@{your file path}'

How do you send a document with ID verification?

Set authenticationType to IdVerification and add an identityVerificationSettings object. The signer photographs a government ID before the document opens.

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}' \
  -F 'Title=Sample Document' \
  -F 'Signers={
  "name": "Alex",
  "emailAddress": "alex@example.com",
  "authenticationType": "IdVerification",
  "identityVerificationSettings": {
    "type": "EveryAccess",
    "maximumRetryCount": 10,
    "requireLiveCapture": true,
    "requireMatchingSelfie": true,
    "nameMatcher": "Strict"
  },
  "signerType": "Signer",
  "formFields": [
    {
      "id": "signature",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 100,
        "y": 100,
        "width": 200,
        "height": 25
      },
      "isRequired": true
    }
  ]
}'

The settings object controls how the check runs:

  • type sets how often: EveryAccess, UntilSignCompleted or OncePerDocument.
  • maximumRetryCount sets the number of tries, up to 10.
  • requireLiveCapture asks for a live camera photo of the ID, not an uploaded file.
  • requireMatchingSelfie compares the ID photo with a selfie.
  • nameMatcher sets how closely the names must match: Strict, Moderate or Lenient.

Read our identity verification documentation for every setting.

How do you send a document with knowledge-based authentication?

Set authenticationType to KBA and add a kbaSettings object. The signer gives their identity details and answers questions drawn from public records.

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 'Signers={
  "name": "Alex",
  "emailAddress": "alex@example.com",
  "signerType": "Signer",
  "authenticationType": "KBA",
  "kbaSettings": {
    "type": "EveryAccess",
    "maximumRetryCount": 3,
    "nameMatcher": "Strict"
  },
  "formFields": [
    {
      "id": "signature",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 50,
        "y": 100,
        "width": 200,
        "height": 25
      },
      "isRequired": true
    }
  ]
}' \
  -F 'Title=Sample Document' \
  -F 'Files=@{your file path}'

The kbaSettings object works like the ID settings:

  • type takes the same three values as ID verification.
  • maximumRetryCount takes 1 to 3 tries.
  • nameMatcher takes Strict, Moderate or Lenient.

KBA cannot be paired with another method for the same signer. It also does not work for group signers or in-person signers. Our KBA documentation has the full rules.

What else should you check before you go live?

Test each method in the sandbox with your own email and phone. Then review the settings that change what the signer sees.

  • authenticationRetryCount sets 1 to 10 tries for access codes and one-time codes.
  • authenticationSettings sets how often those three methods ask for a code.
  • A wrong phone number means the signer never gets the SMS code.

See mandating signer authentication after sending to add or change a check on a sent document.

Which BoldSign plan do you need for the API, and what does it cost?

Live API access comes with the Enterprise API plan, which starts at $30 a month with 40 envelopes. Extra envelopes cost $0.75 each.

Email codes and access codes have no extra charge. SMS authentication costs $0.20 per SMS, KBA costs $1.50 per attempt and ID verification costs $2 per check.

You can build and test first in our free sandbox, with no credit card. Sandbox documents carry a test watermark and are deleted after 14 days. Prices are in USD, as listed on the BoldSign pricing page in November 2026.

Where do you go next with signer authentication in the API?

Start with email codes for everyday documents, and add ID checks where the risk is higher.

Frequently asked questions

How do I require authentication for a signer in the BoldSign API?

Set authenticationType on that signer in the send document request. Add the extra values the method needs, such as a phone number for SMS codes or settings for knowledge-based authentication (KBA).

Which authenticationType values does the API accept?

The send document reference lists five values, for an access code, an email code, an SMS code, an ID check and KBA. Leave the field out and the signer opens the document with no extra check.

Can I give each signer a different authentication method?

Yes. The setting sits on each signer object, so one signer can use an email code while another passes an ID check.

Can I combine KBA with another method for the same signer?

No. Our developer guide says KBA cannot be paired with an access code, email code, SMS code or ID verification for one signer.

How many tries does a signer get?

You allow one to three tries for KBA and up to 10 for ID verification. For access codes and one-time codes, authenticationRetryCount takes 1 to 10.

Does KBA work for signers outside the US?

No. KBA works only for signers based in the US. Use ID verification, which covers the US and other supported countries, or a one-time code.

Is a document signed after an ID check legally binding?

Yes, when the signers agree to sign electronically and the signed record is kept. Confirm the rules for your document type and country.

Can I add authentication after a document is sent?

Yes, while the signer has not signed yet. A separate endpoint adds or changes authentication on a sent document.

Gopinath Kannusamy

Gopinath is a passionate software developer with 2 years of experience at BoldSign. He is an avid writer and enjoys sharing his insights on technology and development. In his free time, he enjoys exploring new technologies and learning new things. Connect with him on LinkedIn.

More posts by Gopinath Kannusamy
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required