API reference

This page is generated from the API's OpenAPI document. Every example reads your key from $FENFILL_API_KEY; base URL, authentication, errors and limits are on the API overview. The live reference is at api.fenfill.com/v1/docs, and the OpenAPI document at api.fenfill.com/v1/openapi.json.

Analyze a blank PDF form into a fillable schema, or download a template as a fillable PDF.

Analyze a blank PDF form

Queue a blank PDF for analysis. Poll Location (GET /v1/jobs/{job_id}) until it is done. A PDF with native form fields costs nothing (unless detect_extra_blanks adds a vision pass); otherwise one page scan per analyzed page is reserved now and refunded if the job fails.

Request body: multipart/form-data.

Returns 202 with AnalyzeAccepted:

Errors (codes):

curl -X POST "https://api.fenfill.com/v1/forms/analyze" \  -H "Authorization: Bearer $FENFILL_API_KEY" \  -F "file=@blank-form.pdf" \  -F "save_as_template=true"

Download a template as a fillable PDF

A saved template's PDF with a fillable field on every blank, for any PDF reader. The fields are empty: this returns the blank form only and takes no values (fill it on your machine). Needs the Team plan or above. Shares the PDF download limits of GET /templates/{template_id}/pdf: past either, 429 with Retry-After.

Request body: application/json (AcroformExportRequest).

Returns 200 with application/pdf: The blank form with fillable fields, as an attachment.

Errors (codes):

# Needs the Team plan or above. Saves the blank form with fillable fields; no values are sent.curl -X POST "https://api.fenfill.com/v1/forms/acroform" \  -H "Authorization: Bearer $FENFILL_API_KEY" \  -H "Content-Type: application/json" \  -d '{"template_id": "<template id>"}' \  -o blank-form.pdf

Poll an analyze job and fetch its result.

Get an analyze job's status and result

Status while queued/running, with a polling hint: Retry-After: 10 while queued, 3 while running (so three jobs polled as told stay under the 60/min key limit). Once done, result is the agent schema. An unsaved result is kept 24 hours after the job finishes and 1 hour after its first fetch, then 410 (as is a saved one whose template was deleted).

Returns 200 with JobStatus:

Errors (codes):

curl "https://api.fenfill.com/v1/jobs/$JOB_ID" \  -H "Authorization: Bearer $FENFILL_API_KEY"

The workspace's templates: their agent schemas and blank PDFs.

List the workspace's templates

Active templates, newest first. Frozen templates and unfinished drafts (still awaiting the owner's AI/manual setup choice) are not listed.

Returns 200 with TemplateList:

Errors (codes):

curl "https://api.fenfill.com/v1/templates" \  -H "Authorization: Bearer $FENFILL_API_KEY"

Get a template's agent schema

The fillable inputs of a template, in reading order, as agent-schema v1. updated_at is the version to pass back when correcting it (PATCH).

Returns 200 with AgentSchema:

Errors (codes):

curl "https://api.fenfill.com/v1/templates/$TEMPLATE_ID" \  -H "Authorization: Bearer $FENFILL_API_KEY"

Correct a template's layout

Save corrections to a template's fields, groups and sections: send the whole edited v5 schema (as ?include=render returns it) with the updated_at it was based on. Only layout and the form's own wording are stored (labels, descriptions, placeholders, options), never fill values: an unknown or value-bearing key is refused. Page images, sizes and the page count stay as they are. If the template changed meanwhile, 409 template_conflict with current_updated_at: fetch it again and re-apply. 422 template_needs_migration when the stored template carries data from an older version that can't be saved back unchanged: make that edit in the web editor.

Request body: application/json (TemplateUpdate).

Returns 200 with TemplateUpdated:

Errors (codes):

# corrected-template.json: {"schema": <the edited v5 schema from ?include=render>, "expected_updated_at": "<updated_at from GET>"}curl -X PATCH "https://api.fenfill.com/v1/templates/$TEMPLATE_ID" \  -H "Authorization: Bearer $FENFILL_API_KEY" \  -H "Content-Type: application/json" \  -d @corrected-template.json

Download the blank template PDF

The template's blank PDF (decrypted server-side), for filling locally. Rate-limited per key per minute, and to a few at once across the service: past either, 429 with Retry-After.

Returns 200 with application/pdf: The blank template PDF.

Errors (codes):

curl "https://api.fenfill.com/v1/templates/$TEMPLATE_ID/pdf" \  -H "Authorization: Bearer $FENFILL_API_KEY" \  -o blank-form.pdf

Re-analyze pages of a saved template

Run AI again on chosen pages of a saved template, using the PDF already stored with it (nothing is uploaded). Analyze pages never analyzed (pages[].analyzed false on GET) with scratch; find adds missed blanks; relabel / label_missing fix labels. Poll Location (GET /v1/jobs/{id}) until done: the result is the updated template. One page scan per page is reserved now and refunded if the job fails (label_missing uses the monthly included label pages first). With estimate: true the price is returned (200) and nothing starts.

Request body: application/json (TemplateAnalyze).

Returns 200 with RerunEstimate (With estimate=true: the price; nothing is started.):

Returns 202 with AnalyzeAccepted:

Errors (codes):

curl -X POST "https://api.fenfill.com/v1/templates/$TEMPLATE_ID/analyze" \  -H "Authorization: Bearer $FENFILL_API_KEY" \  -H "Content-Type: application/json" \  -d '{"pages": "2", "kind": "find", "expected_updated_at": "<updated_at from GET>"}'

Per-recipient magic links on restricted templates.

Create a per-recipient link

A magic link for one recipient of a restricted template. The link's status moves pending → opened → completed as the recipient fills (no answers are ever sent back).

Request body: application/json (RecipientCreate).

Returns 201 with Recipient:

Errors (codes):

curl -X POST "https://api.fenfill.com/v1/templates/$TEMPLATE_ID/recipients" \  -H "Authorization: Bearer $FENFILL_API_KEY" \  -H "Content-Type: application/json" \  -d '{"label": "Anna K."}'

List a template's recipient links

The template's live (not revoked) recipient links, newest first, at most 500. Revoking happens in the fenfill app.

Returns 200 with RecipientList:

Errors (codes):

curl "https://api.fenfill.com/v1/templates/$TEMPLATE_ID/recipients" \  -H "Authorization: Bearer $FENFILL_API_KEY"

The workspace behind the API key: plan, limits and branding.

The workspace behind this key

Plan, remaining page scans, limits and branding flags. scans_remaining is the balance at the time of this request. max_pages is how far into a document the plan reads; max_pages_per_job is how many pages one AI analyze job may cover (split a longer document into several jobs with pages; a PDF with native form fields is read whole, up to max_pages).

No parameters.

Returns 200 with Account:

Errors (codes):

curl "https://api.fenfill.com/v1/account" \  -H "Authorization: Bearer $FENFILL_API_KEY"

The workspace's branding logo

The logo to stamp on filled PDFs; 404 when the plan has no custom branding or no logo is uploaded.

No parameters.

Returns 200 with image/png or image/jpeg: The logo image.

Errors (codes):

curl "https://api.fenfill.com/v1/account/logo" \  -H "Authorization: Bearer $FENFILL_API_KEY" \  -o logo