# FormFlow AI — RapidAPI Documentation ## Overview **FormFlow AI** automates AcroForm-heavy document workflows via API. Upload a PDF, get structured fields back, fill them programmatically — or let the AI-guided flow ask users the right questions and produce a filled PDF in seconds. Interactive AcroForms are the primary path; overlay is available as a fallback for selected text-based PDFs. **Use cases:** - Government & tax form automation (DE, AT, CH) - HR onboarding document completion - Insurance, legal, and benefit application workflows - Chatbot-driven form completion UX --- ## Base URL ``` https://api.ops-os.ai ``` --- ## Authentication All endpoints except `/health` require an API key in the `X-API-Key` header: ``` X-API-Key: YOUR_RAPIDAPI_KEY ``` RapidAPI automatically injects `X-RapidAPI-Key` — the proxy forwards it as `X-API-Key`. --- ## Pricing Tiers | Plan | Price | Calls/month | Overage | |------------|-------------|-------------|-----------------| | **Free** | $0 | 100 | — | | **Basic** | $19/month | 1,000 | $0.04/call | | **Pro** | $59/month | 5,000 | $0.02/call | | **Business**| $199/month | 25,000 | $0.01/call | | **Enterprise** | Custom | Unlimited | Contact us | > One "call" = one API request to `/analyze`, `/fill`, or `/v1/ai/jobs`. > Check your RapidAPI plan configuration for the exact metering behavior on assistant and download endpoints. --- ## Quickstart (3 steps) ### Step 1 — Analyze a PDF ```bash curl -X POST https://api.ops-os.ai/analyze \ -H "X-API-Key: YOUR_KEY" \ -F "file=@form.pdf" ``` Returns a `document_id` and list of all fillable fields. ### Step 2 — Fill the PDF ```bash curl -X POST https://api.ops-os.ai/fill \ -H "X-API-Key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "document_id": "abc123", "mode": "acroform", "fields": [ {"field_name": "Vorname", "value": "Max"}, {"field_name": "Nachname", "value": "Müller"} ] }' ``` ### Step 3 — Download the Result ```bash curl -O https://api.ops-os.ai/output/abc123_acroform_filled.pdf \ -H "X-API-Key: YOUR_KEY" ``` --- ## Endpoints --- ### `GET /health` Check API availability. **Response:** ```json {"status": "ok"} ``` --- ### `POST /analyze` Upload a PDF and extract all fillable fields with positions, types, and labels. **Request:** `multipart/form-data` | Field | Type | Required | Description | |--------|------|----------|--------------------------| | `file` | file | ✅ | PDF file (max 20MB) | **Response:** ```json { "document_id": "3f7a1c2d", "filename": "form.pdf", "document_type": "acroform", "page_count": 4, "preferred_fill_mode": "acroform", "form_type": "eks", "has_acroform": true, "has_extractable_text": true, "needs_ocr": false, "fields": [ { "key": "vorname", "label": "Vorname", "type": "text", "required": false, "page": 1, "field_name": "f1_01", "bbox": [72.0, 142.3, 290.0, 158.0], "confidence": 0.99, "states": null }, { "key": "verheiratet", "label": "verheiratet", "type": "radio", "page": 1, "field_name": "rbtnFamilienstand", "states": ["0", "1", "Off"] } ], "text_preview": "Anlage EKS..." } ``` **Field types:** | Type | Description | |------------|--------------------------------------| | `text` | Free-text input | | `date` | Date field (format: DD.MM.YYYY) | | `email` | Email address | | `checkbox` | Boolean on/off | | `radio` | Multiple-choice (see `states`) | **Code examples:**

Python

```python import httpx with open("form.pdf", "rb") as f: response = httpx.post( "https://api.ops-os.ai/analyze", headers={"X-API-Key": "YOUR_KEY"}, files={"file": ("form.pdf", f, "application/pdf")}, ) data = response.json() document_id = data["document_id"] fields = data["fields"] print(f"Found {len(fields)} fields") ```

JavaScript (fetch)

```javascript const form = new FormData(); form.append("file", fileBlob, "form.pdf"); const response = await fetch("https://api.ops-os.ai/analyze", { method: "POST", headers: { "X-API-Key": "YOUR_KEY" }, body: form, }); const { document_id, fields } = await response.json(); console.log(`Found ${fields.length} fields`); ```

