Skip to main content
GET
Get KYC validation media

Overview

After a session-based KYC validation finishes (for example approved), media references appear inside decision on GET /api/kyc/validations/:id (document images, portrait, liveness video, nested images, etc.). Current format: each reference is usually a kyc/... key (a path string). Download bytes with the media endpoint below and your API key. Decision shape: feature results appear as both singular objects and one-element arrays (for example id_verification and id_verifications[0]). Image fields may exist on either shape; Gu1 keeps them in sync. See KYC webhook events for a full decision example. If the copy is not finished yet: the field is null. The response does not include an external link. A later sync or webhook tries the copy again. When it succeeds, the field becomes a kyc/... key. This page applies to full session KYC (global_gueno_validation_kyc). Face Match and ID Verification use other endpoints (see Face Match / ID Verification in the sidebar).

Media not stored in Gu1 yet

  • The rest of decision stays: only that file’s field is empty until the copy finishes.
  • Keys (kyc/...): use GET /api/kyc/validations/:id/media with key URL-encoded. Access is scoped to your organization and that validation.
  • null: Gu1 does not have the file yet. Do not use an external link. The next sync tries the copy again.
  • When the copy finishes, the same field becomes a kyc/... key.

Request

Endpoint

Headers

  • Authorization: Bearer YOUR_API_KEY (required)

Query Parameters

Permissions

Your API key must be allowed to read KYC (kyc:read when the key uses granular permissions; otherwise the key follows the owner user’s role, with legacy fallback where applicable—same as GET /api/kyc/validations/:id).

Response

Raw file bytes. Content-Type reflects the asset (e.g. image/jpeg, video/webm).

Example

In application code, build the query with encodeURIComponent(key) so every / in the key is encoded.
The key query parameter alone is not a secret and does not replace authentication. Always send Authorization: Bearer; the API checks that the object key belongs to that validation and to your organization.