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.

Required data

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

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.

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. Then, filter the list to find the IDs of the signers who used a partner service.

Call the listRecipients 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"
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})

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

declare -a Headers=('--header' "Authorization: Bearer ${access_token}" '--header' "Accept: application/json")

Step 4. Call the Trust Records API to retrieve evidence artifacts

Now that you have constructed your API headers, call the TrustRecords : GetTrustRecord endpoint with your {API_ACCOUNT_ID} and {RECIPIENT_ID_GUID} to retrieve ID Evidence event data for a recipient.

{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

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

uri="https://api-d.docusign.com/v1/accounts/${account_id}/trust-records/${record_id}"
response_json=$(mktemp /tmp/trust_record.XXXXXX)

Step 5. Call the Trust Records API to download evidence artifact files

Execute the API endpoint to download all the evidence files of artifacts

{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}”

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

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.

{
    "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 or launcher projects: Bash, PowerShell
• Learn more about Trust Records API
• See how to Go-Live with a completed app and find the base path for API calls in the production environment.