Collect Signer Information Using Image Form Fields via API

TL;DR: BoldSign Image Form Fields allow developers to configure image upload fields via the API, which signers fill by uploading photos or documents, such as IDs or receipts during the signing process. This enables teams to collect visual proof as part of the signed agreement, eliminating separate upload steps and keeping signatures and evidence together for compliance-driven workflows.

Collecting supporting documents during an eSignature workflow, such as ID cards, receipts, or proof images is often inefficient. When signers are asked to send files separately through email or external portals, teams face delays, follow-ups, and fragmented records.

BoldSign Image Form Fields address this by allowing developers to define image upload fields using the API, which signers complete directly inside the document while signing. The uploaded image is captured at the moment of signing and becomes part of the finalized document, making workflows cleaner, faster, and easier to manage.

This guide is intended for developers, product teams, and automation engineers using BoldSign APIs. It explains what Image Form Fields are, how they work, when to use them, and how to add them to documents using the API, with practical examples.

What are image form fields in BoldSign?

Image Form Fields in BoldSign are special form fields that allow signers to upload images directly into specific positions on a document during the signing process.

Instead of just typing text or drawing a signature, signers can attach photos or scanned images exactly where you place the field.

What can you do with image form fields?

• Collect images as part of signing: Signers upload files like ID cards, receipts, or photos without leaving the signing page.
• Guide signers clearly: Each field can show a title and description explaining what to upload.
• Control allowed formats: You can restrict uploads to formats like .jpg, .jpeg, .png, .svg, .bmp using allowedFileExtensions.

How do image form fields keep documents and evidence together?

Uploaded images are rendered into the signed document and stored with it, so your record is complete.

Why would you use image form fields for signers?

You’d use Image Form Fields whenever signers must provide visual proof along with their signature.

They help you:

• Collect documents easily: Signers upload ID images, property photos, receipts, pay slips, etc., in the same flow as signing.
• Save time and reduce manual work: No more asking for files via email or uploading to separate portals.
• Keep everything in one place: The images live inside the signed document stored in BoldSign, not scattered across inboxes.
• Improve signer experience: Signers complete all steps: upload + sign, in a single guided flow.
• Support compliance and verification: Ideal for KYC, claims, approvals, or regulatory workflows that require visual evidence.

What do you need before adding image form fields via API?

Make sure you have the following in place:

• A BoldSign account (sandbox or production).
• An API key (or OAuth2 access token) to call BoldSign APIs over HTTPS.
• A REST client such as cURL, Postman, or your preferred HTTP library.
• Document details and signer information.
• Form field definitions, including imageInfo for image fields

Authentication headers should be in one of the following formats:

• API Key: X-API-KEY:<your key>
• OAuth2: Authorization: Bearer <access_token>

Note: The examples below use API Key authentication for clarity.

How do you add image form fields when sending a document?

To add Image fields via API, you call the POST /v1/document/send endpoint and include Image form fields for each signer. Inside each Image form field, you pass an imageInfo object.

Which properties can you configure for an image form field?

Key properties for an Image field:

• id / name
  • Internal and display names for the field.
• fieldType
  • Must be “Image” (or FieldType.Image in SDKs).
• pageNumber
  • The page where the image will appear.
• bounds
  • Position and size on the page: { “x”, “y”, “width”, “height” }.
• isRequired
  • If true, the signer must upload an image before they can complete signing.
• imageInfo
  • title: A label above the field (e.g., “Upload your ID”).
  • description: Instructions or context (e.g., “Front side only, clear and readable”).
  • allowedFileExtensions: A comma-separated list of allowed formats such as .jpg,.jpeg,.png (supports JPG/JPEG, SVG, PNG, BMP).

The following sample code snippets show how to add image field to a document via the BoldSign API.

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 'Signers={
        "name": "david",
        "emailAddress": "[email protected]",
        "signerType": "Signer",
        "formFields": [
           {
                "id": "Image",
                "name": "Image",
                "fieldType": "Image",
                "pageNumber": 1,
                "isRequired": true,
                "bounds": {
                  "x": 200,
                  "y": 200,
                  "width": 125,
                  "height": 25
                   },
                "imageInfo": {
                  "title": "Add Image",
                  "description": "Image Description",
                  "allowedFileExtensions": ".jpg, .png"
                   }
           }
  ],
  "locale": "EN"
}' 
  -F 'Files=@{your file}'
  -F 'Title=Invitation form' \
    

