> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# How to retrieve ID Evidence media

> Demonstrates how to retrieve the image of an ID stored as part of the ID Verification (IDV) process.

This topic demonstrates how to retrieve the image of an ID stored as part of the ID Verification (IDV) process. To retrieve such an image, you need its URL, which is part of the JSON response when you [retrieve ID Evidence events](/docs/idevidence-api/how-to/retrieve-idevidence-events#expected-response).

## Prerequisites

* If you do not see a sidebar link named **Identity Verification** under eSignature Settings in your Docusign account, you do not have ID Verification (IDV) enabled. See [ID verification](/docs/esign-rest-api/esign101/concepts/recipients/auth#idv)  for information on enabling IDV in your account.
* You must [enable ID Evidence storage](/docs/idevidence-api/idevidence101/enabling-idevidence-storage).
* In your Docusign account, you must have a completed IDV envelope: you must have [sent an IDV envelope](/docs/esign-rest-api/how-to/id-verification), the recipient must have [completed the IDV process](https://support.docusign.com/s/document-item?bundleId=ced1643229641057\&topicId=iww1578456547699.html), and they must have signed the envelope.
* In your locally downloaded Quickstart or launcher `/``config` folder, you must save your IDV envelope ID GUID in a file named `IDV_ENVELOPE_ID`.

> **Note**
>
> Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [PowerShell](https://github.com/docusign/code-examples-powershell).

## Required data

Running the code in this how-to requires this data:

| Data element            | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \{API_ACCOUNT_ID}       | A [GUID](http://guid.one/) value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the **API Account ID** field on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page.                                                                                                     |
| \{BASE_PATH}            | A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at https\://\<domain>/restapi Where \<domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.                                                                       |
| \{COPY_OF_ID_FRONT_URL} | A URL associated with the front of a photo ID media image. The media URL will be of the following format: \{PROOF_BASE_PATH}/api/v1/events/person/\{RECIPIENT_ID_GUID}/\{EVENT_ID}/media/\{MEDIA_ID} For information on retrieving an ID Evidence event list containing a media image URL, see [How to retrieve ID Evidence events](/docs/idevidence-api/how-to/retrieve-idevidence-events). |
| \{IDV_ENVELOPE_ID}      | A [GUID](http://guid.one/) value that identifies the [Docusign envelope completed using ID Verification](/docs/esign-rest-api/how-to/id-verification).                                                                                                                                                                                                                                       |
| \{PROOF_BASE_PATH}      | A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at https\://\<domain>/api Where \<domain> is proof-d.docusign.net for the developer environment and \{server}.proof.docusign.net for production.                                                                                |
| \{RECIPIENT_ID_GUID}    | A [GUID](http://guid.one/) value that Docusign assigns to identify each recipient in an envelope. This value is globally unique for all recipients, not just those in your account.                                                                                                                                                                                                          |

## Step 1. Obtain your OAuth token

To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

> **Note**
>
> See [Confidential Authorization Code Grant](/platform/auth/authcode#confidential-authorization-code-grant) for guidance on your options to get an Confidential Authorization Code Grant  OAuth token.

![Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant](/_fern-files/_img/64f473773042ee439449a096bf7673292b1585b86a4ccc55f82ba0dda41f61a1.webp)

## Step 2. Retrieve your recipient ID GUID

To obtain your resource token in the next step, you must provide your recipient ID GUID in the request body. Call the [EnvelopeRecipients:list](/docs/esign-rest-api/reference/envelopes/enveloperecipients/list) endpoint with your \{API_ACCOUNT_ID} and \{IDV_ENVELOPE_ID} to retrieve your recipient ID GUID.

**`Bash`**

```bash title="Bash"
uri="https://demo.docusign.net/restapi/v2.1/accounts/${account_id}/envelopes/${idv_envelope_id}/recipients"
response=$(mktemp /tmp/response.XXXXXX)

echo "Retrieving recipient data"

status=$(curl -s -w "%{http_code}" --request GET "${uri}" \
	"${Headers[@]}" \
	--output ${response})
```

**`PowerShell`**

```text title="PowerShell"
$uri = "https://demo.docusign.net/restapi/v2.1/accounts/${APIaccountId}/envelopes/${envelopeId}/recipients"

write-host "Retrieving recipient data"

try{
	write-host "Response:"
	$result = Invoke-RestMethod -uri $uri -headers $headers -method GET
	$result.content
    #Obtain the recipient ID GUID from the API response
	$recipientIdGuid = $result.signers.recipientIdGuid
	}
```

## Step 3. Obtain your resource token

To call the ID Evidence API, you need a valid [resource token](/docs/idevidence-api/idevidence101/resource-tokens). To obtain your resource token, call the [EnvelopeRecipients:createRecipientProofFileResourceToken](/docs/esign-rest-api/reference/envelopes/enveloperecipients/createrecipientprooffileresourcetoken) endpoint with your \{API_ACCOUNT_ID}, \{IDV_ENVELOPE_ID}, and \{RECIPIENT_ID_GUID}.

**`Bash`**

```bash title="Bash"
uri="https://demo.docusign.net/restapi/v2.1/accounts/${account_id}/envelopes/${idv_envelope_id}/recipients/${recipientIdGuid}/identity_proof_token"
response=$(mktemp /tmp/response.XXXXXX)

echo "Attempting to retrieve your identity proof token"

status=$(curl -s -w "%{http_code}" --request POST "${uri}" \
	"${Headers[@]}" \
	--output ${response})
```

**`PowerShell`**

```text title="PowerShell"
$uri = "https://demo.docusign.net/restapi/v2.1/accounts/${APIaccountId}/envelopes/${envelopeId}/recipients/${recipientIdGuid}/identity_proof_token"

write-host "Attempting to retrieve your identity proof token"

try{
	write-host "Response:"
	$result = Invoke-RestMethod -uri $uri -headers $headers -method POST
	$result.content
    #Obtain the resourceToken from the API response
	$resourceToken = $result.resourceToken
	}
```

## Step 4. Construct your API headers

After you have a valid resource token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid resource token for \{RESOURCE_TOKEN}.

**`Bash`**

```bash title="Bash"
declare -a Headers=('--header' "Authorization: Bearer ${resourceToken}" \
    '--header' "Accept: application/json, text/plain, */*" \
    '--header' "Content-Type: application/json;charset=UTF-8")
```

**`PowerShell`**

```text title="PowerShell"
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.add("Authorization","Bearer $resourceToken")
$headers.add("Accept","application/json, text/plain, */*")
$headers.add("Content-Type","application/json;charset=UTF-8")
```

## Step 5. Call the ID Evidence API to retrieve event data

Now that you have constructed your API headers, call the [Events:list](/docs/idevidence-api/reference/idevidence/events/list) endpoint with your \{PROOF_BASE_PATH} and \[RECIPIENT_ID_GUID} to retrieve ID Evidence event data for a recipient.

**`Bash`**

```bash title="Bash"
uri="https://proof-d.docusign.net/api/v1/events/person/${recipientIdGuid}.json"
response=$(mktemp /tmp/response.XXXXXX)

echo "Retrieving recipient data"

status=$(curl -s -w "%{http_code}" --request GET "${uri}" \
	"${Headers[@]}" \
	--output ${response})
```

**`PowerShell`**

```text title="PowerShell"
$uri = "https://proof-d.docusign.net/api/v1/events/person/$recipientIdGuid.json"

write-host "Retrieving recipient data"

try{
	write-host "Response:"
	$result = Invoke-RestMethod -uri $uri -headers $headers -UseBasicParsing -method GET
    #Obtain the Event List from the API response
	$EventList = $result.events | ConvertTo-Json
	write-host $EventList
```

## Step 6. Call the ID Evidence API to retrieve the ID image

Call your \{COPY_OF_ID_FRONT_URL} to return the image of the front of your photo ID.

> **Note**
>
> View the source code for this how-to on GitHub: [Bash](https://github.com/docusign/code-examples-bash/blob/master/examples/IdEvidence/eg002RetrieveMedia.sh), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/ID_Evidence/retrieveMedia.ps1).

**`Bash`**

```bash title="Bash"
curl --request GET "${copy_of_id_front}" \
	"${Headers[@]}" \
	--output ${response}
```

**`PowerShell`**

```text title="PowerShell"
$uri = $copy_of_id_front -replace '"'

write-host "Retrieving recipient data"

try{
	#Obtain the base-64 image
	$result = Invoke-RestMethod -uri $uri -headers $headers -method GET
	$result | Out-File -FilePath .\id_front_base64_image.txt
	write-host "Response: Saved to .\id_front_base64_image.txt"
	}
```

## Expected response

If you run this code example from our Quickstart or launcher projects, you should see a text file saved to your local directory that contains the image of the front of your photo ID encoded in Base64 format.

You will need to use a Base64 decoder to convert the string into a binary image that can be displayed to the user

**Note**: The image of the front of your photo ID will have a honeycomb pattern superimposed on it and cannot be used to make additional IDV requests.

## Next steps

* Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [PowerShell](https://github.com/docusign/code-examples-powershell).
* Learn more about [ID Evidence](/docs/idevidence-api/idevidence101).
* See [How to retrieve ID Evidence events](/docs/idevidence-api/how-to/retrieve-idevidence-events).
* [Send an envelope requiring ID Verification (IDV) for a recipient.](/docs/esign-rest-api/how-to/id-verification)
* See [ID Evidence Q\&A](https://support.docusign.com/s/document-item?rsc_301\&bundleId=ced1643229641057\&topicId=mrc1578885288021.html).
* See how to [Go-Live](/docs/idevidence-api/go-live) with a completed app and find the base path for API calls in the production environment.