> ## 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.

# Get ID Verification (List & Single)

> List ID verification audit records or get one by ID — in the gu1 KYC API for identity verification flows, with examples for get id verification.

## Overview

After submitting document images via [POST ID Verification](/en/use-cases/kyc/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](/en/use-cases/kyc/id-verification-images).

All endpoints are scoped to your organization.

Each list/get item uses the same `extractedData` shape as POST (see [extractedData fields](/en/use-cases/kyc/id-verification#extracteddata-fields)), including `ejemplar` when present on Argentine DNI.

## 1. List Verifications

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

### Query Parameters

| Parameter       | Type          | Description                                              |
| --------------- | ------------- | -------------------------------------------------------- |
| `entityId`      | string (UUID) | Optional. Filter by person entity.                       |
| `withoutEntity` | boolean       | If `true`, only verifications with no associated entity. |
| `status`        | string        | Optional. `approved` \| `declined` \| `failed`.          |
| `limit`         | number        | Max items (default 50, max 100).                         |
| `offset`        | number        | Pagination offset.                                       |

### Response (200 OK)

```json theme={null}
{
  "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

<ParamField path="id" type="string" required>
  UUID of the ID verification (same as <code>verificationId</code> from POST or list).
</ParamField>

### 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

| Code           | HTTP | Description                                                        |
| -------------- | ---- | ------------------------------------------------------------------ |
| `NOT_FOUND`    | 404  | Verification ID does not exist or belongs to another organization. |
| `UNAUTHORIZED` | 401  | Missing or invalid API key or organization context.                |

## Example

<CodeGroup>
  ```javascript Node.js List theme={null}
  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);
  ```

  ```javascript Node.js Get one theme={null}
  const id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/id-verification/verifications/${id}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const verification = await response.json();
  ```

  ```curl cURL Get one theme={null}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.gu1.ai/api/kyc/id-verification/verifications/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="ID Verification (POST)" icon="play" href="/en/use-cases/kyc/id-verification">
    Submit document front/back and get validation
  </Card>

  <Card title="Face Match" icon="play" href="/en/use-cases/kyc/face-match">
    Compare document and selfie
  </Card>
</CardGroup>