Get verification results

Retrieve a KYC result and its document records by refId.

Returns the current KYC resource associated with your stable refId.

GET https://api.voveid.net/v2/users/customer-7f3d
x-api-key: vove_sandbox_replace_me
accept: application/json

Path parameters

Parameter	Type	Required	Description
refId	string	Yes	The value supplied when the verification session was created

URL-encode refId when constructing the request.

Example request

curl 'https://api.voveid.net/v2/users/customer-7f3d' \
  --header 'accept: application/json' \
  --header 'x-api-key: vove_sandbox_replace_me'

Example response

The fields returned depend on the selected flow and completed checks. This example shows a representative document-verification result. Calendar dates use DD.MM.YYYY; timestamps such as createdAt and updatedAt remain ISO 8601.

{
  "_id": "66f000000000000000000020",
  "refId": "customer-7f3d",
  "status": "successful",
  "createdAt": "2026-09-07T10:20:30.000Z",
  "updatedAt": "2026-09-07T10:24:12.000Z",
  "flowId": "66f000000000000000000001",
  "sessionId": "66f000000000000000000002",
  "sessions": [
    "66f000000000000000000002"
  ],
  "documents": [
    {
      "stepId": "ID_DOCUMENT",
      "type": "Passport",
      "firstName": "AMINA",
      "lastName": "EXAMPLE",
      "dateOfBirth": "01.02.1990",
      "dateOfExpiration": "15.07.2030",
      "issuingAuthority": "EXAMPLE AUTHORITY",
      "idNumber": "X00000000",
      "matchLevel": 7,
      "digitalIDSpoof": "LIKELY_PHYSICAL_ID",
      "faceOnDocumentSpoof": "LIKELY_ORIGINAL_FACE",
      "textOnDocumentSpoof": "LIKELY_ORIGINAL_TEXT",
      "mrzStatus": "SUCCESS"
    }
  ],
  "metadata": {}
}

Response fields

Field	Type	Description
_id	string	VOVE ID user resource identifier
refId	string	Your stable customer identifier
status	string	Current KYC status; see Statuses
createdAt	string	ISO 8601 creation time
updatedAt	string	ISO 8601 last-update time
flowId	string	KYC flow used for the verification
sessionId	string	Most recent session identifier
sessions	string[]	Session identifiers associated with this resource
documents	object[]	Extracted document records returned by completed document steps
metadata	object	Integration metadata when present

TypeScript types

type VerificationStep =
  | 'ID_DOCUMENT'
  | 'DRIVING_LICENSE'
  | 'CAR_REGISTRATION_DOCUMENT'
  | 'ADDRESS_PROOF';

type DigitalIdSpoofStatus =
  | 'LIKELY_PHYSICAL_ID'
  | 'COULD_NOT_CONFIDENTLY_DETERMINE_PHYSICAL_ID_USER_NEEDS_TO_RETRY';

type FaceOnDocumentStatus =
  | 'NOT_AVAILABLE'
  | 'LIKELY_ORIGINAL_FACE'
  | 'CANNOT_CONFIRM_ID_IS_AUTHENTIC'
  | 'OCR_TEMPLATE_DOES_NOT_SUPPORT_DETECTION';

type TextOnDocumentStatus =
  | 'NOT_AVAILABLE'
  | 'LIKELY_ORIGINAL_TEXT'
  | 'CANNOT_CONFIRM_ID_IS_AUTHENTIC';

type MrzStatus =
  | 'NO_MRZ_SPECIFIED_BY_TEMPLATE'
  | 'MRZ_READ_BUT_CHECKSUM_FAILED'
  | 'SUCCESS';

type VerificationDocument = {
  stepId: VerificationStep;
  type?: string;
  firstName?: string;
  lastName?: string;
  fullName?: string;
  dateOfBirth?: string;
  dateOfIssue?: string;
  dateOfExpiration?: string;
  issuingAuthority?: string;
  issuingCountry?: string;
  placeOfBirth?: string;
  sex?: string;
  address?: string;
  address1?: string;
  idNumber?: string;
  mrzLine1?: string;
  mrzLine2?: string;
  matchLevel?: number;
  digitalIDSpoof?: DigitalIdSpoofStatus;
  faceOnDocumentSpoof?: FaceOnDocumentStatus;
  textOnDocumentSpoof?: TextOnDocumentStatus;
  mrzStatus?: MrzStatus;
  [field: string]: unknown;
};

type VerificationResult = {
  _id: string;
  refId: string;
  status: string;
  createdAt: string;
  updatedAt: string;
  flowId?: string;
  sessionId?: string;
  sessions?: string[];
  documents?: VerificationDocument[];
  metadata?: Record<string, unknown>;
};

Treat unknown status values as pending review rather than assuming success.

Retrieve document media

GET https://api.voveid.net/v2/users/customer-7f3d/documents
x-api-key: vove_sandbox_replace_me
accept: application/json

Representative response:

{
  "selfie": "base64_redacted",
  "documents": [
    {
      "stepId": "ID_DOCUMENT",
      "front": "base64_redacted",
      "back": "base64_redacted",
      "photo": "base64_redacted",
      "frontCropped": "base64_redacted",
      "backCropped": "base64_redacted",
      "type": "Passport"
    }
  ]
}

Document and biometric media is sensitive. Retrieve it only when required, restrict access, avoid logging response bodies, and apply your retention and deletion policy.

Server example

const response = await fetch(
  `https://api.voveid.net/v2/users/${encodeURIComponent(refId)}`,
  { headers: { 'x-api-key': process.env.VOVE_API_KEY } },
);

if (response.status === 404) {
  return { status: 'not_found' };
}

if (!response.ok) {
  throw new Error(`VOVE result retrieval failed (${response.status})`);
}

const verification = await response.json();

Use this endpoint as the server-side authority after a webhook. Browser redirects and SDK callbacks are immediate journey outcomes, not sufficient by themselves for an irreversible decision.