Skip to content
  1. Blog
  2. API

How to Send Documents for eSignature with an Identity Verification API

TL;DR: An identity verification API asks a signer to show a photo ID, and often a selfie, before they can open your document. In BoldSign, you set authenticationType to IdVerification for a signer and add the settings you want. Our signer identity verification page shows what the signer sees.

Picture a loan agreement sent to a new customer by email. Anyone who gets into that inbox could open the link and sign. An email address alone does not prove who is on the other end.

An online identity verification API closes that gap. This guide explains how our check works, which settings you can control, and how to send your first ID-verified document with code.

What is an identity verification API?

An identity verification API lets your app ask a person to prove who they are with a government ID. In BoldSign, the check sits between the signer and the document.

Think of a hotel front desk. The clerk looks at your passport before handing over the room key. Our check does the same: the signer shows an ID first, and the document opens only after the check passes.

Because the check reads the ID itself, it also works as a document verification API for signers. Our guide on identity verification in eSignature explains why the check matters.

How does BoldSign check a signer’s ID?

The signer takes a photo of their ID and, when you ask for it, a selfie. Stripe Identity powers the check, and the signer can view and sign the document once it passes.

You can think of it as document ID authentication software built into signing. Here is what happens on the signer’s side:

  1. The signer opens the signing link from your email.
  2. The signer picks one of the ID types you allow and capture it with their camera.
  3. The signer takes a selfie when you require one, so the face can be matched to the ID.
  4. The name on the ID is compared with the name you entered for the signer.
  5. The document opens once the check passes.

Read our identity verification introduction for the full picture.

Which identity verification settings can you set?

You set each signer’s options in an identityVerificationSettings object. Use it only when the signer’s authenticationType is IdVerification.

How often must the signer verify?

The type setting decides how often the check runs. Pick one of three values:

  • EveryAccess: the signer verifies each time they open the document, even after signing.
  • UntilSignCompleted: the check runs on each visit until the signer has signed.
  • OncePerDocument: the signer verifies once, however often they come back.

Set maximumRetryCount to limit how many tries a signer gets. The top value is 10.

How strict is the check?

Three settings control how closely the signer and the ID must match:

  • nameMatcher sets how closely names match: Strict, Moderate or Lenient.
  • requireLiveCapture asks the signer to photograph the ID live with their camera.
  • requireMatchingSelfie asks for a selfie that is compared with the ID photo.

With Moderate, middle names, prefixes and suffixes may differ. Lenient also allows small spelling mistakes.

Which IDs and countries can you accept?

List the accepted ID types in allowedDocumentTypes. The values are Passport, IDCard and DriverLicense.

Countries are set for your whole account, not per request. Turn on Allowed Countries in your Business Profile, and IDs from other countries are rejected. Our help article on allowed countries and ID document types shows each step.

The help article on identity verification settings in BoldSign lists every value. You can browse more identity verification help articles there too.

How do you send a document with identity verification via the API?

You send it with the same call as any other document, plus two signer settings. Here are the steps:

  1. Add your API key and the file you want signed.
  2. Add the signer’s name and email address.
  3. Set the signer’s authenticationType to IdVerification.
  4. Add an identityVerificationSettings object with the options you chose.
  5. Post the request to the send document endpoint.

Our software development kits (SDKs) take the same settings as the plain request. Our send a document with ID verification guide walks through each one.

How do you test the check in the sandbox?

Use the signer name “Jenny Rosen” for every test in sandbox mode. That name passes the name match, so your tests give the same result each time.

