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 --location 'https://api.boldsign.com/v1/document/send' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: {your API key}' \
--data-raw '{
    "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": [
        "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);

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 requests

url = 'https://api.boldsign.com/v1/document/send'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your API key}'
}
data = {
    "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": [
        "data:application/pdf;base64,JVBERi0xLjcKJcfs..."
    ]
}

response = requests.post(url, headers=headers, json=data)

print(response.status_code)
print(response.json())

const axios = require('axios');

const url = 'https://api.boldsign.com/v1/document/send';
const headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your API key}'
};
const data = {
    "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": [
        "data:application/pdf;base64,JVBERi0xLjcKJcfs..."
    ]
};

axios.post(url, data, { headers })
    .then(response => {
        console.log(response.status);
        console.log(response.data);
    })
    .catch(error => {
        console.error('Error:', error.response ? error.response.data : error.message);
    });

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

use GuzzleHttp\Client;

$client = new Client();

$url = 'https://api.boldsign.com/v1/document/send';
$headers = [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '{your API key}'
];
$data = [
    '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' => [
        'data:application/pdf;base64,JVBERi0xLjcKJcfs...'
    ]
];

try {
    $response = $client->post($url, [
        'headers' => $headers,
        'json' => $data
    ]);

    echo 'Status code: ' . $response->getStatusCode() . PHP_EOL;
    echo 'Response body: ' . $response->getBody() . PHP_EOL;
} catch (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
}

Fetch Verification Data

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

curl --location 'https://api.boldsign.com/v1-beta/identityVerification/report?documentId=55a6f0cf-xxx-xxxx-xxxx-796d02cb0977' \
--header 'accept: application/json' \
--header 'X-API-KEY: {your-api-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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 requests
import json

url = "https://api.boldsign.com/v1-beta/identityVerification/report?documentId=55a6f0cf-xxx-xxxx-xxxx-796d02cb0977"

payload = {
    "emailId": "alex.gayle@cubeflakes.com",
    "order": 1
}
headers = {
    'accept': 'application/json',
    'X-API-KEY': '{your-api-key}', # Replace {your-api-key} with your actual API key
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

print(response.text)

const axios = require('axios');

const url = "https://api.boldsign.com/v1-beta/identityVerification/report?documentId=55a6f0cf-xxx-xxxx-xxxx-796d02cb0977";

const payload = {
    emailId: "alex.gayle@cubeflakes.com",
    order: 1
};

const headers = {
    'Accept': 'application/json',
    'X-API-KEY': '{your-api-key}', // Replace {your-api-key} with your actual API key
    'Content-Type': 'application/json'
};

axios.post(url, payload, { headers })
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error('Error:', error.response.data);
    });

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$url = 'https://api.boldsign.com/v1-beta/identityVerification/report?documentId=55a6f0cf-xxx-xxxx-xxxx-796d02cb0977';

$payload = [
    'emailId' => 'alex.gayle@cubeflakes.com',
    'order' => 1
];

$headers = [
    'Accept' => 'application/json',
    'X-API-KEY' => '{your-api-key}', // Replace {your-api-key} with your actual API key
    'Content-Type' => 'application/json'
];

$client = new Client();

$response = $client->post($url, [
    'headers' => $headers,
    'json' => $payload
]);

echo $response->getBody()->getContents();

?>

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 --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=b5529f7e-xxxx-xxxx-xxxx-7686e52dfa8a' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: {your API key}' \
--data '{
    "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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
document_id = 'b5529f7e-xxxx-xxxx-xxxx-7686e52dfa8a'
api_key = '{your API key}'

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': api_key
}

data = {
    "fields": [
        {
            "id": "FieldId",
            "value": "A prefilled value"
        }
    ]
}

response = requests.patch(f'{url}?documentId={document_id}', headers=headers, json=data)

print(response.json())

const axios = require('axios');

const documentId = 'b5529f7e-xxxx-xxxx-xxxx-7686e52dfa8a';
const apiKey = '{your API key}';

axios.patch(`https://api.boldsign.com/v1/document/prefillFields?documentId=${documentId}`, {
    fields: [
        {
            id: "FieldId",
            value: "A prefilled value"
        }
    ]
}, {
    headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': apiKey
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$documentId = 'b5529f7e-xxxx-xxxx-xxxx-7686e52dfa8a';
$apiKey = '{your API key}';

$response = $client->patch('https://api.boldsign.com/v1/document/prefillFields', [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-API-KEY' => $apiKey,
    ],
    'query' => [
        'documentId' => $documentId,
    ],
    'json' => [
        'fields' => [
            [
                'id' => 'FieldId',
                'value' => 'A prefilled value'
            ]
        ]
    ]
]);