add_field
ChatGPTCreate a new fillable field on a page when detection missed an input (false negative). Coordinates (x, y, w, h) are in percentages of page width/height (0.0–100.0, top-left origin), read off render_preview. Assigns a sequential agent field ID (p{page_index}_a{n}) with confidence=1.0 and source="agent", and returns the created field object. Allowed field_type values: 'text' (default), 'number', 'date', 'checkbox', 'radio', 'signature', 'dropdown', 'field', or 'cell'. Optional align ('left', 'center', 'right') and vertical_align ('top', 'middle', 'bottom') control where text sits inside the box. Persistence & review impact: persists immediately in the active workspace (workspace_id) and invalidates any prior visual review receipt for page_index on ML-detected layouts. Does not alter saved account templates unless save_template is called after filling. When to use: - Use add_field only to create a missing field that detection missed. - Use update_field (single) or update_fields (batch) to move, resize, rename, or change the type/alignment of an existing field. - Use remove_field or remove_fields to delete false-positive fields.
close_workspace
ChatGPTDelete one temporary workspace and its stored PDF and preview files when work is finished. Deletes the temporary workspace record (workspace_id), its uploaded source PDF, any rendered preview images (preview_url), and any generated output PDF (download_url) before the automatic 24-hour TTL expiration. This does not delete saved templates created with save_template or files the user has already downloaded. The operation is idempotent (already_closed=True when already gone), so cleanup code may safely call it in `finally. When to use: - Call close_workspace only after the user has received or downloaded the filled PDF from fill_pdf (and after calling save_template, if saving the layout), because closing immediately invalidates download_url and preview_url` links.
fill_pdf
ChatGPTFill the PDF and return a download link (valid until the workspace expires). values maps field id -> text (checkboxes: "yes"/"x"/"true" to tick). flatten=False preserves existing form fields; it does not create fields on scans. fillable=True creates interactive fields (subject to the account's existing export entitlement) and takes precedence over flatten. editable, editable_widget_count and output_type describe the actual PDF. editable means at least one form widget is writable, not that all values are. warnings lists text printed too small or cut off (with flatten=True render_filled_preview reports them beforehand; with flatten=False editable widgets are not measured). output_mode "watermarked" means the result contains a JustFill watermark. A clean final output may consume one of the account's existing fill entitlements; when none is available, the result is watermarked. Visual review gate & workflow routing: - For ML-detected layouts (source="ml"), fill_pdf requires prior render_preview and render_filled_preview calls (with matching values, flatten, and fillable flags) on every populated page; otherwise it returns required_calls without generating the PDF. - Use render_filled_preview first to verify placement and text fit at no cost; call fill_pdf only when ready to generate the downloadable PDF. - Do not call close_workspace until the user has downloaded the file from download_url.
list_fields
ChatGPTList the current working fields and workspace summary for an open PDF workspace. Returns {"summary": ..., "fields": [...]} for workspace_id, reflecting any in-workspace edits made via add_field, update_field, update_fields, remove_field, remove_fields, or prune_fields. Each field entry includes id, name, type, page_index (0-based), bounding-box percentages (x, y, w, h), confidence, source ('template', 'acroform', 'ml', or 'agent'), and needs_name_review. Filtering: pass a 0-based page_index to return only the fields on that single page, or omit page_index (pass None) to list fields across all pages in the workspace. When to use: - Use list_fields to inspect current field IDs, coordinates, or labels in an already-open workspace (for example, after editing fields or narrowing to one page) without re-running detection. - Use open_pdf to load a document for the first time and create a workspace. - Use list_templates to list saved, reusable account-level templates rather than the fields of an active workspace.
list_templates
ChatGPTList saved, reusable form templates on the authenticated JustFill account. Ordering & limit behavior: returns up to limit (default 50) saved calibration templates for the authenticated account, ordered from most recently updated to oldest, as templates (name, document_id, and fields count). Does not require an open workspace. When to use: - Use list_templates to inspect which reusable document templates are already saved on the user's account (via save_template or the web editor). - Do not confuse with list_fields, which lists the individual fillable form fields (id, name, x, y, w, h) of a currently open workspace_id.
open_pdf
ChatGPTOpen a PDF (or an image of a form: JPG/PNG/TIFF) and detect its fields. The document comes from exactly ONE of: - file: a PDF/image the user attached in the chat, for clients that provide file parameters (no upload needed). A file without a download_url cannot be fetched; an upload_token covers that case, - url: a public link to the document, - upload_token: from request_file_upload, for files on the user's device or chat attachments that file cannot carry, - file_base64: exact bytes of a small file (< ~200 KB). Larger base64 passed through a model gets truncated, and a compressed or rebuilt file breaks field detection and no longer matches its template. Resolution order: saved template (deterministic) -> embedded AcroForm -> ML detection with per-field confidence. force_detect=True skips templates. ML detection scans only the first max_pages pages; for a longer document the result lists unprocessed_page_indices, which another open_pdf call with a larger max_pages scans. Returns a 24-hour workspace_id (summary.workspace_id), which every subsequent workspace tool takes. When to use: - Call open_pdf once to load a document and initialize a workspace (or call it again with a larger max_pages or force_detect=True). - Use list_fields to re-read fields in an already-open workspace without re-running detection, or list_templates to browse saved account templates.
prune_fields
ChatGPTBulk-delete fields matching ALL given criteria (detection noise) in the active workspace. Filter & guardrail semantics: permanently deletes every field in workspace_id that satisfies all non-None filter criteria (field_type, confidence_below, width_below, height_below, page_index). At least one criterion must be provided — omitting all five criteria (None) is rejected with {"error": ...} to prevent accidentally deleting all fields. Thresholds (confidence_below, width_below, height_below) are strictly-less-than (<); width_below and height_below are in % of page width/height (0.0–100.0). Pass exclude_ids as a guardrail allowlist of field_ids that must be preserved even when they match the criteria. Returns {"removed": <count>, "removed_ids": [...], "fields_remaining": <count>} so deletions are auditable (and reversible via add_field). Does not affect saved templates unless save_template is called. When to use: - Use prune_fields for rule-based bulk cleanup of detection noise (e.g. tiny table cells or low-confidence boxes). - Use remove_fields to delete an explicit list of known field_ids, or remove_field to delete a single field by ID.
remove_field
ChatGPTPermanently delete a single false-positive field from the active workspace by its field_id. Permanence & unknown-id behavior: immediately removes field_id from workspace_id and returns {"removed": 1, "fields_remaining": <count>} (or {"removed": 0, "fields_remaining": <count>, "unknown_field_ids": [field_id]} if field_id is not found). Deletion is permanent within the active workspace — to restore a deleted field, re-add it with add_field or re-open the document with open_pdf. Saved account templates are unaffected unless save_template is called afterward. When to use: - Use remove_field to delete one specific false-positive field box (e.g. a stray box over printed text). - Use remove_fields to delete 2 or more known field_ids in a single batch call. - Use prune_fields for rule-based bulk filtering by confidence_below, width_below, height_below, field_type, or page_index.
remove_fields
ChatGPTPermanently delete multiple fields by ID from the active workspace in a single batch mutation. ID-list, partial-failure & persistence semantics: deduplicates field_ids, deletes every matching field from workspace_id, and commits the updated workspace state immediately. Returns {"removed": <count>, "fields_remaining": <count>}. Any ID in field_ids that does not exist in the workspace is ignored during deletion and reported in sorted unknown_field_ids while all valid IDs in the batch are still removed (no error is raised for unknown IDs). Deletion is irreversible within the active workspace — removed fields can only be recovered via add_field or a fresh open_pdf call, and saved account templates are not altered unless save_template is called afterward. When to use: - Use remove_fields when deleting an explicit list of 2 or more known false-positive field_ids at once. - Use remove_field when deleting a single field_id. - Use prune_fields for criteria-based bulk removal by confidence_below, width_below, height_below, field_type, or page_index instead of listing individual IDs.
render_filled_preview
ChatGPTPreview how the filled page will look before fill_pdf. Costs nothing. values maps field id -> text (checkboxes tick on "yes"/"x"/"true"). Text placement, size and wrapping come from the same code as the export, with the same flatten/fillable flags as fill_pdf. Not simulated: a watermark or an account limit that stops fill_pdf. In the JSON, fit lists values that were shrunk or cut and warnings what to fix first. preview_url links to the same image; some clients (e.g. ChatGPT) do not display tool images, so there the user sees the page only through preview_url. Restricted data (payment cards, PHI, government ids, or authentication secrets) is not accepted by this public plugin. When to use: - Use render_filled_preview to verify text placement, alignment, and font sizing on each populated page at no cost before calling fill_pdf (required for every populated page on ML-detected layouts). - Use render_preview to inspect empty field bounding boxes and field_id labels without values. - Use fill_pdf once visual review is complete to generate the downloadable filled PDF.
render_preview
ChatGPTRender a page with the field boxes drawn on it, to verify placement. Blue = deterministic (template/AcroForm/agent), green/orange/red = ML confidence bands (>= 0.7, 0.4–0.7, < 0.4). Labels show field ids. The result has the image and a preview_url link to the same image; some clients (e.g. ChatGPT) do not display tool images, so there the user sees the page only through preview_url. Also records the field-layout visual review receipt for page_index required before fill_pdf or save_template on ML-detected layouts. When to use: - Use render_preview to inspect empty field box positions, IDs, false positives, and missed inputs before filling or after modifying geometry with add_field, update_field, update_fields, remove_field, remove_fields, or prune_fields. - Use render_filled_preview instead to see actual field values typeset inside those boxes and check for text overflow before calling fill_pdf.
request_file_upload
ChatGPTCreate a one-time upload slot for a PDF (or form photo) when direct file input is unavailable. For a document on the user's device, or a chat attachment that open_pdf's file parameter cannot carry (the tool call does not accept a file, or the file arrives without a download_url); tool arguments cannot carry file bytes reliably. Documents with payment-card data, PHI, government identifiers, passwords, API keys/tokens, or MFA/OTP codes are not accepted. Returns upload_url, a page where the user opens and drops the file (one click); post_url, which accepts the file as a multipart POST (curl -sf -F "file=@document.pdf" <post_url>) for headless runtimes with network access to justfill.app (n8n, a server shell; chat sandboxes usually have none); and upload_token for open_pdf. A base64 copy or a shrunk file is no substitute: modified bytes break detection. The slot is single-use and expires in 30 minutes. When to use: - Use open_pdf(file=...) directly if the client passes a chat attachment with a download_url, or open_pdf(url=...) if the file is at a public HTTP/HTTPS link. - Call request_file_upload only as a fallback when neither file nor url can deliver the original document, then pass the returned upload_token to open_pdf(upload_token=...).
save_template
ChatGPTPersist the reviewed field layout: a future open_pdf of this exact file returns these fields with confidence 1.0 and no ML pass. Field names (set with update_fields name=..., e.g. 'age_score', 'total_abcd2') are stored in the template, so later sessions map values by meaning instead of by coordinates. False positives present at save time are stored too, so remove them first with remove_fields or prune_fields. For ML-detected layouts, every page with fields must be reviewed via render_preview before saving. When to use: - Call save_template after filling (only when the user confirms) to persist in-workspace field edits (add_field, update_field, remove_field) across future sessions for the same blank PDF. - Use list_templates to view existing saved templates on the account.
update_field
ChatGPTModify an existing field's position, size, semantic name, type, or alignment in the active workspace. Overwrite/merge behavior: performs a partial update (patch) on field_id in workspace_id. Only the optional parameters explicitly provided with non-None values (x, y, w, h, name, field_type, align, vertical_align) overwrite the field's attributes; omitted or None parameters keep their existing values unchanged. Editing an ML-detected field (source="ml") promotes it to source="agent" with confidence=1.0. Returns the updated field dict, or {"error": ...} if field_id is not found in the workspace. Persistence & review impact: changes persist immediately in the active workspace (workspace_id), invalidate the page's visual review receipt when geometry (x, y, w, h) changes, and do not affect saved account templates unless save_template is called. When to use: - Use update_field when modifying a single existing field. - Use update_fields for batch updates across 2 or more fields in one call (e.g. assigning semantic names before save_template). - Use add_field to create a missing field, or remove_field to delete a false-positive field.
update_fields
ChatGPTBatch-update multiple existing fields in the active workspace in a single call. Each item in updates is {"field_id": ..., x?, y?, w?, h?, name?, field_type?, align?, vertical_align?}. Only keys provided with non-None values overwrite the target field's attributes; omitted keys keep their existing values, and edited ML fields (source="ml") are promoted to source="agent" (confidence=1.0). Partial-failure & persistence semantics: unknown field_ids are skipped and reported in unknown_field_ids while all valid updates in the batch are applied and listed in updated. However, an invalid field_type, align, or vertical_align raises an error and aborts the entire batch without saving partial edits. Changes persist immediately in workspace_id without affecting saved templates unless save_template is called. When to use: - Prefer update_fields over repeated update_field calls whenever renaming, repositioning, or resizing 2 or more fields at once. - Use update_field for a single field, or add_field to create new fields.