The samples below use it, and each one checks the signer on every visit. Our sandbox mode page has more detail.

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 name};type=application/pdf' \
  -F 'Title={DOCUMENT_TITLE}' \
  -F 'Signers={
  "name": "Jenny Rosen",
  "emailAddress": "alex@example.com",
  "authenticationType": "IdVerification",
  "deliveryMode": "Email",
  "identityVerificationSettings": {
    "type": "EveryAccess",
    "maximumRetryCount": 10,
    "requireLiveCapture": true,
    "requireMatchingSelfie": true,
    "nameMatcher": "Strict",
    "allowedDocumentTypes": [
      "Passport",
      "IDCard",
      "DriverLicense"
    ]
  },
  "signerType": "Signer",
  "locale": "EN",
  "formFields": [
    {
      "id": "signature1",
      "fieldType": "Signature",
      "pageNumber": 1,
      "bounds": {
        "x": 160,
        "y": 150,
        "width": 51,
        "height": 21
      },
      "isRequired": true
    }
  ]
}'
var apiClient = new ApiClient("https://api.boldsign.com", "YOUR_API_KEY");
var documentClient = new DocumentClient(apiClient);

var file = new DocumentFilePath
{
    ContentType = "application/pdf",
    FilePath = "FILE_PATH",
};

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 formFields = new List<FormField> { signatureField };
var idVerification = new IdentityVerificationSettings
{
    Type = IdVerificationType.EveryAccess,
    MaximumRetryCount = 10,
    RequireLiveCapture = true,
    RequireMatchingSelfie = true,
    NameMatcher = NameVariation.Strict,
    AllowedDocumentTypes = new List<AllowedDocumentType>
    {
        AllowedDocumentType.Passport,
        AllowedDocumentType.IDCard,
        AllowedDocumentType.DriverLicense
    }
};

var signer = new DocumentSigner(
    signerName: "Jenny Rosen",
    signerType: SignerType.Signer,
    signerEmail: "alex@example.com",
    authenticationType: AuthenticationType.IdVerification,
    identityVerificationSettings: idVerification,
    formFields: formFields,
    locale: Locales.EN);

var sendForSign = new SendForSign
{
    Title = "DOCUMENT_TITLE",
    Signers = new List<DocumentSigner> { signer },
    Files = new List<IDocumentFile> { file },
};

var documentCreated = documentClient.SendDocument(sendForSign);
import boldsign

