Image Retrieval

Starting with v1.1.0, Kora IDV automatically persists verification images (document front, document back, selfie, liveness frames) to Google Cloud Storage. You can retrieve these images via the API for compliance reviews, audit trails, and admin dashboards.

How it works

1. When a user completes a verification step (document upload, selfie, liveness), the image is asynchronously persisted to GCS
2. The imagePersisted field on the verification object becomes true when all images are stored
3. You can then list available images and retrieve time-limited signed URLs

note

Image persistence is automatic — you don't need to change your integration. The retrieval API is for accessing images after the fact (compliance reviews, support cases, audit).

List available images

Returns the image types available for a verification.

GET /api/v1/idv/verifications/{id}/images

cURL

curl https://api.korastratum.com/api/v1/idv/verifications/ver_abc123/images \
  -H "Authorization: Bearer $KORAIDV_API_KEY" \
  -H "X-Tenant-ID: $KORAIDV_TENANT_ID"

Node.js

const response = await fetch(
  `https://api.korastratum.com/api/v1/idv/verifications/${verificationId}/images`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.KORAIDV_API_KEY}`,
      "X-Tenant-ID": process.env.KORAIDV_TENANT_ID,
    },
  }
);

const images = await response.json();
// { "images": [{"type": "document_front", "available": true}, {"type": "document_back", "available": true}, {"type": "selfie", "available": true}, {"type": "liveness_frame", "available": true}] }

Python

response = requests.get(
    f"https://api.korastratum.com/api/v1/idv/verifications/{verification_id}/images",
    headers={
        "Authorization": f"Bearer {os.environ['KORAIDV_API_KEY']}",
        "X-Tenant-ID": os.environ["KORAIDV_TENANT_ID"],
    },
)

images = response.json()
# {"images": [{"type": "document_front", "available": true}, {"type": "document_back", "available": true}, {"type": "selfie", "available": true}, {"type": "liveness_frame", "available": true}]}

Response:

{
  "images": [
    {"type": "document_front", "available": true},
    {"type": "document_back", "available": true},
    {"type": "selfie", "available": true},
    {"type": "liveness_frame", "available": true}
  ]
}

Get a signed image URL

Returns a time-limited signed URL (valid for 15 minutes) for a specific image.

GET /api/v1/idv/verifications/{id}/images/{imageType}

cURL

curl https://api.korastratum.com/api/v1/idv/verifications/ver_abc123/images/document_front \
  -H "Authorization: Bearer $KORAIDV_API_KEY" \
  -H "X-Tenant-ID: $KORAIDV_TENANT_ID"

Node.js

const response = await fetch(
  `https://api.korastratum.com/api/v1/idv/verifications/${verificationId}/images/document_front`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.KORAIDV_API_KEY}`,
      "X-Tenant-ID": process.env.KORAIDV_TENANT_ID,
    },
  }
);

const { url, expiresIn } = await response.json();
// Use the signed URL to display the image (expires in 900 seconds)

Python

response = requests.get(
    f"https://api.korastratum.com/api/v1/idv/verifications/{verification_id}/images/document_front",
    headers={
        "Authorization": f"Bearer {os.environ['KORAIDV_API_KEY']}",
        "X-Tenant-ID": os.environ["KORAIDV_TENANT_ID"],
    },
)

data = response.json()
url = data["url"]           # Signed GCS URL
expires_in = data["expiresIn"]  # Expiration in seconds (900)

Response:

{
  "url": "https://storage.googleapis.com/koraidv-images/tenant-id/ver_abc123/document_front.jpg?X-Goog-Signature=...",
  "expiresIn": 900,
  "imageType": "document_front"
}

Valid image types

Image Type	Description
document_front	Front of the identity document
document_back	Back of the identity document (if uploaded)
selfie	Selfie photo used for face matching
liveness_frame	Key frame from the liveness session

Storage details

• Storage path: {tenant_id}/{verification_id}/{type}.jpg
• Signed URL validity: 15 minutes
• Access control: Tenant-scoped — you can only access images for verifications belonging to your tenant
• Retention: Images are retained per your compliance settings (configurable in dashboard)

Checking persistence status

Before requesting images, check that persistence is complete:

const verification = await fetch(
  `https://api.korastratum.com/api/v1/idv/verifications/${verificationId}`,
  { headers }
);

const data = await verification.json();

if (data.imagePersisted) {
  // Safe to retrieve images
  const images = await fetch(
    `https://api.korastratum.com/api/v1/idv/verifications/${verificationId}/images`,
    { headers }
  );
}

warning

Image persistence is asynchronous. The imagePersisted field may be false immediately after a verification completes. Wait for it to become true or listen for the verification.completed webhook which includes the final persistence status.