Skip to navigation
How-to guides

How to retrieve ID Evidence events

View as Markdown

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

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

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

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 for more information.

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