Request Logging & Audit Trail

A complete record of every form fill, source upload, API call, and access event — searchable, exportable, and scoped to your workspace

Overview

Request logging in Instafill.ai captures the full lifecycle of every document automation action: when a form filling session started, which source files were uploaded, which fields the AI filled and from what source content, when the filled PDF was downloaded, which API key was used, and who performed each action. Every entry is timestamped, tied to a user identity and workspace, and retained for compliance and debugging purposes.

This matters most in regulated industries where document submissions have legal or financial consequences. A healthcare organization filling HIPAA authorization forms needs to demonstrate that a specific staff member filled the form at a specific time using approved source documents. A mortgage processor filling 1003 applications for a CFPB audit needs to show exactly when each application was completed and who touched it. A legal team filling court filings needs an unmodifiable record of when documents were finalized. The audit trail provides these records automatically, without any manual logging effort.

Logs are indexed in Elasticsearch 7.17.9 for fast querying, distributed across both the .NET web service and Python processing API with tracing via OpenTelemetry, retained for 12 months by default (configurable for Enterprise), and accessible to administrators with appropriate role permissions.

Key Capabilities

• Full session lifecycle logging: form filling sessions logged from creation through source processing, AI fill completion, PDF generation, and download
• Source-to-field data lineage: audit records capture which source documents were used in a session, enabling traceback from a filled field to the document it came from
• API request logging: every REST API call logged with endpoint, API key identity, response status, and processing duration
• Batch job tracking: batch fill operations logged per row — which rows completed, which failed, how long each took
• Webhook delivery logging: outbound webhook payloads recorded with destination URL, HTTP status, and retry attempts
• Authentication events: login, logout, failed login attempts, 2FA challenges, API key creation and revocation, OAuth authorizations
• Permission and access events: workspace membership changes, role changes, file access, form sharing
• Structured JSON format: all logs in consistent JSON format with standardized fields, compatible with SIEM and log aggregation tools
• Elasticsearch-backed search: query logs by user, action type, date range, resource ID, status code, or any combination
• Retention tiers: hot storage (0–30 days, instant search), warm storage (31–365 days), configurable archive for Enterprise
• Immutable append-only: logs cannot be modified or deleted before the retention period expires
• Export: download logs as JSON or CSV for external analysis, compliance submissions, or BI tool import

How It Works

Log Structure

Each log entry contains:

{
  "timestamp": "2024-02-16T14:32:18.234Z",
  "request_id": "req_abc123xyz",
  "user_id": "user_789",
  "user_email": "[email protected]",
  "organization_id": "org_456",
  "workspace_id": "ws_321",
  "action": "session.fill.completed",
  "resource_type": "Session",
  "resource_id": "session_999",
  "ip_address": "203.0.113.45",
  "user_agent": "Mozilla/5.0...",
  "request_method": "POST",
  "request_path": "/api/sessions/session_999/filled-pdf",
  "status_code": 200,
  "duration_ms": 1842,
  "metadata": {
    "form_name": "CMS-1500 Claim Form",
    "fields_filled": 34,
    "fields_total": 36,
    "source_files": ["patient_record_jan.pdf", "insurance_card.pdf"]
  }
}

The metadata field carries context specific to each action type. For session fill events, it includes the form name, field counts, and source file list. For batch jobs, it includes row count and success/failure breakdown. For API calls, it includes the API key identifier (not the key value).

Event Categories

Form filling events (most operationally relevant):

• session.created — new fill session opened with a form and workspace context
• session.sources.uploaded — source documents attached to a session
• session.sources.processed — OCR and vector indexing of source documents complete
• session.fill.started — AI fill job dispatched
• session.fill.completed — all fields filled, PDF available; includes fields_filled and fields_total counts
• session.fill.failed — fill job failed; includes error reason
• session.pdf.downloaded — filled PDF downloaded by a user or via API

Batch processing events:

