Skip to navigation
How-to guides

How to retrieve ID Evidence media

View as Markdown

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.

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 for information on enabling IDV in your account.
  • You must enable ID Evidence storage.
  • In your Docusign account, you must have a completed IDV envelope: you must have sent an IDV envelope, the recipient must have completed the IDV process, 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.

Run this code example from our Quickstart or launcher projects: Bash, PowerShell.

Required data

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

Data elementDescription
{API_ACCOUNT_ID}A GUID 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 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.
{IDV_ENVELOPE_ID}A GUID value that identifies the Docusign envelope completed using 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 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.

See 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

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 endpoint with your {API_ACCOUNT_ID} and {IDV_ENVELOPE_ID} to retrieve your recipient ID GUID.

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})

Step 3. Obtain your resource token

To call the ID Evidence API, you need a valid resource token. To obtain your resource token, call the EnvelopeRecipients:createRecipientProofFileResourceToken endpoint with your {API_ACCOUNT_ID}, {IDV_ENVELOPE_ID}, and {RECIPIENT_ID_GUID}.

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})

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}.

declare -a Headers=('--header' "Authorization: Bearer ${resourceToken}" \
    '--header' "Accept: application/json, text/plain, */*" \
    '--header' "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 endpoint with your {PROOF_BASE_PATH} and [RECIPIENT_ID_GUID} to retrieve ID Evidence event data for a recipient.

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})

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.

View the source code for this how-to on GitHub: Bash, PowerShell.

curl --request GET "${copy_of_id_front}" \
	"${Headers[@]}" \
	--output ${response}

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