TL;DR: You can download the ID image a signer uploaded during identity verification in two API calls. First call the report endpoint to get the image’s file ID, then send that ID to the image endpoint, which returns the file. Our signer identity verification page explains the feature.
A signer uploads a passport photo to verify their identity, and the automated check fails because of glare. Your compliance team now has to decide whether to approve the signer or ask them to start again.
That decision is easier when the team can see the photo. This guide shows how to fetch the file ID from the verification report and download the image, with code in six languages.
What is identity verification in BoldSign?
Identity verification is a signer authentication option that checks a signer’s government ID before they can open a document. You decide which signers must verify, on single documents or on templates.
Think of a hotel front desk that checks your passport at check-in. The desk writes down what it saw and keeps a copy of the page. In our API, the identity verification report is the written note, and the image endpoint hands you the copy.
The identity verification introduction in our developer docs covers the settings. Our guide to sending documents with identity verification via API shows how to turn it on for a signer.
Why download identity verification documents?
You download an uploaded ID when a person needs to look at it. The most common case is an automated check that failed on a readable document.
Teams pull these images for a few reasons:
- A blurry, cropped or glare-hit photo needs a human review.
- Know your customer (KYC) rules ask you to check who a customer is.
- Auditors or internal reviewers want to see the evidence behind a decision.
- Asking a signer to upload again slows them down and can lose the deal.
Pulling the image through the API keeps it in your own systems. Copies stay out of email threads and screenshots.
What do you need before you call the identity verification API?
You need an account, a way to authenticate and the IDs of the document and signer. Gather these first:
- A free API sandbox account or a live API account.
- An API key or an OAuth 2.0 access token.
- The documentId of the document that used identity verification.
- The signer’s email address for email delivery, or country code and phone number for SMS delivery.
Send the API key in the X-API-KEY header. With OAuth 2.0, send Authorization: Bearer <access_token> instead.
Which endpoints return the identity verification report and image?
Two endpoints do the work. The report gives you the file ID, and the image endpoint returns the file for that ID.
| Task | Method and path | Main inputs | Output |
|---|---|---|---|
| Get the report and file IDs | POST /v1/identityVerification/report |
documentId (query), signer details, Order | JSON report with file IDs |
| Download an uploaded image | POST /v1/identityVerification/image |
documentId (query), the same signer details, FileId, Order | The image file |
Both endpoints answer only the sender of the document. They work after the signer finishes verification, whether it passed or failed.
How do you get the file ID from the identity verification report?
Call the report endpoint with the documentId and the signer’s details. The response lists the result, the data read from the ID and the IDs of the uploaded files.
What does the report contain?
The sample response in our docs includes these fields:
verificationResultandverifiedDate: the outcome and when it happened.error: a code and message when verification fails.document: the ID type, name, country, number, dates and address read from it.documentFiles: the file IDs of the uploaded ID images, which you pass to the image endpoint.
The document object also has a selfieFile ID for the selfie, when the signer took one.
Which inputs does the report endpoint take?
Put documentId in the query string. Pick the signer fields in the request body by how the signer got the request:
| Delivery mode | Fields to send |
|---|---|
| EmailId | |
| SMS | CountryCode and PhoneNumber |
Add Order to pick the right signer when the document has a signing order. Add OnBehalfOf when you fetch the report for a sender identity.
Code samples for the report call
The samples below call the report endpoint in client URL (cURL), C#, Python, PHP: Hypertext Preprocessor (PHP), Java and Node.js.
curl -X POST \
'https://api.boldsign.com/v1/identityVerification/report?documentId=55a6f0cf-xxx-xxxx-xxxx-796d02cb0977' \
-H 'accept: application/json' \
-H 'X-API-KEY: {your-api-key}' \
-H 'Content-Type: application/json' \
-d '{
"EmailId": "alex@example.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@example.com",
Order = 1,
};
var idVerificationReport = idVerificationClient.GetReport(documentId,
verificationReportRequest);
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
identity_verification_api = boldsign.IdentityVerificationApi(api_client)
identity_verification_report = boldsign.VerificationDataRequest(
emailId="alex@example.com", countryCode="+91", phoneNumber="87654345678", order=1
)
document_id = "YOUR_DOCUMENT_ID"
report_response = identity_verification_api.report(document_id, identity_verification_report)
use BoldSign\Configuration;
$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$apiInstance = new BoldSign\Api\IdentityVerificationApi($config);
$document_id = "YOUR_DOCUMENT_ID";
$verification_report_request = new \BoldSign\Model\VerificationDataRequest();
$verification_report_request ->setEmailId("alex@example.com");
$verification_report_request ->setCountryCode("+91");
$verification_report_request ->setPhoneNumber("9876543210");
$verification_report_request ->setOrder(1);
$result = $apiInstance->report($document_id, $verification_report_request);
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setApiKey("YOUR_API_KEY");
IdentityVerificationApi identityVerificationApi = new IdentityVerificationApi(apiClient);
String document_id = "YOUR_DOCUMENT_ID";
VerificationDataRequest verificationDataRequest = new VerificationDataRequest();
verificationDataRequest.setEmailId("alex@example.com");
verificationDataRequest.setCountryCode("+91");
verificationDataRequest.setPhoneNumber("9944445555");
IdReport verificationReport = identityVerificationApi.report(document_id, verificationDataRequest);
import { VerificationDataRequest, IdentityVerificationApi } from "boldsign";
const identityVerificationApi = new IdentityVerificationApi();
identityVerificationApi.setApiKey("YOUR_API_KEY");
var data_request = new VerificationDataRequest();
data_request.emailId = "alex@example.com";
data_request.countryCode = "+91";
data_request.phoneNumber = "23467898765";
var document_id = "YOUR_DOCUMENT_ID";
var verification_report = await identityVerificationApi.report(document_id, data_request);
How do you download the uploaded ID image with the image endpoint?
Send the same documentId and signer details to the image endpoint, plus the FileId from the report. The response is the image file itself.
Which inputs does the image endpoint take?
- documentId in the query string.
- EmailId, or CountryCode and PhoneNumber, matching the delivery mode.
- FileId, taken from
documentFilesin the report. - Order when the document has a signing order, and OnBehalfOf for a sender identity.
Once you have the file, you can save it to secure storage. You can also attach it to an internal case for review.
Code samples for the image call
Here are the same six languages for the image call.
curl --location \
'https://api.boldsign.com/v1/identityVerification/image?documentId={document Id}' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: {your-api-key}' \
--data-raw '{
"EmailId": "alex@example.com",
"Order": 1,
"FileId": "{file Id}"
}'
var apiClient = new ApiClient("https://api.boldsign.com", "{your-api-key}");
var idVerificationClient = new IdVerificationClient(apiClient);
var documentId = "{document Id}";
var verificationImageRequest = new VerificationImageRequest()
{
EmailId = "alex@example.com",
FileId = "{file Id}",
Order = 1,
};
var idVerificationImage = idVerificationClient.GetImage(documentId,
verificationImageRequest);
import boldsign
configuration = boldsign.Configuration(api_key="YOUR_API_KEY")
with boldsign.ApiClient(configuration) as api_client:
identity_verification_api = boldsign.IdentityVerificationApi(api_client)
identity_verification_image = boldsign.DownloadImageRequest(
emailId="alex@example.com",
countryCode="+91",
phoneNumber="87654345678",
fileId="YOUR_FILE_ID",
order=1,
)
document_id = "YOUR_DOCUMENT_ID"
image_response = identity_verification_api.image(document_id, identity_verification_image)
use BoldSign\Configuration;
$config = new Configuration();
$config->setApiKey('YOUR_API_KEY');
$apiInstance = new BoldSign\Api\IdentityVerificationApi($config);
$document_id = "YOUR_DOCUMENT_ID";
$image_request = new \BoldSign\Model\DownloadImageRequest();
$image_request ->setEmailId("alex@example.com");
$image_request ->setCountryCode("+91");
$image_request ->setPhoneNumber("9876543210");
$image_request->setFileId("YOUR_FILE_ID");
$image_request ->setOrder(1);
$result = $apiInstance->image($document_id, $image_request );
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setApiKey("YOUR_API_KEY");
IdentityVerificationApi identityVerificationApi = new IdentityVerificationApi(apiClient);
String document_id = "YOUR_DOCUMENT_ID";
DownloadImageRequest downloadImageRequest = new DownloadImageRequest();
downloadImageRequest.setEmailId("alex@example.com");
downloadImageRequest.setCountryCode("+91");
downloadImageRequest.setPhoneNumber("9944445555");
downloadImageRequest.setFileId("YOUR_FILE_ID");
File verificationimage = identityVerificationApi.image(document_id, downloadImageRequest);
import { IdentityVerificationApi, DownloadImageRequest } from "boldsign";
const identityVerificationApi = new IdentityVerificationApi();
identityVerificationApi.setApiKey("YOUR_API_KEY");
var image_request = new DownloadImageRequest();
image_request.emailId = "alex@example.com";
image_request.countryCode = "+91";
image_request.phoneNumber = "23467898765";
image_request.fileId = "YOUR_FILE_ID";
var document_id = "YOUR_DOCUMENT_ID";
var verification_image = await identityVerificationApi.image(document_id, image_request);
How do teams use the report and image endpoints?
Teams use these two calls to review failed checks by hand instead of asking for a new upload. Three cases show the pattern.
How does a bank review a failed check?
A bank asks for ID verification before it opens an account. One customer’s check fails because the photo is blurry.
The compliance team calls the report endpoint and reads the file ID. Then they download the image, confirm the customer’s identity and open the account without a second upload.
How does a law firm confirm a remote client?
A law firm needs to confirm a remote client before a large contract is signed. The automated check fails on the client’s passport.
The firm downloads the passport image through the API. A staff member checks it by hand and then moves the contract forward.
How does a clinic grant portal access?
A clinic checks identity before it opens a patient portal account. A patient’s driver’s license fails the automated check, and asking again would delay care.
Staff download the image the patient already uploaded. They review it under the clinic’s own policies and grant access.
What should you watch out for with identity document images?
ID images are some of the most sensitive files you will hold. Treat each download as personal data from the moment it arrives.
- Store images with access controls, and keep them only as long as your rules require.
- Keep image contents out of logs, tickets and chat tools.
- Check the privacy and identity rules that apply where your signers live.
See our embedded manual verification endpoint to review a failed check inside your app. Test in sandbox mode with the signer name Jenny Rosen, so name matching gives a steady result.
Which BoldSign plan do you need for the API, and what does it cost?
Live API access comes with the Enterprise API plan, which starts at $30 a month with 40 envelopes. Extra envelopes cost $0.75 each.
Identity verification is an add-on at $2 per verification on that plan. You can build and test first in our free sandbox, where identity verification runs at no cost. Prices are in USD, as listed on the BoldSign pricing page in November 2026.
Where do you go next with identity verification via API?
Start with one test document in the sandbox, then fetch its report and image. Our how-to guide for the uploaded verification document walks through the same steps.
- Create a free API sandbox account and run the report sample.
- Schedule a demo to talk through your verification workflow with our team.
- Open a ticket in our support portal with a question about your integration.
Frequently asked questions
Can I get a signer's ID image when identity verification failed?
Yes. The report and the uploaded images are available after the signer finishes verification, whether it passed or failed. That lets your team look at a failed upload instead of asking for a new one.
Does downloading the ID image change the verification result?
No. The image call only reads what the signer already uploaded. The result in the report stays the same.
Where do I find the file ID for the image call?
Call the identity verification report endpoint first. The documentFiles array in its response holds the file IDs of the images the signer uploaded.
Which signer details do I send to the report and image endpoints?
Send the details the signer received the request on. Use EmailId for email delivery, and CountryCode with PhoneNumber for SMS delivery.
Who can download identity verification images?
Only the sender of the document can fetch the report and the images. A sender identity can be named with OnBehalfOf when you act for another sender.
Can I test identity verification in the sandbox?
Yes. Documents sent with a sandbox API key run in sandbox mode at no cost. Use the signer name Jenny Rosen so the name match gives a steady result.
Is it legal to store copies of signer ID documents?
Yes, when your storage follows the privacy and data protection rules that apply to you. Keep access tight and keep copies only as long as you need them. Ask your legal team about your own case.
How much does identity verification cost with the BoldSign API?
Identity verification is an add-on at $2 per verification, on top of the Enterprise API plan. That plan starts at $30 a month with 40 envelopes, as of November 2026.