extractor

name	extractor
description	Downloads and extracts structured data from tax documents.

Tax Document Extractor

Extract structured field data from tax documents stored in Box using the Box AI Extract API.

Workflow

1. Identify the file — get the Box file ID from the upstream task context or by searching.
2. Extract via Box AI — use ai:extract (freeform) or ai:extract-structured (typed fields) via the Box CLI. Prefer ai:extract-structured when you know the document type and fields ahead of time, as it returns typed key-value pairs. Fall back to ai:extract for unknown document types or exploratory extraction.
3. Return structured results — output each file's data using the JSON code fence + table pattern described below.

Box AI Extract Commands

CLI reference: ai:extract-structured

USAGE
  $ box ai:extract-structured --items <value>... [-t <value>] [--json | --csv]
    [--fields <value>...] [--metadata-template <value>] [--ai-agent <value>]

KEY FLAGS
  --items=<value>...              (required) Comma-separated key=value pairs: id=FILE_ID,type=file
  --fields=<value>...             Repeatable. Each flag is one field to extract (see format below).
  --metadata-template=<value>     Alternative to --fields. Comma-separated: type=metadata_template,scope=enterprise,template_key=KEY
  --json                          Output formatted JSON
  -t, --token=<value>             Auth token
  --ai-agent=<value>              JSON string to override the default AI agent config

--fields value format (single comma-separated string per field): key=KEY,type=TYPE,description=DESC,prompt=PROMPT,displayName=LABEL,options=OPT1;OPT2

Supported attributes: key (required), type, description, prompt, displayName, options (semicolon-separated for enum/multiSelect).

Supported types: string, float, date, enum, multiSelect.

CRITICAL --fields parsing bug — no reserved words anywhere in values. The CLI parser scans the entire --fields string for reserved attribute names (key, type, description, prompt, displayName, options) using substring matching. If ANY attribute value contains one of these words — even as a substring — parsing breaks with Invalid key '...'. This applies to ALL attributes, not just key.

Examples that FAIL:

• key=description,... — value description is a reserved name
• key=item_description,... — value contains description as substring
• prompt=What is the description?,... — value contains description
• prompt=What is the prompt?,... — value contains prompt
• description=Full type of document,... — value contains type

Examples that WORK:

• key=notes,... — no reserved words
• key=desc,... — desc is not a reserved name
• prompt=What is this item?,... — no reserved words
• description=Person hobby,... — no reserved words (from official --help example)

Avoid commas inside attribute values. The comma is the delimiter between attributes. If a value needs a comma, rephrase to avoid it (e.g. "Wages tips and other compensation" instead of "Wages, tips, and other compensation").

Every attribute MUST have =value. Omitting =value (e.g. description,type=string) causes the same parsing error.

CLI reference: ai:extract

USAGE
  $ box ai:extract --prompt <value> --items <value>... [-t <value>] [--json | --csv]
    [--ai-agent <value>]

KEY FLAGS
  --prompt=<value>    (required) Freeform prompt — plain text, field list, or stringified JSON
  --items=<value>...  (required) Comma-separated key=value pairs: id=FILE_ID,type=file
  --json              Output formatted JSON
  -t, --token=<value> Auth token

Structured extraction (ai:extract-structured)

Use when you know the exact fields and their types. Each --fields flag specifies one field. You can repeat --fields for each field you want to extract.

npx @box/cli ai:extract-structured \
  --items="id=FILE_ID,type=file" \
  --fields "key=employer_name,type=string,displayName=Employer Name,prompt=What is the employer name?" \
  --fields "key=wages_box1,type=float,displayName=Wages Box 1,prompt=What is the amount in Box 1?" \
  --fields "key=federal_tax_withheld_box2,type=float,displayName=Federal Tax Withheld,prompt=What is the federal income tax withheld in Box 2?" \
  --token $BOX_DEVELOPER_TOKEN --json

The response is a flat JSON object with the extracted values keyed by the key names.

Freeform extraction (ai:extract)

Use when you want a natural-language prompt or don't know the exact fields. The prompt can be plain text, a list of field names, or a stringified JSON structure.

npx @box/cli ai:extract \
  --items="id=FILE_ID,type=file" \
  --prompt "vendor, invoice_number, total, date, document_type" \
  --token $BOX_DEVELOPER_TOKEN --json

The response contains an answer field with a JSON string of extracted key-value pairs.

Using a metadata template

If a Box metadata template already exists for the document type, use --metadata-template instead of --fields:

npx @box/cli ai:extract-structured \
  --items="id=FILE_ID,type=file" \
  --metadata-template="type=metadata_template,scope=enterprise,template_key=TEMPLATE_KEY" \
  --token $BOX_DEVELOPER_TOKEN --json

Field Templates

Use these field definitions with ai:extract-structured for each document type. Pass each field as a separate --fields flag. Each value below is the exact string to pass after --fields.

W-2:

npx @box/cli ai:extract-structured \
  --items="id=FILE_ID,type=file" \
  --fields "key=employer_name,type=string,displayName=Employer Name,prompt=What is the employer name?" \
  --fields "key=employer_ein,type=string,displayName=Employer EIN,prompt=What is the employer EIN?" \
  --fields "key=wages_box1,type=float,displayName=Wages (Box 1),prompt=What is the amount in Box 1 Wages tips and other compensation?" \
  --fields "key=federal_tax_withheld_box2,type=float,displayName=Federal Tax Withheld (Box 2),prompt=What is the federal income tax withheld in Box 2?" \
  --fields "key=ss_wages_box3,type=float,displayName=SS Wages (Box 3),prompt=What is the Social Security wages in Box 3?" \
  --fields "key=ss_tax_box4,type=float,displayName=SS Tax (Box 4),prompt=What is the Social Security tax withheld in Box 4?" \
  --fields "key=medicare_wages_box5,type=float,displayName=Medicare Wages (Box 5),prompt=What is the Medicare wages in Box 5?" \
  --fields "key=medicare_tax_box6,type=float,displayName=Medicare Tax (Box 6),prompt=What is the Medicare tax withheld in Box 6?" \
  --fields "key=state,type=string,displayName=State,prompt=What is the state?" \
  --fields "key=state_wages,type=float,displayName=State Wages,prompt=What are the state wages?" \
  --fields "key=state_tax,type=float,displayName=State Tax,prompt=What is the state income tax?" \
  --fields "key=401k_box12,type=float,displayName=401k (Box 12),prompt=What is the 401k contribution in Box 12?" \
  --token $BOX_DEVELOPER_TOKEN --json

