Retrieving ID verification data
In a previous blog post, I wrote about how you can create an envelope with identity verification applied to a recipient, so that they must authenticate using a government-issued ID. In this post, I’m going to discuss how you can retrieve the information that the recipient provided, in the event that you need to store this for any of your own internal processes.
Getting started
First, you will need to enable ID evidence storage to store recipient identity information after they have provided it. You can do this by logging into a Docusign account with identity verification available as an admin and going to Settings > Identity Verification.
In the Identity Verification settings, you will need to edit the identity verification configuration that you would like to use, or create a new one if you don’t have edit rights on any of the existing configurations. Once you are editing the configuration that you’d like to use, you will then need to ensure that the checkboxes for “Front side of the ID” and “Back side of the ID” under the Data to save from each Photo ID or Passport verification section.
Next, you will need an envelope successfully signed by a recipient who was assigned the identity verification that you configured. This blog won’t provide any code examples for actually creating the envelope with identity verification for the recipient; if you need any resource for that, please see the link at the top of this blog or refer to our how-to guide.
Code example:
After the above steps have been completed, you can start the process of requesting the identity information. I will be using Postman for my examples. The first step is to perform the listRecipients information request for the envelope. You do this to get the recipientIdGuid parameter for the recipient whose identity information you want to retrieve.
Step 1:
Request:
GET https://demo.docusign.net/restapi/v2.1/accounts/{{accountId}}/envelopes/
{{envelopeId}}/recipients
Example response:
{
"signers": [
{
"creationReason": "sender",
"isBulkRecipient": "false",
"proofFile": {
"isInProofFile": "true"
},
"requireUploadSignature": "false",
"name": "John Doe",
"email": "john.doe@email.com",
"recipientId": "5070xxxx",
"recipientIdGuid": "7b072a38-1d8b-xxxx-xxxx-xxxxxxxxxxxx",
"requireIdLookup": "false",
"identityVerification": {
"workflowId": "ad47e17d-7408-xxxx-xxxx-xxxxxxxxxxxx",
"inputOptions": [],
"workflowLabel": ""
},
"userId": "9c15fbe3-29e7-xxxx-xxxx-xxxxxxxxxxxx",
"routingOrder": "1",
"note": "",
"status": "completed",
"completedCount": "1",
"signedDateTime": "2024-06-19T10:06:28.3770000Z",
"deliveredDateTime": "2024-06-19T10:06:20.4100000Z",
"sentDateTime": "2024-06-19T10:04:21.1900000Z",
"deliveryMethod": "email",
"recipientType": "signer"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [],
"certifiedDeliveries": [],
"inPersonSigners": [],
"seals": [],
"witnesses": [],
"notaries": [],
"recipientCount": "1",
"currentRoutingOrder": "1"
}
Step 2:
After retrieving the recipientIdGuid, you can generate your resource token and ID Evidence API base URI. The resource token is a special Authorization token that is used with the ID Evidence API to authenticate calls. A recipientIdGuid for a recipient that has signed with identity verification is required to generate it. The token only lives for two minutes, so you will need to use it quickly in the subsequent calls or you will have to generate it more than once.
Request:
POST https://demo.docusign.net/restapi/v2.1/accounts/{{accountId}}/envelopes/
{{envelopeId}}/recipients/{{recipientIdGuid}}/identity_proof_token
Expected response:
{
"resourceToken": "eyJ0eXAiOiJNVCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiNjg.........",
"proofBaseURI": "https://proof-d.docusign.net"
}
Step 3:
Using the new base URI and resource token that was generated, you can now make an API call to the ID Evidence API endpoint for event data. This will return the identity events from the envelope for the specified recipient. Ensure that you pass the Authorization header as you would using OAuth, so Bearer should precede the token, like this: Authorization: Bearer {{resourceToken}}
Request:
GET https://proof-d.docusign.net/api/v1/events/person/{{recipientIdGuid}}.json
Expected response:
{
"events": [
{
"event_type": "IdVerificationPhotoIdSuccess",
"entity_type": "person",
"schema_version": 0,
"creation_date": "2024-06-19T10:06:07.9187937Z",
"data": {
"trace_uid": "ace7ce73-e6db-xxxx-xxxx-xxxxxxxxxxxx",
"session_id": "27ee9466-1ce9-xxxx-xxxx-xxxxxxxxxxxx",
"task_uid": "373f8c80-94f8-xxxx-xxxx-xxxxxxxxxxxx",
"person_id": "7b072a38-1d8b-xxxx-xxxx-xxxxxxxxxxxx",
"person_name": "John Doe",
"type_of_id": "DRIVING_LICENCE",
"country_selected_by_signer": "IE",
"provider_name": "ACUANT"
},
"has_media": false
},
{
"event_type": "envelopesent",
"entity_type": "person",
"schema_version": 0,
"creation_date": "2024-06-19T10:04:21.2612673Z",
"data": {
"envelope_id": "76beb5c8-2351-xxxx-xxxx-xxxxxxxxxxxx",
"recipient_id": "7b072a38-1d8b-xxxx-xxxx-xxxxxxxxxxxx",
"recipient_name": "John Doe",
"recipient_email": "john.doe@email.com",
"created_by": "Josh Doe"
},
"has_media": false
},
{
"event_type": "IdVerificationPhotoIdImageSent",
"entity_type": "person",
"schema_version": 0,
"creation_date": "2024-06-19T10:06:03.6851546Z",
"data": {
"trace_uid": "ace7ce73-e6db-xxxx-xxxx-xxxxxxxxxxxx",
"session_id": "27ee9466-1ce9-xxxx-xxxx-xxxxxxxxxxxx",
"task_uid": "373f8c80-94f8-xxxx-xxxx-xxxxxxxxxxxx",
"copy_of_id_front": "https://proof-d.docusign.net/api/v1/events/person/7b072a38-1d8b-xxxx-xxxx-xxxxxxxxxxxx/aeb0b641-24c1-xxxx-xxxx-xxxxxxxxxxxx/media/a07e0066-36e3-xxxx-xxxx-xxxxxxxxxxxx",
"copy_of_id_back": "https://proof-d.docusign.net/api/v1/events/person/7b072a38-1d8b-xxxx-xxxx-xxxxxxxxxxxx/aeb0b641-24c1-xxxx-xxxx-xxxxxxxxxxxx/media/d571359e-7778-xxxx-xxxx-xxxxxxxxxxxx"
},
"has_media": true
}
],
"paging": {
"page_index": 1,
"page_size": 50,
"total_items": 3,
"total_pages": 1,
"has_previous_page": false,
"has_next_page": false
}
}
Step 4:
Finally, you can make an API call to the copy_of_id_front and copy_of_id_back URIs that were returned in the previous response to get the Base64-encoded version of the image of the recipient's identity that they uploaded. You can then Base64-decode the returned string for the image, which will have a honeycomb pattern overlaid on the image so that it cannot be used anywhere else.
