Document Extraction

HTTP Endpoint
POST https://worker.formextractorai.com/extract
Overview
Send the image with a POST request to the Extract API endpoint and FormX will isolate extraction fields from the uploaded image then perform OCR on these fields. 
FormX will use the form model of your choice to extract and return the data in a JSON format. The form model can be specified by the form_id parameter. An Access Token should also be included. They can be obtained from the web portal dashboard.
FormX provides two modes to access the API, synchronous or asynchronous, which can be specified by a parameter. See more details below.
cURL Example
1
curl -X POST \
2
https://worker.formextractorai.com/extract \
3
-H 'Content-Type: image/jpeg' \
4
-H 'X-WORKER-FORM-ID: REPLACE-YOUR-FORM-ID-HERE' \
5
-H 'X-WORKER-TOKEN: REPLACE-YOUR-WORKER-TOKEN-HERE' \
6
--data-binary "@/path/to/query/image.jpg"
Copied!
Code Examples
Python
Node.js
Go
PHP
1
import requests
2
​
3
url = "https://worker.formextractorai.com/extract"
4
​
5
payload=open('FILE_PATH_TO_IMAGE', 'rb')
6
headers = {
7
  'X-WORKER-TOKEN': 'ACCESS_TOKEN',
8
  'X-WORKER-FORM-ID': 'FORM_ID',
9
  'Content-Type': 'image/jpeg'
10
}
11
​
12
response = requests.request("POST", url, headers=headers, data=payload)
13
​
14
print(response.text)
Copied!
1
var fs = require('fs');
2
var request = require('request');
3
var options = {
4
  'method': 'POST',
5
  'url': "https://worker.formextractorai.com/extract",
6
  'headers': {
7
    'X-WORKER-TOKEN': "ACCESS_TOKEN",
8
    'X-WORKER-FORM-ID': "FORM_ID",
9
    'Content-Type': 'image/jpeg',
10
    'X-WORKER-ENCODING': 'base64'
11
  },
12
  body: base64_encode("FILE_PATH_TO_IMAGE")
13
​
14
};
15
​
16
request(options, function (error, response) {
17
  if (error) throw new Error(error);
18
  console.log(response.body);
19
});
20
​
21
​
22
// function to encode file data to base64 encoded string
23
function base64_encode(file) {
24
    // read binary data
25
    var bitmap = fs.readFileSync(file);
26
    // convert binary data to base64 encoded string
27
    return new Buffer(bitmap).toString('base64');
28
}
Copied!
1
package main
2
​
3
import (
4
  "fmt"
5
  "strings"
6
  "net/http"
7
  "io/ioutil"
8
)
9
​
10
func main() {
11
​
12
  url := "https://worker.formextractorai.com/extract"
13
  method := "POST"
14
​
15
  payload := strings.NewReader("<file contents here>")
16
​
17
​
18
  client := &http.Client {
19
  }
20
  req, err := http.NewRequest(method, url, payload)
21
​
22
  if err != nil {
23
    fmt.Println(err)
24
    return
25
  }
26
  req.Header.Add("X-WORKER-TOKEN", "ACCESS_TOKEN")
27
  req.Header.Add("X-WORKER-FORM-ID", "FORM_ID")
28
  req.Header.Add("Content-Type", "image/jpeg")
29
​
30
  res, err := client.Do(req)
31
  if err != nil {
32
    fmt.Println(err)
33
    return
34
  }
35
  defer res.Body.Close()
36
​
37
  body, err := ioutil.ReadAll(res.Body)
38
  if err != nil {
39
    fmt.Println(err)
40
    return
41
  }
42
  fmt.Println(string(body))
43
}
Copied!
1
$curl = curl_init();
2
​
3
curl_setopt_array($curl, array(
4
  CURLOPT_URL => 'https://worker.formextractorai.com/extract',
5
  CURLOPT_RETURNTRANSFER => true,
6
  CURLOPT_ENCODING => '',
7
  CURLOPT_MAXREDIRS => 10,
8
  CURLOPT_TIMEOUT => 0,
9
  CURLOPT_FOLLOWLOCATION => true,
10
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
11
  CURLOPT_CUSTOMREQUEST => 'POST',
12
  CURLOPT_POSTFIELDS => "<file contents here>",
13
  CURLOPT_HTTPHEADER => array(
14
    'X-WORKER-TOKEN: ACCESS_TOKEN',
15
    'X-WORKER-FORM-ID: FORM_ID',
16
    'Content-Type: image/jpeg'
17
  ),
18
));
19
​
20
$response = curl_exec($curl);
21
​
22
curl_close($curl);
23
echo $response;
Copied!
Postman Example
You can download the following file and import it to the Postman app to test the API. Remember to set the X-WORKEN_TOKEN and X-WORKER-FORM-ID variables in the collection scope to configure your form.
FormX Document Extraction.postman_collection.json.zip
1KB
Binary
Postman Collection
Image Sizing Recommendations
The images submitted to the extraction API should be of sufficient size so that the text and features can be easily distinguished. 
The API supports JPEG, PDF, and PNG image types. It is recommended to use an image minimum of 1000x750 pixels or 100 DPI.
Making the Request
If you want to upload the image directly, it can be uploaded in the request body or via multipart/form-data. If you want to specify an image URL, it can be submitted via a header or multipart/form-data.
Most of the parameters can be submitted either as multipart/form-data or as request headers.
Using parameters in HTTP request headers
Name
Optional
Description
Content-Type
optional
image/jpeg or image/png or application/pdf
*required if image is sent in the request body
X-WORKER-TOKEN
required
Access token
This parameter must be included in the header.
X-WORKER-FORM-ID
required
Form ID
X-WORKER-IMAGE-URL
optional
URL of the image, can be a JPG, PNG or PDF file
*required if request body is empty
X-WORKER-ENCODING
optional
Encoding of the request body, allowed 'raw' or 'base64'
Default value: raw
X-WORKER-PDF-DPI
optional
DPI of the uploaded pdf file
Default value: 100
X-WORKER-SHOW-CONFIDENCE
optional
Flag for showing confidence score in response
Default value: false
X-WORKER-AUTO-ADJUST-IMAGE-SIZE
optional
Flag for auto adjusting image size for better extraction result, it will take a longer for extraction if enabled
Default value: true
X-WORKER-ASYNC
optional
Flag for using the asynchronous mode
Default value: false
Using parameters in form data
Name
Optional
Description
form_id
required
Form ID
image
optional
The image file, can be a JPG, PNG or PDF file
Either specify this or provide the image_url parameter
image_url
optional
URL of the image, can be a JPG, PNG or PDF file
Either specify this or provide the image parameter
pdf_dpi
optional
DPI of the uploaded pdf file
Default value: 100
show_confidence
optional
Flag for showing confidence score in response
Default value: false
auto_adjust_image_size
optional
Flag for auto adjusting image size for better extraction result, it will take a longer for extraction if enabled
Default value: true
async
optional
Flag for using the asynchronous mode
Default value: false
API Response
Name
Type
Description
status
string
"ok" if success, "failed" if failed
form_id
string
Form ID
fields
Field[]
List of extracted fields and fields in detection regions
auto_extraction_items
AutoExtractionItem[]
List of detected auto extraction items
key_values
KeyValue[]
List of detected token groups
token_groups
TokenGroup[]
List of detected token groups
error
any
Only exists if failed, its shape depends on the failure, but it always contain the "code" and "message" fields
Field
Name
Type
Description
region_id
string
Detection region ID
name
string
Field label
type
string
Field type
value
any
Extracted content
error
string
Message of the error if exists
confidence
number
Confidence score
*exists if confidence score is enabled
If there is a list of values, e.g. fields with the type name or address, this will be return alongside the value in the list.
AutoExtractionItem
Name
Type
Description
name
string
Item name
value
any
Item value
confidence
number
Confidence score
*exists if confidence score is enabled
If there is a list of values, e.g. for name, address, and job_title items, this will be return alongside the value in the list.
KeyValue
Name
Type
Description
name
string
Item name
value
string
Item value
confidence
number
Confidence score
*exists if confidence score is enabled
TokenGroup
Name
Type
Description
name
string
Token group name
texts
Token[]
List of detected text tokens in this group
images
Token[]
List of detected image tokens in this group
Token
Name
Type
Description
id
string
Token id
value
string
Token value
confidence
number
Confidence score
*exists if confidence score is enabled
Using the Asynchronous mode
If the request takes too long to complete, you can use the asynchronous mode to avoid timeout. This can be enabled by the async parameter either in the header or form data.
Job ID
If the async job is successfully created, a 202 Accepted response will be returned with the job_id and the page_count.
1
202 Accepted {
2
  async: true,
3
  job_id: <string>,
4
  page_count: <number>,
5
}
Copied!
Getting the extraction result
GET https://worker.formextractorai.com/extract/jobs/:job_id
The extraction result can be queried by polling the Job endpoint. Send GET request to the endpoint /extract/jobs/:job_id with the access token in the header until the result is returned.
The extraction result will be deleted 24 hours after the job is completed, no matter it has been queried or not.
Pending
1
201 Created {
2
   status: "pending"
3
}
Copied!
Completed
1
200 OK {
2
   status: "OK",
3
   pages: [
4
       // structure same as the extract API
5
   ]
6
}
Copied!