> 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 TSP evidence artifacts > Learn how to retrieve TSP evidence artifacts. This How-to article details the step-by-step process required to retrieve and download third-party Trust Service Provider (TSP) evidence artifacts using the Trust Records API. The current scope is limited to TSP evidence artifacts generated during a Qualified Electronic Signature process. ## Prerequisites * The initial phase requires triggering a process that produces the identity verification records intended for retrieval. Depending on the specific business requirements, the following method is available: * The envelope must contain at least one recipient who has completed the identification process and subsequently signed the document. The aforementioned signature produces several TSP evidence artifacts. These artifacts can be retrieved using the Trust Records API. The following steps in this article provide a detailed procedure for downloading the evidence files. > **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). | | \{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. | | \{TRUST_RECORD_URL_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 api-d.docusign.com for the developer environment and api.docusign.com for production. | ## 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 TSP evidence artifacts are generated per participant, you need the participant ID to retrieve them. **eSign Envelopes** In eSign envelopes, the participants of interest are the recipients. Get the list of various recipient IDs for the envelope using [listRecipients](/docs/esign-rest-api/reference/envelopes/enveloperecipients/list). Then, filter the list to find the IDs of the signers who used a partner service. Call the [listRecipients](/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" declare -a Headers=('--header' "Authorization: Bearer ${access_token}" '--header' "Accept: application/json") response_file=$(mktemp /tmp/recipients.XXXXXX) status=$(curl -s -w "%{http_code}" --request GET "${uri}" "${Headers[@]}" --output ${response_file}) ``` **`PowerShell`** ```text title="PowerShell" $uri = "https://demo.docusign.net/restapi/v2.1/accounts/$account_id/envelopes/$idv_envelope_id/recipients" try { $headers = @{ "Authorization" = "Bearer $access_token" "Accept" = "application/json" } $response = Invoke-RestMethod -Uri $uri -Headers $headers -Method Get # Extract the first recipientIdGuid to use as record_id $record_id = $response.signers[0].recipientIdGuid Write-Host "Found Record ID: $record_id" } catch { Write-Host "Failed to retrieve recipients. Error: $_" -ForegroundColor Red exit } ``` ## Step 3. Construct your API headers After you have a valid OAuth access 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 access token for \{ACCESS_TOKEN}. **`Bash`** ```bash title="Bash" declare -a Headers=('--header' "Authorization: Bearer ${access_token}" '--header' "Accept: application/json") ``` **`PowerShell`** ```text title="PowerShell" try { $headers = @{ "Authorization" = "Bearer $access_token" "Accept" = "application/json" } $apiResponse = Invoke-WebRequest -Uri $uri -Headers $headers -Method Get ``` ## Step 4. Call the Trust Records API to retrieve evidence artifacts Now that you have constructed your API headers, call the [TrustRecords : GetTrustRecord](/docs/trust-records-api/reference/trustrecords/trustrecords/gettrustrecord) endpoint with your \{API_ACCOUNT_ID} and \{RECIPIENT_ID_GUID} to retrieve ID Evidence event data for a recipient. ```json {TRUST_RECORD_URL_BASE_PATH}/accounts/{API_ACCOUNT_ID}/ trust-records/{RECIPIENT_ID_GUID} ``` The outcome of this API call is a list of URLs from which the partner evidence artifacts can be downloaded. Once the list of artifacts has been obtained, they can be downloaded directly using the `file_url`. Alternatively, a dedicated API may be utilized as follows by using the `fileId` and encrypted data available in `file_url`. `{FILE_ID}` and `{ENCRYPTED_DATA}` is obtained from **file_url** field as ```json {TRUST_RECORD_URL_BASE_PATH}/accounts/{API_ACCOUNT_ID}/ trust-records/{RECIPIENT_ID_GUID}/files/ {FILE_ID}?context={ENCRYPTED_DATA} ``` In addition to the authentication error (**401 Unauthorized**) previously mentioned, this API may also yield a **404 Not Found** error. This outcome is possible when the `{RECIPIENT_ID_GUID}` cannot be successfully mapped to an evidence artifact. This situation can arise either because the participant has not executed a process generating an evidence artifact, or the associated envelope has been deleted which consequently removes the evidence artifacts. The evidence artifacts can also expire after a fixed timeline. The configured Time-To-Live (TTL) for evidence artifacts varies depending on the specific use cases. For example, signatures using IDnow for GwG have a TTL of **90 days**. **`Bash`** ```bash title="Bash" uri="https://api-d.docusign.com/v1/accounts/${account_id}/trust-records/${record_id}" response_json=$(mktemp /tmp/trust_record.XXXXXX) ``` **`PowerShell`** ```text title="PowerShell" $uri = "https://api-d.docusign.com/v1/accounts/$account_id/trust-records/$record_id" ``` ## Step 5. Call the Trust Records API to download evidence artifact files Execute the API endpoint to download all the evidence files of artifacts ```json {TRUST_RECORD_URL_BASE_PATH}/accounts/{API_ACCOUNT_ID}/ trust-records/{RECIPIENT_ID_GUID}/files/ {FILE_ID}?context={ENCRYPTED_DATA} ``` **Note: Query Parameters and API Response** **context** = Encrypted data Mandatory parameter containing metadata used by the application to retrieve the file. It should not be modified. The response is the raw file content returned as a binary stream with appropriate headers: * **Content-Type**: The MIME type of the file (e.g., application/pdf, image/jpeg) * **Content-Disposition**: attachment; filename="\{fileName}" > **Note** > > View the source code for this how-to on GitHub: [Bash](https://github.com/docusign/code-examples-bash/blob/master/examples/TrustRecords/eg001RetrieveIDEvidenceArtifacts.sh), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/TrustRecords/retrieveIDEvidenceArtifacts.ps1) **`Bash`** ```bash title="Bash" pdf_path=$(cat $response_json | grep -o '"pdf_url":"[^"]*' | sed 's/"pdf_url":"//') if [ -n "$pdf_path" ]; then # Construct the Full URL using the requested base clean_path=$(echo $pdf_path | sed 's/^\///') full_download_url="https://api-d.docusign.com/v1/${clean_path}" ``` **`PowerShell`** ```text title="PowerShell" $pdf_path = $jsonObj.pdf_url if ([string]::IsNullOrWhiteSpace($pdf_path)) { # Fallback: Extract using regex if standard JSON object access fails if ($rawContent -match '"pdf_url"\s*:\s*"([^"]+)"') { $pdf_path = $matches[1] } } } ``` ## 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. **`Sample response`** ```json title="Sample response" { "trusted_partners_files": [], "identity_verifications": [ { "proof_file_id": "ec302470-xxxx-xxxx-807f-86fcd4550656", "events": [ { "event_type": "envelopesent", "entity_type": "person", "schema_version": 0, "creation_date": "2026-05-06T09:16:31.8470627Z", "data": { "envelope_id": "4d852aea-xxxx-xxxx-8081-415369500643", "recipient_id": "ec302470-xxxx-xxxx-807f-86fcd4550656", "recipient_name": "Patrick Smith", "recipient_email": "patrick.smith@acme.com", "created_by": "Morris" }, "has_media": false }, { "event_type": "IdVerificationPhotoIdImageSent", "entity_type": "person", "schema_version": 0, "creation_date": "2026-05-06T09:17:54.874737Z", "data": { "trace_uid": "a0500dcf-xxxx-xxxx-ba68-e14ce5c02ed4", "session_id": "3d49d613-xxxx-xxxx-ad7d-44656f567256", "task_uid": "ed77c3ec-xxxx-xxxx-a1ef-2da51e04b594", "copy_of_id_front": "328c49d7-xxxx-xxxx-a6c9-a374e17a1679" }, "has_media": true }, { "event_type": "IdVerificationPhotoIdSuccess", "entity_type": "person", "schema_version": 0, "creation_date": "2026-05-06T09:17:55.3702604Z", "data": { "trace_uid": "a0500dcf-xxxx-xxxx-ba68-e14ce5c02ed4", "session_id": "3d49d613-xxxx-xxxx-ad7d-44656f567256", "task_uid": "ed77c3ec-xxxx-xxxx-a1ef-2da51e04b594", "person_id": "ec302470-xxxx-xxxx-807f-86fcd4550656", "person_name": "Patrick Smith", "last_names": [ "Smith" ], "middle_names": [], "first_names": [ "Patrick" ], "date_of_birth": "1970-01-01T00:00:00", "type_of_id": "PASSPORT", "issuing_country": "US", "residence_address": "657003 - Brevig Mission, US 98104", "country_selected_by_signer": "US", "provider_name": "MOCK_ID" }, "has_media": false } ], "pdf_url": "/trust-records-app/v1/accounts/f96de068-xxxx-xxxx-xxxx-1a945759e7fe/trust-records/ec302470-xxxx-xxxx-xxxx-86fcd4550656/files/d20edae5-xxxx-xxxx-xxxx-a75ea4eecd60?context=AQEAAADBEuVO0HmcOuId3VEcXkJZJC7sVHhpdDoHvDoWSYmih6l8tw4rvbLW8h4NjyzEF01wC9qfnvWnoa9_1V8Qc0nXcn9K5FwN0vRN4edMtw35SzdkAVFXTWu1LeoORLEClY2_V8EGpSJVh3gheiqLgOt6cIL9W3bORDlkvGS1TAGRkH-F77qdmg0wOXXNCv4For1d9nqEWl-IMfqUxpxtUMIMUcv6IglIKiXKd305e-SpoYItT7pw8bk7ZVNum0eTteDp", "media": { "328c49d7-e909-4bac-a6c9-a374e17a1679": { "media_url": "/trust-records-app/v1/accounts/f96de068-xxxx-xxxx-xxxx-1a945759e7fe/trust-records/ec302470-xxxx-xxxx-xxxx-86fcd4550656/files/328c49d7-xxxx-xxxx-xxxx-a374e17a1679?context=AQEAAADaPwJlGKcPb48AnG6piClCXWYymK32Ow-oXJKJVYvIv0zXVtj8kIP1txdlVNC2fIaGwshKaeQhrWywKsGK6WvIx3_ptbpkAWh8izOYa_u9DKcvAy1An0OfdIELh1PUMho3Hy7ywR8YhvLWjfFCFCVkFTvNdHV9amQKLgsFBym3fqIyxaD6Y7DfhXDL322mCkHbbzcjRm7H28bcT0adNV_8sgIGSntphcMN99Thxv3Ixsbj15gl9_rFAwvdbQVnuOlpNBTazHDWYax3JMONYXcVDql5Jnpt00dJtmW0zFlsIKnp83uPPV3WKDZ3RgN00D2LY2RdxKnrnmBsg4eYBvl3J_PpPO_1rkCYKymtpS0d1InboKm2wUt7" } } } ] } ``` ## 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/blob/master/examples/TrustRecords/eg001RetrieveIDEvidenceArtifacts.sh), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/TrustRecords/retrieveIDEvidenceArtifacts.ps1) * Learn more about [Trust Records API](/docs/trust-records-api/trustrecords101) * See how to [Go-Live](/docs/trust-records-api/go-live) with a completed app and find the base path for API calls in the production environment.