1099-NEC:

npx @box/cli ai:extract-structured \
  --items="id=FILE_ID,type=file" \
  --fields "key=payer_name,type=string,displayName=Payer Name,prompt=What is the payer name?" \
  --fields "key=payer_tin,type=string,displayName=Payer TIN,prompt=What is the payer TIN?" \
  --fields "key=nonemployee_compensation_box1,type=float,displayName=Nonemployee Compensation (Box 1),prompt=What is the nonemployee compensation in Box 1?" \
  --fields "key=federal_tax_withheld_box4,type=float,displayName=Federal Tax Withheld (Box 4),prompt=What is the federal income tax withheld in Box 4?" \
  --token $BOX_DEVELOPER_TOKEN --json

1099-INT:

npx @box/cli ai:extract-structured \
  --items="id=FILE_ID,type=file" \
  --fields "key=payer_name,type=string,displayName=Payer Name,prompt=What is the payer name?" \
  --fields "key=interest_income_box1,type=float,displayName=Interest Income (Box 1),prompt=What is the interest income in Box 1?" \
  --fields "key=early_withdrawal_penalty_box2,type=float,displayName=Early Withdrawal Penalty (Box 2),prompt=What is the early withdrawal penalty in Box 2?" \
  --fields "key=federal_tax_withheld_box4,type=float,displayName=Federal Tax Withheld (Box 4),prompt=What is the federal income tax withheld in Box 4?" \
  --token $BOX_DEVELOPER_TOKEN --json

1099-DIV:

npx @box/cli ai:extract-structured \
  --items="id=FILE_ID,type=file" \
  --fields "key=payer_name,type=string,displayName=Payer Name,prompt=What is the payer name?" \
  --fields "key=ordinary_dividends_box1a,type=float,displayName=Ordinary Dividends (Box 1a),prompt=What are the ordinary dividends in Box 1a?" \
  --fields "key=qualified_dividends_box1b,type=float,displayName=Qualified Dividends (Box 1b),prompt=What are the qualified dividends in Box 1b?" \
  --fields "key=capital_gain_box2a,type=float,displayName=Capital Gain (Box 2a),prompt=What is the total capital gain distribution in Box 2a?" \
  --fields "key=federal_tax_withheld_box4,type=float,displayName=Federal Tax Withheld (Box 4),prompt=What is the federal income tax withheld in Box 4?" \
  --token $BOX_DEVELOPER_TOKEN --json

Receipt/Invoice:

npx @box/cli ai:extract-structured \
  --items="id=FILE_ID,type=file" \
  --fields "key=vendor,type=string,displayName=Vendor,prompt=What is the vendor or merchant name?" \
  --fields "key=date,type=date,displayName=Date,prompt=What is the invoice or receipt date?" \
  --fields "key=amount,type=float,displayName=Total Amount,prompt=What is the total amount?" \
  --fields "key=category,type=string,displayName=Category,prompt=What category does this expense belong to?" \
  --fields "key=notes,type=string,displayName=Notes,prompt=Briefly summarize what was purchased or invoiced" \
  --token $BOX_DEVELOPER_TOKEN --json

Unknown document type — use freeform extraction:

npx @box/cli ai:extract \
  --items="id=FILE_ID,type=file" \
  --prompt "Extract all key financial data: document type, names, dates, amounts, account numbers, tax IDs, and any other relevant fields" \
  --token $BOX_DEVELOPER_TOKEN --json

Error Handling (CRITICAL)

If Box AI extraction fails (API error, unsupported format, empty response, etc.), do NOT fall back to downloading the file and parsing it locally with Python. Instead:

1. Report the failure clearly — state which file failed, the error message, and the HTTP status if available.
2. Suggest possible causes (e.g., file format not supported, file too large, permissions issue).
3. Move on to the next file if processing multiple documents.

Do NOT write Python scripts, use pdfplumber, or attempt any local text extraction. The Box AI Extract API is the only extraction method.

Output Structure (CRITICAL)

For EACH document you process, output its file reference as a JSON code fence FIRST, then show the extracted data below it. NEVER group all files into one JSON array. NEVER list files as text without a JSON code fence.

Pattern to follow for EVERY file:

Extracted data from the W-2:

```json
[{ "fileId": "111", "fileName": "W2_Acme.pdf", "type": "W-2", "boxPath": "Tax Docs/02_Income" }]
```

| Field | Value |
|---|---|
| Employer | Acme Robotics |
| Wages (Box 1) | $85,000 |

Next, the 1099-INT:

```json
[{ "fileId": "222", "fileName": "1099INT_Bluebird.pdf", "type": "1099-INT", "boxPath": "Tax Docs/02_Income" }]
```

| Field | Value |
|---|---|
| Payer | Bluebird Bank |
| Interest Income | $1,250 |

Each JSON code fence becomes a clickable file card in the UI.

If a command fails, run it with --help to check syntax, gather context, then retry.