Skip to main content
GET
/
api
/
kyc
/
id-verification
/
verifications
Get ID Verification (List & Single)
curl --request GET \
  --url http://api.gu1.ai/api/kyc/id-verification/verifications \
  --header 'Authorization: Bearer <token>'

Documentation Index

Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

After submitting document images via POST ID Verification, each request is stored for audit. You can:
  1. List verifications (with optional filters: entityId, withoutEntity, status, pagination).
  2. Get a single verification by ID (same UUID as verificationId in the POST response).
To download stored document front/back bytes, use Get ID Verification images. All endpoints are scoped to your organization. Each list/get item uses the same extractedData shape as POST (see extractedData fields), including extraFields for non-promoted document keys.

​
1. List verifications

GET https://api.gu1.ai/api/kyc/id-verification/verifications

​
Query parameters

ParameterTypeDescription
entityIdstring (UUID)Optional. Filter by person entity.
withoutEntitybooleanIf true, only verifications with no associated entity.
statusstringOptional. approved | declined | failed.
limitnumberMax items (default 50, max 100).
offsetnumberPagination offset.

​
Response (200 OK)

{
  "verifications": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "entityId": "223e4567-e89b-12d3-a456-426614174001",
      "status": "declined",
      "requestId": "4e2bf9fb-d75b-4b26-9362-e51436cfe1eb",
      "vendorData": "my-ref-001",
      "errorMessage": null,
      "warnings": ["DOCUMENT_EXPIRED", "POSSIBLE_DUPLICATED_USER"],
      "extractedData": {
        "providerStatus": "Declined",
        "fullName": "Breno Henrique Ferreira Silva",
        "firstName": "Breno Henrique",
        "lastName": "Ferreira Silva",
        "firstSurname": "Ferreira",
        "secondSurname": "Silva",
        "documentNumber": "08585626509",
        "personalNumber": "2156732124SSPBA",
        "documentType": "Driver's License",
        "taxNumber": "10584158599",
        "dateOfBirth": "2004-08-29",
        "age": 21,
        "expirationDate": "2025-03-07",
        "dateOfIssue": "2024-03-08",
        "firstIssueDate": "2024-03-08",
        "nationality": "BRA",
        "gender": "U",
        "placeOfBirth": "Barreiras/Ba",
        "maritalStatus": "UNKNOWN",
        "issuingState": "BRA",
        "issuingStateName": "Brazil",
        "warningMeta": {
          "duplicatedSessionId": "a4bfeef8-6d6e-4e9b-8fcb-44950912b2b4",
          "duplicatedSessionNumber": 2834,
          "duplicatedApiService": "ID_VERIFICATION"
        },
        "frontImageQualityScore": {
          "overall_score": 98.2,
          "focus_score": 100,
          "brightness_score": 94,
          "is_document_fully_visible": true
        },
        "backImageQualityScore": { "overall_score": 97.1, "focus_score": 100 },
        "extraFields": { "license_category": "AB", "restrictions": "01" },
        "mrz": {
          "line1": "IDBRA085856265<<<<<<<<<<<<<<<",
          "line2": "0408299M2503077BRA<<<<<<<<<<<6",
          "line3": "SILVA<<BRENO<HENRIQUE<FERREIRA"
        },
        "parsedAddress": {},
        "barcodes": []
      },
      "createdAt": "2026-05-26T14:32:10.123Z",
      "documentFrontStoragePath": "org/.../front.jpg",
      "documentBackStoragePath": "org/.../back.jpg",
      "storageProvider": "s3"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

​
2. Get a single verification

GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id
Returns one audit record by ID. Use the verificationId from the POST response or from the list.

​
Path parameters

​
id
string
required
UUID of the ID verification (same as verificationId from POST or list).

​
Response (200 OK)

Same object shape as one item in the list above (full extractedData). 404 if not found or not in your organization.

​
Headers

For all requests: 
Authorization: Bearer YOUR_API_KEY
Include X-Organization-Id if your account is organization-scoped.

​
Error Responses

CodeHTTPDescription
NOT_FOUND404Verification ID does not exist or belongs to another organization.
UNAUTHORIZED401Missing or invalid API key or organization context.

​
Example

const response = await fetch(
  'https://api.gu1.ai/api/kyc/id-verification/verifications?limit=20',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const { verifications, pagination } = await response.json();
const first = verifications[0];
console.log(first?.extractedData?.taxNumber, first?.extractedData?.extraFields);

​
Next Steps

ID Verification (POST)

Submit document front/back and get validation

Face Match

Compare document and selfie