Form Metadata & Organization

Attach descriptions, instructions, tags, and training status to every form in your library

Overview

Every form record in Instafill.ai carries a metadata layer stored alongside its field definitions and workspaceId. This metadata — name, description, tags, instructions, and training status — is scoped to the workspace and is not shared with other workspaces, even when two workspaces hold the same form template identified by the same field-hash.

The field-hash that create_form() computes for deduplication is also part of the form record's metadata. This hash determines whether a newly uploaded PDF can be served from an existing entry in the catalog (avoiding re-extraction), and it also determines which forms benefit from shared AI fine-tuning. Workspace-specific metadata (description, tags, instructions) is layered on top of the shared structural record, so each workspace can customize how the form is labeled and documented without affecting other workspaces.

Key Capabilities

• Form Name and Description: Set a human-readable name and a plain-language description explaining what the form is, who fills it, and when it is used
• Filling Instructions: Write step-by-step guidance displayed to users during a fill session — e.g., "For box 24D on CMS-1500, enter the CPT procedure code without decimal points"
• FAQs per Form: Document common questions and answers attached to the form record — visible to all workspace members in the form detail view
• Tags: Apply free-form or predefined tags for categorization (e.g., "tax", "immigration", "hipaa", "employment") — tags drive filtering in Form Search & Filtering
• Bookmarks: Mark forms as favorites for quick access from the workspace home
• AI Training Status: The form record exposes the training_status object ({status, fields_total, fields_finetuned, version, first_page_only}) so workspace members can see at a glance whether the form has been fine-tuned, is being fine-tuned, or has never been fine-tuned
• Preview Images: Thumbnail renders of the first page, generated from the PDF at upload time, give visual confirmation that the correct template is selected
• Field-Hash Display: The form detail view shows whether the current form is recognized as a catalog entry (field-hash matched at upload), helping administrators understand which forms are shared infrastructure vs. custom uploads

How It Works

1. Set Form Name: After upload, assign a descriptive name. The file name from the upload is used as the default; rename it to something meaningful, e.g., "CMS-1500 — Medical Claims (2024 Version)" rather than "CMS-1500_v3_final.pdf".

2. Write a Description: Enter a plain-language description explaining the form's purpose, the regulatory context, and which department or role uses it. Example: "IRS W-9 Request for Taxpayer Identification — collected from all new vendors before first payment is issued."

3. Add Filling Instructions: Write step-by-step notes attached to the form that appear during fill sessions. These are most useful for forms where certain fields require non-obvious input — for example, instructing users that the "Date of Service" on CMS-1500 box 24A must match the service date in the EHR, not today's date.

4. Add FAQs: Document common questions workspace members ask about the form. Examples: "Q: Should I enter SSN or EIN on the W-9? A: Enter SSN for individual contractors, EIN for incorporated entities." FAQs are visible in the form detail view and reduce repetitive support questions.

5. Apply Tags: Add tags that match how your team searches for forms — by regulatory area, document type, department, or year. Tags are the primary filter dimension in Form Search & Filtering.

6. Bookmark: Star frequently-used forms to pin them to the workspace home and the bookmarks section of the sidebar.

7. Review Training Status: The form detail page reads the training_status object from the AI fine-tuning pipeline. The workspace can see whether fine-tuning is "In Progress", "Completed", or has never been run — and whether a free-tier run (first_page_only: true) was the only processing performed.

Use Cases

Metadata organization matters most when a workspace grows beyond a handful of forms. An HR department managing W-4 withholding elections, I-9 employment eligibility verifications, and state-specific new-hire forms can tag each with the applicable state and year, write instructions clarifying which fields are mandatory under USCIS guidance, and add an FAQ entry addressing the most common I-9 question ("Q: Which List B documents are acceptable? A: See the M-274 Handbook for Employers link in the form description"). A healthcare billing team can use the AI training status field to identify which CMS-1500 and UB-04 templates have been fine-tuned to completion vs. which are still running on the base model, allowing them to prioritize fine-tuning for the highest-volume forms first. A legal team uploading jurisdiction-specific court filing forms can tag each form with the court name and case type, add a description with the filing deadline rules, and bookmark the three forms used in every new matter for quick access.

Benefits

• Workspace-Specific Context on Shared Infrastructure: Tags, descriptions, and instructions are workspace-scoped even when the underlying form field-hash is shared across the catalog — each workspace documents the form according to its own workflows
• Training Status Visibility: Surfacing training_status.fields_finetuned and training_status.version in the form record gives workspace administrators a concrete measure of AI optimization progress without needing to navigate to a separate admin panel
• Reduced Errors Through Instructions: Attaching form-specific instructions directly to the template record means users see guidance in context, during filling — not buried in a wiki or training document they might not find
• Tag-Driven Search: Because tags are the primary filter in the search pipeline, consistent tagging (e.g., always using "w-9" not "w9" or "W9") determines how quickly forms can be located by search

Security & Privacy

Data is scoped to workspaceId and protected via the shared JWT authentication middleware running in both the .NET and Python service layers. Form metadata — names, descriptions, tags, instructions, and FAQs — is stored against the workspace-specific form record. The field-hash is shared infrastructure used for deduplication and fine-tuning propagation, but workspace metadata layered on top of that hash is never exposed to other workspaces. Only workspace members with appropriate roles can edit form metadata; read access to descriptions and instructions is available to all workspace members.