Developers

Une API pour lire et remplir les PDF.

Envoyez un formulaire, laissez iFillPDF détecter les champs et les personnes, puis poussez vos valeurs pour produire un PDF rempli. Même pipeline que l'éditeur, exposé proprement pour vos intégrations.

Démarrer MCP server OpenAPI JSON Créer une clé API

Fill resultv1

document_id:"a3f9c1…"

status:"completed"

schema.fields:18 detected

values.field_1:"Jean Dupont"

→ filled.pdf:signed url · 1h

Auth

Bearer key

Rate limit

0/min

Endpoints

Formats

PDF in, PDF out

Langage

Quickstart

Utilisez une clé API d’équipe, envoyez un PDF, et laissez l’endpoint synchrone renvoyer un schéma. Pour les fichiers plus lourds ou les flux type interface, passez par le pending upload puis le flux document asynchrone.

curl -s -X POST https://www.ifillpdf.com/api/v1/documents/analyze \
  -H "Authorization: Bearer ifk_live_..." \
  -F "pdf=@cerfa.pdf" \
  -F "description=Déclaration fiscale avec déclarant et conjoint" \
  -F 'suggested_entities=[{"id":"declarant","label":"Déclarant","color":"#6D7BFF"}]'

Authentification

Chaque endpoint v1 accepte Authorization: Bearer ifk_live_…. Les clés API sont à l’échelle de l’équipe. L’application web peut aussi appeler ces endpoints via son cookie de session Supabase, mais les intégrations externes doivent utiliser l’auth Bearer uniquement.

Authorization: Bearer ifk_live_...

Flux d’analyse asynchrone

La route asynchrone répond immédiatement avec status: analyzing. Interrogez le document jusqu’à ce que status passe à completed ou failed.

PID=$(curl -s -X POST https://www.ifillpdf.com/api/pending-uploads \
  -F "pdf=@document.pdf" | jq -r '.id')