configuration = boldsign.Configuration(api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:
    document_api = boldsign.DocumentApi(api_client)
    signature_field = boldsign.FormField(
        id="Signature1",
        field_type="Signature",
        page_number=1,
        bounds=boldsign.Rectangle(x=100, y=100, width=100, height=50),
        is_required=True,
    )

    idVerification = boldsign.IdentityVerificationSettings(
        type="EveryAccess",
        maximum_retry_count=10,
        require_live_capture=True,
        require_matching_selfie=True,
        name_matcher="Strict",
        allowed_document_types=["Passport", "IDCard", "DriverLicense"],
    )

    signer = boldsign.DocumentSigner(
        name="Jenny Rosen",
        email_address="alex@example.com",
        signer_type="Signer",
        authentication_type="IdVerification",
        identity_verification_settings=idVerification,
        form_fields=[signature_field],
        locale="EN",
    )

    send_for_sign = boldsign.SendForSign(
        title="DOCUMENT_TITLE", signers=[signer], files=["FILE_PATH"]
    )

    document_created = document_api.send_document(send_for_sign=send_for_sign)
<?php
require 'vendor/autoload.php';

use BoldSign\Configuration;
use BoldSign\Api\DocumentApi;
use BoldSign\Model\DocumentSigner;
use BoldSign\Model\FormField;
use BoldSign\Model\Rectangle;
use BoldSign\Model\SendForSign;
use BoldSign\Model\IdentityVerificationSettings;

$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$documentApi = new DocumentApi($config);

$bounds = new Rectangle();
$bounds->setX(100);
$bounds->setY(100);
$bounds->setWidth(100);
$bounds->setHeight(50);

$field = new FormField();
$field->setId("Signature1");
$field->setFieldType(FormField::FIELD_TYPE_SIGNATURE);
$field->setPageNumber(1);
$field->setBounds($bounds);
$field->setIsRequired(true);

$idVerification = new IdentityVerificationSettings();
$idVerification->setType(IdentityVerificationSettings::TYPE_EVERY_ACCESS);
$idVerification->setMaximumRetryCount(10);
$idVerification->setRequireLiveCapture(true);
$idVerification->setRequireMatchingSelfie(true);
$idVerification->setNameMatcher(IdentityVerificationSettings::NAME_MATCHER_STRICT);
$idVerification->setAllowedDocumentTypes(["Passport", "IDCard", "DriverLicense"]);

$signer = new DocumentSigner();
$signer->setName("Jenny Rosen");
$signer->setEmailAddress("alex@example.com");
$signer->setSignerType(DocumentSigner::SIGNER_TYPE_SIGNER);
$signer->setAuthenticationType(DocumentSigner::AUTHENTICATION_TYPE_ID_VERIFICATION);
$signer->setIdentityVerificationSettings($idVerification);
$signer->setFormFields([$field]);
$signer->setLocale("EN");

$sendForSign = new SendForSign();
$sendForSign->setTitle("DOCUMENT_TITLE");
$sendForSign->setSigners([$signer]);
$sendForSign->setFiles(["FILE_PATH"]);

$documentCreated = $documentApi->sendDocument($sendForSign);
ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");
DocumentApi documentApi = new DocumentApi(client);

Rectangle rect = new Rectangle();
rect.setX(100f);
rect.setY(100f);
rect.setWidth(100f);
rect.setHeight(50f);

FormField field = new FormField();
field.setId("Signature1");
field.setFieldType(FormField.FieldTypeEnum.SIGNATURE);
field.setPageNumber(1);
field.setBounds(rect);
field.setIsRequired(true);

List<IdentityVerificationSettings.AllowedDocumentTypesEnum> allowedDocTypes = new ArrayList<>();
allowedDocTypes.add(IdentityVerificationSettings.AllowedDocumentTypesEnum.PASSPORT);
allowedDocTypes.add(IdentityVerificationSettings.AllowedDocumentTypesEnum.ID_CARD);
allowedDocTypes.add(IdentityVerificationSettings.AllowedDocumentTypesEnum.DRIVER_LICENSE);

IdentityVerificationSettings idVerification = new IdentityVerificationSettings();
idVerification.setType(IdentityVerificationSettings.TypeEnum.EVERY_ACCESS);
idVerification.setMaximumRetryCount(10);
idVerification.setRequireLiveCapture(true);
idVerification.setRequireMatchingSelfie(true);
idVerification.setNameMatcher(IdentityVerificationSettings.NameMatcherEnum.STRICT);
idVerification.setAllowedDocumentTypes(allowedDocTypes);

DocumentSigner signer = new DocumentSigner();
signer.setName("Jenny Rosen");
signer.setEmailAddress("alex@example.com");
signer.setSignerType(DocumentSigner.SignerTypeEnum.SIGNER);
signer.setAuthenticationType(DocumentSigner.AuthenticationTypeEnum.ID_VERIFICATION);
signer.setIdentityVerificationSettings(idVerification);
signer.setFormFields(Arrays.asList(field));
signer.setLocale(DocumentSigner.LocaleEnum.EN);

List<File> files = new ArrayList<>();
files.add(new File("FILE_PATH"));

SendForSign sendForSign = new SendForSign();
sendForSign.setTitle("DOCUMENT_TITLE");
sendForSign.setSigners(Arrays.asList(signer));
sendForSign.setFiles(files);

DocumentCreated documentCreated = documentApi.sendDocument(sendForSign);
import {
  DocumentApi,
  DocumentSigner,
  FormField,
  Rectangle,
  SendForSign,
  IdentityVerificationSettings,
} from "boldsign";
import * as fs from "fs";

async function main() {
  const documentApi = new DocumentApi();
  documentApi.setApiKey("YOUR_API_KEY");

  const rect = new Rectangle();
  rect.x = 100;
  rect.y = 100;
  rect.width = 100;
  rect.height = 50;

  const field = new FormField();
  field.id = "Signature1";
  field.fieldType = FormField.FieldTypeEnum.Signature;
  field.pageNumber = 1;
  field.bounds = rect;
  field.isRequired = true;

  const idVerification = new IdentityVerificationSettings();
  idVerification.type = IdentityVerificationSettings.TypeEnum.EveryAccess;
  idVerification.maximumRetryCount = 10;
  idVerification.requireLiveCapture = true;
  idVerification.requireMatchingSelfie = true;
  idVerification.nameMatcher = IdentityVerificationSettings.NameMatcherEnum.Strict;
  idVerification.allowedDocumentTypes = ["Passport", "IDCard", "DriverLicense"];

  const signer = new DocumentSigner();
  signer.name = "Jenny Rosen";
  signer.emailAddress = "alex@example.com";
  signer.signerType = DocumentSigner.SignerTypeEnum.Signer;
  signer.authenticationType = DocumentSigner.AuthenticationTypeEnum.IdVerification;
  signer.identityVerificationSettings = idVerification;
  signer.formFields = [field];
  signer.locale = "EN";

  const sendForSign = new SendForSign();
  sendForSign.title = "DOCUMENT_TITLE";
  sendForSign.signers = [signer];
  sendForSign.files = [fs.createReadStream("FILE_PATH")];

  const documentCreated = await documentApi.sendDocument(sendForSign);
}
main();

Can you send an ID-verified document from the web app?

Yes. Senders who prefer not to code can turn on identity verification for a signer when they prepare a document in the web app.

Our help article on how to send a document with identity verification shows each screen. The account-wide country and ID type settings apply to both routes.

What should you watch out for?

A few settings change what each check costs and how the signer feels about it. Plan them before you go live:

  • You pay $2 per successful check, and each repeat check is billed again.
  • EveryAccess checks the signer again on each visit, so costs can add up.
  • A Strict name match fails when the name you typed differs from the ID.
  • Signers pass only with an ID from a country you allow.

Type each signer’s full legal name, as it appears on their ID, to avoid failed matches.

Which plan do you need, and what does API identity verification cost?

Live sending through the API needs the Enterprise API plan, from $30 a month with 40 envelopes, billed yearly. Each extra envelope costs $0.75.

You can build and test first with a free sandbox account, and no credit card is needed. Sandbox documents are for testing only.

Each successful identity verification costs $2 on top of any plan, as our help article on ID verification charges explains. Trial accounts do not include free checks.

In the web app, ID verification comes with the Business plan at $15 per user a month, billed yearly. The Premium plan also includes it, at $99 a month for unlimited users, billed yearly. Prices are in USD.

Where do you go from here?

Your sandbox account is the quickest way to watch an ID check from the signer’s side. Pick the next step that fits:

Frequently asked questions

What is an ID verification API?

It is a set of calls your app uses to ask a person to prove who they are with a photo ID. In BoldSign, you turn it on per signer, and the signer passes the check before the document opens.

Is an identity validation API the same as identity verification?

People use the two names for the same job: checking that a real ID belongs to the person in front of the camera. Our check compares the ID, an optional selfie and the name you entered for the signer.

Do I need separate document authentication software or identity verification APIs?

Only when you need ID checks outside of signing. Our check runs inside the signing flow, is powered by Stripe Identity, and its result stays with the document.

Which ID documents can signers use?

Signers can upload a passport, an ID card or a driver's license. You can narrow the list for one signer in the API call, or for your whole account in your Business Profile.

How much does each identity verification cost?

Each successful check costs $2 and is billed apart from your plan. A repeat check, for example on every visit to the document, costs another $2.

Can I test identity verification for free?

Yes. Send from a free sandbox account and use the signer name Jenny Rosen, which passes the name match in test mode. Sandbox documents carry no live charges.

How many times can a signer retry a failed ID check?

You decide, from 1 to 10 tries, with the maximumRetryCount setting. Fewer tries also keeps the cost of repeat checks down.

Can I limit ID checks to signers from certain countries?

Yes. Turn on Allowed Countries in your Business Profile and pick the countries you accept. IDs issued anywhere else are rejected during the check.

BoldSign Team

The official team behind BoldSign—the simple, secure eSignature solution trusted by businesses worldwide. Our platform helps individuals and teams create, sign, and manage documents effortlessly while maintaining full compliance. Experience BoldSign yourself with a free trial or request a personalized demo to see it in action.

More posts by BoldSign Team
Get started

Sign up for your free trial today!

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