---
name: fillfaster-api
description: >-
  Guides integrations with FillFaster's public REST API (PDF forms, submission
  links, webhooks-first lifecycle, PDF download, server-side PDF). Use when
  building or debugging FillFaster API clients, OpenAPI usage, tokens, or
  automation; prefer webhooks over polling for submission state; always fetch
  the OpenAPI JSON for exact request and response shapes. On every create
  submission, include user_data.recipient_name by default so the dashboard
  shows the recipient. For templates with 2 or more signers (signature round),
  send a recipients array with one entry per signer role instead. Use whenever the user mentions FillFaster, its HTTP API,
  submission links, webhooks, or PDF generation via FillFaster.
---

<!--
  FillFaster - public agent / LLM skill (installable folder: .well-known/agent-skills/fillfaster-api/).
  Served at: https://help.fillfaster.com/.well-known/agent-skills/fillfaster-api/SKILL.md
  Discovery index: https://help.fillfaster.com/.well-known/agent-skills/index.json
  You may fetch over HTTPS and cache; prefer the OpenAPI JSON for exact shapes.
-->

# FillFaster API - skill for agents and LLMs

## Purpose

This document helps **any autonomous agent or LLM** integrate with **FillFaster's public HTTP API** without guessing endpoints. It describes **workflows and priorities** only. **All concrete paths, parameters, bodies, status codes, and schemas** must be taken from the **OpenAPI document** linked below.

## Freshness

Re-fetch this `SKILL.md` and the OpenAPI JSON (URLs below) at the start of each
new integration session. Do not rely on cached copies from AI training data or
previous sessions — API paths, field names, and event types may have changed.
The canonical live URL for this skill is:
`https://help.fillfaster.com/.well-known/agent-skills/fillfaster-api/SKILL.md`

## Setting up a new integration (start here)

When the user asks you to connect a project to FillFaster, follow these steps in order.
Reply in the language the user writes in.

1. **Load the contract.** Read this skill and the OpenAPI JSON (see below). If your tool
   supports skills, offer to install this skill folder in the project so later sessions have it.
2. **Ask what they want to automate.** For example: send a template for signing from their
   app, get the signed PDF back, generate a PDF from data, or send one document to several
   signers in order. Templates are created in the
   FillFaster form builder; the API cannot create them.
3. **Get an API Token.** Ask the user to create one in their FillFaster account. Guide:
   `https://help.fillfaster.com/developers/create-api-token/` (Hebrew:
   `https://help.fillfaster.com/he/developers/create-api-token/`). The API is available on
   every plan, including the free plan. Do **not** ask the user to paste the token into the
   chat: it would stay in the conversation history. Ask them to put it in place themselves
   (step 4) and tell you when it is done.
4. **Store the token on the server.** A server-side environment variable such as
   `FILLFASTER_API_TOKEN`, with env files kept out of git. In AI app builders (Lovable, Base44,
   Replit, Bolt, v0 and similar), a project secret, and FillFaster is called from a backend or
   server function. Never put it in browser code. When you run requests yourself, read it from
   the environment (`Authorization: Bearer $FILLFASTER_API_TOKEN`) and never print it.
5. **Inspect the template before planning.** Ask the user for the link to the template and
   extract the `fid` yourself:
   - Share link: `https://fillfaster.com/fill/<fid>` (also on a customer's custom domain,
     `https://<their-domain>/fill/<fid>`). The `fid` is the path segment after `/fill/`.
   - Form builder link: `https://fillfaster.com/form-builder?edit=<fid>`. The `fid` is the
     `edit` query value.
   - A link with `/fills/<sid>/<token>` is one signer's personal submission link, not a
     template. Ask for the template link instead.

   Then get the fields, using the first option that works in your environment. Do not stop
   if one is not available:
   - **You can run commands or HTTP requests** (Claude Code, Codex CLI, Gemini CLI, Cursor or
     Windsurf agent mode): call **get form fields** (`getFormFields`) with the `fid` yourself.
     Today it needs only the `fid`, no token. To let the user pick from all templates instead,
     call **list templates** (`getFormsList`), which needs the token from the environment.
   - **You cannot send requests from the chat** (most AI app builders): give the user a
     ready `curl` command for `getFormFields` with their `fid` filled in (build it from
     OpenAPI), ask them to run it and paste the output. The field list is not secret.
   - **No access at all yet:** continue to the plan and code with clearly marked placeholder
     field names, list what is missing, and add a small script to the project that prints the
     template's fields so the user can fill the gaps later.

   Show the user a short table of the fields (name, label, type) and ask where each value
   comes from: their database, a form in their app, or left for the recipient to fill.
   How to read the response today:
   - `name` is the key to use in `prefill_data`. `label` is the human name.
   - `required: true` means a **hidden** field the recipient cannot see or fill, so your
     integration must send it in `prefill_data`. `required: false` does not mean optional for
     the recipient; it means the recipient can fill it, and you may prefill it. Table fields
     always return `required: true`.
   - `validation_type` tells the kind of value (email, tel, date, select, checkbox, file,
     table and more). Tables also return `headers` (the column names).
   - Signature, company stamp and today's-date fields are not listed: the signer completes them.
   - Templates with 2 or more signers also return `roles` (each with `role_id`, `name`,
     `order` and its own `fields`) and `signing_order`. Ask who each signer is in the user's
     flow. See **Templates with multiple signers** below.