• batch.created — batch job created with form and spreadsheet source
• batch.row.started / batch.row.completed / batch.row.failed — per-row events for granular tracking
• batch.completed — all rows processed; includes success/failure counts
• batch.merged — individual PDFs merged into a single combined output

API and integration events:

• All REST API calls — endpoint path, API key ID, response status, duration
• webhook.delivered / webhook.failed — webhook delivery attempts with destination URL and HTTP response
• email.received — inbound email-to-fill triggers

Access and security events:

• auth.login.success / auth.login.failed — with IP address and user agent
• auth.2fa.required / auth.2fa.verified
• apikey.created / apikey.revoked
• workspace.member.added / workspace.member.removed
• form.deleted / profile.deleted — deletion events with user identity

Log Infrastructure

HTTP request telemetry flows through OpenTelemetry instrumentation in both the .NET web service and the Python processing API, enabling distributed traces that span the full request lifecycle across both services. A single form fill — which involves the .NET service coordinating the session and the Python service running the AI fill — produces a linked trace showing time spent in each service.

Logs are indexed in Elasticsearch 7.17.9, which powers the admin log search interface. Queries run against Elasticsearch indices rather than primary database tables, so log searches don't impact application performance.

Access Control

• Organization admins: full log access for all workspaces in their organization
• Workspace admins: log access scoped to their workspace only
• Members: their own activity log only — session fills they initiated, files they uploaded
• Compliance officers (Enterprise): read-only access to all logs for audit purposes

Log access itself is logged — viewing or exporting audit logs creates a meta-log entry so administrators can see who accessed the audit trail.

Use Cases

HIPAA compliance for healthcare document workflows: A healthcare administrator filling patient intake forms, HIPAA authorizations, and medical history questionnaires needs to demonstrate that each document was filled by an authorized user on a specific date using approved source data. The audit trail provides this record per session, with source file names included in the metadata field.

SOC 2 audit preparation: Security auditors reviewing access controls need evidence that only authorized users accessed sensitive forms and that no unauthorized access occurred. Log exports covering authentication events, workspace access changes, and file operations provide this evidence.

Debugging failed form fills: When a batch job fails on row 47 of 200, the batch.row.failed event captures the error reason — source document parsing failure, field mapping timeout, PDF generation error — without requiring staff to re-run the entire batch to reproduce the issue.

API integration monitoring: Teams using the REST API to automate form filling can monitor API call logs to identify rate limit violations, slow endpoints, and error patterns. Per-API-key logs let teams trace which integration is responsible for specific call volumes.

Webhook delivery verification: When a downstream system didn't receive a webhook notification that a filled PDF was ready, the webhook delivery log shows whether the delivery was attempted, what HTTP response the destination returned, and whether retries occurred.

Benefits

• Regulatory compliance without extra work: every fill session, API call, and access event is logged automatically — no manual record-keeping required for HIPAA, SOC 2, or GDPR audit responses
• Data lineage for filled forms: the audit trail connects each filled PDF back to the source documents used — useful when a submitted form needs to be explained or defended
• Faster debugging: session and batch events capture error reasons, field counts, and timing data that make diagnosing failures faster than reconstructing from application logs
• Security incident investigation: failed login patterns, unusual API key usage, and unexpected file access surface in log queries without specialized tooling
• Accountability: every form modification, deletion, and access tied to a specific user identity

Security & Privacy

Logs are append-only and cannot be modified or deleted before the retention period expires. Log entries do not contain form field values or source document content — only metadata (form name, field counts, file names, user identity, timing). Passwords, credit card numbers, and SSNs are never logged.

Logs are encrypted at rest and in transit. Access requires role-based authorization — regular workspace members cannot view other users' audit logs. IP addresses are retained for the log retention period and anonymized when a user account is deleted (GDPR right to erasure compliance: the action record is preserved, the identifying information is replaced with an anonymized identifier).

All log data is scoped to workspaceId and protected via the shared JWT authentication middleware running in both the .NET and Python service layers.

Common Questions