RESTful API Endpoints

Comprehensive REST API for seamless integration with your existing systems and workflows

Overview

Instafill.ai's REST API spans two service layers: one handles sessions, sources, profiles, batch jobs, and webhook delivery; the other handles form upload and conversion, authentication (OAuth, JWT issuance), file management, and organization/workspace administration. Both services validate the same JWT format — tokens issued for a user session are accepted by both layers without re-authentication.

API keys are workspace-scoped — a key for workspace A cannot access workspace B's forms, sessions, or profiles regardless of the caller's identity. Every request is evaluated against the workspace binding of the presented key or JWT.

All endpoints follow REST conventions: predictable URLs, standard HTTP methods, JSON bodies, and standard HTTP status codes. The API powers the Instafill.ai web interface, Chrome/Edge extensions, and all third-party integrations — so every platform capability has a corresponding API endpoint. Full interactive documentation at docs.instafill.ai.

Key Capabilities

• Complete Platform Access: Every feature available in the web interface is accessible via API
• RESTful Design: Predictable URL structure, standard HTTP methods, JSON request/response format
• Authentication Options: JWT tokens for user context, API keys for server-to-server integration
• Rate Limiting: Fair-use rate limits with headers indicating remaining quota
• Pagination: Efficient handling of large result sets with cursor-based pagination
• Filtering & Sorting: Query parameters for filtering, sorting, and searching resources
• Webhooks: Push notifications for completed jobs, failed processes, and status changes
• Batch Operations: Bulk create, update, or delete operations for efficiency
• Error Handling: Detailed error messages with specific error codes for troubleshooting
• API Versioning: Backwards-compatible API versions for stable integrations
• Interactive Documentation: OpenAPI (Swagger) specification with live testing environment

API Categories

Form Management APIs

Upload, convert, and manage PDF forms programmatically.

Endpoints:

• POST /api/forms - Upload new PDF form
• GET /api/forms - List all forms with filtering
• GET /api/forms/{formId} - Get form details and field definitions
• PUT /api/forms/{formId} - Update form metadata
• DELETE /api/forms/{formId} - Delete form
• GET /api/forms/{formId}/fields - Get extracted field definitions
• POST /api/forms/{formId}/convert - Trigger flat-to-fillable conversion
• GET /api/forms/{formId}/preview - Get form preview image

Session Management APIs

Create and manage form filling sessions.

Endpoints:

• POST /api/sessions - Create new form filling session
• GET /api/sessions - List all sessions with filtering
• GET /api/sessions/{sessionId} - Get session details and status
• PUT /api/sessions/{sessionId} - Update session data
• DELETE /api/sessions/{sessionId} - Delete session
• POST /api/sessions/{sessionId}/sources - Add source documents
• POST /api/sessions/{sessionId}/fill - Trigger AI form filling
• GET /api/sessions/{sessionId}/pdf - Download filled PDF
• POST /api/sessions/{sessionId}/complete - Mark session as complete

Profile Management APIs

Create and manage reusable data profiles.

Endpoints:

• POST /api/profiles - Create new profile
• GET /api/profiles - List all profiles
• GET /api/profiles/{profileId} - Get profile details
• PUT /api/profiles/{profileId} - Update profile data
• DELETE /api/profiles/{profileId} - Delete profile
• POST /api/profiles/{profileId}/apply - Apply profile to session

Batch Processing APIs

Submit and monitor bulk form filling jobs.

Endpoints:

• POST /api/batches - Create batch processing job
• GET /api/batches - List all batch jobs
• GET /api/batches/{batchId} - Get batch job status and progress
• GET /api/batches/{batchId}/results - Download batch results
• DELETE /api/batches/{batchId} - Cancel running batch job
• POST /api/batches/{batchId}/retry - Retry failed batch rows

File Management APIs

Upload, download, and manage files.

Endpoints:

• POST /api/files - Upload file (forms, sources, attachments)
• GET /api/files/{fileId} - Download file
• DELETE /api/files/{fileId} - Delete file
• GET /api/files/{fileId}/metadata - Get file metadata

Organization & Workspace APIs

Manage organizations, workspaces, and permissions.

Endpoints:

• GET /api/organizations - List accessible organizations
• GET /api/organizations/{orgId}/workspaces - List workspaces in organization
• POST /api/workspaces - Create new workspace
• GET /api/workspaces/{workspaceId}/members - List workspace members
• POST /api/workspaces/{workspaceId}/members - Add member to workspace

Utility APIs

Support operations like PDF manipulation, field extraction, format conversion.

Endpoints:

• POST /api/tools/extract-text - Extract text from PDF or image
• POST /api/tools/merge-pdfs - Merge multiple PDFs
• POST /api/tools/flatten-pdf - Flatten fillable PDF to static
• POST /api/tools/rotate-pdf - Rotate PDF pages
• POST /api/tools/word-to-pdf - Convert Word document to PDF

Authentication

API Keys

Server-to-server authentication using API keys.

Creating API Keys:

1. Navigate to Account Settings → API Keys
2. Click "Create New API Key"
3. Name your key (e.g., "Production Server", "CI/CD Pipeline")
4. Copy key immediately (only shown once)
5. Store securely (treat like a password)

Using API Keys:

curl https://api.instafill.ai/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY"

API Key Security:

• Never commit API keys to version control
• Rotate keys periodically (every 90 days recommended)
• Use different keys for development, staging, and production
• Revoke compromised keys immediately
• Monitor key usage in API dashboard

