> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintelite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifications

> Understanding the verification workflow and lifecycle

## What are Verifications?

Verifications are the core of AnyCheck - they represent document or identity validation requests that are processed through external verification providers.

## Verification Components

* **Service:** The specific verification type to perform (KTP, BPKB, Land Certificate, etc.). Each service has specialized processing logic and integration with relevant external providers.

* **Folder:** Organizational container for grouping verifications by project, client, or use case. Examples: "Q4 2024 Loan Applications", "Corporate Client Onboarding".

* **Result ID:** Links multiple verifications for a single entity or transaction. Use the same result ID when verifying different documents for the same customer.

* **Configuration:** Service-specific input data required for verification. Can be form-based (direct data input) or file-based (document uploads with parameters).

## Verification Status

<Steps>
  <Step title="IN_QUEUE">
    Verification submitted and queued for background processing
  </Step>

  <Step title="IN_PROGRESS">
    Verification being processed by dedicated verifier and external providers
  </Step>

  <Step title="FRAUD_DETECTED">
    Verification data not extracted yet because potential fraud detected in
    documents and requires user confirmation to keep proceed (Bank Statement and
    Financial Statement services). This is to prevent heavy processing for
    untrusted large documents.
    <Info>Only occur if `fraud_detection = true` on configuration</Info>
  </Step>

  <Step title="NEED_REVIEW">
    For API integrations, verifications proceed directly to `COMPLETED`. The
    `NEED_REVIEW` state is used by the AnyCheck dashboard for manual data review
    and is not part of the API integration flow.
  </Step>

  <Step title="COMPLETED">
    Verification successfully completed with analysis results
  </Step>

  <Step title="PARTIALLY_COMPLETED">
    Some verifications in the result group completed successfully; others are still pending or failed
  </Step>

  <Step title="FAILED">
    Verification failed due to an error or validation failure. Retryable via `POST /verifications/{id}/retry`
  </Step>

  <Step title="PARTIALLY_FAILED">
    Some verifications in the result group failed while others completed successfully
  </Step>

  <Step title="CANCELLED">
    Verification was cancelled before completion. Can be retried if needed
  </Step>
</Steps>

## Creating Verifications

### Workflow

<Steps>
  <Step title="Get Folder ID">Create folder or get existing folder ID</Step>
  <Step title="Get Service ID">Get service list and find the service ID</Step>

  <Step title="Submit Verification">
    Build the `configuration` payload using the [Verification Services](/anycheck/concepts/verification-services) guide and submit
  </Step>

  <Step title="Get Results">Poll verification status or receive results via webhook</Step>
</Steps>

### Step 1: Get Folder ID

Create folder or get existing folder ID

