Image Retrieval

Retrieve document and selfie images captured during DocV verification using the RiskOS™ Dashboard or the Evaluation API download endpoint.

RiskOS™ provides access to end-user images captured during Document Verification (DocV) through the RiskOS™ Dashboard or the Evaluation API. Both methods require a completed DocV capture session with existing images for the evaluation.

👍
RiskOS™ Dashboard (case management and viewing):
To ensure images appear in the RiskOS™ case view, include the Socure Image Request enrichment step in your workflow. This step retrieves images and attaches them to the evaluation for reviewers.

API: Download evaluation documents

Use the Download Evaluation Documents endpoint to programmatically retrieve a ZIP of images and case attachments for a given eval_id. Contents may include consumer ID images, selfie images, secondary documents, and attachments added by reviewers.

Endpoint

Environment	URL
Production	`https://riskos.socure.com/api/evaluation/{eval_id}/documents`
Sandbox	`https://riskos.sandbox.socure.com/api/evaluation/{eval_id}/documents`

Path parameter

Parameter	Type	Description
`eval_id`	string (UUID)	The evaluation ID returned when you created the evaluation.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY` — use the correct key for Sandbox or Production.
`X-API-Version`	No	Specifies the API version for the request (for example, `2025-01-01.orion`).

Response

Status	Content type	Description
`200 OK`	`application/zip`	ZIP archive containing the requested documents. The `Content-Disposition` header includes the filename in the format `{eval_id}_document.zip`.
`400 Bad Request`	`application/json`	The request was unacceptable or no documents were found. See No-image scenarios.
`401 Unauthorized`	`application/json`	An invalid API key was provided.
`403 Forbidden`	`application/json`	The client does not have permission to access this resource.
`404 Not Found`	`application/json`	The requested evaluation does not exist.
`500 Internal Server Error`	`application/json`	An unexpected condition occurred on the server.

Sample request

curl --location --request GET \
  'https://riskos.socure.com/api/evaluation/fb1ddadc-6dba-4ce4-aa6d-25c005b192b5/documents' \
  --header 'Authorization: Bearer YOUR_API_KEY'

ZIP structure

user_uploaded/                    # Consumer-submitted identity documents
├─ document_verification/
│  ├─ documentfrontDoc_Front_1_blob.jpg
│  └─ documentbackDoc_Back_1_blob.jpg
└─ vouched_id_verification/
   └─ Doc_Selfie_1_blob.jpg

case_attachments/                 # Attachments added via the RiskOS™ Dashboard
├─ identity.pdf
└─ additional_doc.pdf

📘
Filenames:
When present, images use these names:
Filename Description
documentfrontDoc_Front_1_blob.jpg Front of the identity document
documentbackDoc_Back_1_blob.jpg Back of the identity document
Doc_Selfie_1_blob.jpg Selfie image

Filename	Description
`documentfrontDoc_Front_1_blob.jpg`	Front of the identity document
`documentbackDoc_Back_1_blob.jpg`	Back of the identity document
`Doc_Selfie_1_blob.jpg`	Selfie image

No-image scenarios

The endpoint returns a 400 Bad Request error when DocV images are not available. This is expected behavior in certain cases, not an integration error.

Scenario	Detail
Military IDs	Images are deleted immediately due to regulatory requirements. Identified by `documentType.type = "Military"`.
Minors	Images are deleted immediately when the user is under 18. Identified by reason code `R844`.
Data retention	Images were removed after capture due to data-retention policies or customer deletion requests.

Example error response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "message": "No Documents Found"
}

📘
Workflow error handling:
Avoid adding error handling for the Socure Image Request enrichment step in your RiskOS™ workflow. The scenarios described above are expected, and the step returns errors by design when no images are available.

Updated about 1 month ago