API Documentation

Quick Start

Get up and running with Refractr in 60 seconds. You'll need an API key: create an account, confirm your email address, and generate one from your dashboard.

import requests

BASE_URL = "https://api.refractr.io"
API_KEY = "re_your_api_key_here"

payload = {
    "document_text": "Invoice #2847\nDate: January 15, 2026\nTotal: EUR 1,249.00",
    "template": {
        "invoice_number": "__str__",
        "date": "__date__",
        "total_amount": "__float__",
        "currency": "__str__"
    }
}

# Create the session once and reuse it for every call (keeps the connection open)
session = requests.Session()
session.headers["Authorization"] = f"Bearer {API_KEY}"

response = session.post(
    f"{BASE_URL}/api/v1/extract/",
    json=payload,
    timeout=30
)

result = response.json()
print(result["extracted_data"])
# {"invoice_number": "2847", "date": "2026-01-15",
#  "total_amount": 1249.0, "currency": "EUR"}

import base64
import requests

BASE_URL = "https://api.refractr.io"
API_KEY = "re_your_api_key_here"

# Send the file itself, base64-encoded
with open("invoice.pdf", "rb") as f:
    pdf = base64.b64encode(f.read()).decode()

payload = {
    "document": pdf,
    "template": {
        "invoice_number": "__str__",
        "date": "__date__",
        "total_amount": "__float__",
        "currency": "__str__"
    }
}

# Create the session once and reuse it for every call (keeps the connection open)
session = requests.Session()
session.headers["Authorization"] = f"Bearer {API_KEY}"

response = session.post(
    f"{BASE_URL}/api/v1/extract/",
    json=payload,
    timeout=30
)

result = response.json()
print(result["extracted_data"])
# {"invoice_number": "2847", "date": "2026-01-15",
#  "total_amount": 1249.0, "currency": "EUR"}

curl -X POST https://api.refractr.io/api/v1/extract/ \
  -H "Authorization: Bearer re_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document_text": "Invoice #2847\nDate: January 15, 2026\nTotal: EUR 1,249.00",
    "template": {
      "invoice_number": "__str__",
      "date": "__date__",
      "total_amount": "__float__",
      "currency": "__str__"
    }
  }'

# Put the file, base64-encoded, into the JSON body and send it
printf '{
  "document": "%s",
  "template": {
    "invoice_number": "__str__",
    "date": "__date__",
    "total_amount": "__float__",
    "currency": "__str__"
  }
}' "$(base64 < invoice.pdf | tr -d '\n')" |
curl -X POST https://api.refractr.io/api/v1/extract/ \
  -H "Authorization: Bearer re_your_api_key_here" \
  -H "Content-Type: application/json" \
  --data-binary @-

const response = await fetch(
  "https://api.refractr.io/api/v1/extract/",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer re_your_api_key_here",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      document_text: "Invoice #2847\nDate: January 15, 2026\nTotal: EUR 1,249.00",
      template: {
        invoice_number: "__str__",
        date: "__date__",
        total_amount: "__float__",
        currency: "__str__"
      }
    })
  }
);

const result = await response.json();
console.log(result.extracted_data);

import { readFile } from "node:fs/promises";

// Send the file itself, base64-encoded
const pdf = (await readFile("invoice.pdf")).toString("base64");

const response = await fetch(
  "https://api.refractr.io/api/v1/extract/",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer re_your_api_key_here",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      document: pdf,
      template: {
        invoice_number: "__str__",
        date: "__date__",
        total_amount: "__float__",
        currency: "__str__"
      }
    })
  }
);

const result = await response.json();
console.log(result.extracted_data);

The API returns your extracted data structured exactly as you defined it. Because each field declares its type, the values are guaranteed to be that type. Note the normalization: "January 15, 2026" comes back as "2026-01-15", and "EUR 1,249.00" becomes the bare number 1249.0 with the currency in its own field. See Templates & Types. To send a file such as a PDF or Word document instead of text, pick Documents above, or see Documents.

