# AI Checklist
Source: https://docs.file.ai/verify/ai-checklist

> Check that every folder holds the documents and filled fields you require, and read the verdict over the API.

fileAI app

# AI Checklist

Copy pageCopy page

Check that every folder holds the documents and filled fields you require, and read the verdict over the API.

Copy pageCopy page

## 

[​

](#what-it-does)

What it does

AI Checklist checks the files in your folders against rules you define: which document types must be present, and which fields must be filled. Configure the rules once, and fileAI flags every folder that falls short, so your team only acts on what needs attention.

## 

[​

](#when-to-use-it)

When to use it

*   You receive document packs into folders and need to know which ones are missing a required document type, such as a Bill of Lading.
*   You need every required field filled on a document before a folder moves on, not just the document being present.
*   You want your own system to read a pass/fail verdict per folder over the API instead of checking in the app.

## 

[​

](#how-it-works)

How it works

A checklist is built from Groups (AND) and Verified Schemas (OR). Every Group must pass for the folder to pass; within a Group, any one of its Verified Schemas is enough.

1

Build the checklist in the app

Choose the folders it applies to, add Groups with the required document types, and optionally add field rules. Checklists are created and edited in the app only; there is no API for that yet.

2

fileAI checks each folder

The checklist runs automatically once published, and flags folders that are missing a document type or have empty required fields.

3

Read the verdict

See the results in the app, or call `GET /v1/directories/{directoryId}/checklist-validation`.

**Example:** Group 1 requires a Contract **or** an NDA. Group 2 requires an Invoice. A folder passes only if it contains a Contract or an NDA, **and** an Invoice.

## 

[​

](#try-it)

Try it

`GET /v1/directories/{directoryId}/checklist-validation` returns a verdict for every checklist that targets a folder. The answer comes back in the same response: there is no job to poll and no pending state. The verdict comes from a cached result when one exists, and is evaluated on request otherwise (see [Freshness](#freshness)). Checklist validation must be enabled for your workspace. If it isn’t, the endpoint returns **`403 FEATURE_DISABLED`**; ask your account manager or [support@file.ai](mailto:support@file.ai) to turn it on. `FILEAI_BASE_URL` (or `BASE`) is `https://api.orion.file.ai/prod/v1`, or your [regional host](/authentication#regions).

cURL

Python

Node.js

```
curl "$FILEAI_BASE_URL/directories/<directoryId>/checklist-validation" \
  -H "x-api-key: $FILEAI_API_KEY"
```

```
import os, requests

BASE = "https://api.orion.file.ai/prod/v1"

r = requests.get(
    f"{BASE}/directories/{directory_id}/checklist-validation",
    headers={"x-api-key": os.environ["FILEAI_API_KEY"]},
)
result = r.json()
```

```
const BASE = "https://api.orion.file.ai/prod/v1";

const result = await fetch(
  `${BASE}/directories/${directoryId}/checklist-validation`,
  { headers: { "x-api-key": process.env.FILEAI_API_KEY } },
).then((r) => r.json());
```

## 

[​

](#understand-the-result)

Understand the result

Response

```
{
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "pass": 1,
  "fail": 1,
  "checklists": [
    {
      "checklistId": "649e2d2d2d2d2d2d2d2d2d2e",
      "checklistName": "Customs clearance pack",
      "status": "fail",
      "summary": { "missing": 2, "complete": 3, "incomplete": 1 },
      "missingSchemas": [
        { "schemaId": "649e2d2d2d2d2d2d2d2d2d2d", "schemaName": "Bill of Lading" }
      ]
    }
  ]
}
```

Field

Meaning

`pass`, `fail`

How many checklists passed and failed. Counts of checklists, not documents.

`checklists[].status`

`pass` when `summary.missing` and `summary.incomplete` are both 0, otherwise `fail`.

`summary.missing`

Required document types absent from the folder.

`summary.complete`

Present documents with every required field filled.

`summary.incomplete`

Present documents with at least one required field empty.

`missingSchemas`

The absent document types by `schemaId` and `schemaName`. Always present; empty on a pass.

`checklists: []` means no checklist targets the folder. It is not an all-passed result, even though `fail` is `0`. Check the array before treating `fail: 0` as a pass.

## 

[​

](#next-steps)

Next steps

## Folders

Create folders and find their `directoryId`.

## AI Schemas

The document types and fields checklists test against.

## 

[​

](#reference)

Reference

### 

[​

](#groups-and-verified-schemas)

Groups and Verified Schemas

Piece

Logic

Meaning

**Group**

AND

A checklist can have many Groups. **All** of them must pass for the folder to pass.

**Verified Schema**

OR

A document type a Group requires. If a Group lists several, **any one** of them is enough.

Inside a Group you can also add field rules: a required document type passes only when those fields are filled.

### 

[​

](#set-up-a-checklist-in-the-app)

Set up a checklist in the app

1

Create a checklist

Open **AI Checklist** from the main navigation and create a new checklist.

2

Configure Settings first

In **Settings**, choose the folders the checklist applies to and which outcomes appear in the summary.

3

Add a Group

In the **File Validation** tab, click **\+ Group** and pick the required document type from the schema dropdown.

4

Add field rules (optional)

Click **\+ Field** to require that a specific field is filled.

5

Allow alternatives (optional)

Click **\+ Verified Schema** to accept another document type in the same Group.

6

Add more Groups and save

Add any further Groups your folders must satisfy, then save and publish. The checklist runs automatically from then on.

### 

[​

](#manage-rules)

Manage rules

*   Use the enable/disable toggle on a schema block to turn a rule off without deleting it.
*   Click **Remove Group** to delete a Group and all its rules.
*   The **File Validation** tab shows a badge with your active Group count, e.g. **File validation 2**.

### 

[​

](#settings)

Settings

Setting

Default

What it does

**Sub Folders**

Off

Applies the checklist to all nested subfolders, at any depth.

**Missing Schemas**

On

Shows folders where a required document type is absent.

**Incomplete Fields**

On

Shows folders where the documents are present but field rules are not met.

**Complete**

On

Shows folders that pass. Turn off to see only folders that need attention.

### 

[​

](#api-behavior)

API behavior

*   A checklist with no field rules reports `complete: 0, incomplete: 0` and is judged on `missing` alone.
*   A checklist with no name is returned as `Untitled checklist`.
*   The endpoint only reads. It never changes the folder, its files or any checklist.
*   `403 FEATURE_DISABLED` means checklist validation is off for the workspace, not that the folder failed.

### 

[​

](#freshness)

Freshness

The first call for a folder evaluates its checklists and stores the result for up to an hour. Later calls return that stored result, so they are fast. fileAI clears it when the folder, its files or your schemas change, so the next call evaluates again. Pass `skipCache=true` to evaluate now and skip the stored result, for example right after a change you made outside fileAI. It is a heavy query, so don’t send it on every call. Values other than `true`, `false`, `1` or `0` return `422`.

### 

[​

](#current-limitations)

Current limitations

*   **No cross-file validation.** Rules apply to individual files.
*   **OR logic applies within a Group only.** Across Groups the logic is always AND.
*   **Subfolders are off by default.** Turn on **Sub Folders** in **Settings**.

### 

[​

](#faqs)

FAQs

What happens if a folder has no files?

Every Group is flagged as missing, since there is nothing to match.

Can I disable a rule without deleting it?

Yes. Use the toggle on any Verified Schema block. It stays in place and can be turned back on.

Can a checklist have only one Group?

Yes. You can add more Groups at any time.

[Previous](/verify/citations-validations)[

File Intelligence

Set your project's defaults for how files are split, read and classified, and manage its AI Schemas.

Next

](/verify/file-intelligence)

⌘I

## On this page

*   [What it does](#what-it-does)
*   [When to use it](#when-to-use-it)
*   [How it works](#how-it-works)
*   [Try it](#try-it)
*   [Understand the result](#understand-the-result)
*   [Next steps](#next-steps)
*   [Reference](#reference)
    *   [Groups and Verified Schemas](#groups-and-verified-schemas)
    *   [Set up a checklist in the app](#set-up-a-checklist-in-the-app)
    *   [Manage rules](#manage-rules)
    *   [Settings](#settings)
    *   [API behavior](#api-behavior)
    *   [Freshness](#freshness)
    *   [Current limitations](#current-limitations)
    *   [FAQs](#faqs)