Prefill form fields
patch/v1/document/prefillFieldsPrefill form fields is a feature that allows you to assign values to the form fields in the document before or after sending it to the signers. You can prefill the form fields with the data collected from the signer or from any other source. However, it's important to note that prefilling form fields is not allowed after the document has been signed by the signer.
Supported field types
The following field types are supported for prefilling:
- Textbox
- Checkbox
- Radio buttons
- Editable date
- Dropdown
- Image
Unsupported field types
The following field types are not supported for prefilling:
- Name
- Signature
- Initial
- DateSigned
- Attachment
- Hyperlink
- Title
- Company
- Label
DataSync
The prefill fields feature also supports the DataSyncTag
. If the form field has a DataSyncTag
, then the value applied to the targeted field will also be applied to other form fields with the same DataSyncTag
value and the same form field type.
Limitations
- Unsupported fields cannot be prefilled.
- The signer related to the form field should not have already signed the document.
- Revoked, declined, expired or other invalid status documents cannot be prefilled. Only in-progress documents can be prefilled.
Prerequisite
To prefill a form field, you need to know its id
. This identifier allows you to target the specific field and assign a value. There are two methods to obtain the id
:
Assign Custom IDs When Sending a Document When you send a document for signing, you can assign custom
id
values to form fields. This approach allows you to predetermine theid
of fields you may want to prefill later.Retrieve Auto-generated IDs Using the API If you haven't assigned custom IDs, you can use the
/v1/document/properties
API to retrieve the entire document details, including auto-generatedid
values for all form fields. Learn more about the document properties API
Custom IDs provide more control and predictability when prefilling fields. Auto-generated IDs can be used when working with existing documents or when custom IDs weren't assigned.
Textbox
Prefilling a textbox form field is a straightforward process. You need to provide the id
of the form field and the value
you want to assign to it.
curl --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=2a448030-xxx-xxx-xxxx-58b1349662fc' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: {your-api-key}' \ --data '{ "fields": [ { "id": "textbox_mShRr", "value": "Prefill value" } ] }'
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentId = "b5529f7e-a904-49ff-859f-7686e52dfa8a"; var prefillFieldRequest = new PrefillFieldRequest(documentId) { Fields = new List<PrefillField>() { new PrefillField() { Id = "textbox_mShRr", Value = "Prefill 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_field = boldsign.PrefillField( id="textbox_mShRr", value="Prefill value" ) prefill_field_requests = boldsign.PrefillFieldRequest( fields=[prefill_field] ) documentId = "YOUR_DOCUMENT_ID" prefill_fields_response = document_api.prefill_fields( document_id=documentId, prefill_field_request =prefill_field_requests )
const axios = require('axios'); const url = 'https://api.boldsign.com/v1/document/prefillFields'; const apiKey = '{your-api-key}'; const documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; const headers = { 'Content-Type': 'application/json', 'X-API-KEY': apiKey, }; const data = { fields: [ { id: 'textbox_mShRr', value: 'Prefill value', }, ], }; axios .patch(url, data, { headers, params: { documentId } }) .then((response) => { console.log(response); }) .catch((error) => { console.error('Error:', error); });
<?php require 'vendor/autoload.php'; // Make sure to include the autoload file from GuzzleHttp use GuzzleHttp\Client; $url = 'https://api.boldsign.com/v1/document/prefillFields'; $apiKey = '{your-api-key}'; $documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; $headers = [ 'Content-Type' => 'application/json', 'X-API-KEY' => $apiKey ]; $data = [ 'fields' => [ [ 'id' => 'textbox_mShRr', 'value' => 'Prefill value' ] ] ]; $client = new GuzzleHttp\Client(); $response = $client->request('PATCH', $url, [ 'headers' => $headers, 'json' => $data, 'query' => ['documentId' => $documentId] ]); $body = $response->getBody(); echo $body;
Checkbox
To prefill a checkbox form field, you will need to provide the id
of the form field and its value
. The id
must match exactly with the checkbox's id
in your document, while the value
should be either "ON"
(to check the box) or "OFF"
(to uncheck it).
curl --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=2a448030-xxx-xxx-xxxx-58b1349662fc' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: {your-api-key}' \ --data '{ "fields": [ { "id": "checkbox_b5yuo", "value": "ON" } ] }'
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentId = "b5529f7e-a904-49ff-859f-7686e52dfa8a"; var prefillFieldRequest = new PrefillFieldRequest(documentId) { Fields = new List<PrefillField>() { new PrefillField() { Id = "checkbox_b5yuo", Value = "ON" } }, }; 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_field = boldsign.PrefillField( id="checkbox_b5yuo", value="ON" ) prefill_field_requests = boldsign.PrefillFieldRequest( fields=[prefill_field] ) documentId = "YOUR_DOCUMENT_ID" prefill_fields_response = document_api.prefill_fields( document_id=documentId, prefill_field_request =prefill_field_requests )
const axios = require('axios'); const url = 'https://api.boldsign.com/v1/document/prefillFields'; const apiKey = '{your-api-key}'; const documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; const headers = { 'Content-Type': 'application/json', 'X-API-KEY': apiKey, }; const data = { fields: [ { id: 'checkbox_b5yuo', value: 'ON', }, ], }; axios .patch(url, data, { headers, params: { documentId } }) .then((response) => { console.log(response); }) .catch((error) => { console.error('Error:', error); });
<?php require 'vendor/autoload.php'; // Make sure to include the autoload file from GuzzleHttp use GuzzleHttp\Client; $url = 'https://api.boldsign.com/v1/document/prefillFields'; $apiKey = '{your-api-key}'; $documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; $headers = [ 'Content-Type' => 'application/json', 'X-API-KEY' => $apiKey ]; $data = [ 'fields' => [ [ 'id' => 'checkbox_b5yuo', 'value' => 'ON' ] ] ]; $client = new GuzzleHttp\Client(); $response = $client->request('PATCH', $url, [ 'headers' => $headers, 'json' => $data, 'query' => ['documentId' => $documentId] ]); $body = $response->getBody(); echo $body;
Radio button
Radio buttons can be prefilled in two ways:
- Using the
id
of a radio button in the group - Using the
groupName
andlabel
property of radio buttons
Using radio button ID
To prefill a radio button form field using its ID:
- Provide the
id
of the form field and itsvalue
- The
id
must match exactly with one of the radio button'sid
in your document - Set
value
to"ON"
to select it or"OFF"
to unselect it
Selecting one radio button automatically unselects other radio buttons in the same group.
curl --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=2a448030-xxx-xxx-xxxx-58b1349662fc' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: {your-api-key}' \ --data '{ "fields": [ { "id": "radioChild_AknIg", "value": "ON" } ] } '
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentId = "b5529f7e-a904-49ff-859f-7686e52dfa8a"; var prefillFieldRequest = new PrefillFieldRequest(documentId) { Fields = new List<PrefillField>() { new PrefillField() { Id = "radioChild_AknIg", Value = "ON" } }, }; 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_field = boldsign.PrefillField( id="radioChild_AknIg", value="ON" ) prefill_field_requests = boldsign.PrefillFieldRequest( fields=[prefill_field] ) documentId = "YOUR_DOCUMENT_ID" prefill_fields_response = document_api.prefill_fields( document_id=documentId, prefill_field_request =prefill_field_requests )
const axios = require('axios'); const url = 'https://api.boldsign.com/v1/document/prefillFields'; const apiKey = '{your-api-key}'; const documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; const headers = { 'Content-Type': 'application/json', 'X-API-KEY': apiKey, }; const data = { fields: [ { id: 'radioChild_AknIg', value: 'ON', }, ], }; axios .patch(url, data, { headers, params: { documentId } }) .then((response) => { console.log(response); }) .catch((error) => { console.error('Error:', error); });
<?php require 'vendor/autoload.php'; // Make sure to include the autoload file from GuzzleHttp use GuzzleHttp\Client; $url = 'https://api.boldsign.com/v1/document/prefillFields'; $apiKey = '{your-api-key}'; $documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; $headers = [ 'Content-Type' => 'application/json', 'X-API-KEY' => $apiKey ]; $data = [ 'fields' => [ [ 'id' => 'radioChild_AknIg', 'value' => 'ON' ] ] ]; $client = new GuzzleHttp\Client(); $response = $client->request('PATCH', $url, [ 'headers' => $headers, 'json' => $data, 'query' => ['documentId' => $documentId] ]); $body = $response->getBody(); echo $body;
Using radio button group
To prefill a radio button using groupName
and label
:
- Use the
groupName
of the radio button group as theid
- Provide one of the radio button's
label
as thevalue
Consider the following example where a radio button group is created to allow job applicants to select their level of expertise in a coding. The radio buttons provide three options: Novice
, Intermediate
and Expert
.
Below is a simplified code snippet for document send API request. Please note that this is a minimal example, and many properties have been omitted for the brevity.
{ "signers": { "formFields": { { "fieldType": "RadioButton", "label": "Novice", "groupName": "CodingExpertise", }, { "fieldType": "RadioButton", "label": "Intermediate", "groupName": "CodingExpertise", }, { "fieldType": "RadioButton", "label": "Expert", "groupName": "CodingExpertise", } } } }
Here's how you can select the Intermediate
radio button within the CodingExpertise
group. If either the Novice
or Expert
radio buttons are currently selected, they will automatically deselect when you prefill the choice as Intermediate
.
curl --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=2a448030-xxx-xxx-xxxx-58b1349662fc' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: {your-api-key}' \ --data '{ "fields": [ { "id": "CodingExpertise", "value": "Intermediate" } ] } '
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentId = "b5529f7e-a904-49ff-859f-7686e52dfa8a"; var prefillFieldRequest = new PrefillFieldRequest(documentId) { Fields = new List<PrefillField>() { new PrefillField() { Id = "CodingExpertise", Value = "Intermediate" } }, }; 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_field = boldsign.PrefillField( id="CodingExpertise", value="Intermediate" ) prefill_field_requests = boldsign.PrefillFieldRequest( fields=[prefill_field] ) documentId = "YOUR_DOCUMENT_ID" prefill_fields_response = document_api.prefill_fields( document_id=documentId, prefill_field_request =prefill_field_requests )
const axios = require('axios'); const url = 'https://api.boldsign.com/v1/document/prefillFields'; const apiKey = '{your-api-key}'; const documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; const headers = { 'Content-Type': 'application/json', 'X-API-KEY': apiKey, }; const data = { fields: [ { id: 'CodingExpertise', value: 'Intermediate', }, ], }; axios .patch(url, data, { headers, params: { documentId } }) .then((response) => { console.log(response); }) .catch((error) => { console.error('Error:', error); });
<?php require 'vendor/autoload.php'; // Make sure to include the autoload file from GuzzleHttp use GuzzleHttp\Client; $url = 'https://api.boldsign.com/v1/document/prefillFields'; $apiKey = '{your-api-key}'; $documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; $headers = [ 'Content-Type' => 'application/json', 'X-API-KEY' => $apiKey ]; $data = [ 'fields' => [ [ 'id' => 'CodingExpertise', 'value' => 'Intermediate' ] ] ]; $client = new GuzzleHttp\Client(); $response = $client->request('PATCH', $url, [ 'headers' => $headers, 'json' => $data, 'query' => ['documentId' => $documentId] ]); $body = $response->getBody(); echo $body;
Editable date
To prefill an editable date field, you must provide the date value exactly as it was specified when sending the document or as configured in the template.
curl --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=2a448030-xxx-xxx-xxxx-58b1349662fc' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: {your-api-key}' \ --data '{ "fields": [ { "id": "editableDate_67P9d", "value": "02/19/2024" } ] } '
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentId = "b5529f7e-a904-49ff-859f-7686e52dfa8a"; var prefillFieldRequest = new PrefillFieldRequest(documentId) { Fields = new List<PrefillField>() { new PrefillField() { Id = "editableDate_67P9d", Value = "02/19/2024" } }, }; 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_field = boldsign.PrefillField( id="editableDate_67P9d", value="02/19/2024" ) prefill_field_requests = boldsign.PrefillFieldRequest( fields=[prefill_field] ) documentId = "YOUR_DOCUMENT_ID" prefill_fields_response = document_api.prefill_fields( document_id=documentId, prefill_field_request =prefill_field_requests )
const axios = require('axios'); const url = 'https://api.boldsign.com/v1/document/prefillFields'; const apiKey = '{your-api-key}'; const documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; const headers = { 'Content-Type': 'application/json', 'X-API-KEY': apiKey, }; const data = { fields: [ { id: 'editableDate_67P9d', value: '02/19/2024', }, ], }; axios .patch(url, data, { headers, params: { documentId } }) .then((response) => { console.log(response); }) .catch((error) => { console.error('Error:', error); });
<?php require 'vendor/autoload.php'; // Make sure to include the autoload file from GuzzleHttp use GuzzleHttp\Client; $url = 'https://api.boldsign.com/v1/document/prefillFields'; $apiKey = '{your-api-key}'; $documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; $headers = [ 'Content-Type' => 'application/json', 'X-API-KEY' => $apiKey ]; $data = [ 'fields' => [ [ 'id' => 'editableDate_67P9d', 'value' => '02/19/2024' ] ] ]; $client = new GuzzleHttp\Client(); $response = $client->request('PATCH', $url, [ 'headers' => $headers, 'json' => $data, 'query' => ['documentId' => $documentId] ]); $body = $response->getBody(); echo $body;
Dropdown
To prefill an dropdown field, you must provide one of the dropdonw value exactly as it was specified when sending the document or as configured in the template.
curl --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=2a448030-xxx-xxx-xxxx-58b1349662fc' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: {your-api-key}' \ --data '{ "fields": [ { "id": "dropdown_qrsr1", "value": "option1" } ] } '
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentId = "b5529f7e-a904-49ff-859f-7686e52dfa8a"; var prefillFieldRequest = new PrefillFieldRequest(documentId) { Fields = new List<PrefillField>() { new PrefillField() { Id = "dropdown_qrsr1", Value = "option1" } }, }; 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_field = boldsign.PrefillField( id="dropdown_qrsr1", value="option1" ) prefill_field_requests = boldsign.PrefillFieldRequest( fields=[prefill_field] ) documentId = "YOUR_DOCUMENT_ID" prefill_fields_response = document_api.prefill_fields( document_id=documentId, prefill_field_request =prefill_field_requests )
const axios = require('axios'); const url = 'https://api.boldsign.com/v1/document/prefillFields'; const apiKey = '{your-api-key}'; const documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; const headers = { 'Content-Type': 'application/json', 'X-API-KEY': apiKey, }; const data = { fields: [ { id: 'dropdown_qrsr1', value: 'option1', }, ], }; axios .patch(url, data, { headers, params: { documentId } }) .then((response) => { console.log(response); }) .catch((error) => { console.error('Error:', error); });
<?php require 'vendor/autoload.php'; // Make sure to include the autoload file from GuzzleHttp use GuzzleHttp\Client; $url = 'https://api.boldsign.com/v1/document/prefillFields'; $apiKey = '{your-api-key}'; $documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; $headers = [ 'Content-Type' => 'application/json', 'X-API-KEY' => $apiKey ]; $data = [ 'fields' => [ [ 'id' => 'dropdown_qrsr1', 'value' => 'option1' ] ] ]; $client = new GuzzleHttp\Client(); $response = $client->request('PATCH', $url, [ 'headers' => $headers, 'json' => $data, 'query' => ['documentId' => $documentId] ]); $body = $response->getBody(); echo $body;
Image
To prefill an image field, you must provide the image in base64 (data URI scheme) format in the value
property.
Format Syntax
The format for the value
property should be:
data:{{imageType}};base64,{{content}}
Where:
{{imageType}}
is the MIME type of the image (e.g., image/png, image/jpeg){{content}}
is the base64-encoded image data
curl --location --request PATCH 'https://api.boldsign.com/v1/document/prefillFields?documentId=2a448030-xxx-xxx-xxxx-58b1349662fc' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: {your-api-key}' \ --data '{ "fields": [ { "id": "image_6Ogud", "value": "data:image/png;base64,iVBORw0KGgoAAAANS..." } ] } '
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}"); var documentClient = new DocumentClient(apiClient); var documentId = "b5529f7e-a904-49ff-859f-7686e52dfa8a"; var prefillFieldRequest = new PrefillFieldRequest(documentId) { Fields = new List<PrefillField>() { new PrefillField() { Id = "image_6Ogud", Value = "data:image/png;base64,iVBORw0KGgoAAAANS..." } }, }; 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_field = boldsign.PrefillField( id="image_6Ogud", value="data:image/png;base64,iVBORw0KGgoAAAANS..." ) prefill_field_requests = boldsign.PrefillFieldRequest( fields=[prefill_field] ) documentId = "YOUR_DOCUMENT_ID" prefill_fields_response = document_api.prefill_fields( document_id=documentId, prefill_field_request =prefill_field_requests )
const axios = require('axios'); const url = 'https://api.boldsign.com/v1/document/prefillFields'; const apiKey = '{your-api-key}'; const documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; const headers = { 'Content-Type': 'application/json', 'X-API-KEY': apiKey, }; const data = { fields: [ { id: 'image_6Ogud', value: 'data:image/png;base64,iVBORw0KGgoAAAANS...', }, ], }; axios .patch(url, data, { headers, params: { documentId } }) .then((response) => { console.log(response); }) .catch((error) => { console.error('Error:', error); });
<?php require 'vendor/autoload.php'; // Make sure to include the autoload file from GuzzleHttp use GuzzleHttp\Client; $url = 'https://api.boldsign.com/v1/document/prefillFields'; $apiKey = '{your-api-key}'; $documentId = '2a448030-xxx-xxx-xxxx-58b1349662fc'; $headers = [ 'Content-Type' => 'application/json', 'X-API-KEY' => $apiKey ]; $data = [ 'fields' => [ [ 'id' => 'image_6Ogud', 'value' => 'data:image/png;base64,iVBORw0KGgoAAAANS...' ] ] ]; $client = new GuzzleHttp\Client(); $response = $client->request('PATCH', $url, [ 'headers' => $headers, 'json' => $data, 'query' => ['documentId' => $documentId] ]); $body = $response->getBody(); echo $body;
Query parameters
documentIdstringRequired | The ID of the document to which the form fields have to be prefilled. |
Request body
fieldsarrayRequired | Array of form fields to be prefilled.
| ||||
onBehalfOfarray | Email address of the sender if you are prefilling the on behalf of documents. |