Authentication

All API requests must include your API key in the Authorization header.

Authorization: Bearer re_your_api_key_here

Keys work once you have confirmed your email address with the link we send at signup. Until then, requests return 403.

Templates & Types

A template is a JSON object shaped like the answer you want. Each leaf value declares the expected type using a typed placeholder. The type is enforced during generation, so the output is guaranteed to be that JSON type or null, not "usually". That guarantee is about shape, not accuracy: you always get well-formed, correctly typed JSON, but the values inside it come from a model and can be wrong.

Missing values

null means "not present in the document". Every typed field is nullable by design. A field is either a value of the declared type or null; never an empty string, a placeholder artifact, or malformed JSON.

Accuracy. Typed placeholders guarantee the shape of the response, not the correctness of the values. Extraction is model-based, so validate values against your own rules before treating them as authoritative, particularly for fields you are not certain the document contains.

Arrays

Untyped fields

A bare null leaf is still legal and means "any JSON type". Typed placeholders are recommended for every field where you know the type. They make results predictable and remove the need for defensive parsing on your side.

Canonical value formats

Rule of thumb: representation is normalized, content is verbatim. Refractr converts date and number formats to the canonical forms below, but never summarizes or paraphrases a text span.

Documents

To extract from a file, such as a PDF, a Word document or a photo, send it as document, base64-encoded, in place of document_text. No file name or type is needed: Refractr detects the file type from the content. The template, the response and the price are the same as for text: 1 credit per extraction, or 2 with OCR.

import base64

with open("invoice.pdf", "rb") as f:
    pdf = base64.b64encode(f.read()).decode()

payload = {
    "document": pdf,
    "template": {"invoice_number": "__str__", "total_amount": "__float__"}
}

Complete examples in Python, curl and JavaScript are in the Quick Start, under Documents.

Supported files

Other files are not supported, for example older Word files (.doc), RTF, spreadsheets and presentations. Save them as PDF first.

If you can select and copy the text in a PDF viewer, the PDF has a text layer. Without OCR, text inside images is not read, for example a scanned page or a photo pasted into the PDF, and a PDF without any text layer is rejected with 422 OCR_REQUIRED, not charged.

Word and OpenDocument files are read directly, so OCR does not apply to them: they cost 1 credit, also with "ocr": true. A document without any text, for example scans pasted in as pictures, is rejected with 422 NO_TEXT, not charged. Save it as PDF and send that with OCR instead.

Scans and photos (OCR)

For scans, photos and PDFs with scanned pages, add "ocr": true. Refractr then reads every page: from the text layer where it is complete, and with OCR where it is not. An extraction with OCR costs 2 credits, whatever the file contains, and usually adds well under a second.

with open("receipt.jpg", "rb") as f:
    photo = base64.b64encode(f.read()).decode()

payload = {
    "document": photo,
    "template": {"merchant": "__str__", "total_amount": "__float__"},
    "ocr": True
}

The response is the same as without OCR, with metadata.credits_charged set to 2. A file longer than the model can read in one go is extracted from its first part, and validation.warnings says so (DOCUMENT_TRUNCATED).

If OCR can't be done, the response has "status": "error" and no credits are charged. The error code is one of:

• OCR_NO_TEXT: no text was found, for example a blank page or a photo without text.
• OCR_FAILED: the file could not be read. Retrying may help.
• OCR_UNAVAILABLE: OCR is temporarily unavailable. Retry later.

Limits

A file that is over a limit, of another type, password-protected or unreadable gets a 413 or 415 error, also not charged. See Error Codes.

Postman collection

Every endpoint, pre-filled with working examples, including a sample PDF, Word file and receipt image. Import it, paste your API key once, and send.

Download the collection

Setting it up

1. In Postman, choose Import and select the downloaded file.
2. Open the collection's Variables tab and paste your key into the current value of api_key. Create a key from your dashboard; it works once your email address is confirmed.
3. Send Extract (sync). It ships with a sample invoice and a typed template.

