Prefill using verification data

When sending out documents for signatures, you might want to prefill certain form fields using the verification data provided by the signer during the ID verification process. BoldSign offers an API that allows you to prefill form fields in a document after the signer has verified their identity during the signing process.

To streamline the signing process and ensure accurate data, you can prefill form fields with the signer's verification data once they have completed the ID verification. This is achieved by setting the holdForPrefill property of the document's identityVerificationSettings to true. By doing so, you can temporarily hold the signer until the necessary form fields are prefilled.

Process Flow

Enable Hold for Prefill: Set the holdForPrefill property to true in the document's identityVerificationSettings. This ensures that the signer is held for prefill after completing ID verification.
Listen for Identity Verification Succeeded Event: Once the signer has successfully completed the ID verification, listen for the Identity Verification Succeeded event. This event provides the details necessary to proceed with the next steps.
Fetch Verification Data: Use the Identity Verification Report API to retrieve the signer's verification data. This data includes the information provided by the signer during the ID verification process.
Use Document Properties API: Use the Document Properties API to retrieve the field data for the document. This data will be used in the Prefill API to prefill the specific form fields.
Prefill Form Fields: With the verification data in hand, call the Prefill API to fill out the relevant form fields in the document. This ensures that the form fields are accurately populated with the signer's verified information.
Complete Prefill Process: Once the prefill is completed, the signer can proceed with the signing process. The hold time for this process is a maximum of 30 seconds. If the prefill process exceeds this time limit, the signer will be redirected to the signing page automatically.

The following APIs are discussed in this guide:

Send out document with holdForPrefill

Set the holdForPrefill property within the document's identityVerificationSettings to true when sending documents.

Here are example codes you can use to do this:

curl -X POST 'https://api.boldsign.com/v1/document/send' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {your API key}' \
-d '{
    "Title": "Document title",
    "Message": "This is a document message",
    "Signers": [
        {
            "Name": "David",
            "EmailAddress": "david@cubeflakes.com",
            "IdentityVerificationSettings": {
                "Type": "EveryAccess",
                "MaximumRetryCount": 10,
                "RequireLiveCapture": true,
                "RequireMatchingSelfie": true,
                "NameMatcher": "Strict",
                "HoldForPrefill": true,
                "AllowedDocumentTypes": [
                    "Passport",
                    "IDCard",
                    "DriverLicense"
                ]
            },
            "FormFields": [
                {
                    "Id": "TextBox1",
                    "FieldType": "Textbox",
                    "PageNumber": 1,
                    "Bounds": {
                        "X": 50,
                        "Y": 50,
                        "Width": 200,
                        "Height": 30
                    }
                }
            ]
        }
    ],
    "Files": [
        "data:application/pdf;base64,JVBERi0xLjcKJcfs..."
    ]
}'

var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}");
var documentClient = new DocumentClient(apiClient);

var textField = new FormField(
    id: "TextBox1",
    isReadOnly: true,
    type: FieldType.TextBox,
    pageNumber: 1,
    bounds: new Rectangle(x: 50, y: 50, width: 200, height: 30));

var idVerificationSettings = new IdentityVerificationSettings(
    type: IdentityVerificationType.EveryAccess,
    maximumRetryCount: 10,
    requireLiveCapture: true,
    requireMatchingSelfie: true,
    nameMatcher: NameVariation.Strict)
{
    HoldForPrefill = true,
    AllowedDocumentTypes = new List<AllowedDocumentType>()
    {
        AllowedDocumentType.IDCard,
        AllowedDocumentType.Passport,
        AllowedDocumentType.DriverLicense,
    },
};

var signer = new DocumentSigner(
    signerName: "David",
    signerType: SignerType.Signer,
    identityVerificationSettings: idVerificationSettings,
    signerEmail: "david@cubeflakes.com",
    formFields: new List<FormField>() { textField },
    locale: Locales.EN);

var documentSigners = new List<DocumentSigner>()
{
    signer,
};

var sendForSign = new SendForSign()
{
    Message = "please sign this",
    Title = "Agreement",
    HideDocumentId = false,
    Signers = documentSigners,
    Files = new List<IDocumentFile>()
    {
        new DocumentFileBytes()
        {
            ContentType = "application/pdf",
            FileName = "sample.pdf",
            FileData = fileStreamArray,
        },
    },
};

var documentCreated = await documentClient.SendDocumentAsync(sendForSign);

import boldsign

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

