Guide / QR JSON
QR upload JSON
Everything a backend needs to generate the upload QR codes that PageSnap scans. The code carries a small JSON payload; the app reads it, captures what it asks for, and posts the file to your address.
Version 1 Payload: JSON Updated 18 Sep 2026
- Method
- POST
- Content type
- multipart/form-data
- File field
- file
- Payload shape
- One object, or an array of them
01 How it works
- 1Build the upload instructions as one JSON object, or an array of them.
- 2Encode the JSON into a QR code with any generator, and show the code to the person who will scan.
- 3In the app, open Remote Upload on the home screen and scan the code.
- 4The app captures what the instruction asks for: a document, an ID card (front and back in one image), a passport, a passport photo in a print size, or a book spread.
- 5The app posts the file to your url as multipart/form-data, with your headers and form fields attached.
With an array, the app shows a destination picker first and uploads to the one that is chosen.
02 The instruction object
The smallest working instruction only needs a url.
{
"url": "https://example.com/upload"
}
A full instruction with a name, capture type, format, headers, and form fields.
[
{
"name": "Office scans",
"type": "document",
"format": "pdf",
"url": "https://api.example.com/upload",
"headers": [
"Authorization: Bearer <token>"
],
"params": {
"id": "case-123",
"ocr": "devanagari"
}
}
]
An array can hold several destinations. The app then asks which one to use.
03 Field reference
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| name | string | No | "Upload" | Label shown on the destination card and used in the uploaded file name. |
| type | string | No | "document" | What to capture: document, id, passport, passport_photo, or book. The id type captures the front and back and combines them into one image; a book spread is split into two pages. |
| size | string | No | "35x45" | Print size for a passport_photo instruction, in millimetres. Accepts the presets us (2x2 in), bd, icao, and ca, or any WxH value. Ignored by the other types. |
| format | string | No | "pdf" | jpg, webp, or pdf. jpg and webp hold a single page; a document in pdf can hold several. |
| url | string | Yes | none | Upload address. Must start with http:// or https:// and be reachable from the phone. |
| headers | object or array | No | none | Extra HTTP headers. Accepts an object like {"Authorization": "Bearer TOKEN"} or a list of "Key: Value" strings. |
| params | object | No | none | Form fields sent with the upload. The captured file is sent as the file field. The ocr key has a special meaning; see below. |
Unknown fields are ignored, so you can park extra keys in the JSON for your own tooling.
04 OCR values
A param key named ocr (the older spelling orc still works too) marks a text recognition job. Its value is listed on the destination card in the app.
Three script values run on the bundled ML Kit models. Each value names a script, not a single language, so one job covers every language written with that script.
| Value | Engine | Script and coverage | Good for |
|---|---|---|---|
| latin | ML Kit | The Latin alphabet: English and most European languages, plus other languages written with Latin letters, such as Indonesian, Turkish, and Vietnamese. | Invoices, letters, and forms in English or another Latin script language. |
| devanagari | ML Kit | The Devanagari script: Hindi, Marathi, and Nepali, along with Sanskrit text. It also reads Bangla (Bengali) text. | Hindi, Marathi, Nepali, or Bangla documents, forms, and textbooks. |
| chinese | ML Kit | Chinese characters in both Simplified and Traditional form, including pages that mix Chinese with English. | Chinese receipts, labels, and mixed language pages. |
The app also accepts the spelling chiness for the Chinese model.
Any other value is treated as a Tesseract language code and runs on the Tesseract engine. The codes available in the app: eng (English), ben (Bengali), urd (Urdu), ara (Arabic), hin (Hindi), fra (French), deu (German), spa (Spanish), por (Portuguese), ita (Italian), rus (Russian), zho_sim (Chinese Simplified), jpn (Japanese), and kor (Korean). Packs download once, from public sources, the first time they are used.
Bangla (Bengali) is covered by the devanagari model as well, so a Bangla page works with either value. The dedicated ben pack on Tesseract remains available as the specialist option for Bengali text.
Several jobs can be requested in one value, separated by | or ,. For example, "latin|ben" covers a page that mixes English and Bengali text, and "latin|devanagari" covers a form printed in both English and Hindi.
Text extraction itself is started by the user from the page viewer with the Text button. If a scan already has extracted text when it is uploaded, that text replaces the ocr value in the form. Otherwise the value is forwarded as is.
{
"name": "Bill scan",
"type": "document",
"format": "pdf",
"url": "https://api.example.com/upload",
"params": {
"id": "case-123",
"ocr": "latin|ben"
}
}
05 The upload request
Here is what your server sees. The file always arrives in the file field, next to your params.
POST /upload HTTP/1.1
Host: api.example.com
Authorization: Bearer TOKEN
Content-Type: multipart/form-data; boundary=----page-snap
------page-snap
Content-Disposition: form-data; name="id"
case-123
------page-snap
Content-Disposition: form-data; name="ocr"
devanagari
------page-snap
Content-Disposition: form-data; name="file"; filename="Office_scans_1758263040123.pdf"
Content-Type: application/pdf
<file bytes>
------page-snap--
The app treats any 2xx response as success and shows the response body on screen. Other status codes, timeouts, and connection errors are reported in the app as an error message.
06 Examples
Two destinations. The app asks which one to use, then uploads to it.
[
{
"name": "Scan for the case file",
"type": "document",
"format": "pdf",
"url": "https://api.example.com/cases/upload",
"headers": { "Authorization": "Bearer TOKEN" },
"params": { "id": "case-123" }
},
{
"name": "ID card to the KYC inbox",
"type": "id",
"format": "jpg",
"url": "https://kyc.example.com/intake"
}
]
While you are building, point the code at a request bin, such as RequestCatcher or any equivalent, to watch the multipart body arrive before you wire up the real endpoint.
07 Error messages
| Message in the app | What it means |
|---|---|
| The QR code does not contain valid JSON. | The scanned text is not JSON at all. |
| Each upload instruction must be a JSON object. | An item inside the array is not an object. |
| An upload instruction is missing its "url". | A destination has no url, or the url is empty. |
| Invalid upload url (must be http/https). | The url has no scheme, or it is not http and https. |
| Unsupported format (expected jpg, webp or pdf). | The format value is not one of the three accepted ids. |
| The QR code contains no upload instructions. | The array is empty. |
08 Good to know
- The JSON lives in the QR code, so treat it like a secret. Anyone who sees the code can read the headers, tokens included. Keep tokens short lived and limited to the upload endpoint.
- Keep the payload compact. QR codes get dense quickly, and some generators need a higher version for longer JSON.
- A document in pdf can capture several pages. jpg and webp capture a single page.
- Use https for the upload address. http works, but the file and headers travel unprotected.
Important
Uploads go straight from the phone to the destination in the QR code. That destination is run by you or another service, so its own terms of service and privacy policy apply to the files it receives. We do not run it and bear no responsibility for it.
The app also ships this reference on the device, under Remote Help on the home screen.