The key is applied to every request as Authorization: Bearer {{api_key}} through collection-level auth, so you only set it once. base_url is a variable too, if you ever need to point it elsewhere.

The file requests, Extract a PDF, Extract a Word file and Extract with OCR, send small sample files kept in the collection variables sample_pdf, sample_docx and sample_receipt. To try your own file, replace a variable's current value with the file's base64.

Scope & Accuracy

Refractr is built for one thing: simple-field extraction, fast and cheap. The sweet spot is a template of up to ~10 concrete fields (IDs, names, dates, amounts, booleans, short verbatim spans), extracted at around 500ms per document.

Out of scope

Fields that require derived reasoning or aggregation are not what this API is for: summaries, key-point lists, "all X mentioned in the document" sweeps, sentiment. The model will attempt them, but accuracy is materially lower; by design, this is not the product. If you need both, split your pipeline: use Refractr for the concrete fields and a separate step for derived ones.

Reporting a bad extraction

Corrections from alpha users feed directly into model training. If an extraction comes back wrong, email [email protected] with the job_id from the response, the field in question, and either the correct value or "not in the document".

Both cases are useful, and the second is the one we can least easily determine on our own.

Extract Data

The core endpoint. Submit a document and get back structured data matching your template.

Request Body

{
  "document_text": "BREAKING: Nvidia soars 12% to ~$187 after crushing Q4 earnings. Revenue hit $22.1B vs $20.4B expected.",
  "template": {
    "company": "__str__",
    "stock_move_pct": "__float__",
    "revenue_billions": "__float__",
    "currency": "__str__"
  },
  "wait": true
}

Response (Sync Mode)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "extracted_data": {
    "company": "Nvidia",
    "stock_move_pct": 12.0,
    "revenue_billions": 22.1,
    "currency": "USD"
  },
  "confidence": {
    "company": 0.9962,
    "stock_move_pct": 0.9814,
    "revenue_billions": 0.9731,
    "currency": 0.8847
  },
  "validation": {
    "warnings": []
  },
  "metadata": {
    "model": "refractr-v9",
    "inference_ms": 340,
    "credits_charged": 1
  }
}

validation.warnings lists informational notes about your template, for example that an empty string was normalized to null for a field. They're useful while iterating on a template and safe to ignore in production.

Confidence scores

Every successful extraction includes a confidence object next to extracted_data, at no extra cost. It has one entry per returned value: the estimated probability, from 0 to 1, that the value is correct.

Refractr never filters or changes values based on confidence. You choose the threshold; a practical starting point is to review values below 0.9 first:

to_review = [path for path, score in result.get("confidence", {}).items()
             if score is not None and score < 0.9]

If scores are unavailable for a request, the response has no confidence key and validation.warnings contains a CONFIDENCE_UNAVAILABLE entry with the reason. The extracted data is unaffected.

Response (Async Mode)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Job submitted. Poll GET /api/v1/extract/{job_id}/ for results."
}

When wait: false, the API returns immediately with a job ID. Use the Poll Status endpoint to check when your result is ready.

Poll Status

Check the status of an async extraction job.

Response (Still Processing)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Job is still processing.",
  "queue_depth": 2
}

status is queued until a worker picks the job up, then processing. queue_depth is the number of jobs currently waiting ahead in the queue.

Response (Complete)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "extracted_data": { ... },
  "confidence": { ... },
  "validation": { "warnings": [] },
  "metadata": { ... }
}

Pricing & Limits

Extractions are billed in credits, pay-as-you-go. Pricing is flat: it does not depend on document or template size.

The metadata.credits_charged field in each response tells you exactly what a call cost (0 for a failed extraction).

Rate limits

Requests are throttled per API key, 60 requests per minute by default. Exceeding the limit returns 429 with a Retry-After header; back off and retry after that interval.

Error Codes