Retrieve verification images

With the API endpoints described in this article, you can retrieve the identity document images and the selfie images that were captured for a given completed transaction that has passed verification.

Retrieving the verification images involves the following steps:

  1. Get verification ID
  2. Get URL of verification images
  3. Download image binary data

Get verification ID

Get the verification ID of a transaction based on the transaction ID. The verification ID is then used to obtain the image URLs.

For information about syntax, status codes, and for an example request, see Get transaction status and metadata.

In the response, the vhub-verification_id property in the verifications array with status="SUCCESS" is the required verification ID. Only images of this verification can be retrieved.

  1. {
  2.   "id": "84f29725-7b57-4baa-a290-3be937f95ce6",
  3.   ...
  4.   "verifications": [
  5.     {
  6.       "id": "document_id_authentication",
  7.       "revision_id": "3dc47509-a2c3-41ff-aa5b-2f1cfa95b321",
  8.       "name": "doc_id",
  9.       ...
  10.       "status": "SUCCESS",
  11.       "timestamp": 1657216749097,
  12.       "vhub_workflow_id": "3e16826f-fb30-4cfb-bc7d-ac96545e0e93",
  13.       "vhub_transaction_id": "4254041b-1228-44c0-8455-627553987636",
  14.       "vhub_verification_id": "3e16826f-fb30-4cfb-bc7d-ac96545e0111",
  15.       "vhub_transaction_status": "COMPLETED",
  16.       ...
  17.   }]
  18. }

Get URL of verification images

Get the URL of the verification images based on the transaction ID and the verification ID.

Syntax

GET /api/transactions/transaction_id/verifications/verification_id/verification-images

  • transaction_id is the orchestrator transaction ID.
  • verification_id is the vhub_verification_id that was obtained in the previous step (see Get verification ID).

Example response

The SFS URLs in verified_images will be used to download the verification images (see Download image binary data).

  1. {
  2.   "transaction_id": "EdafBFdc-7cCB-D7b0-8591-c9e6a73Da1a8",
  3.   "verification_id": "4fddd4cD-D547-914C-6EFd-f7f5dcc73D83",
  4.   "verified_images": [
  5.   {
  6.     "image_submitted_document_front": "sfs://my_db/default/onespanidv/transaction/0fcde1ce-7649-
  7. 48f1-948c-000324280bar/session/0eb54e2b-67gc-4161-ba08-
  8. 630d425201b0/verifications/doc_id/driver-license-front/3.png"
  9.   },
  10.   {
  11.     "image_submitted_document_back": "sfs://my_db/default/onespanidv/transaction/0fcde1ce-7649-
  12. 48f1-948c-000324280bar/session/0eb54e2b-67gc-4161-ba08-
  13. 630d425201b0/verifications/doc_id/driver-license-back/3.png"
  14.   },
  15.   {
  16.     "image_submitted_selfie1": "sfs://my_db/default/onespanidv/transaction/0fcde1ce-7649-
  17. 48f1-948c-000324280bar/session/0eb54e2b-67gc-4161-ba08-
  18. 630d425201b0/verifications/doc_id/face_capture/1.png"
  19.   },
  20.   {
  21. "image_submitted_selfie2": "sfs://my_db/default/onespanidv/transaction/0fcde1ce-7649-
  22. 48f1-948c-000324280bar/session/0eb54e2b-67gc-4161-ba08-
  23. 630d425201b0/verifications/doc_id/face_capture/2.png"
  24.   }
  25.   ]
  26. }

Status codes

Status codes
Status code Name Description Comment
200 OK

No error.

  
400 Bad Request The transaction data is invalid.

Can occur if one of the following applies:

  • The transaction ID is invalid.
  • The verification ID is invalid.
  • The verification type is not supported.
  • Verification results are ambiguous.
404 Not Found The requested resource was not found.

Can occur if one of the following applies:

  • The resource was not found, or your token may not grant you sufficient visibility to get that resource.
  • The verification process for requested verification has failed. The end point retrieves only images that are associated with a transaction that has passed verification.
500 Internal Server Error The server encountered an unexpected condition which prevented it from completing the request.

Can occur if one of the following applies:

  • An unknown internal server error occurred.
  • Verification results are duplicated.

Download image binary data

Use the URL(s) that you obtained in the previous step (see Get URL of verification images) to download the verification images.

Syntax

GET /api/transactions/transaction_id/data?url=sfs_url

  • transaction_id is the orchestrator transaction ID.
  • sfs_url is the image URL.

Example request

  1. /api/transactions/transaction_id/data?url=sfs://my_db/default/onespanidv/transaction/0fcde1ce-7649-48f1-948c-000324280bar/session/0eb54e2b-67gc-4161-ba08-630d425201b0/verifications/doc_id/driver-license-front/3.png

Status codes

Status codes
Status code Name Description Comment
200 OK

No error.

 The expected file is returned.
400 Bad Request The transaction data is invalid. Validation error. Invalid SFS URLs may be caused by backward path traversal characters.
401 Unauthorized Invalid token.  
404 Not Found The requested resource was not found. The file does not exist in the system.
500 Internal Server Error Server or application error.