Flat forms

Most real-world administrative forms have no interactive fields: they are flat PDFs with dotted lines (Name: .............) and box glyphs to tick. pdfforge turns those into virtual fields — the same inspect/fill API as AcroForm works on paper-style forms.

How detection works

When POST /v1/pdf/form/inspect finds no AcroForm (form_type: "none"), the virtual detector kicks in:

• Dotted runs (....., ………) become text fields. The exact geometry of each leader line is measured, so the fill writes precisely on the line.
• Box glyphs (checkbox characters) become checkbox fields.
• Consecutive dotted lines belonging to one label (a multi-line "description" area) are grouped into a single field with continuation lines.

{
  "form_type": "virtual",
  "fields": [
    {
      "name": "nom_et_prenom",
      "label": "Nom et Prénom / raison sociale",
      "type": "text",
      "page": 1,
      "rect": { "x": 182.3, "y": 214.6, "w": 310.2, "h": 14.0,
                "page_w": 595.0, "page_h": 842.0 },
      "font": "times",
      "size": 11
    },
    { "name": "abonne", "type": "checkbox", "page": 1, "rect": { ... } }
  ]
}

Virtual fields carry extras that native fields do not:

Fill a flat form

Same endpoint as native forms — POST /v1/pdf/form/fill. The API inspects the PDF internally and routes flat documents to the virtual fill: text is burned onto the dotted lines, checked boxes get a check stroke.

PDF=$(base64 -w0 flat-form.pdf)

curl -X POST https://api.pdf-forge.dev/v1/pdf/form/fill \
  -H "Authorization: Bearer $PDFFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"pdf\": \"$PDF\",
    \"values\": { \"nom_et_prenom\": \"SAM SARL\", \"abonne\": true }
  }" \
  --output filled.pdf

Zones the detector missed

You can pass extra fields — zones traced by a user (or your code) that the detector did not find. They use the same FormField shape as inspect returns (name, type, page, rect):

{
  "pdf": "<base64>",
  "values": { "reference": "BF-2026-0099" },
  "fields": [
    { "name": "reference", "type": "text", "page": 1,
      "rect": { "x": 300, "y": 700, "w": 150, "h": 14,
                "page_w": 595, "page_h": 842 } }
  ]
}

Next steps

• Fill via API — the end-to-end script, native and virtual.
• AcroForm forms — when the PDF has real fields.
• Import a PDF — recurring fills are better served by a template.