Skip to main content
FlexOrch converts unstructured files into structured, LLM-ready data automatically. This guide walks you through uploading a document, waiting for the pipeline to finish, and reading back the extracted results — you’ll have your first processed document in under five minutes.

​
Prerequisites

Before you begin, make sure you have:
  • A FlexOrch account. Sign up for free at app.flexorch.com — no credit card required on the Trial plan.
  • An API key. Generate one under Settings → API Keys. It will look like dfx_xxxxxxxxxxxxxx. See API Keys for details.
  • curl (or any HTTP client) available in your terminal.
Each processed document consumes one credit. Trial accounts include 1,200 credits valid for 30 days — more than enough to follow this guide.

​
Steps

1
Upload a document
2
Send your file to the async processing endpoint using a multipart/form-data POST request. Replace dfx_your_key_here with your actual API key and invoice.pdf with a real file path.
3
curl -X POST https://api.flexorch.com/v1/data-process/async \
  -H "X-API-KEY: dfx_your_key_here" \
  -F "files=@invoice.pdf"
4
FlexOrch immediately queues a job and returns its ID:
5
{
  "data": {
    "job_ids": ["job_abc123"],
    "status": "queued"
  }
}
6
Copy the job_id value — you’ll need it in the next step.
7
Poll for job completion
8
Processing is asynchronous. Use the job status endpoint to check when your document is ready. Replace job_abc123 with the ID you received above.
9
curl https://api.flexorch.com/v1/jobs/job_abc123 \
  -H "X-API-KEY: dfx_your_key_here"
10
Poll every few seconds until status changes from queued or running to completed (or failed). A completed response looks like this:
11
{
  "data": {
    "status": "completed",
    "detected_language": "en",
    "quality": {
      "score": 91,
      "grade": "A"
    },
    "pii_findings_count": 2,
    "privacy_applied": true,
    "processing_summary": {
      "fields": {
        "vendor": "Acme Ltd.",
        "total_amount": 12500.00,
        "currency": "EUR"
      }
    }
  }
}
12
A quality.grade of A (score 85–100) means the document is clean and ready for production use. Grades B through D indicate progressively lower extraction confidence — see Core Concepts for the full grading scale.
13
Inspect the results
14
The processing_summary.fields object contains the structured data FlexOrch extracted — vendor name, amounts, currency, and any other fields detected for the document type. The pii_findings_count tells you how many personal data items were found, and privacy_applied: true confirms that PII masking was applied before the result was stored.
15
You now have a complete pipeline execution record. From here you can add this result to a dataset and export it in any of FlexOrch’s nine supported formats.

​
Full example with a Python script

If you prefer to automate polling rather than running curl commands manually, here is a minimal Python script that uploads a file and waits for completion: 
import time
import requests

API_KEY = "dfx_your_key_here"
BASE_URL = "https://api.flexorch.com/v1"
HEADERS = {"X-API-KEY": API_KEY}

# Upload
with open("invoice.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE_URL}/data-process/async",
        headers=HEADERS,
        files={"files": f},
    )
resp.raise_for_status()
job_id = resp.json()["data"]["job_ids"][0]
print(f"Job queued: {job_id}")

# Poll
while True:
    result = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=HEADERS).json()
    status = result["data"]["status"]
    print(f"Status: {status}")
    if status == "completed":
        print(result["data"])
        break
    elif status == "failed":
        raise RuntimeError(result["data"].get("failure_reason", "Unknown error"))
    time.sleep(3)

​
Next steps

Pipeline Deep Dive

Understand every step of the FlexOrch pipeline — extraction, classification, PII detection, and quality scoring.

Build a Dataset

Curate completed job results into a dataset and export to JSONL, Parquet, CSV, Markdown, and more.

Python SDK

Install flexorch-sdk and process documents with just a few lines of Python.

API Reference

Explore every endpoint, request parameter, and response schema in the full API reference.