# Field detection

When you upload a PDF with no text tags, Docustay looks at the page the way a person would and places the boxes it would draw by hand: signature lines, "Date:" blanks, initials, text lines, empty boxes and table cells, tick boxes, and highlighted "sign here" bars. It reads the words beside each blank (in English, Spanish, French, German, Italian, Portuguese, Dutch, Polish, Russian, Turkish, Japanese, Korean, Chinese and Arabic), works out which person each box belongs to ("Participant", "Witness", "Case Manager", "Landlord"…), and says how sure it is of each one.

Nothing is placed until you accept it. In the editor the boxes appear dashed in each person's colour, with a line such as "Found 14 fields, 3 signers; 2 not sure about". **Accept all**, or fix them one at a time. A form you have sent before comes back with the boxes you finally placed.

A photographed or scanned page has no text, so it is read by character recognition on the server (English). A page in another script is read by shape alone.

Detection is free. The optional **Look again with AI** button (or `ai: true` in the API) lets the model check the pages the program is unsure of: 0.25 credit a page, at most 8 pages a file.

## Over the API

`POST /api/v1/documents/detect-fields` takes a file and stores nothing:

```bash
curl https://app.docustay.app/api/v1/documents/detect-fields \
  -H "Authorization: Bearer $DOCUSTAY_KEY" -H "Content-Type: application/json" \
  -d "{\"fileName\":\"intake.pdf\",\"file\":\"$(base64 -i intake.pdf)\"}"
```

Each field has `type`, `page`, `x`, `y`, `w`, `h` (fractions of the page, origin top left), `confidence` (0 to 1), `source` (`native`, `line`, `text`, `box`, `table`, `checkbox`, `highlight`, `remembered`, `vision`), the printed `label`, the `role` (a seat key from `signers`), `sensitive` (an SSN, a date of birth, an account number) and `group` (tick boxes that answer one question). Fields under `minConfidence` (default 0.6) are marked `uncertain`. `pages` says which pages are forms and which are reference pages; `documents` says how a packet splits.

To make a template and place the sure fields in one call, upload with `fields: "auto"`:

```bash
curl https://app.docustay.app/api/v1/templates/file -H "Idempotency-Key: $(uuidgen)" \
  -H "Authorization: Bearer $DOCUSTAY_KEY" -H "Content-Type: application/json" \
  -d "{\"name\":\"Intake\",\"fileName\":\"intake.pdf\",\"file\":\"$(base64 -i intake.pdf)\",\"fields\":\"auto\"}"
```

The answer's `detected` says how many fields were found, how many seats, how many it was unsure of and how many were placed. A `documents.template.fields_detected` webhook event is sent with the same numbers.

From the command line: `docustay detect intake.pdf`. From an assistant: the MCP tool `detect_fields`. In Node, `docustay.detectFields({ file, fileName })`; in Python, `client.detect_fields(file, file_name)`.

## What it will not do

It does not read ID, card or bank numbers out of a picture, and it never sends a page to the AI unless you asked for the AI look. Files are checked first: scripts, launch actions and embedded files are removed from the copy that is kept, and at most the first 100 pages are read, within a time limit. A file that cannot be read simply has no suggestions.