<Tabs>
  <Tab title="Create Folder">
    ```bash theme={null}
    curl -X POST "https://api.anycheck.ai/folders" \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "January 2024 Verifications"
      }'
    ```

    Response:

    ```json theme={null}
    {
      "id": "folder-uuid",
      "group": {
        "id": "group-uuid",
        "name": "My Group"
      },
      "name": "January 2024 Verifications",
      "is_starred": false,
      "created_at": "2024-01-15T10:00:00Z",
      "created_by": "user-uuid",
      "updated_at": "2024-01-15T10:00:00Z",
      "updated_by": "user-uuid"
    }
    ```
  </Tab>

  <Tab title="Get Existing Folders">
    ```bash theme={null}
    curl -X GET "https://api.anycheck.ai/groups/{group_id}/folders?page_size=10&page_offset=0&search=February" \
      -H "X-API-Key: YOUR_API_KEY"
    ```

    Response:

    ```json theme={null}
    {
      "total": 1,
      "items": [
        {
          "id": "folder-uuid",
          "group": {
            "id": "group-uuid",
            "name": "My Group"
          },
          "name": "February 2024 Verifications",
          "is_starred": false,
          "total_service": 3,
          "total_result": 15,
          "created_at": "2024-01-15T10:00:00Z",
          "created_by": "user-uuid",
          "updated_at": "2024-01-15T10:00:00Z",
          "updated_by": "user-uuid"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### Step 2: Get Service ID

Get service list and find service ID

```bash theme={null}
curl -X GET "https://api.anycheck.ai/services" \
  -H "X-API-Key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "total": 12,
  "items": [
    {
      "id": "service-uuid",
      "category": {
        "id": "category-uuid",
        "name": "Ownership Verification",
        "type": "DOCUMENT_VERIFICATION"
      },
      "code": "KTP_VERIFICATION",
      "name": "KTP & PEP Verification",
      "description": "Verifying customer identity and screening for PEP (Politically Exposed Person) status by checking NIK, name, and date of birth against trusted databases.",
      "icon_file_url": "https://example.com/icon.png",
      "action_param": {},
      "is_enabled": true,
      "created_at": "2024-01-15T10:00:00Z",
      "created_by": "admin-uuid",
      "updated_at": "2024-01-15T10:00:00Z",
      "updated_by": "admin-uuid"
    },
    ...
  ]
}
```

### Step 3: Submit Verification

Build the `configuration` payload using the field definitions in the [Verification Services](/anycheck/concepts/verification-services) guide, then submit the verification.

<Note>
  Each service requires a specific set of configuration fields. Refer to the [Verification Services](/anycheck/concepts/verification-services) guide for the exact fields, types, and accepted values for each service.
</Note>

<Tabs>
  <Tab title="Form-based Verification">
    ```bash theme={null}
    curl -X POST https://api.anycheck.ai/verifications \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "service_id": "ktp-service-uuid",
        "folder_id": "folder-uuid",
        "configuration": {
          "verification_type": "NIK",
          "nik": "1234567890123456"
        }
      }'
    ```

    Response:

    ```json theme={null}
    {
      "id": "verification-uuid",
      "service": {
        "id": "service-uuid",
        "name": "KTP & PEP Verification"
      },
      "user_id": "user-uuid",
      "api_key": "api-key",
      "folder_id": "folder-uuid",
      "result_id": "result-uuid",
      "execution_time": 0,
      "status": "IN_QUEUE",
      "start_date": null,
      "end_date": null,
      "input_config": {
        "verification_type": "NIK",
        "nik": "1234567890123456"
      },
      "input_file_url": null,
      "output": null,
      "output_file_url": null,
      "output_status": null,
      "external_job_id": null,
      "webhook_url": null,
      "webhook_metadata": null,
      "export_file_url": null,
      "credit_used": 10,
      "total_files": 0,
      "total_pages": 0
    }
    ```
  </Tab>

  <Tab title="File-based Verification">
    **First upload the files**

    ```bash theme={null}
    curl -X POST https://api.anycheck.ai/uploads \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: multipart/form-data" \
      -F "file_category=VERIFICATION_INPUT_FILE" \
      -F "files=@ktp.jpg" \
      -F "files=@selfie.jpg"
    ```

    <AccordionGroup>
      <Accordion title="Password Protection for File Uploads">
        If uploading password-protected PDFs, include the `file_passwords` parameter with passwords in the same order as the files. The first password corresponds to the first file, second password to second file, etc. Use empty string for files without passwords. If all files are unprotected, omit the `file_passwords` parameter entirely.

        Example with password-protected files:

        ```bash theme={null}
        curl -X POST https://api.anycheck.ai/uploads \
          -H "X-API-Key: YOUR_API_KEY" \
          -H "Content-Type: multipart/form-data" \
          -F "file_category=VERIFICATION_INPUT_FILE" \
          -F "files=@protected_statement.pdf" \
          -F "files=@regular_document.pdf" \
          -F "file_passwords=mypassword" \
          -F "file_passwords="
        ```
      </Accordion>
    </AccordionGroup>

    Response:

    ```json theme={null}
    {
      "file_category": "VERIFICATION_INPUT_FILE",
      "files": [
        {
          "file_name": "ktp.jpg",
          "path": "/uploads/object-uuid/ktp.jpg",
          "url": "https://storage.example.com/uploads/object-uuid/ktp.jpg",
          "page_count": 1
        },
        {
          "file_name": "selfie.jpg",
          "path": "/uploads/object-uuid/selfie.jpg",
          "url": "https://storage.example.com/uploads/object-uuid/selfie.jpg",
          "page_count": 1
        }
      ]
    }
    ```

    **Then create verification with file paths**

    ```bash theme={null}
    curl -X POST https://api.anycheck.ai/verifications \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "service_id": "ktp-service-uuid",
        "folder_id": "folder-uuid",
        "configuration": {
          "verification_type": "KTP_SELFIE",
          "files": {
            "ktp_file": ["/uploads/object-uuid/ktp.jpg"],
            "selfie_file": ["/uploads/object-uuid/selfie.jpg"]
          },
          "fraud_detection": false
        }
      }'
    ```

    Response:

    ```json theme={null}
    {
      "id": "verification-uuid",
      "service": {
        "id": "service-uuid",
        "name": "KTP & PEP Verification"
      },
      "user_id": "user-uuid",
      "api_key": "api-key",
      "folder_id": "folder-uuid",
      "result_id": "result-uuid",
      "execution_time": 0,
      "status": "IN_QUEUE",
      "start_date": null,
      "end_date": null,
      "input_config": {
        "verification_type": "KTP_SELFIE",
        "files": {
          "ktp_file": ["files/ktp.jpg"],
          "selfie_file": ["files/selfie.jpg"]
        }
      },
      "input_file_url": {
        "ktp_file": ["https://example.com/files/ktp.jpg"],
        "selfie_file": ["https://example.com/files/selfie.jpg"]
      },
      "output": null,
      "output_file_url": null,
      "output_status": null,
      "external_job_id": null,
      "webhook_url": null,
      "webhook_metadata": null,
      "export_file_url": null,
      "credit_used": 10,
      "total_files": 2,
      "total_pages": 2
    }
    ```
  </Tab>
</Tabs>

### Step 4: Get Results

Retrieve verification results via API or webhook

<Tabs>
  <Tab title="API Polling">
    ```bash theme={null}
    curl -X GET https://api.anycheck.ai/verifications/{verification_id} \
      -H "X-API-Key: YOUR_API_KEY"
    ```

    Response:

    ```json theme={null}
    {
      "id": "verification-uuid",
      "service": {
        "id": "service-uuid",
        "name": "KTP & PEP Verification"
      },
      "user_id": "user-uuid",
      "api_key": "api-key",
      "folder_id": "folder-uuid",
      "result_id": "result-uuid",
      "execution_time": 2.28439,
      "status": "COMPLETED",
      "start_date": "2025-10-14T20:12:56.102166+07:00",
      "end_date": "2025-10-14T20:12:58.386556+07:00",
      "input_config": {
        "verification_type": "KTP_SELFIE",
        "files": {
          "ktp_file": ["files/ktp.jpg"],
          "selfie_file": ["files/selfie.jpg"]
        }
      },
      "input_file_url": {
        "ktp_file": ["https://example.com/files/ktp.jpg"],
        "selfie_file": ["https://example.com/files/selfie.jpg"]
      },
      "output": {
        "face_match_confidence_level": "LOW",
        "face_match_confidence_score": 2.284846674563825,
        "is_match_face": false
      },
      "output_file_url": "https://example.com/output.json",
      "output_status": "NOT_VERIFIED",
      "external_job_id": null,
      "webhook_url": null,
      "webhook_metadata": null,
      "export_file_url": null,
      "credit_used": 10,
      "total_files": 2,
      "total_pages": 2
    }
    ```
  </Tab>

  <Tab title="Webhook Notifications">
    Register a `webhook_url` when creating the verification. AnyCheck will POST a signed payload
    to that URL on each status transition.

    ```bash theme={null}
    curl -X POST https://api.anycheck.ai/verifications \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "service_id": "service-uuid",
        "folder_id": "folder-uuid",
        "configuration": { ... },
        "webhook_url": "https://your-app.com/webhooks/anycheck",
        "webhook_metadata": {
          "webhook_secret": "your-signing-secret"
        }
      }'
    ```

    Your endpoint receives:

    ```json theme={null}
    {
      "event": "verification.status_changed",
      "timestamp": "2025-10-14T20:12:58.386556Z",
      "verification_id": "verification-uuid",
      "status": "COMPLETED",
      "data": {
        "face_match_confidence_level": "LOW",
        "face_match_confidence_score": 2.284846674563825,
        "is_match_face": false
      }
    }
    ```

    See the [Webhooks guide](/anycheck/concepts/webhooks) for full details on payload format,
    HMAC-SHA256 signature verification, and best practices.
  </Tab>
</Tabs>

## Working with Results

Once a verification is complete, you can:

* View Folder Results: Get all verifications within a folder grouped by result ID using the [Get Folder Results](/anycheck/api-reference/folders/get-folder-results) endpoint.

* Get Verifications by Result ID: Retrieve all verifications in a result group using the [List Verifications](/anycheck/api-reference/verifications/list-verifications-by-result-id) endpoint.

* Export Verification Results: Generate formatted verification reports in Excel formats using the [Export Verification](/anycheck/api-reference/verifications/export-verification-results) endpoint.

* Download Raw OCR Data: Access raw OCR extraction data in JSON format using the [Download Raw OCR](/anycheck/api-reference/verifications/download-raw-ocr) endpoint.

* Download Raw Excel Data: Download raw verification data in Excel format using the [Download Raw Excel](/anycheck/api-reference/verifications/download-raw-excel) endpoint.is.

## Retry Mechanism

Retry failed verifications using the [Retry Verification](/anycheck/api-reference/verifications/retry-verification) endpoint. This will retry the verification with the same configuration.

**Retry Scenarios:**

* Temporary service outage
* Network timeout
* Provider rate limiting

## Credit Usage

Each verification consumes credits upon submission. The `credit_used` field in the verification response shows the exact amount consumed for that request. Credit costs vary by service and may differ between organizations. Contact your account manager or check the AnyCheck dashboard for your group's pricing.

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Folders for Organization" icon="folder">
    Create folders for projects or clients to manage large volumes of
    verifications and provide structure for reporting
  </Card>

  <Card title="Group Related Verifications" icon="link">
    Use the same result ID to link multiple verifications for a single entity or
    transaction
  </Card>

  <Card title="Use Webhooks" icon="bolt">
    Register a `webhook_url` on each verification to receive instant status updates instead of polling
  </Card>
</CardGroup>

## Checking for Duplicates

Before submitting a file-based verification, check whether the same document has already been verified within your group. This prevents accidentally processing the same document twice.

```bash theme={null}
curl -X POST https://api.anycheck.ai/verifications/check-duplicate \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@ktp.jpg"
```

**Response:**

```json theme={null}
{
  "is_duplicate": true,
  "detected_documents": ["KTP"],
  "previous_verifications": [
    {
      "id": "prev-verification-uuid",
      "service": { "id": "service-uuid", "name": "KTP & PEP Verification" },
      "folder": { "id": "folder-uuid", "name": "January Verifications" },
      "detected_documents": ["KTP"]
    }
  ]
}
```

To exclude a specific verification from the check (useful when retrying), pass `verification_id` as an additional form field:

```bash theme={null}
curl -X POST https://api.anycheck.ai/verifications/check-duplicate \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@ktp.jpg" \
  -F "verification_id=prev-verification-uuid"
```

***

## Bulk Export

Export multiple verification results into a single Excel file. Supports up to 10 result groups or 50 individual verifications per request.

```bash theme={null}
curl -X POST https://api.anycheck.ai/verifications/bulk-export \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "result_ids": ["result-uuid-1", "result-uuid-2"],
    "format": "xlsx",
    "sheet_mode": "multiple"
  }'
```

For large exports, provide an `email` address to receive the download link asynchronously:

```bash theme={null}
-d '{
  "result_ids": ["result-uuid-1", "result-uuid-2", "result-uuid-3"],
  "email": "user@example.com",
  "format": "xlsx"
}'
```

***

## Next Steps

<CardGroup cols={1}>
  <Card title="Verification Service" icon="list-check" href="/anycheck/concepts/verification-services">
    Learn about available services
  </Card>
</CardGroup>