# fill

Start a Paradoc form or checklist draft from seed data

Canonical URL: https://docs.paradoc.dev/ai-tools/fill/

Starts a draft of a form or checklist from seed data and applies defaults. The result reports two things separately: `accepted` says the supplied values passed validation, and `complete` says the draft meets every requirement. A draft does not need to be complete to be updated or rendered.

> **Note:** Only forms and checklists can be filled. A document or bundle returns an `unsupported_artifact` error.

## Input

Takes a [source](/ai-tools#sources) plus:

| Field                | Type     | Required | Description                                                                                  |
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------- |
| `data`               | `object` | Yes      | For a form: `{ fields, parties?, annexes? }`. For a checklist: item values keyed by item ID. |
| `evaluation_context` | `object` | No       | The `evaluation_context` from a previous draft, so date logic keeps the same "as of" date    |

Party IDs follow the pattern `<role>-<index>`, such as `tenant-0`.

## Output

| Field                | Type                              | Description                                                                                                                                                                      |
| -------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accepted`           | `boolean`                         | Whether the supplied values passed validation                                                                                                                                    |
| `complete`           | `boolean`                         | Whether the draft meets every requirement                                                                                                                                        |
| `artifact_kind`      | `"form" \| "checklist"`           | Artifact kind                                                                                                                                                                    |
| `data`               | `object`                          | The full draft payload, with defaults applied. Pass it to [`update_fill`](/ai-tools/update-fill), [`get_fill_state`](/ai-tools/get-fill-state), or [`render`](/ai-tools/render). |
| `evaluation_context` | `object`                          | The fixed context of the draft, such as `asOf`. Pass it to the next call.                                                                                                        |
| `errors`             | [`ToolError[]`](/ai-tools#errors) | One entry per rejected value                                                                                                                                                     |
| `error`              | [`ToolError`](/ai-tools#errors)   | Summary error when the fill failed                                                                                                                                               |

## Direct usage

```typescript
import { executeFill } from "@paradoc/ai-tools"

const result = await executeFill({
  source: "registry",
  registry_url: "https://public.paradoc.dev",
  artifact_name: "pet-addendum",
  data: {
    fields: { petName: "Buddy", species: "dog" },
    parties: { tenant: { id: "tenant-0", name: "Jane Doe" } },
  },
})
```

From inline artifact JSON:

```typescript
const result = await executeFill({
  source: "artifact",
  artifact: {
    kind: "form",
    name: "contact",
    version: "1.0.0",
    title: "Contact",
    fields: {
      name: { type: "text", label: "Name", required: true },
      email: { type: "email", label: "Email" },
    },
  },
  data: {
    fields: { name: "Jane Doe", email: "jane@example.com" },
  },
})
```

## Example responses

### Accepted but not complete

```json
{
  "accepted": true,
  "complete": false,
  "artifact_kind": "form",
  "data": {
    "fields": { "petName": "Buddy", "species": "dog" },
    "parties": { "tenant": { "id": "tenant-0", "name": "Jane Doe" } }
  },
  "evaluation_context": {
    "asOf": { "date": "2026-09-22", "datetime": "2026-09-22T14:05:11.630Z" }
  }
}
```

### Rejected value

```json
{
  "accepted": false,
  "complete": false,
  "artifact_kind": "form",
  "errors": [
    {
      "code": "validation_error",
      "message": "Invalid input: expected number, received string",
      "path": ["fields", "weight"]
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "Form data validation failed: Invalid input: expected number, received string"
  }
}
```