with boldsign.ApiClient(configuration) as api_client:
    document_api = boldsign.DocumentApi(api_client)

    send_for_sign = boldsign.SendForSign(
        title="Document title",
        message="This is a document message",
        signers=[
            boldsign.DocumentSigner(
                name="David",
                emailAddress="david@cubeflakes.com",
                identityVerificationSettings=boldsign.IdentityVerificationSettings(
                    type="EveryAccess",
                    maximumRetryCount=10,
                    requireLiveCapture=True,
                    requireMatchingSelfie=True,
                    nameMatcher="Strict",
                    holdForPrefill=True
                ),
                formFields=[
                    boldsign.FormField(id="TextBox1", fieldType="Textbox", pageNumber=1,bounds=boldsign.Rectangle(x=50, y=50, width=200, height=30))
                ]
            )
        ],
        files=["FILE_PATH"]
    )

    response = document_api.send_document(send_for_sign=send_for_sign)

<?php
require 'vendor/autoload.php';

// Configure API key
$config = new BoldSign\Configuration();
$config->setApiKey('YOUR_API_KEY');

$documentApi = new BoldSign\Api\DocumentApi($config);

$sendForSign = new BoldSign\Model\SendForSign();
$sendForSign->setTitle('Document title');
$sendForSign->setMessage('This is a document message');
$sendForSign->setHoldForPrefill(true);
// build signers and files per SDK model
$documentCreated = $documentApi->sendDocument($sendForSign);

import { DocumentApi } from "boldsign";

const documentApi = new DocumentApi();
documentApi.setApiKey("YOUR_API_KEY");

const sendForSign = {
    title: "Document title",
    message: "This is a document message",
    signers: [
        {
            name: "David",
            emailAddress: "david@cubeflakes.com",
            identityVerificationSettings: {
                type: "EveryAccess",
                maximumRetryCount: 10,
                requireLiveCapture: true,
                requireMatchingSelfie: true,
                nameMatcher: "Strict",
                holdForPrefill: true
            },
            formFields: [ { id: "TextBox1", fieldType: "Textbox", pageNumber: 1, bounds: { x:50, y:50, width:200, height:30 } } ]
        }
    ],
    files: ["FILE_PATH"]
};
documentApi.sendDocument(sendForSign);

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

DocumentApi documentApi = new DocumentApi(client);

FormField textField = new FormField();
textField.setId("TextBox1");
textField.setFieldType("Textbox");
textField.setPageNumber(1);
textField.setBounds(new Rectangle(50, 50, 200, 30));

IdentityVerificationSettings identityVerificationSettings = new IdentityVerificationSettings();
identityVerificationSettings.setType("EveryAccess");
identityVerificationSettings.setMaximumRetryCount(10);
identityVerificationSettings.setRequireLiveCapture(true);
identityVerificationSettings.setRequireMatchingSelfie(true);
identityVerificationSettings.setNameMatcher("Strict");
identityVerificationSettings.setHoldForPrefill(true);

DocumentSigner signer = new DocumentSigner();
signer.setName("David");
signer.setEmailAddress("david@cubeflakes.com");
signer.setSignerType("Signer");
signer.setIdentityVerificationSettings(identityVerificationSettings);
signer.setFormFields(Arrays.asList(textField));

SendForSign sendForSign = new SendForSign();
sendForSign.setTitle("Document title");
sendForSign.setMessage("This is a document message");
sendForSign.setSigners(Arrays.asList(signer));
sendForSign.setFiles(Arrays.asList("FILE_PATH"));

DocumentCreated created = documentApi.sendDocument(sendForSign);

Fetch Verification Data

After receiving the Identity Verification Succeeded event, utilize the /v1/identityVerification/report API to obtain the signer's verification data.

curl -X POST 'https://api.boldsign.com/v1/identityVerification/report?documentId=55a6f0cf-xxx-xxxx-xxxx-796d02cb0977' \
-H 'accept: application/json' \
-H 'X-API-KEY: {your-api-key}' \
-H 'Content-Type: application/json' \
-d '{
    "EmailId": "alex.gayle@cubeflakes.com",
    "Order": 1
}'

var apiClient = new ApiClient("https://api.boldsign.com", "{your-api-key}");
var idVerificationClient = new IdVerificationClient(apiClient);

var documentId = "55a6f0cf-xxx-xxxx-xxxx-796d02cb0977";

var verificationReportRequest = new VerificationReportRequest()
{
    EmailId = "alex.gayle@cubeflakes.com",
    Order = 1,
};

