Quickstart - Simplicity AI

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.

Option A — API Key (Recommended for server-to-server)

(a) Visit simplicity.ai and create an account

(b) Generate an API key from your dashboard under Integrations → API Keys. Pass it as the X-API-Key header on every request.

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'

import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const form = new FormData();
form.append("file", fs.createReadStream("./your-form.pdf"), "your-form.pdf");

// document_type defaults to SOURCE_DOCUMENT if not specified
// Use FORM_DOCUMENT for the form to be filled, SOURCE_DOCUMENT for knowledge base files
const response = await fetch(
  "https://api.simplicity.ai/documents/upload-document?document_type=SOURCE_DOCUMENT",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      ...form.getHeaders(),
    },
    body: form,
  }
);

const data = await response.json();
console.log(data); // { task_id: "..." }

import requests

url = "https://api.simplicity.ai/documents/upload-document"

params = {"document_type": "SOURCE_DOCUMENT"}
files = {
    "file": ("your-form.pdf", open("your-form.pdf", "rb"))
}
headers = {"X-API-Key": "YOUR_API_KEY"}

response = requests.post(url, params=params, files=files, headers=headers)
print(response.text)  # { "task_id": "..." }

package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

func main() {
	file, _ := os.Open("./your-form.pdf")
	defer file.Close()

	var body bytes.Buffer
	writer := multipart.NewWriter(&body)
	part, _ := writer.CreateFormFile("file", filepath.Base("your-form.pdf"))
	io.Copy(part, file)
	writer.Close()

	// document_type defaults to SOURCE_DOCUMENT if not specified
	// Use FORM_DOCUMENT for the form to be filled, SOURCE_DOCUMENT for knowledge base files
	req, _ := http.NewRequest(
		"POST",
		"https://api.simplicity.ai/documents/upload-document?document_type=SOURCE_DOCUMENT",
		&body,
	)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", writer.FormDataContentType())

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody)) // { "task_id": "..." }
}

(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'

import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const form = new FormData();
form.append("file", fs.createReadStream("./your-form.pdf"), "your-form.pdf");

// document_type defaults to SOURCE_DOCUMENT if not specified
// Use FORM_DOCUMENT for the form to be filled, SOURCE_DOCUMENT for knowledge base files
const response = await fetch(
  "https://api.simplicity.ai/documents/upload-document?document_type=FORM_DOCUMENT",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      ...form.getHeaders(),
    },
    body: form,
  }
);

const data = await response.json();
console.log(data); // { task_id: "..." }

import requests

url = "https://api.simplicity.ai/documents/upload-document"

params = {"document_type": "FORM_DOCUMENT"}
files = {
    "file": ("your-form.pdf", open("your-form.pdf", "rb"))
}
headers = {"X-API-Key": "YOUR_API_KEY"}

response = requests.post(url, params=params, files=files, headers=headers)
print(response.text)  # { "task_id": "..." }

package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

func main() {
	file, _ := os.Open("./your-form.pdf")
	defer file.Close()

	var body bytes.Buffer
	writer := multipart.NewWriter(&body)
	part, _ := writer.CreateFormFile("file", filepath.Base("your-form.pdf"))
	io.Copy(part, file)
	writer.Close()

	// document_type defaults to SOURCE_DOCUMENT if not specified
	// Use FORM_DOCUMENT for the form to be filled, SOURCE_DOCUMENT for knowledge base files
	req, _ := http.NewRequest(
		"POST",
		"https://api.simplicity.ai/documents/upload-document?document_type=FORM_DOCUMENT",
		&body,
	)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", writer.FormDataContentType())

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody)) // { "task_id": "..." }
}

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>"
  }'

const response = await fetch("https://api.simplicity.ai/forms/autofill", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    form_file_document_id: "<string>",
    source_document_ids: ["<string>"],
    instructions: "<string>",
    context: "<string>",
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.simplicity.ai/forms/autofill"

payload = {
    "form_file_document_id": "<string>",
    "source_document_ids": ["<string>"],
    "instructions": "<string>",
    "context": "<string>"
}
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"form_file_document_id": "<string>",
		"source_document_ids":   []string{"<string>"},
		"instructions":          "<string>",
		"context":               "<string>",
	})

	req, _ := http.NewRequest(
		"POST",
		"https://api.simplicity.ai/forms/autofill",
		bytes.NewBuffer(payload),
	)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

Response

{
  "task_id": "<string>",
  "status": "processing"
}

Autofill runs asynchronously. Use the returned task_id to poll for completion.

Field	Type	Description
`form_file_document_id`	string	The `document_id` of the form to be filled.
`source_document_ids`	string[]	Optional IDs of documents the AI agent uses as a knowledge source to extract fill data from. This is Optional if `context` is provided.
`instructions`	string	Optional plain-text instructions to guide how the form should be filled.
`context`	string	Optional 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'

const taskId = "<your_task_id>";

const response = await fetch(
  `https://api.simplicity.ai/tasks/${taskId}`,
  {
    method: "GET",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
    },
  }
);

const task = await response.json();
console.log(task);

import requests

url = "https://api.simplicity.ai/tasks/{task_id}"

headers = {"X-API-Key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	taskID := "<your_task_id>"

	req, _ := http.NewRequest(
		"GET",
		"https://api.simplicity.ai/tasks/"+taskID,
		nil,
	)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

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"
}

Field	Type	Description
`task_id`	string	Unique identifier for the task.
`task_type`	string	The type of operation (e.g. `document-upload`, `form-autofill`).
`status`	string	Current task status: `processing`, `completed`, or `failed`.
`progress`	number	Completion percentage from `0` to `100`.
`result_data`	object	Output data when the task completes successfully.
`document_id`	string	The ID of the resulting document once processing is complete.
`error_message`	string	Details of what went wrong if the task failed.
`estimated_completion`	string	ISO 8601 timestamp estimating when the task will finish.

Authentication Quick Reference

Method	Header	When to Use
API Key	`X-API-Key: YOUR_API_KEY`	Server-to-server integrations
External User ID	`external-user-id: A_USER_ID`	Multi-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.

​Overview

​Step 1: Authenticate

​Option A — API Key (Recommended for server-to-server)

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

​Step 2: Upload a Document

​Step 3: Autofill the Form

​Step 4: Retrieve the Result

​Authentication Quick Reference

​Next Steps

Document Management

AI Form Autofill

Task Monitoring

Webhooks

Overview

Step 1: Authenticate

Option A — API Key (Recommended for server-to-server)

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

Step 2: Upload a Document

Step 3: Autofill the Form

Step 4: Retrieve the Result

Authentication Quick Reference

Next Steps