Skip to main content

Quickstart

Extract structured data from a document in five steps. This guide uses curl; the same flow works with any HTTP client.

Time: ~5 minutes
Prerequisites: Running ExtractForm API (see Local Development)

:::info Using the dashboard instead? You can complete this same flow in the web dashboard: register an account, create a schema, upload a document, and view the extraction result — no curl required. This guide focuses on the API for automation and integration. :::

Step 1 — Create an account​

curl -X POST http://localhost:4000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo User",
    "email": "demo@example.com",
    "password": "securepass123"
  }'

Response:

{
  "user": { "id": "...", "email": "demo@example.com", "name": "Demo User" },
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresIn": 900
}

Save accessToken for the following steps. Alternatively, use an API key for automation.

Step 2 — Create a schema​

A schema defines which fields to extract from your documents.

curl -X POST http://localhost:4000/api/schema \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice",
    "description": "Extract invoice fields",
    "fields": [
      {
        "name": "invoice_number",
        "type": "text",
        "required": true,
        "description": "Invoice or reference number"
      },
      {
        "name": "total_amount",
        "type": "number",
        "required": true,
        "description": "Total amount due"
      },
      {
        "name": "invoice_date",
        "type": "date",
        "required": false,
        "description": "Date on the invoice"
      }
    ]
  }'

Save the schema id from the response.

Step 3 — Upload a document and start extraction​

curl -X POST http://localhost:4000/api/jobs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/invoice.pdf" \
  -F "type=EXTRACTION" \
  -F "schemaId=YOUR_SCHEMA_ID"

Response includes a job id and initial status (PENDING or QUEUED).

Step 4 — Poll for completion​

curl http://localhost:4000/api/jobs/YOUR_JOB_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Wait until status is COMPLETED (or FAILED — check errorMessage).

Step 5 — Read the extraction result​

curl http://localhost:4000/api/jobs/YOUR_JOB_ID/extraction \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response:

{
  "id": "...",
  "jobId": "...",
  "fields": {
    "invoice_number": "INV-2024-001",
    "total_amount": 1250.00,
    "invoice_date": "2024-03-15"
  },
  "metadata": {},
  "createdAt": "2026-01-01T12:00:00.000Z"
}

JavaScript example​

const BASE = 'http://localhost:4000/api';
const token = 'YOUR_ACCESS_TOKEN';

// Create job with file upload
const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('type', 'EXTRACTION');
form.append('schemaId', schemaId);

const jobRes = await fetch(`${BASE}/jobs`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const job = await jobRes.json();

// Poll until complete
let status = job.status;
while (status !== 'COMPLETED' && status !== 'FAILED') {
  await new Promise((r) => setTimeout(r, 2000));
  const poll = await fetch(`${BASE}/jobs/${job.id}`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  status = (await poll.json()).status;
}

// Get extraction
const extraction = await fetch(`${BASE}/jobs/${job.id}/extraction`, {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

console.log(extraction.fields);

Next steps​