Document Extraction
POST https://worker.formextractorai.com/extractSend the image with a
POST request to the Extract API endpoint and FormX will recognize the information from the document. FormX will use the extractor of your choice to extract and return the data in a JSON format. The extractor 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 -X POST \
https://worker.formextractorai.com/extract \
-H 'Content-Type: image/jpeg' \
-H 'X-WORKER-FORM-ID: REPLACE-YOUR-FORM-ID-HERE' \
-H 'X-WORKER-TOKEN: REPLACE-YOUR-WORKER-TOKEN-HERE' \
--data-binary "@/path/to/query/image.jpg"
Python
Node.js
Go
PHP
import requests
url = "https://worker.formextractorai.com/extract"
payload=open('FILE_PATH_TO_IMAGE', 'rb')
headers = {
'X-WORKER-TOKEN': 'ACCESS_TOKEN',
'X-WORKER-FORM-ID': 'FORM_ID',
'Content-Type': 'image/jpeg'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
var fs = require('fs');
var request = require('request');
var options = {
'method': 'POST',
'url': "https://worker.formextractorai.com/extract",
'headers': {
'X-WORKER-TOKEN': "ACCESS_TOKEN",
'X-WORKER-FORM-ID': "FORM_ID",
'Content-Type': 'image/jpeg',
'X-WORKER-ENCODING': 'base64'
},
body: base64_encode("FILE_PATH_TO_IMAGE")
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
// function to encode file data to base64 encoded string
function base64_encode(file) {
// read binary data
var bitmap = fs.readFileSync(file);
// convert binary data to base64 encoded string
return new Buffer(bitmap).toString('base64');
}
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://worker.formextractorai.com/extract"
method := "POST"
payload := strings.NewReader("<file contents here>")
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("X-WORKER-TOKEN", "ACCESS_TOKEN")
req.Header.Add("X-WORKER-FORM-ID", "FORM_ID")
req.Header.Add("Content-Type", "image/jpeg")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://worker.formextractorai.com/extract',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => "<file contents here>",
CURLOPT_HTTPHEADER => array(
'X-WORKER-TOKEN: ACCESS_TOKEN',
'X-WORKER-FORM-ID: FORM_ID',
'Content-Type: image/jpeg'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
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
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.
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.
The simplest way is to send the image content in the body as raw binary data or base64, and send the parameters in the header
Header | 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-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-MULTI-PAGE-PDF | optional | Flag for processing a multi-page PDF document. If disabled, only the first page of the PDF is extracted. Default value: false |
X-WORKER-DETECT-MULTI-DOCUMENT | optional | Flag for detecting multiple documents in a page. Turn this on if more than one documents are in each page. For example, 3 identity cards in a scan.
Default value: false |
X-WORKER-ASYNC | optional | Flag for using the asynchronous mode Default value: false |
If you send the image file in multipart/form-data, you should put the parameters in the form-data too. Only the access token is transferred in header.
Header | Optional? | Description |
|---|---|---|
Content-Type | required | multipart/form-data |
X-WORKER-TOKEN | required | Access token |
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 |
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 |
multi_page_pdf | optional | Flag for processing a multi-page PDF document. If disabled, only the first page of the PDF is extracted. Default value: false |
detect_multi_document | optional | Flag for detecting multiple documents in a page. Turn this on if more than one documents are in each page. For example, 3 identity cards in a scan.
Default value: false |
async | optional | Flag for using the asynchronous mode Default value: false |
Instead of attaching the image file in the request, you can also specify the URL to the image. Either send it in the header or in the body as multipart/form-data.
Header | Description |
|---|---|
X-WORKER-IMAGE-URL | URL of the image to be processed in jpg or png format, or URL of a pdf file |
If the image URL is sent in the Header, other parameters should be sent in the Header too. Please refer to Option 1 for the parameter descriptions.
Name | Description |
|---|---|
image_url | URL of the image to be processed in jpg or png format, or URL of a pdf file |
If the image URL is sent in the form-data, other parameters should be sent in the form-data too. Please refer to Option 2 for the parameter descriptions.
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 |
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. |
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. |
Name | Type | Description |
name | string | Item name |
value | string | Item value |
confidence | number | Confidence score *exists if confidence score is enabled |
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 |
Name | Type | Description |
id | string | Token id |
value | string | Token value |
confidence | number | Confidence score *exists if confidence score is enabled |
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.If the async job is successfully created, a
202 Accepted response will be returned with the job_id and the page_count.202 Accepted {
async: true,
job_id: <string>,
page_count: <number>,
}
GET https://worker.formextractorai.com/extract/jobs/:job_idThe 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.
201 Created {
status: "pending"
}
200 OK {
status: "OK",
pages: [
// structure same as the extract API
]
}
If an error occured, the endpoint returns an error response in the following structure.
{
"error": {
"code": ERROR_CODE,
"message": "ERROR_MESSAGE"
},
"status": "failed"
}
Below is a table containing the possible errors and a short description of their cause.
Code | Message |
|---|---|
401 | Unauthorized |
1001 | Invalid token or Invalid argument |
1002 | Form ID not found |
1003 | Unsafe image url |
1004 | Cannot load image |
1005 | Uploaded file is too large |
1006 | Free quota used up, please upgrade to a
paid plan to continue. |
1007 | Too many requests |
1008 | Usage reached hard limit |
1009 | Image dimension is too large |
2001 | Form not found |
2002 | Form not ready |
2003 | Query image is not match the specified form |
2004 | Error during extracting form info |
2005 | Form group not found |
2006 | Form group is empty |
2007 | Cannot recognize any text from the input image |
3001 | Receipt group ID not found |
3002 | Google Cloud Vision service account key is not set |
3003 | Error during extracting receipt info |
3004 | Error during accessing Google Vision API |
3005 | Azure computer vision subscription key and/or endpoint is not set |
4001 | Extract job not found |
4002 | Fail to submit extract job, please try again later |
5001 | Custom model ID not found |
5002 | Custom model not found |
5003 | Error during creating the sync cvat project task |
6001 | Endpoint is not available because Procrastinate is disabled |
Last modified 1mo ago