Node.js (axios)

```javascript const axios = require("axios"); const FormData = require("form-data"); const fs = require("fs"); const form = new FormData(); form.append("file", fs.createReadStream("form.pdf")); const { data } = await axios.post("https://api.ops-os.ai/analyze", form, { headers: { "X-API-Key": "YOUR_KEY", ...form.getHeaders(), }, }); console.log(data.document_id, data.fields.length); ```

--- ### `POST /fill` Fill a previously analyzed PDF with field values. **Request body (JSON):** | Field | Type | Required | Description | |-------------------|--------|----------|--------------------------------------------------| | `document_id` | string | ✅ | From `/analyze` response | | `mode` | string | ✅ | `"acroform"` or `"overlay"` | | `fields` | array | ⬜ | List of fields to fill (see below) | | `business_fields` | object | ⬜ | Key-value map — auto-mapped to PDF fields | **Acroform mode fields** (for PDFs with AcroForm interactive fields): ```json { "field_name": "f1_01", "value": "Max" } ``` **Overlay mode fields** (for scanned/static PDFs): ```json { "key": "vorname", "value": "Max", "font_size": 11 } ``` Or with explicit position: ```json { "page": 1, "bbox": [72.0, 142.3, 290.0, 158.0], "value": "Max", "font_size": 11 } ``` **Business fields (auto-mapping):** Skip field name lookup — send human-readable keys and the API maps them automatically: ```json { "document_id": "3f7a1c2d", "mode": "acroform", "business_fields": { "first_name": "Max", "last_name": "Müller", "date_of_birth": "01.01.1985", "married": true, "annual_income": 42000 } } ``` **Radio / Checkbox values:** | Value | Result | |--------------------|------------------------------------------| | `"yes"` / `"true"` | Checks the field (picks first non-Off state) | | `"no"` / `"false"` | Unchecks the field (`/Off`) | | `"0"` / `"1"` | Selects by widget index (German forms) | | `"/Yes"` | Sets exact PDF state | **Response:** ```json { "success": true, "filename": "3f7a1c2d_acroform_filled.pdf", "output_path": "/data/output/3f7a1c2d_acroform_filled.pdf", "filled_fields": [ { "key": "vorname", "value": "Max", "page": 1, "bbox": [72.0, 142.3, 290.0, 158.0], "font_size": null } ], "skipped_fields": [] } ``` **Code examples:**

Python

```python import httpx response = httpx.post( "https://api.ops-os.ai/fill", headers={"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"}, json={ "document_id": "3f7a1c2d", "mode": "acroform", "fields": [ {"field_name": "f1_01", "value": "Max"}, {"field_name": "f1_02", "value": "Müller"}, ], }, ) data = response.json() filename = data["filename"] print(f"Filled {len(data['filled_fields'])} fields → {filename}") ```

JavaScript

```javascript const response = await fetch("https://api.ops-os.ai/fill", { method: "POST", headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ document_id: "3f7a1c2d", mode: "acroform", business_fields: { first_name: "Max", last_name: "Müller", date_of_birth: "01.01.1985", }, }), }); const { filename, filled_fields } = await response.json(); ```