JWT Tokens

User-context authentication for web and mobile apps.

OAuth Flow:

1. Redirect user to OAuth authorization URL
2. User authenticates and grants permissions
3. Receive authorization code
4. Exchange code for JWT access token
5. Include token in API requests

Using JWT Tokens:

curl https://api.instafill.ai/api/sessions \
  -H "Authorization: Bearer JWT_ACCESS_TOKEN"

Token Management:

• Access tokens expire after 1 hour
• Use refresh tokens to obtain new access tokens
• Implement token refresh logic in your app
• Store tokens securely (never in localStorage for web apps)

How It Works

Example Workflow: Automated Form Filling

Let's walk through a complete workflow using the API to fill a form programmatically.

Step 1: Upload Form Template (one-time setup)

curl -X POST https://api.instafill.ai/api/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "name=Job Application Form"

Response:

{
  "formId": "frm_abc123",
  "name": "Job Application Form",
  "status": "converted",
  "fieldCount": 45,
  "pages": 3
}

Step 2: Create Form Filling Session

curl -X POST https://api.instafill.ai/api/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "frm_abc123",
    "name": "John Doe Application"
  }'

Response:

{
  "sessionId": "ses_xyz789",
  "formId": "frm_abc123",
  "status": "draft",
  "createdAt": "2024-02-16T10:30:00Z"
}

Step 3: Upload Source Document

curl -X POST https://api.instafill.ai/api/sessions/ses_xyz789/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "type=document"

Response:

{
  "sourceId": "src_def456",
  "filename": "john-doe-resume.pdf",
  "status": "uploaded",
  "size": 245632
}

Step 4: Trigger AI Form Filling

curl -X POST https://api.instafill.ai/api/sessions/ses_xyz789/fill \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autoComplete": true
  }'

Response:

{
  "sessionId": "ses_xyz789",
  "status": "processing",
  "estimatedCompletionTime": "2024-02-16T10:30:45Z"
}

Step 4b: Check Source Processing Status

Before triggering fill, confirm sources are processed and page-mapped:

curl https://api.instafill.ai/api/sessions/ses_xyz789/process-sources-status \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 5: Poll for Completion

curl https://api.instafill.ai/api/sessions/ses_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (when complete):

{
  "sessionId": "ses_xyz789",
  "status": "completed",
  "fieldsCompleted": 43,
  "fieldsTotal": 45,
  "accuracy": 97.8,
  "completedAt": "2024-02-16T10:30:42Z"
}

Step 6: Download Filled PDF

curl https://api.instafill.ai/api/sessions/ses_xyz789/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o filled-application.pdf

Use Cases

The API powers embedded form automation across a wide range of business systems. HR platforms pre-fill internal job applications from employee records the moment someone applies, insurance companies batch-generate hundreds of claim forms per day from submission data, accounting software produces year-end IRS forms for all contractors at once, and mobile field-service apps combine on-site photos with structured job data to produce completed work orders in under two minutes.

Integration Guides: See our n8n workflow automation tutorial or Cognito Forms webhook integration for step-by-step API setup examples.

Benefits

• Automation: Eliminate manual form filling by integrating with your existing systems
• Scalability: Process one form or millions via API without workflow changes
• Reliability: Production-grade API with 99.9% uptime SLA for Enterprise customers
• Flexibility: Build custom integrations matching your exact workflow needs
• Real-Time: Synchronous API calls for immediate results or async for batch operations
• Monitoring: API dashboard tracks usage, errors, and performance metrics
• Documentation: Comprehensive docs with code examples in Python, JavaScript, Java, C#, PHP, Ruby
• Support: Dedicated API support for troubleshooting integration issues
• Version Stability: API versioning ensures your integrations don't break with platform updates

Security & Privacy

API security includes multiple protection layers:

Authentication Security:

• API keys use cryptographically strong random generation
• JWT tokens signed with RS256 (RSA-SHA256) asymmetric encryption
• Token rotation supported for zero-downtime key updates
• Failed authentication attempts logged and monitored

Transport Security:

• All API requests must use HTTPS (TLS 1.3)
• HTTP requests automatically redirected to HTTPS
• Certificate pinning available for mobile apps

Authorization:

• All resources are workspace-scoped — API keys cannot cross workspace boundaries
• JWT tokens are validated by both service layers via shared JWT middleware
• Role-based access control enforced for all API endpoints
• Audit logging: all API calls logged with user identity, endpoint, and workspace context

Rate Limiting:

• Prevents abuse and ensures fair resource allocation
• Limits based on subscription plan
• Headers indicate remaining quota and reset time
• Graceful degradation with 429 status codes

Audit Logging:

• All API calls logged with timestamp, user, endpoint, and result
• Audit logs available for compliance and troubleshooting
• Retention period: 90 days (extended for Enterprise)

Common Questions

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1613491200

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid form ID format",
    "details": {
      "field": "formId",
      "issue": "Must be a valid form identifier starting with 'frm_'"
    }
  }
}

https://api.instafill.ai/v1/sessions    (current)
https://api.instafill.ai/v2/sessions    (future)

{
  "event": "session.completed",
  "timestamp": "2024-02-16T10:30:42Z",
  "data": {
    "sessionId": "ses_xyz789",
    "formId": "frm_abc123",
    "status": "completed",
    "fieldsCompleted": 43,
    "accuracy": 97.8
  }
}