6. **Show a short plan before writing code:** which operations (by `operationId` from
   OpenAPI), which webhook events, where the token lives, and what the user still has to do.
   Wait for the user to approve it.
7. **Build, then test with one real template.** Confirm the result with the user, for example
   that the new submission shows in the dashboard with the recipient name.

## What FillFaster is

**FillFaster** is a **PDF form automation** product: template forms, **submission links** for recipients, signatures and data collection, **filled PDF** output, and automation via integrations (e.g. Make.com, monday.com) plus a **REST API** for your own software.

## Machine-readable contract (required)

- **OpenAPI 3 (canonical):** `https://help.fillfaster.com/fillfaster-openapi.json`
- **Rules:** Do **not** invent paths, query names, JSON fields, or enums. Resolve **operationId**, **tags**, **components.schemas**, and **servers** from that document (or from a checked-out copy of the same file).
- **Authentication:** Use the **security schemes** defined in the OpenAPI file (API token / Bearer as documented there). End-user documentation for creating tokens: `https://help.fillfaster.com/developers/create-api-token/` (human-oriented).

## Bundled references (optional)

For a compact OpenAPI reminder, read [references/openapi-contract.md](references/openapi-contract.md).

## Never do

- Do **not** invent API paths, query parameters, JSON field names, or enum
  values. Every name must be resolved from the OpenAPI document.
- Do **not** construct the base API URL from memory — always read the `servers`
  field in the OpenAPI JSON.
- Do **not** store the API token in client-side code, public repositories, or
  logs. Treat it as a password.
- Do **not** poll submission status in a tight loop — use webhooks. If webhooks
  are unavailable, apply exponential backoff and stop at terminal states.
- Do **not** omit `user_data.recipient_name` from a create-submission payload
  for a single-signer template. See **Create submission defaults** below.
- Do **not** create a submission for a template with 2 or more signers without
  a `recipients` array. See **Templates with multiple signers** below.

## Human-friendly exploration (optional)

- **AI agents overview (help center):** `https://help.fillfaster.com/developers/ai-agents/`
- **Interactive API reference (Scalar):** `https://help.fillfaster.com/developers/api/`
- **Help center API guides:** `https://help.fillfaster.com/developers/`
- **Webhooks guide:** `https://help.fillfaster.com/developers/webhooks/`
- **Multiple signers (API section):** `https://help.fillfaster.com/form-builder/multiple-signers/#send-to-multiple-signers-via-api`

## Integration preference: webhooks over polling

**Prefer webhooks** for submission lifecycle and completion: subscribe per **form** (see OpenAPI and the webhooks guide), expose a **reachable HTTPS endpoint**, validate and process push payloads, then **fetch the submission PDF** (or next step) when the webhook indicates the right state.

Use **polling** (e.g. repeated **get submission status** - exact name in OpenAPI) **only when webhooks are not viable** (no stable public URL, short-lived prototypes, or strict firewall rules). If you poll, use **sensible backoff** and stop at terminal states documented in the spec.

## Create submission defaults

On **Create a submission** (`POST /v1/createSubmission`) and **bulk create**, always send `user_data.recipient_name`. It is optional in the OpenAPI schema. Treat it as a **default field** on every payload you generate.

