How to Retrieve Uploaded Identity Verification Documents via API

If a signer uploads an ID document during BoldSign identity verification flow, you can later download that same image through the Identity Verification APIs. This is for developers building KYC, onboarding, healthcare, or legal workflows who must access uploaded ID documents, even when automated verification fails. In this guide, you’ll see exactly how to get the fileId from the Identity Verification Report and then use it with the Identity Verification Image API to download the image stream, with code samples in multiple languages.

What is BoldSign identity verification and when is it useful?

BoldSign Identity Verification is a signer authentication feature that adds an identity check to your eSignature workflows. It:

Validates whether a signer is who they claim to be before they can access or sign a document.
Works with flows where verification requests are delivered via email, SMS, or WhatsApp delivery modes.
Lets signers upload government-issued IDs for proof-of-identity checks.
Supports both automated verification and manual review.
Stores verification data (including images) so senders can retrieve reports and documents later for audits and compliance.

Why would you need to download identity verification documents?

You typically want to download uploaded ID images when:

Automated verification fails and a human must review the document (glare, blur, cropping, etc.).
Your organization must meet KYC/AML or industry-specific regulations.
You need to retain ID documents for audits or regulatory reviews.
You want to avoid asking signers to re-upload the same document, reducing friction and drop-offs.
You must confirm identity before executing high-value or high-risk agreements.

Downloading verification images via API keeps identity data inside your controlled systems instead of spreading copies across email chains or screenshots.

What you’ll need before calling the identity verification API

Make sure you have:

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.
The documentId for the document that used identity verification
The signer’s identifier used during verification:
- Email address, if the verification request was delivered via email, or
- Country code + phone number, if the request was delivered via SMS or WhatsApp.

Authentication headers should be in one of the following formats:

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

Which endpoints do you use to retrieve identity documents?

Task	Method + Path	Key inputs	Output
Get verification report + fileId	POST /v1/identityVerification/report	documentId (query), emailId or countryCode + phoneNumber, order (optional)	JSON report including fileIds
Download uploaded image	POST /v1/identityVerification/image	documentId (query), same identifier (emailId or countryCode + phoneNumber), fileId, order (optional)	Binary image file (stream)

The report gives you the fileId; the image API returns the actual image for that fileId.

How do you get the fileId from the identity verification report?

When a signer finishes identity verification, whether it succeeds or fails, BoldSign generates an Identity Verification Report. This report contains:

The result of the verification attempt.
The timestamp of verification.
Extracted document data (name, document type, etc.).
One or more file IDs for the associated verification images.

One of these IDs is the fileId you’ll pass to the Image API.

What inputs are required for the report API?

You must provide:

documentId as a query parameter.
In the request body, either:
- EmailId , or
- CountryCode and PhoneNumber .

Delivery Method	Required Input(s) to the API	Description
Email	EmailId	Verification request was delivered to the signer by email.
SMS	CountryCode + PhoneNumber	Signer received the verification request by SMS.
WhatsApp	CountryCode + PhoneNumber	WhatsApp uses the signer’s mobile number; therefore treated the same as SMS.
Email + SMS (either)	Either one is OK: • EmailId or • CountryCode + PhoneNumber	Either email or SMS can be used; both are supported, but only one is required

Optionally, you can include:

Order: required if signing order is enabled in the document (to specify which signer’s report you want)..
OnBehalfOf: if you’re acting on behalf of another sender identity.

Below is an example code snippet showing how to generate a verification report via the API.

cURL

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.gayle@cubeflakes.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.gayle@cubeflakes.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.gayle@cubeflakes.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.gayle@cubeflakes.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.gayle@cubeflakes.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.gayle@cubeflakes.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 identity image with the image API?

Once you have a fileId, you can download the actual ID image through the Identity Verification Image API. The call structure is similar: you supply the same signer identifier (email, SMS or WhatsApp), the same documentId, plus the specific fileId.

The API then returns the image file as a binary stream, which you can:

Save to disk or cloud storage.
Pipe into an image-processing or document-handling pipeline.
Attach to an internal case or ticket for compliance review.

What inputs are required for the image API?

documentId as a query parameter.
In the request body:
- EmailId or CountryCode + PhoneNumber (matching how verification was delivered).
- Order – only required if the document has signing order enabled.
- FileId (from the Identity Verification Report).

Here’s a code snippet showing how to get the uploaded verification document using the API

cURL

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": "alexgayle@cubeflakes.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 = "alexgayle@cubeflakes.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.gayle@cubeflakes.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.gayle@cubeflakes.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.gayle@cubeflakes.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.gayle@cubeflakes.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 can this workflow help in real-world scenarios?

How can compliance teams manually review failed verifications?

Scenario: A bank requires ID verification to open accounts. A customer’s automated verification fails because the ID photo is blurry.
Problem: Most systems don’t expose failed verification images, so the customer has to start over.
Solution: The compliance team calls the Report API to get the fileId, then downloads the ID image through the Image API, manually confirms identity, and approves the account without asking for a new upload.

How can law firms confirm remote signer identity?

Scenario: A law firm needs to verify a remote client’s identity before they sign a high-value contract.
Problem: Automated verification flags the passport as low confidence.
Solution: The firm uses the Image API to retrieve the uploaded passport, manually validates it, and proceeds with the contract while keeping a verifiable audit trail.

How can healthcare portals grant access without re-uploads?

Scenario: A hospital uses identity verification before granting access to a patient portal. A patient’s driver’s license fails automated checks.
Problem: Re-upload requests slow down care and frustrate patients.

Solution: Staff download the previously uploaded license image via the API, review it, and grant portal access while following internal compliance policies

How does this improve compliance and manual verification workflows?

Using the Identity Verification Report + Image APIs together helps you:

Access uploaded ID images regardless of verification outcome (success or failure).
Reduce friction by enabling manual validation without forcing repeated document uploads.
Maintain a complete audit trail for regulators and internal reviews.
Align with requirements like KYC, AML, and healthcare privacy rules by centralizing identity evidence.
Integrate identity data into your CRM, onboarding flows, ticketing systems, or risk engines.

Compliance Reminder

Identity documents are highly sensitive. Ensure your storage, logging, and access control follow your organization’s security standards and any applicable regulations (such as GDPR, HIPAA, and local KYC/AML rules).

What should you do next with the BoldSign identity verification APIs?

Enable identity verification for high-risk or regulated workflows in BoldSign.
Integrate the Identity Verification Report API to capture verification results and fileId after each attempt.
Add the Identity Verification Image API to download and store ID images whenever manual review is needed.
Automate routing of failed verifications (and their images) to compliance or risk queues.

You can prototype everything in a sandbox account and then move the same code to production once your flows are validated.

Conclusion: When should you use the BoldSign identity verification API?

The BoldSign Identity Verification API makes it easy to securely retrieve uploaded identity documents, whether verification succeeds or not. Whether you’re building onboarding flows, automating compliance checks, or integrating identity data into internal systems, the API helps you maintain trust, meet regulatory standards, and streamline operations with minimal effort.

Get started today! Sign up for a free sandbox account to explore our API features. You can also connect with our support team anytime through the support portal.

Related blogs

Note: This blog was originally published at boldsign.com

Search This Blog

BoldSign Blogs