Skip to main content

​
Overview

The Simplicity AI API lets you programmatically upload documents, trigger AI-powered form filling, and retrieve completed results. This guide walks you through authenticating and making your first API call. Base URL 
https://api.simplicity.ai

​
Step 1: Authenticate

Simplicity AI supports two authentication methods depending on your use case. API key generation screen
  • (b) Generate an API key from your dashboard under Integrations → API Keys. Pass it as the X-API-Key header on every request.
API key generation screen 
X-API-Key: YOUR_API_KEY
Keep your API key secret. Never expose it in client-side code or public repositories. Regenerate it immediately from the dashboard if it is ever compromised.

​
Option B — External User ID (For user-scoped requests)

If you are building a multi-user application, you can scope API requests to a specific user by passing their unique identifier in the external-user-id. This allows you to attribute document uploads and form submissions to individual users within your platform. 
X-API-Key: YOUR_API_KEY
external-user-id: user_abc123
Use this when you want Simplicity AI to associate activity (uploads, form fills, history) with a specific user in your system rather than your account as a whole.

​
Step 2: Upload a Document

Upload the PDF form you want to fill. The API returns a task_id you can use to track the upload progress. You can upload a document with the param of document_type which could be: (a) SOURCE_DOCUMENT: These are documents that are used as knowledge bases or data source for the AI agent when filling a form document. 
curl --request POST \
  --url 'https://api.simplicity.ai/documents/upload-document?document_type=SOURCE_DOCUMENT' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'file=@/path/to/your-form.pdf'
(b) FORM_DOCUMENT : The actual form that will be converted to an interactive form. 
curl --request POST \
  --url 'https://api.simplicity.ai/documents/upload-document?document_type=FORM_DOCUMENT' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --form 'file=@/path/to/your-form.pdf'
Response: Each returns a task_id and status. You can then query the /tasks/:task_id endpoint to check the upload status. 
{
  "task_id": "<string>",
  "status": "processing"
}

​
Step 3: Autofill the Form

Pass the form_file_document_id from your upload withdocument_type set toFORM_DOCUMENT (from step 2b above), along with optional source documents, instructions, and context to let the AI agent fill the form automatically. 
curl --request POST \
  --url https://api.simplicity.ai/forms/autofill \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "form_file_document_id": "<string>",
    "source_document_ids": ["<string>"],
    "instructions": "<string>",
    "context": "<string>"
  }'
Response 
{
  "task_id": "<string>",
  "status": "processing"
}
Autofill runs asynchronously. Use the returned task_id to poll for completion.
FieldTypeDescription
form_file_document_idstringThe document_id of the form to be filled.
source_document_idsstring[]Optional IDs of documents the AI agent uses as a knowledge source to extract fill data from. This is Optional if context is provided.
instructionsstringOptional plain-text instructions to guide how the form should be filled.
contextstringOptional additional context or raw data the AI agent can use when filling the form. This is Optional if source_document_ids is provided.

​
Step 4: Retrieve the Result

Poll the Tasks API with your task_id until the status is completed, then use the document_id in the response to download your filled form. 
curl --request GET \
  --url https://api.simplicity.ai/tasks/{task_id} \
  --header 'X-API-Key: YOUR_API_KEY'
Response 
{
  "task_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "task_type": "document-upload",
  "status": "processing",
  "progress": 0,
  "result_data": {},
  "error_message": "<string>",
  "estimated_completion": "2023-11-07T05:31:56Z",
  "document_id": "<string>",
  "updated_at": "2023-11-07T05:31:56Z"
}
FieldTypeDescription
task_idstringUnique identifier for the task.
task_typestringThe type of operation (e.g. document-upload, form-autofill).
statusstringCurrent task status: processing, completed, or failed.
progressnumberCompletion percentage from 0 to 100.
result_dataobjectOutput data when the task completes successfully.
document_idstringThe ID of the resulting document once processing is complete.
error_messagestringDetails of what went wrong if the task failed.
estimated_completionstringISO 8601 timestamp estimating when the task will finish.

​
Authentication Quick Reference

MethodHeaderWhen to Use
API KeyX-API-Key: YOUR_API_KEYServer-to-server integrations
External User IDexternal-user-id: A_USER_IDMulti-user platforms, user-scoped activity

​
Next Steps

Document Management

Learn how to list, retrieve, update, and delete your uploaded documents.

AI Form Autofill

Explore advanced autofill options including source document upload and field mapping.

Task Monitoring

Understand how to track and manage asynchronous operations with the Tasks API.

Webhooks

Receive real-time notifications when form submissions are complete.