var idVerificationReport = idVerificationClient.GetReport(documentId, verificationReportRequest);

import boldsign

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

with boldsign.ApiClient(configuration) as api_client:
    identity_verification_api = boldsign.IdentityVerificationApi(api_client)

    verification_request = boldsign.VerificationReportRequest(
        emailId="alex.gayle@cubeflakes.com",
        order=1
    )

    report = identity_verification_api.get_report("DOCUMENT_ID", verification_request)

<?php

require 'vendor/autoload.php';

$config = new BoldSign\Configuration();
$config->setApiKey('YOUR_API_KEY');

$identityApi = new BoldSign\Api\IdentityVerificationApi($config);

$verificationRequest = new BoldSign\Model\VerificationReportRequest();
$verificationRequest->setEmailId('alex.gayle@cubeflakes.com');
$verificationRequest->setOrder(1);

$report = $identityApi->getReport('DOCUMENT_ID', $verificationRequest);
print_r($report);

import { IdentityVerificationApi, VerificationReportRequest } from "boldsign";

const identityApi = new IdentityVerificationApi();
identityApi.setApiKey("YOUR_API_KEY");

const verificationRequest = new VerificationReportRequest();
verificationRequest.emailId = "alex.gayle@cubeflakes.com";
verificationRequest.order = 1;

identityApi.getReport("DOCUMENT_ID", verificationRequest);

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

IdentityVerificationApi identityVerificationApi = new IdentityVerificationApi(client);

String documentId = "DOCUMENT_ID";

VerificationReportRequest verificationRequest = new VerificationReportRequest();
verificationRequest.setEmailId("alex.gayle@cubeflakes.com");
verificationRequest.setOrder(1);

VerificationReport report = identityVerificationApi.getReport(documentId, verificationRequest);

Prefill Form Fields

You can now prefill form fields using the /v1/document/prefillFields API. To achieve this, you must provide the document ID, the form field ID, and the value you want to prefill from the verification data.

curl -X PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=b5529f7e-xxxx-xxxx-xxxx-7686e52dfa8a' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {your API key}' \
-d '{
    "Fields": [
        {
            "Id": "FieldId",
            "Value": "A prefilled value"
        }
    ]
}'

var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}");
var documentClient = new DocumentClient(apiClient);

var documentId = "b5529f7e-xxxx-xxxx-xxxx-7686e52dfa8a";

var prefillFieldRequest = new PrefillFieldRequest(documentId)
{
    Fields = new List<PrefillField>()
    {
        new PrefillField()
        {
            Id = "FieldId",
            Value = "A prefilled value"
        }
    },
};

await documentClient.PrefillFieldsAsync(prefillFieldRequest);

import boldsign

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

with boldsign.ApiClient(configuration) as api_client:
    document_api = boldsign.DocumentApi(api_client)

    prefill_request = boldsign.PrefillFieldRequest(documentId="YOUR_DOCUMENT_ID")
    prefill_request.fields = [ boldsign.PrefillField(id="YOUR_FIELD_ID", value="A prefilled value") ]

    result = document_api.prefill_fields(prefill_request)

<?php

require 'vendor/autoload.php';

$config = new BoldSign\Configuration();
$config->setApiKey('YOUR_API_KEY');

$documentApi = new BoldSign\Api\DocumentApi($config);

$prefill = new BoldSign\Model\PrefillFieldRequest();
$prefill->setDocumentId('YOUR_DOCUMENT_ID');
$field = new BoldSign\Model\PrefillField();
$field->setId('YOUR_FIELD_ID');
$field->setValue('A prefilled value');
$prefill->setFields([$field]);

$result = $documentApi->prefillFields($prefill);

import { DocumentApi, PrefillFieldRequest } from "boldsign";

const documentApi = new DocumentApi();
documentApi.setApiKey("YOUR_API_KEY");

const req = new PrefillFieldRequest('YOUR_DOCUMENT_ID');
req.fields = [ { id: 'YOUR_FIELD_ID', value: 'A prefilled value' } ];

const resp = await documentApi.prefillFields(req);

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");

DocumentApi documentApi = new DocumentApi(client);

PrefillFieldRequest prefill = new PrefillFieldRequest("YOUR_DOCUMENT_ID");
PrefillField field = new PrefillField();
field.setId("YOUR_FIELD_ID");
field.setValue("A prefilled value");
prefill.setFields(Arrays.asList(field));

documentApi.prefillFields(prefill);