TL;DR: An image form field lets a signer upload a photo, such as an ID card or a receipt, straight into the document while signing. You add it with the BoldSign eSignature API by sending a form field of type Image with an imageInfo object. The picture then stays in the signed PDF, next to the signature.
An insurance team sends a claim form for signature. The form also needs two photos of the damage. The customer signs, then emails the photos a day later, and someone has to match them to the right claim.
Image form fields put that upload inside the signing step. This guide covers what the fields do, how to add them with the API, and how to check the result.
What are image form fields in BoldSign?
Image form fields are boxes on a document where the signer uploads a picture during signing. You choose the page and position, and the picture lands in that spot.
Think of a passport form with a printed box that says “glue your photo here”. An image field is the same box, only the signer fills it with a file from a phone or computer.
What can you set on an image field?
- The page number and the position of the box on that page.
- A title and a short description that tell the signer what to upload.
- The picture formats you accept, such as
.jpgand.png. - Whether the field is required before signing can end.
Why use image form fields for signers?
Use them whenever a signature needs visual proof alongside it. The signer uploads and signs in one sitting, so nothing arrives later by email.
Your team stops chasing missing files and matching them to records by hand. Each picture sits inside the signed document we store, not in someone’s inbox. For the signer, it is one guided task instead of two.
Where do image fields help most?
- A photo of a government-issued ID during customer onboarding.
- Photos of damage on an insurance claim.
- Receipts attached to an expense approval.
- Proof of income on a loan application.
What do you need before adding image form fields via API?
You need a BoldSign account, a way to sign in to the API and a document to send. A free API sandbox account is enough to build and test.
- An API key or an OAuth 2.0 access token.
- A tool for calling the API, such as the curl command line, Postman or our software development kits (SDKs).
- The document file, the signer’s name and email address, and the image field settings.
Send the API key in the X-API-KEY header, or the OAuth token as Authorization: Bearer <access_token>. The examples below use an API key.
How do you add image form fields when sending a document?
Call POST /v1/document/send and add an image field to the signer’s form fields. Set the field type to Image and pass an imageInfo object with it.
Which properties can you configure for an image form field?
idandname: the field’s internal name and display name.fieldType: set it to"Image", orFieldType.Imagein the SDKs.pageNumberandbounds: the page, then the x, y, width and height of the box.isRequired: set it totrueso the signer must upload before finishing.
What goes in the imageInfo object?
title: a label above the field, such as “Upload your ID”.description: a hint, such as “Front side only, clear and readable”.allowedFileExtensions: a comma-separated list such as.jpg, .png.
Our send document reference lists the formats you can allow: .jpg or .jpeg, .svg, .png and .bmp. The samples below send one document with one required image field.
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": "Alex",
"emailAddress": "alex@example.com",
"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: "Alex",
signerType: SignerType.Signer,
signerEmail: "alex@example.com",
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="Alex",
emailAddress="alex@example.com",
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('Alex');
$document_signer->setEmailAddress('alex@example.com');
$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("Alex");
signer.setEmailAddress("alex@example.com");
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 = "Alex";
documentSigner.emailAddress = "alex@example.com";
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);
Our how-to guide on image form fields shows the full request with every optional setting.
How can you confirm that uploaded images are stored in the signed document?
Download the signed PDF, or read the document’s details through the API. Either way, you can see the picture the signer uploaded.
In the signed PDF, the picture appears inside the box set by the field’s bounds. Through the API, call the document properties endpoint (/v1/document/properties) with the document ID. The response lists the Image field and its value.
What should you watch out for with image fields?
Size the box for the picture you expect, since we draw the upload inside the bounds you set. Match its shape to the picture, tall for a portrait photo and wide for a card.
- Keep the list of allowed formats short, so signers know what works.
- Write the description as a direct instruction, such as “Photo of the front of your card”.
- Use an attachment field for PDFs and other non-image files.
You can also fill an image field after sending. The prefill form fields endpoint accepts Image fields on documents still in progress, though not on drafts or embedded requests. Our guide to prefilling form fields after sending walks through the call.
Which BoldSign API plan do you need, and what does it cost?
Live API requests need our Enterprise API plan, from $30 a month with 40 envelopes, as listed on the BoldSign pricing page in November 2026. Each extra envelope costs $0.75, and prices are in USD.
You can build and test image fields first in the free API sandbox, with no credit card. Sandbox documents carry a test watermark and are deleted after 14 days.
Where do you go next with image form fields?
Start in the sandbox, send yourself a test document and upload a photo as the signer. Then try the same field in your own app.
- Create a free API sandbox account and run the samples above.
- Book a demo to walk through your signing flow with our team.
- Read how to add other form fields with the BoldSign API, or ask our team on the support portal.
Frequently asked questions
What is an image form field in BoldSign?
An image form field is a box on the document where the signer uploads a picture. The picture then appears in that spot on the signed PDF.
How do I add an image field with the BoldSign API?
Add a form field with the field type Image to the signer in your send request. Give it a page number, bounds and an imageInfo object.
What file types can signers upload to an image field?
Signers can upload .jpg or .jpeg, .png, .svg and .bmp files. You can narrow the list with allowedFileExtensions, for example to .jpg and .png only.
Can I make an image upload required?
Yes. Set isRequired to true on the field, and the signer must upload a picture before they can finish signing.
Can I prefill an image field through the API?
Yes, on documents that are still in progress. The prefill form fields endpoint accepts Image fields, but it does not work on drafts or embedded requests.
Where does the uploaded image end up?
The picture is drawn at the field's position on the signed PDF. You can also call the document properties endpoint to check the field and its value.
Can signers upload a PDF instead of a picture?
Not in an image field, which takes picture files only. Use an attachment field when signers need to send other file types.
Do I need a paid plan to test image fields?
No. You can build and test image fields in our free API sandbox account. Sending live documents through the API needs the Enterprise API plan.