var apiClient = new ApiClient("https://api.boldsign.com/", "YOUR_API_KEY");
	var documentClient = new DocumentClient(apiClient);
	List<FormField> formField = new List<FormField>
	{
		new FormField(
			id: "Image",
			isRequired: true,
			type: FieldType.Image,
			pageNumber: 1,
			imageInfo: new ImageInfo(
				title: "Add Image",
				description: "Image Description",
				allowedFileExtensions: ".jpg, .png"
			),
			bounds: new Rectangle(x: 100, y: 100, width: 125, height: 25)
		)
	};
	var documentDetails = new SendForSign
	{
		Title = "Agreement",
		Signers = new List<DocumentSigner>
		{
			new DocumentSigner(
				signerName: "david",
				signerType: SignerType.Signer,
				signerEmail: "[email protected]",
				formFields: formField)
		},
		Files = new List<IDocumentFile>
		{
			new DocumentFilePath
			{
				ContentType = "application/pdf",
			   FilePath = "YOUR_FILE_PATH",
			}
		},
	};
	var documentCreated = documentClient.SendDocument(documentDetails);

import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
    document_api = boldsign.DocumentApi(api_client)
    image_field = boldsign.FormField(
        id="Image",
        name="Image",
        fieldType="Image",
        pageNumber=1,
        isRequired=True,
        bounds=boldsign.Rectangle(x=50, y=50, width=200, height=25),
        imageInfo=boldsign.ImageInfo(
            title="Add Image",
            description="Image Description",
            allowedFileExtensions=".jpg, .png"
        )
    )
    # Signer with only image field
    document_signer = boldsign.DocumentSigner(
        name="david",
        emailAddress="[email protected]",
        signerType="Signer",
        formFields=[image_field]
    )
    # Send document for signing
    send_for_sign = boldsign.SendForSign(
       title="Document SDK API",
       files=["YOUR_FILE_PATH"],
       signers=[document_signer]
    )
    document_created = document_api.send_document(send_for_sign)

<?php require_once "vendor/autoload.php";
use BoldSign\Configuration;
use BoldSign\Api\DocumentApi;
use BoldSign\Model\{FormField, Rectangle, DocumentSigner, SendForSign, FileInfo, ImageInfo};
$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$document_api = new DocumentApi($config);
$image_bounds = new Rectangle([100, 100, 100, 50]);
$image_info = new ImageInfo();
$image_info->setTitle('Add Image');
$image_info->setDescription('Image Description');
$image_info->setAllowedFileExtensions('.jpg, .png');
$image_field = new FormField();
$image_field->setId('Image');
$image_field->setName('Image');
$image_field->setFieldType('Image');
$image_field->setPageNumber(1);
$image_field->setIsRequired(true);
$image_field->setBounds($image_bounds);
$image_field->setImageInfo($image_info);
$document_signer = new DocumentSigner();
$document_signer->setName('david');
$document_signer->setEmailAddress('[email protected]');
$document_signer->setSignerType('Signer');
$document_signer->setFormFields([$image_field]);
$send_for_sign = new SendForSign();
$files = new FileInfo();
$files = 'YOUR_FILE_PATH';
$send_for_sign->setFiles([$files]);
$send_for_sign->setSigners([$document_signer]);
$send_for_sign->setTitle('Document SDK API');
$document_created = $document_api->sendDocument($send_for_sign);
     

ApiClient client = Configuration.getDefaultApiClient();
client.setApiKey("YOUR_API_KEY");
DocumentApi documentApi = new DocumentApi(client);
FormField imageField = new FormField();
imageField.setFieldType(FormField.FieldTypeEnum.IMAGE);
imageField.setPageNumber(1);
imageField.setBounds(new Rectangle().x(100f).y(200f).width(125f).height(25f));
imageField.setIsRequired(true);
imageField.setId("Image");
ImageInfo imageInfo = new ImageInfo();
imageInfo.setTitle("Add Image");
imageInfo.setDescription("Image Description");
 imageInfo.setAllowedFileExtensions(".jpg, .png");
 imageField.setImageInfo(imageInfo);