DOC=$(curl -s -X POST https://www.ifillpdf.com/api/v1/documents \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d "{\"pending_upload_id\":\"$PID\",\"name\":\"Contrat client\"}" | jq -r '.document_id')

curl -s https://www.ifillpdf.com/api/v1/documents/$DOC \
  -H "Authorization: Bearer ifk_live_..."

Référence des endpoints

Chaque endpoint inclut ses paramètres, la forme de la requête, les réponses courantes, et un exemple curl / JS / Python. Le contrat complet lisible par machine est aussi disponible sur /openapi.json.

GET/api/v1/documents

List documents+

Paginated document list with q, status, limit, cursor, and include_voided filters.

Parameters

limitquery1-100, default 20

cursorqueryCursor returned as next_cursor

qquerySearch by document name

statusqueryanalyzing, completed, failed, draft, filling, …

include_voidedquerytrue or false

Request body

None.

Responses

200{ documents: DocumentSummary[], next_cursor: string | null }

Example

curl -s "https://www.ifillpdf.com/api/v1/documents?limit=20&status=completed" \
  -H "Authorization: Bearer ifk_live_..."

POST/api/v1/documents

Create async analysis+

Uploads or claims a PDF, debits quota, prepares page images, starts semantic analysis, then returns 202 for polling.

Parameters

No parameters.

Request body

multipart/form-data with pdf, name, description, suggested_entities; or JSON with pending_upload_id or pdf_url.

Responses

202{ document_id, status: "analyzing", page_count, quota, … }

Example

PID=$(curl -s -X POST https://www.ifillpdf.com/api/pending-uploads \
  -F "pdf=@document.pdf" | jq -r '.id')

DOC=$(curl -s -X POST https://www.ifillpdf.com/api/v1/documents \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d "{\"pending_upload_id\":\"$PID\",\"name\":\"Contrat client\"}" | jq -r '.document_id')

curl -s https://www.ifillpdf.com/api/v1/documents/$DOC \
  -H "Authorization: Bearer ifk_live_..."

POST/api/v1/documents/analyze

Create sync analysis+

Runs analysis inline and returns the final schema. Best for short PDFs.

Parameters

No parameters.

Request body

Same inputs as POST /api/v1/documents.

Responses

200{ document_id, page_count, schema, quota, … }

Example

curl -s -X POST https://www.ifillpdf.com/api/v1/documents/analyze \
  -H "Authorization: Bearer ifk_live_..." \
  -F "pdf=@cerfa.pdf" \
  -F "description=Déclaration fiscale avec déclarant et conjoint" \
  -F 'suggested_entities=[{"id":"declarant","label":"Déclarant","color":"#6D7BFF"}]'

GET/api/v1/documents/{id}

Get document+

Returns status, schema, entities, field list, values, preview metadata, and errors.

Parameters

idpathDocument UUID

Request body

None.

Responses

200Document with schema and values

404Document not found in the authenticated team

410Document is voided

Example

curl -s "https://www.ifillpdf.com/api/v1/documents/$DOC" \
  -H "Authorization: Bearer ifk_live_..."

PATCH/api/v1/documents/{id}

Update document+

Renames a document, updates description/entity hints, or patches field values.

Parameters

idpathDocument UUID

Request body

JSON with name, description, user_context, suggested_entities, and/or values keyed by schema field id.

Responses

200Updated document

400Invalid name, context, entity hints, or values

410Document is voided

Example

curl -s -X PATCH "https://www.ifillpdf.com/api/v1/documents/$DOC" \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Contrat signé","values":{"field_1":"Jean Dupont"}}'

DELETE/api/v1/documents/{id}

Delete document+

Soft-deletes the document by moving it to state voided.

Parameters

idpathDocument UUID

Request body

None.

Responses

200{ ok: true, document_id, state: "voided" }

Example

curl -s -X DELETE "https://www.ifillpdf.com/api/v1/documents/$DOC" \
  -H "Authorization: Bearer ifk_live_..."

POST/api/v1/documents/{id}/reanalyze

Reanalyze+

Reruns page rendering and AI semantic labeling with the persisted user context.

Parameters

idpathDocument UUID

Request body

None.

Responses

202Re-analysis started

200Analysis was already running

402Page quota exhausted

Example

curl -s -X POST "https://www.ifillpdf.com/api/v1/documents/$DOC/reanalyze" \
  -H "Authorization: Bearer ifk_live_..."

POST/api/v1/documents/{id}/fill

Fill PDF+

Applies values and streams the PDF, or returns a signed URL with ?format=url.

Parameters

idpathDocument UUID

formatquerypdf or url

Request body

JSON with values keyed by schema field id. Signatures can be { dataUrl }. watermark can force watermarking.

Responses

200application/pdf binary by default

200{ url, expires_in, filled, failed } when format=url

409Schema is not ready

Example

curl -s -X POST "https://www.ifillpdf.com/api/v1/documents/$DOC/fill?format=pdf" \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"values":{"field_1":"Jean Dupont","checkbox_2":true}}' \
  -o filled.pdf

POST/api/v1/uploads

Request signed upload+

Returns a one-time signed PUT URL so you can upload PDFs up to 25 MB directly, bypassing the function body limit.

Parameters

No parameters.

Request body

JSON with fileName (must end with .pdf), sizeBytes, and optional contentType (defaults to application/pdf).

Responses

200{ id, upload_url, token, storage_path, expires_at, max_bytes }

413PDF exceeds the maximum stored size

415fileName not .pdf or contentType not application/pdf

Example

# 1. request a signed URL
curl -s -X POST https://www.ifillpdf.com/api/v1/uploads \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"fileName":"contrat.pdf","sizeBytes":1840221}'

# 2. PUT the bytes to upload_url, then analyze with pending_upload_id
curl -X PUT "<upload_url>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/pdf" \
  --data-binary @contrat.pdf

GET/api/v1/templates

List templates+

Lists public-library templates (scope=public) or your own team/private templates (scope=mine). Cursor-paginated.

Parameters

scopequerypublic (default) or mine

categoryqueryFilter by category

languagequeryFilter by language code, e.g. fr

qquerySearch by template name

limitquery1-100, default 24

cursorqueryCursor returned as next_cursor

Request body

None.

Responses

200{ templates: Template[], next_cursor: string | null }

Example

curl -s "https://www.ifillpdf.com/api/v1/templates?scope=public&q=cerfa" \
  -H "Authorization: Bearer ifk_live_..."

POST/api/v1/templates

Create template+

Snapshots an analyzed document into a reusable template. Regular keys can create private or team templates only.

Parameters

No parameters.

Request body

JSON with source_document_id (required) plus optional name, description, category, tags[], language, visibility.

Responses

201{ template }

400Missing source_document_id

429Rate limit exceeded (60/min)

Example

curl -s -X POST "https://www.ifillpdf.com/api/v1/templates" \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"source_document_id":"$DOC","name":"Bail meublé","visibility":"team"}'

GET/api/v1/templates/{id}

Get template+

Returns a single template with its field and party structure. Never returns pre-filled defaults or values.

Parameters

idpathTemplate UUID

Request body

None.

Responses

200{ template } with fields and parties

404Not found or not visible to the caller

