> 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 events > Demonstrates how to retrieve ID Evidence data in JSON format. This topic demonstrates how to retrieve ID Evidence event data in JSON format. ## 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\://\/restapi Where \ is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production. | | \{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\://\/api Where \ 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. > **Note** > > View the source code for this how-to on GitHub: [Bash](https://github.com/docusign/code-examples-bash/blob/master/examples/IdEvidence/eg001RetrieveEvents.sh), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/ID_Evidence/retrieveEvents.ps1). **`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 } ``` ## Expected response If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown. You can also export your data to a PDF document that is digitally signed by Docusign to guarantee the origin and integrity of your data. See [Events:list](/docs/idevidence-api/reference/idevidence/events/list) for more information. **`Sample response`** ```json title="Sample response" [ { "event_type": "envelopesent", "entity_type": "person", "schema_version": 0, "creation_date": "2023-06-30T19:14:49.2878377Z", "data": { "envelope_id": "b71dbd28-xxxx-xxxx-xxxx-1044842a04ac", "recipient_id": "eecbf35c-xxxx-xxxx-xxxx-9fe993fe6b6c", "recipient_name": "my name", "recipient_email": "my email", "created_by": "Susan Signer" }, "has_media": false }, { "event_type": "IdVerificationPhotoIdSuccess", "entity_type": "person", "schema_version": 0, "creation_date": "2023-06-30T19:16:16.8148786Z", "data": { "trace_uid": "9da998ef-xxxx-xxxx-xxxx-4d18b969ef54", "session_id": "cf41e192-xxxx-xxxx-xxxx-73be63c70c38", "task_uid": "e5d67096-xxxx-xxxx-xxxx-7f6183cd54a8", "person_id": "eecbf35c-xxxx-xxxx-xxxx-9fe993fe6b6c", "person_name": "my name", "type_of_id": "PHOTOID", "country_selected_by_signer": "US", "provider_name": "MITEK" }, "has_media": false }, { "event_type": "IdVerificationPhotoIdImageSent", "entity_type": "person", "schema_version": 0, "creation_date": "2023-06-30T19:16:16.4053499Z", "data": { "trace_uid": "9da998ef-xxxx-xxxx-xxxx-4d18b969ef54", "session_id": "cf41e192-xxxx-xxxx-xxxx-73be63c70c38", "task_uid": "e5d67096-xxxx-xxxx-xxxx-7f6183cd54a8", "copy_of_id_front": "https://proof-d.docusign.net/api/v1/events/person/eecbf35c-xxxx-xxxx-xxxx-9fe993fe6b6c/2e914d89-xxxx-xxxx-xxxx-53328cb92170/media/e6b45fc9-xxxx-xxxx-xxxx-f7a939d5dbc9", "copy_of_id_back": "https://proof-d.docusign.net/api/v1/events/person/eecbf35c-xxxx-xxxx-xxxx-9fe993fe6b6c/2e914d89-xxxx-xxxx-xxxx-53328cb92170/media/b1af2fdb-xxxx-xxxx-xxxx-9d640679dbe4" }, "has_media": true } ] ``` ## 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 media](/docs/idevidence-api/how-to/retrieve-idevidence-media). * [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.