FormRead Server-Side Processing API

Server-Side Form Processing

The FormRead Server-Side API lets you send a scanned form image and receive structured results (OMR, OCR, BCR) directly as JSON. No browser, no iframe — just a simple HTTP request from your backend to ours.

• Send an image, get results back as JSON in a single request
• Supports OMR (bubble detection), OCR (text extraction), and BCR (barcode/QR reading)
• Form configuration is loaded automatically from the form you set up in the dashboard

Authentication

For enterprise uses the API can be used by generating and Bearer Auth token.

Login in the FormRead dashboard and access the API Token option:

Create the API tokens to allow third-party services to authenticate with our application on your behalf:

Process a Form Image

Send a scanned form image to be processed. The form must already be set up with read areas (OMR, OCR, BCR) via the dashboard or iframe. The API uses the saved form configuration to process the image.

Headers

With file upload:

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'image=@"/path/to/scanned-form.jpg"'

With image URL:

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"image_url": "https://example.com/scanned-form.jpg"}'

Response

{
  "success": true,
  "results": {
    "OMR-0-0": "A",
    "OMR-0-1": "C",
    "OMR-0-2": "B,D",
    "OCR-1": "John Smith",
    "BCR-2": "1234567890"
  },
  "omr_details": {
    "OMR-0": {
      "questions": [
        [
          {"left": 0.12, "top": 0.22, "width": 0.02, "height": 0.02, "blackPixelsRatio": 0.72},
          {"left": 0.15, "top": 0.22, "width": 0.02, "height": 0.02, "blackPixelsRatio": 0.15}
        ]
      ]
    }
  },
  "anchor_error": false,
  "processing_time_ms": 450
}

Response Fields

Image Input Options

You can provide the image in three ways. Use exactly one:

Batch Processing

To process multiple images of the same form in one request, pass a comma-separated list of URLs in the image_url field. Results are returned as an array in the same order.

Request

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"image_url": "https://example.com/a.jpg,https://example.com/b.jpg,https://example.com/c.jpg"}'

Response

{
  "results": [
    {
      "id": "0",
      "image_url": "https://example.com/a.jpg",
      "success": true,
      "results": { "OMR-0-0": "A", "OCR-1": "John Smith" },
      "anchor_error": false,
      "processing_time_ms": 430
    },
    {
      "id": "1",
      "image_url": "https://example.com/b.jpg",
      "success": true,
      "results": { "OMR-0-0": "B", "OCR-1": "Jane Doe" }
    },
    {
      "id": "2",
      "image_url": "https://example.com/c.jpg",
      "success": false,
      "error": "Failed to fetch image from URL: 404"
    }
  ],
  "total": 3
}

Batch Parameters

Batch with omr_details

curl --location 'https://formread.org/api/forms/123/process' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_url": "https://example.com/a.jpg,https://example.com/b.jpg",
    "details": true
  }'

Limits

A 429 response looks like this:

{
  "message": "Too Many Attempts."
}

A batched request counts as one call regardless of how many URLs it contains.

Supported Area Types

Code Examples

Here are complete examples in Python and JavaScript for processing a form image:

Python

import requests

API_URL = "https://formread.org/api/forms/{form_id}/process"
TOKEN = "YOUR_API_TOKEN"

with open("scanned-form.jpg", "rb") as f:
    response = requests.post(
        API_URL.format(form_id=123),
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {TOKEN}",
        },
        files={"image": f},
    )

data = response.json()
print(data["results"])
# {"OMR-0-0": "A", "OMR-0-1": "C", "OCR-1": "John Smith"}

Node.js

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('image', fs.createReadStream('scanned-form.jpg'));

const response = await axios.post(
  'https://formread.org/api/forms/123/process',
  form,
  {
    headers: {
      ...form.getHeaders(),
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_API_TOKEN',
    },
  }
);

console.log(response.data.results);
// { 'OMR-0-0': 'A', 'OMR-0-1': 'C', 'OCR-1': 'John Smith' }

Frequently Asked Questions