- The dashboard Submissions list and Search show this value as the recipient name. A name inside `prefill_data` does **not** fill that column.
- Omit it only when you truly do not know who the link is for. An empty dashboard name is the usual result, and it is what customers report as "the API submission has no recipient."
- `recipient_email` stays optional. Set it only when FillFaster should email the signing link. If you set `recipient_email`, `recipient_name` is required.
- Other `user_data` keys (`uid`, `itemId`, and your own ids) are still optional metadata echoed on webhooks.

Default body (add prefill and other optional fields from OpenAPI as needed):

```json
{
  "fid": "<form template id from OpenAPI / list templates>",
  "user_data": {
    "recipient_name": "<person this link is for>"
  }
}
```

## Templates with multiple signers (signature round)

A template can have 2 or more signers (roles), for example "Client" and "Company". Each signer gets a personal link and fills only their own fields. Full guide with examples: `https://help.fillfaster.com/form-builder/multiple-signers/#send-to-multiple-signers-via-api`

1. **Detect it:** **list templates** returns `roles_count` per template, and **get form fields** returns `roles` (each with `role_id`, `name`, `order` and its own `fields`) when the template has 2 or more signers. Single-signer templates return only `fields`, as before.
2. **Create submission:** send `recipients` with exactly one entry per role: `{ role_id, name, email, phone?, prefill_data? }`. A valid email is required for each signer.
3. **Prefill per signer:** values for a signer's fields go in that recipient's `prefill_data`, keyed by the field names from that role's `fields`. Top-level `prefill_data` is only for the template-level `fields` (filled when sending). Unknown names return `400` with the valid names.
4. **No `user_data.recipient_name` needed:** the signers' names come from `recipients`. Emails to the signers are always sent, so `send_email` is not needed.
5. **No public template link:** these templates can only be opened from the personal links. The create response returns `recipients` with each personal `link`.
6. **Track progress (webhooks first):** `recipient_completed` fires after each signer and includes `pending_recipients` with the personal links of who still has to sign. `submitted` fires once, after the last signer. For polling, **get submission activity** returns the signers, progress and full timeline.

Minimal body (verify names in OpenAPI):

```json
{
  "fid": "<form template id>",
  "recipients": [
    { "role_id": "r1", "name": "Dana Levi", "email": "dana@example.com", "prefill_data": { "Full name": "Dana Levi" } },
    { "role_id": "r2", "name": "Avi Cohen", "email": "avi@example.com" }
  ]
}
```

## Primary workflows (conceptual - verify in OpenAPI)

1. **Discover → configure → subscribe → submit → react → download**
   Identify the form → load field identifiers for prefill → **subscribe webhooks** for that form → **create submission** (recipient flow) → on **webhook delivery**, validate payload → **get submission PDF** (or other follow-up calls) when the event implies completion. Use polling only as a fallback (see above).

2. **Server-side PDF**
   With a known form id and **prefill** payload, call the **generate PDF** operation defined in OpenAPI; handle **binary PDF** responses vs documented errors, quotas, and permissions. (Typically synchronous; webhooks are less central here unless your flow chains into submissions.)

3. **Webhook operations**
   Confirm **subscribe** / **unsubscribe** paths, headers, and body fields in OpenAPI; align your handler with documented event types and retries/idempotency expectations from the help article.

## Example integration sequences (still verify in OpenAPI)

- **Single signer with link (webhook-first):** resolve **form** → **get form fields** → **subscribe webhook** → **create submission** with `user_data.recipient_name` → hand off submission URL → on **webhook** for completion (or equivalent event), **get submission PDF** - **avoid** tight polling loops unless webhooks are unavailable.
- **Bulk invites:** same field preparation and **webhook subscription** on the form → **bulk create submissions** or repeated **create submission**, each with its own `user_data.recipient_name` → correlate **submission id** from create responses with incoming **webhook** payloads → fetch PDFs when webhooks fire; poll status sparingly if a webhook is missed.
- **Several signers (signature round):** resolve **form** → **get form fields** (read `roles`) → **subscribe webhook** for `recipient_completed` and `submitted` → **create submission** with one `recipients` entry per role → on `submitted`, **get submission PDF**.
- **Headless document only:** align `prefill_data` with **get form fields** / schemas → **generate PDF** → stream or store the returned PDF bytes.

## Related

- **Interactive reference (Scalar):** `https://help.fillfaster.com/developers/api/`
- **Developer guides on this site:** `https://help.fillfaster.com/developers/`

When in doubt, **re-fetch** `https://help.fillfaster.com/fillfaster-openapi.json` and base your integration on the current version field and paths in that file.
