---
name: formwell
description: Fill out and sign PDF forms for the user from their details, through the Formwell API. Works on normal fillable PDFs and on Adobe XFA government forms (the ones that open as "Please wait..." outside Adobe Reader). Use when the user gives you a PDF form (a link or a file) and asks you to fill it in, complete it, put their info in it, or sign it.
---

# Formwell: fill PDF forms for the user

Formwell reads a PDF form, tells you what every field is for, and fills it in. It runs on a server, so all you need is HTTP (or MCP). No browser, no local install.

- **API:** `https://form.mycli.tools/api`
- **MCP:** `https://form.mycli.tools/mcp`, with the tools `read_form` and `fill_form`.
- **Auth:** every call except downloads needs `Authorization: Bearer <FORMWELL_API_KEY>`. If you can only give a URL, append `?key=<FORMWELL_API_KEY>` instead. The user gives you the key; keep it secret.

Forms and filled PDFs are kept for 24 hours, then deleted.

## Steps

### 1. Read the form

```
POST https://form.mycli.tools/api/forms
Content-Type: application/pdf          (body: the PDF bytes)
```

You can also send JSON instead: `{"pdf_url": "https://..."}` or `{"pdf_base64": "..."}`.

The response is `{form_id, xfa, count, fields: [...]}`. Each field has:

- `name`: the key to use in your answers.
- `type`: `text`, `date`, `radio`, `choice`, `checkbox`, or `signature`.
- `page`: page number.
- `label`: the best guess at what the field asks.
- `left` / `above`: the printed text beside the field and over it. Table column headers show up in `above`.
- `section`: the section heading the field sits under.
- `path`: the form's internal path, e.g. `SectB.Q12.RadioButtonList`. Question numbers live here. Trust it when a label looks off.
- `options`: for radio buttons and choices, a list of `{value, label}`.
- `maxChars`: the most characters the field holds.
- `format`: for dates, usually `yyyy-mm-dd`.
- `rect`: `[x, y, width, height]` in points from the page's top-left.

Some fields are one-character comb boxes. Their label reads like `What is your date of birth? (box 3 of 8, Y)`. Put one character in each: the digits of YYYYMMDD across the 8 boxes.

### 2. Work out the answers

Build an object mapping each field `name` to its value:

- **Text and dates:** strings. Respect `maxChars` and `format`.
- **Radio buttons and choices:** the option's printed `label` (`"Yes"`, `"English"`) or its `value`.
- **Check boxes:** `true` or `false`.
- **Repeated blocks** (previous addresses, other names, table rows): fill them top to bottom, in order.

Only use what the user actually told you, or what is already in your memory of them. Never make up personal details. If the form clearly needs something you don't have, ask the user once, listing everything that's missing together. Leave optional fields blank.

### 3. Fill

```
POST https://form.mycli.tools/api/forms/<form_id>/fill
Content-Type: application/json

{
  "answers": {"lastName1": "Sample", "RadioButtonList": "No", "PosNo": "1"},
  "editable": false,
  "signature": {"image_url": "https://.../signature.png", "near": "Signature"},
  "filename": "record-suspension-application"
}
```

- **`editable`:** `false` (the default) gives a flattened PDF that looks the same in every viewer, ready to print or send. `true` keeps the fields fillable; for XFA forms the answers also go into the form's data, so it opens filled in Adobe Reader.
- **`signature`** is optional and only works on the flattened copy.
  - The image: `image_url` or `image_base64`, PNG or JPEG.
  - Where it goes: `near` (printed text to sign right beside), or `page`, `x`, `y` (points from the top-left; check the field `rect` values to choose a spot).
  - Size: `width` in points, default 150.
  - Only sign when the user asks you to and gives you their signature image.

The response is `{download_url, expires_in_hours, report}`. The report holds `filled`, `fields`, `signed` and `warnings`.

If a field name is wrong or an option isn't on the list, you get a 422 with one line per problem. Fix those and call again.

There's also a one-shot version: `POST https://form.mycli.tools/api/fill` with `pdf_url` or `pdf_base64`, plus the same answers and options.

### 4. Hand it back

Give the user the `download_url`. Tell them three things:
- what you filled,
- what you left blank and why,
- that the link expires in 24 hours.

If `report.warnings` lists anything, such as text that was too long for its box, say so.

## Limits

- The form's own scripts don't run. Repeating sections keep their starting number of rows, so if the user has more entries than rows, tell them; these forms usually say to attach a page.
- Characters outside Western European alphabets may print as `?`.
- PDFs are limited to 25 MB.