---
title: "Read a photo of a filled paper copy → its values (3 credits a page)"
method: POST
path: "/api/v1/engine/scan/{id}"
tags: ["Read"]
---

# Read a photo of a filled paper copy → its values (3 credits a page)

`POST /api/v1/engine/scan/{id}`

## Request

- Base URL: `https://philforms.com`
- URL: `https://philforms.com/api/v1/engine/scan/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-PDFPhile-Embed`

Each field is cut out of the photo and read on its own; every reading goes through the same checks as a fill. Only pages that line up with the form are charged. Test keys: up to 10 pages a day. Does not make a PDF — send the values to /engine/fill.

## Path parameters

- `id` string, required

## Query parameters

- `crops` '1'
- `reader` 'local' | 'hybrid' | 'ai'

## Request body

- object
  - `page` object[]
    - `number` integer
    - `image` string, required: data:image/jpeg|png|webp;base64,… ≤ 8 MB
  - `image` string: page 1 only

## Response `200`

{ data, confidence, rejected, unread, skipped, registration, quality } — confidence ≥ 0.9 = sure; quality[].level "retake" says why a clearer photo would read better. Review, then send data to /engine/fill

## Other responses

- `400`: Bad page list or image
- `402`: Not enough credits left this month / daily scan cap
- `404`: Unknown form
- `413`: An image is over 8 MB
- `422`: The photo could not be lined up with this form
- `503`: Scanning not configured on this server

---

[API](https://skmtc.dev/philforms/apis/philforms-api.md) · [All operations](https://skmtc.dev/philforms/apis/philforms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/philforms/apis/philforms-api/revisions/a43bf313729c?raw)