Prefill form fields

patch/v1/document/prefillFields

Prefill 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
Email
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 the id 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-generated id 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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your-api-key}'
}
data = {
    "fields": [
        {
            "id": "textbox_mShRr",
            "value": "Prefill value"
        }
    ]
}

document_id = '2a448030-xxx-xxx-xxxx-58b1349662fc'
params = {'documentId': document_id}

response = requests.patch(url, headers=headers, json=data, params=params)

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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your-api-key}'
}

data = {
    "fields": [
        {
            "id": "checkbox_b5yuo",
            "value": "ON"
        }
    ]
}

document_id = '2a448030-xxx-xxx-xxxx-58b1349662fc'
params = {'documentId': document_id}


response = requests.patch(url, headers=headers, json=data, params=params)

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 and label 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 its value
The id must match exactly with one of the radio button's id 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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your-api-key}'
}

data = {
    "fields": [
        {
            "id": "radioChild_AknIg",
            "value": "ON"
        }
    ]
}

document_id = '2a448030-xxx-xxx-xxxx-58b1349662fc'
params = {'documentId': document_id}

response = requests.patch(url, headers=headers, json=data, params=params)

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 the id
Provide one of the radio button's label as the value

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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your-api-key}'
}

data = {
    "fields": [
        {
            "id": "CodingExpertise",
            "value": "Intermediate"
        }
    ]
}

document_id = '2a448030-xxx-xxx-xxxx-58b1349662fc'
params = {'documentId': document_id}

response = requests.patch(url, headers=headers, json=data, params=params)

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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your-api-key}'
}

data = {
    "fields": [
        {
            "id": "editableDate_67P9d",
            "value": "02/19/2024"
        }
    ]
}

document_id = '2a448030-xxx-xxx-xxxx-58b1349662fc'
params = {'documentId': document_id}

response = requests.patch(url, headers=headers, json=data, params=params)

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;

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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your-api-key}'
}

data = {
    "fields": [
        {
            "id": "dropdown_qrsr1",
            "value": "option1"
        }
    ]
}

document_id = '2a448030-xxx-xxx-xxxx-58b1349662fc'
params = {'documentId': document_id}

response = requests.patch(url, headers=headers, json=data, params=params)

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 requests

url = 'https://api.boldsign.com/v1/document/prefillFields'
headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{your-api-key}'
}

data = {
    "fields": [
        {
            "id": "image_6Ogud",
            "value": "data:image/png;base64,iVBORw0KGgoAAAANS..."
        }
    ]
}

document_id = '2a448030-xxx-xxx-xxxx-58b1349662fc'
params = {'documentId': document_id}

response = requests.patch(url, headers=headers, json=data, params=params)

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.

idstringRequired	The ID of the form field to be prefilled. This can be obtained from the properties API.
valuestringRequired	The value to be assigned to the form field.

onBehalfOfarray

Email address of the sender if you are prefilling the on behalf of documents.

Prefill form fields

Supported field types

Unsupported field types

DataSync

Limitations

Prerequisite

Textbox

Checkbox

Radio button

Using radio button ID

Using radio button group

Editable date

Image

Format Syntax

Query parameters

Request body

Quick Links

Trust & Security

Company

Quick Links

Trust & Security

Company

Prefill form fields

Supported field types

Unsupported field types

DataSync

Limitations

Prerequisite

Textbox

Checkbox

Radio button

Using radio button ID

Using radio button group

Editable date

Dropdown

Image

Format Syntax

Query parameters

Request body

Quick Links

Trust & Security

Company

Quick Links

Trust & Security

Company