Skip to content
BookendBookend Docs

Read a box drawn on a sample page

POST
/v1/extraction-templates/read-region
curl --request POST \
  --url http://localhost:8080/v1/extraction-templates/read-region \
  --header 'Content-Type: application/json' \
  --data '{ "sampleId": "example", "pageNo": 1, "box": { "x": 1, "y": 1, "w": 1, "h": 1 }, "field": "example", "docType": "example" }'

Takes sampleId, pageNo and box (page fractions x, y, w, h, origin top-left) and returns what the engine reads inside it, the tight box of those words and the label it proposes as the anchor. With field (a canonical field name) it also returns the region rule the box becomes and the value that rule extracts from the sample, proved with nothing else in play (docType scopes the proof; default other). 400 for a box off the page or an unknown field; 404 for an unknown sample. Administrators only.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Body of POST /v1/extraction-templates/read-region: a box drawn on a page of an uploaded sample, and optionally the field it names.

object
sampleId
string
pageNo
integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
box
One of:
null
field

The canonical field the box is for; when null the box is only read (for a title, say).

null | string
docType

The document type the rule will belong to, for the proof extraction; defaults to other.

null | string
Examplegenerated
{
  "sampleId": "example",
  "pageNo": 1,
  "box": {
    "x": 1,
    "y": 1,
    "w": 1,
    "h": 1
  },
  "field": "example",
  "docType": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

What a drawn box reads, the region rule it becomes, and the value that rule extracts from the sample.

object
read
required

What a drawn region contains: the text inside it in reading order, the tight box of those words, the anchor the engine proposes (null when nothing label-like sits beside or above it), and whether the page was recognised by OCR.

object
pageNo
required
integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
rawText
required
string
wordCount
required
integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
box
required

Page-relative box: fractions of page width/height, origin top-left, so it survives any render scale.

object
x
required
number | string format: double
/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/
y
required
number | string format: double
/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/
w
required
number | string format: double
/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/
h
required
number | string format: double
/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/
anchor
required
One of:
null
ocrApplied
required
boolean
engineVersion
required
string
rule
required
One of:
null
value
required
One of:
null
Example
{
  "rule": {
    "requireBold": true
  }
}