---
title: "How to Access Identity Verification Documents via API"
description: "Learn how to retrieve uploaded identity verification documents using the BoldSign API to support KYC, AML, audits, onboarding, and compliance reviews."
url: "https://boldsign.com/blogs/access-identity-verification-document-api/"
---

1. [Blog](https://boldsign.com/blogs.md)
2. [API](https://boldsign.com/category/api.md)

# How to Retrieve Uploaded Identity Verification Documents via API

[Ranjitha Vazhivittan](https://boldsign.com/author/ranjitha-vazhivittan/) April 21, 2026 Updated August 21, 2026 8 min read

> **TL;DR:** Use the Identity Verification Report API to retrieve the verification details and obtain the fileId for the signer’s uploaded ID image. Then, use the Identity Verification Image API with the same documentId and fileId, along with the signer’s email, SMS number, or WhatsApp number, to download the ID image as a binary stream. This works whether the verification succeeds or fails, enabling manual review and preventing repeated uploads.

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](https://developers.boldsign.com/identity-verification/introduction) 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](https://account.boldsign.com/signup?planId=1076) (sandbox or production).

- An [API key](https://developers.boldsign.com/authentication/api-key) (or [OAuth2 access token](https://developers.boldsign.com/authentication/oauth-2-0)) 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](https://developers.boldsign.com/identity-verification/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 -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 --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?

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

You can prototype everything in a [sandbox account](https://account.boldsign.com/signup?planId=1076) 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](https://developers.boldsign.com/how-to-guides/get-the-uploaded-identity-verification-document) 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](https://account.boldsign.com/signup?planId=1076\&utm_source=boldsignblogs\&utm_medium=redirect\&utm_campaign=boldsign) to explore our API features. You can also connect with our support team anytime through the [support portal](https://support.boldsign.com/support/tickets/create).

Topics [API integration](https://boldsign.com/blogs/tag/api-integration.md)[Identity verification](https://boldsign.com/blogs/tag/identity-verification.md)[Compliance](https://boldsign.com/blogs/tag/compliance.md)

## Sign documents 3x faster

Send, sign and manage documents securely and efficiently.

[Try it today](https://account.boldsign.com/signup?planId=1018\&utm_source=boldsignblogs\&utm_medium=redirect\&utm_campaign=boldsign)

## Frequently asked questions

### Can I retrieve identity verification documents even if verification failed?

Yes. The [Identity Verification Report](https://developers.boldsign.com/how-to-guides/get-the-uploaded-identity-verification-document) is generated after each verification attempt, whether it succeeds or fails. As long as a report exists and the document includes uploaded files, you can retrieve their fileIds and download the images.

### Does downloading the verification image change the verification status?

No. Downloading an image via the Identity Verification Image API does **not** change the verification result. It only gives you read access to what was already uploaded.

### What is fileId, and why is it important?

**fileId** is the unique identifier for a specific verification image file returned in the report. You must use fileId when calling the Image API to download that exact ID image.

### Can I retrieve documents for both email and SMS delivery modes?

Yes. You can retrieve documents for verification flows where the request was delivered by email (using EmailId) or by SMS or WhatsApp (using CountryCode + PhoneNumber). Always use the same identifier that was used when sending the verification request.

### Do I need to wait until verification is complete before retrieving the image?

Yes. The Identity Verification Report, and therefore the fileId is only available after the verification attempt is completed (successful or not). Once the report exists, you can immediately use it to download the uploaded ID image.

## Ranjitha Vazhivittan

Ranjitha is a skilled software developer with 3 years of experience at BoldSign. Alongside her technical expertise, she has a passion for writing and enjoys sharing thoughtful insights on technology and development. Beyond work, she stays curious by exploring emerging tools and trends, constantly seeking opportunities to learn and grow.

[More posts by Ranjitha Vazhivittan](https://boldsign.com/author/ranjitha-vazhivittan/)

## Related posts

- [API](https://boldsign.com/category/api.md) September 25, 2026 10 min read

  ## [Build vs Buy an eSignature API: What Should You Choose?](https://boldsign.com/blogs/build-vs-buy-esignature-api-guide.md)

  Compare the real cost, compliance risk, launch speed, and maintenance burden of building vs buying an eSignature API before you commit.

- [API](https://boldsign.com/category/api.md) January 28, 2025 7 min read

  ## [How to Streamline Document Signing with Group Checkbox Fields in the BoldSign API](https://boldsign.com/blogs/how-to-streamline-document-signing-with-group-checkbox-fields-in-the-boldsign-api.md)

  Learn how to use group checkboxes in the BoldSign API to validate multiple fields, ensuring efficient and compliant document signing workflows.

- [API](https://boldsign.com/category/api.md) July 10, 2024 8 min read

  ## [Mandating Signer Authentication After Sending Documents via API](https://boldsign.com/blogs/mandating-signer-authentication-after-sending-documents-via-api.md)

  BoldSign API supports verifying eSignatures via email, SMS, or access code, providing an additional layer of security after document delivery.

Get started

## Sign up for your free trial today!

[Start free trial](https://account.boldsign.com/signup?planId=1018)

- 30-day free trial
- No credit card required

*Picture: A completed employment contract: signed by John Doe on 11/03/2026, all parties have signed*