DocumentSigner signer = new DocumentSigner();
signer.setName("david");
signer.setEmailAddress("[email protected]");
signer.setSignerType(DocumentSigner.SignerTypeEnum.SIGNER);
signer.setFormFields(Arrays.asList(imageField));
SendForSign sendForSign = new SendForSign();
File file = new File("YOUR_FILE_PATH");
sendForSign.setFiles(Arrays.asList(file));
sendForSign.setSigners(Arrays.asList(signer));
sendForSign.setTitle("Document SDK API");
DocumentCreated documentCreated = documentApi.sendDocument(sendForSign);
    

import { DocumentApi, DocumentSigner, FormField, Rectangle, SendForSign } from "boldsign";
import * as fs from 'fs';
const documentApi = new DocumentApi();
documentApi.setApiKey("YOUR_API_KEY");
// Image Field
const imageBounds = new Rectangle();
imageBounds.x = 50;
imageBounds.y = 50;
imageBounds.width = 200;
imageBounds.height = 25;
const imageField = new FormField();
imageField.id = "Image";
imageField.name = "Image";
imageField.fieldType = "Image";
imageField.pageNumber = 1;
imageField.isRequired = true;
imageField.bounds = imageBounds;
imageField.imageInfo = {
  title: "Add Image",
  description: "Image Description",
  allowedFileExtensions: ".jpg, .png"
};
// Signer
const documentSigner = new DocumentSigner();
documentSigner.name = "david";
documentSigner.emailAddress = "[email protected]";
documentSigner.signerType = DocumentSigner.SignerTypeEnum.Signer;
documentSigner.formFields = [imageField];
// File
const files = fs.createReadStream("YOUR_FILE_PATH");
// Send for Sign
const sendForSign = new SendForSign();
sendForSign.title = "Agreement";
sendForSign.signers = [documentSigner];
sendForSign.files = [files];
// Send Document
const documentCreated =documentApi.sendDocument(sendForSign)
    

How can you confirm that uploaded images are stored in the signed document?

Once your document is signed, you can confirm the image upload in several ways:

Download the signed PDF

The signer’s uploaded image will be rendered at the exact coordinates defined by bounds in the Image field.

Check document properties via API

Call the Document Properties API (/v1/document/properties) to inspect the form fields and confirm that the Image field exists and is associated with a value.

Once the signer uploads an image and completes signing, that image becomes part of the finalized document stored in BoldSign.

What should developers know about managing image fields via API?

From a developer’s perspective, Image Form Fields are:

• A form field type (Image) you define per signer.
• Its behavior is controlled via:
  • Placement: pageNumber + bounds
  • Validation: isRequired
  • Guidance & restrictions: imageInfo (title, description, allowed extensions)

With the BoldSign API you can:

• Place image fields exactly where they should appear.
• Restrict acceptable formats to what your workflow needs.
• Keep the signing flow secure.
• Image fields cannot be prefilled via API.

When should you use image form fields in BoldSign workflows?

Use Image Form Fields when:

• Visual documentation is mandatory for approval or compliance.
• You want to avoid separate upload portals or manual email-based collection.
• You need all supporting evidence to travel with the signed document.

By adding image fields via the BoldSign API, you can design signer experiences that are both strict (for compliance) and smooth (for usability), while keeping your automation and integrations intact.

What are common use cases for image form fields?

Image Form Fields are especially useful in workflows that depend on visual documentation.

• Identity Verification (KYC): Ask signers to upload a government-issued ID as part of onboarding or verification flows.
• Supporting Documentation: In insurance claims, loan applications, or expense approvals, signers can attach photos of damage, receipts, or income proofs.
• Signature Capture: If your process requires a scanned handwritten signature, signers can upload a photo or scan alongside their digital signature.

Image fields may not be ideal for very large file uploads or complex multi-document scenarios where files must be processed or transformed before signing. For those, consider external storage and linking.

Conclusion: When should you use image form fields in BoldSign workflows?

Image form fields in BoldSign aren’t just for looks, they make your documents smarter and easier to use. Whether you’re collecting consent, verifying identity, or adding notes to diagrams, this feature helps you gather accurate data directly on images with less effort.

By using BoldSign API, developers can place fields exactly where they’re needed, making the signing process smooth and clear for users. It’s perfect for customizing certificates, guiding people through complex forms, or turning image-based documents into interactive experiences.

If you’d like to explore more about BoldSign capabilities, sign up for a free BoldSign Sandbox account leave a comment, book a demo, or connect with our support team through the BoldSign support portal.

FAQs