Example

curl -s "https://www.ifillpdf.com/api/v1/templates/$TPL" \
  -H "Authorization: Bearer ifk_live_..."

PATCH/api/v1/templates/{id}

Update template+

Updates your own template metadata and visibility. Only the creator can edit. Public publishing stays admin-only.

Parameters

idpathTemplate UUID

Request body

JSON with any of name, description, category, tags[], language, visibility (private | team).

Responses

200{ template }

403Not the creator, or visibility set to public

409Update rejected (e.g. team to private downgrade is frozen)

Example

curl -s -X PATCH "https://www.ifillpdf.com/api/v1/templates/$TPL" \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Bail meublé 2026","visibility":"private"}'

DELETE/api/v1/templates/{id}

Delete template+

Permanently deletes your own template and its stored assets. Documents created from it are unaffected.

Parameters

idpathTemplate UUID

Request body

None.

Responses

200{ deleted: true, id }

403Not the creator

Example

curl -s -X DELETE "https://www.ifillpdf.com/api/v1/templates/$TPL" \
  -H "Authorization: Bearer ifk_live_..."

POST/api/v1/templates/{id}/use

Use template+

Instantiates a template into a new working document pre-filled with its frozen defaults. FREE — does not debit the page quota.

Parameters

idpathTemplate UUID

Request body

None.

Responses

201{ document_id, status: "filling" }

429Too many duplications (30/min per team)

Example

curl -s -X POST "https://www.ifillpdf.com/api/v1/templates/$TPL/use" \
  -H "Authorization: Bearer ifk_live_..."

GET/api/v1/templates/by-slug/{slug}

Resolve template by slug+

Public, no auth. Resolves a marketplace slug to the published public template that backs it, when a real fillable PDF exists.

Parameters

slugpathMarketplace slug, e.g. cerfa-2042

Request body

None.

Responses

200{ template }

404No published public template with a real PDF for this slug

Example

curl -s "https://www.ifillpdf.com/api/v1/templates/by-slug/cerfa-2042"

POST/api/v1/vault/documents

Add to vault+

Uploads a personal ID or financial document (payslip, RIB, KBIS, passport) to the per-user vault for later pre-filling.

Parameters

No parameters.

Request body

JSON with file_base64, file_name, mime_type (pdf/jpeg/png/webp/heic) and optional label.

Responses

200{ document }

413File exceeds the vault size limit

429Rate limit exceeded (30/min)

Example

curl -s -X POST "https://www.ifillpdf.com/api/v1/vault/documents" \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"file_base64":"JVBERi0...","file_name":"rib.pdf","mime_type":"application/pdf","label":"RIB perso"}'

Modèles

Snapshotez un document analysé en modèle (POST /api/v1/templates), puis instanciez-le avec POST /api/v1/templates/{id}/use — gratuit, sans débit de quota.

MCP server

Chaque endpoint est aussi exposé en Model Context Protocol pour les agents IA (Claude, ChatGPT, Cursor).

12 outils, setup et scopes sur la page MCP server.

Schéma et valeurs du document

Le schéma d’analyse est volontairement simple : chaque champ a un id stable, une bounding box, un index de page et un rattachement à une entité. Utilisez ces ids comme clés pour patcher les valeurs ou remplir le PDF.

statusanalyzing | completed | failed

schema.fieldschamps détectés, avec les ids utilisés par values

schema.partiesentités telles que Déclarant, Conjoint, Hébergeur

valuesvaleurs persistées : texte, case à cocher, nombre, signature

preview_image_urlaperçu de la première page rendue quand disponible

curl -s -X POST "https://www.ifillpdf.com/api/v1/documents/$DOC/fill?format=pdf" \
  -H "Authorization: Bearer ifk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"values":{"field_1":"Jean Dupont","checkbox_2":true}}' \
  -o filled.pdf

Erreurs et limites

400

JSON mal formé, curseur invalide, patch de valeur invalide, PDF manquant.

401

Token Bearer manquant ou invalide.

402

Quota de pages épuisé pour l’équipe.

403

Non créateur de la ressource, ou tentative de publier un modèle en public.

404

Ressource introuvable dans l’équipe authentifiée, ou non visible.

409

Schéma non prêt, chemin PDF manquant, ou mise à jour de modèle rejetée.

410

Document supprimé (état voided).

413

PDF ou fichier coffre dépassant la taille acceptée.

415

fileName d’upload non .pdf, ou contentType ≠ application/pdf.

429

Limite de débit dépassée. Start/fill : 60/min. Analyze/reanalyze/vault : 30/min.