--- ### `GET /output/{filename}` Download the filled PDF. **Path parameter:** | Param | Description | |------------|------------------------------------------| | `filename` | `filename` from `/fill` response | **Response:** Binary PDF file (`application/pdf`) **curl:** ```bash curl -O https://api.ops-os.ai/output/3f7a1c2d_acroform_filled.pdf \ -H "X-API-Key: YOUR_KEY" ``` **Python:** ```python pdf_bytes = httpx.get( f"https://api.ops-os.ai/output/{filename}", headers={"X-API-Key": "YOUR_KEY"}, ).content with open("filled_form.pdf", "wb") as f: f.write(pdf_bytes) ``` --- ### `POST /v1/ai/jobs` **AI-guided form filling.** Start an intelligent job — the API analyzes the PDF from a URL and returns a list of questions to ask the user. **Request body:** ```json { "file_url": "https://example.com/form.pdf" } ``` **Response:** ```json { "job_id": "job_8f3a2c", "questions": [ { "key": "vorname", "label": "Vorname", "type": "text", "question": "What is your first name?" }, { "key": "geburtsdatum", "label": "Geburtsdatum", "type": "date", "question": "What is your date of birth? (DD.MM.YYYY)" } ] } ``` **Python:** ```python response = httpx.post( "https://api.ops-os.ai/v1/ai/jobs", headers={"X-API-Key": "YOUR_KEY"}, json={"file_url": "https://example.com/form.pdf"}, ) job = response.json() job_id = job["job_id"] questions = job["questions"] ``` --- ### `POST /v1/ai/jobs/{job_id}/answers` Submit collected answers and receive the filled PDF download URL. **Path parameter:** `job_id` from `/v1/ai/jobs` **Request body:** ```json { "answers": { "vorname": "Max", "nachname": "Müller", "geburtsdatum": "01.01.1985", "verheiratet": "yes" } } ``` **Response:** ```json { "status": "completed", "download_url": "https://api.ops-os.ai/output/job_8f3a2c_filled.pdf" } ``` **Full AI-guided flow example (Python):** ```python import httpx API_KEY = "YOUR_KEY" BASE = "https://api.ops-os.ai" headers = {"X-API-Key": API_KEY} # 1. Start job job = httpx.post(f"{BASE}/v1/ai/jobs", headers=headers, json={"file_url": "https://example.com/steuer_form.pdf"}).json() job_id = job["job_id"] # 2. Collect answers (e.g. from your UI or chatbot) answers = {} for q in job["questions"]: answers[q["key"]] = input(f"{q['question']}: ") # 3. Submit answers result = httpx.post(f"{BASE}/v1/ai/jobs/{job_id}/answers", headers=headers, json={"answers": answers}).json() # 4. Download filled PDF pdf = httpx.get(result["download_url"], headers=headers).content with open("filled.pdf", "wb") as f: f.write(pdf) print(f"Done! Status: {result['status']}") ``` --- ### `POST /v1/ai/assistant` Ask a context-aware AI question about a specific form field. Answers are always 1 sentence, in the user's language. **Request body:** | Field | Type | Required | Description | |-------------|--------|----------|--------------------------------------| | `question` | string | ✅ | User's question | | `field` | string | ⬜ | Technical field key | | `label` | string | ⬜ | Human-readable field label | | `form_type` | string | ⬜ | Form category (e.g. `"eks"`) | | `language` | string | ⬜ | Form language (`"de"`, `"en"`, ...) | | `value` | string | ⬜ | User's current input (for validation)| **Request:** ```json { "question": "Was muss ich hier eintragen?", "field": "f1_01", "label": "Vorname", "form_type": "eks", "language": "de" } ``` **Response:** ```json { "answer": "Tragen Sie hier Ihren Vornamen ein, genau wie in Ihrem Ausweis.", "field": "f1_01", "script_warning": false } ``` `script_warning: true` = user entered text in wrong script (e.g. Arabic in a German form). **Python:** ```python response = httpx.post( "https://api.ops-os.ai/v1/ai/assistant", headers={"X-API-Key": "YOUR_KEY"}, json={ "question": "What format should I use for the date?", "label": "Geburtsdatum", "language": "en", }, ) print(response.json()["answer"]) # → "Enter your date of birth in DD.MM.YYYY format, e.g. 01.01.1985." ``` --- ## Error Codes | Status | Meaning | |--------|-----------------------------------------------------| | 400 | Bad request (missing `document_id`, wrong format) | | 401 | Invalid or missing API key | | 404 | Document not found (wrong `document_id`) | | 422 | Validation error (check request body schema) | | 503 | AI assistant unavailable (OpenAI key not configured)| | 500 | Unexpected server error | Error response shape: ```json { "detail": "document_id is required for /fill" } ``` --- ## Full End-to-End Example ```python import httpx API_KEY = "YOUR_KEY" BASE = "https://api.ops-os.ai" h = {"X-API-Key": API_KEY} # 1. Upload and analyze with open("steuererklärung.pdf", "rb") as f: analyze = httpx.post(f"{BASE}/analyze", headers=h, files={"file": ("steuererklärung.pdf", f, "application/pdf")}).json() doc_id = analyze["document_id"] mode = analyze["preferred_fill_mode"] # "acroform" or "overlay" fields = {f["key"]: f for f in analyze["fields"]} print(f"Document: {doc_id} Mode: {mode} Fields: {len(fields)}") # 2. Fill with business fields (auto-mapped) fill = httpx.post(f"{BASE}/fill", headers=h, json={ "document_id": doc_id, "mode": mode, "business_fields": { "first_name": "Max", "last_name": "Müller", "date_of_birth": "01.01.1985", "street_address": "Musterstraße 42", "city": "Berlin", "postal_code": "10115", "annual_income": 48500, "married": True, }, }).json() print(f"Filled: {len(fill['filled_fields'])} Skipped: {len(fill['skipped_fields'])}") # 3. Download pdf = httpx.get(f"{BASE}/output/{fill['filename']}", headers=h).content with open("filled_form.pdf", "wb") as f: f.write(pdf) print("Saved filled_form.pdf") ``` --- ## Supported Form Types | Code | Description | |---------------|-----------------------------------------------| | `ek` | Einkommenssteuererklärung (income tax) | | `eks` | Anlage EKS (self-employed income supplement) | | `vm` | Vermögensauskunft (asset declaration) | | `kdu` | Kosten der Unterkunft (housing costs) | | `wep` | Wohngeld Erstantrag (housing benefit) | | `hauptantrag` | Sozialleistungen Hauptantrag (benefits main) | | `wba` | Wohnberechtigungsantrag (housing permit) | | `unknown` | Generic/unrecognized form | --- ## Rate Limits - Requests are metered per calendar month - Limit resets on the 1st of each month (UTC) - Exceeding the limit returns HTTP 429 - Upgrade instantly in your RapidAPI dashboard --- ## Why FormFlow AI? | | FormFlow AI | Manual Integration | Generic PDF Library | |---|---|---|---| | AcroForm-first workflows | ✅ | ❌ | Partial | | Overlay fallback for selected PDFs | ✅ | ❌ | Partial | | AI explains every field | ✅ | ❌ | ❌ | | 40+ languages, auto-detected | ✅ | ❌ | ❌ | | GDPR compliant (24h deletion) | ✅ | ❌ | ❌ | | Built for government, legal, and HR flows | ✅ | ❌ | ❌ | --- ## Performance | Metric | Value | |--------|-------| | AcroForm analysis | ~1–2s | | AcroForm fill | ~1–3s | | Scanned PDF (overlay) | ~4–8s | | AI assistant response | ~1–2s | | Max file size | 20MB | | Uptime target (Pro/Business) | 99.5% | --- ## FAQ **Q: What PDF types are supported?** Interactive AcroForm PDFs are the primary path. For selected text-based PDFs without embedded fields, the API can fall back to overlay mode. Use `preferred_fill_mode` from `/analyze` to know which mode to use. **Q: How long are uploaded files stored?** 24 hours, then permanently and automatically deleted. No document content is ever used for model training. **Q: Which languages does the AI assistant support?** 40+ languages including English, German, Arabic, Turkish, French, Spanish, Russian, and more. Language is auto-detected from the user's input — no configuration needed. **Q: What is a "call"?** One request to `/analyze`, `/fill`, or `/v1/ai/jobs`. Check your RapidAPI plan configuration for the exact metering behavior on assistant and download endpoints. **Q: Can I use business_fields instead of raw field names?** Yes. Send human-readable keys like `first_name`, `date_of_birth`, `annual_income` and the API maps them automatically to the correct PDF fields for the detected form type. **Q: What happens if I exceed my plan quota?** HTTP 429 is returned. On paid plans you can continue at the overage rate. Free plan requests are blocked until the next month. **Q: Is the API GDPR compliant?** Yes. Files are processed in the EU, stored for 24 hours maximum, and never used for training. You remain the data controller for any personal data in uploaded documents. --- ## Support - **Live demo:** https://demo.ops-os.ai - **Issues / feedback:** hi@ops-os.ai - **Docs:** https://demo.ops-os.ai