Asynchronous mode

By default, Handl works in synchronous mode. You send a file for classification or recognition, wait for a response and only then send the next file. This mode is convenient for a low flow of documents and for testing purposes. In other cases, we recommend using the asynchronous mode. To enable it, specify async=true in the request parameters.

# asynchronous request for passport recognition from passport.jpg file, cloud version:
$ curl -X POST \
    "https://latest.handl.io/recognize?doc_type=passport_main&quality=75&dpi=300&auto_pdf_raw_images=true&pdf_raw_images=true&async=true&token=ваш_ключ_лицензии" \
    -H  "accept: application/json" \
    -H  "Content-Type: multipart/form-data" \
    -F "image=@passport.jpg;type=image/jpeg"

As a response to an asynchronous request Handl will return this HTTP-header:

access-control-allow-credentials: true 
access-control-allow-origin: https://latest.dbrain.io 
content-length: 130 
content-type: application/json 
date: Tue08 Sep 2020 11:47:52 GMT 
server: nginx/1.15.2 
status: 200

The structure of the HTTP-message body is as follows:

{
  "detail": [],
  "items": [],
  "task_id": "5f576f68a3c2c6b689ff7a83",
  "code": null,
  "message": null,
  "errno": null,
  "traceback": null,
  "fake": null
}

task_id must be specified for recognition or classification results, for example:

# use your license key instead of token parameter 
$ curl -si \
    "https://latest.handl.io/result/5f576f68a3c2c6b689ff7a83?token=xxx"

Possible responses to the results request

Done

If task_id is found and classification or recognition is completed, the response code is 200.

HTTP-header:

content-encoding: gzip 
content-length: 896 
content-type: application/json 
date: Tue08 Sep 2020 11:26:22 GMT 
server: nginx/1.15.2 
status: 200 
vary: Accept-Encoding 

Your possible request using Russian Passport as an example

{
  "detail": [],
  "items": [
    {
      "doc_type": "passport_main",
      "fields": {
        "date_of_birth": {
          "text": "",
          "confidence": 0,
          "valid": null,
          "coords": [
            [
              [
                880,
                1446
              ],
              [
                1187,
                1446
              ],
              [
                1187,
                1497
              ],
              [
                880,
                1497
              ]
            ]
          ]
        },
        "date_of_issue": {
          "text": "17.12.2004",
          "confidence": 0.7422276735305786,
          "valid": null,
          "coords": [
            [
              [
                233,
                422
              ],
              [
                537,
                419
              ],
              [
                537,
                473
              ],
              [
                233,
                476
              ]
            ]
          ]
        },
        "first_name": {
          "text": "Adam",
          "confidence": 0.998583197593689,
          "valid": null,
          "coords": [
            [
              [
                748,
                1289
              ],
              [
                972,
                1289
              ],
              [
                972,
                1340
              ],
              [
                748,
                1340
              ]
            ]
          ]
        },
        "issuing_authority": {
          "text": "The issueing authority of New York city Area",
          "confidence": 0.995008111000061,
          "valid": null,
          "coords": [
            [
              [
                441,
                208
              ],
              [
                646,
                201
              ],
              [
                646,
                240
              ],
              [
                441,
                246
              ]
            ],
            [
              [
                681,
                201
              ],
              [
                976,
                201
              ],
              [
                976,
                236
              ],
              [
                681,
                236
              ]
            ],
            [
              [
                1011,
                201
              ],
              [
                1097,
                201
              ],
              [
                1097,
                236
              ],
              [
                1011,
                236
              ]
            ],
            [
              [
                502,
                278
              ],
              [
                857,
                278
              ],
              [
                857,
                313
              ],
              [
                502,
                313
              ]
            ],
            [
              [
                889,
                275
              ],
              [
                1065,
                275
              ],
              [
                1065,
                307
              ],
              [
                889,
                307
              ]
            ],
            [
              [
                502,
                355
              ],
              [
                678,
                355
              ],
              [
                678,
                390
              ],
              [
                502,
                390
              ]
            ],
            [
              [
                713,
                352
              ],
              [
                1065,
                348
              ],
              [
                1065,
                384
              ],
              [
                713,
                387
              ]
            ]
          ]
        },
        "other_names": {
          "text": "Ivanovich",
          "confidence": 0.9980864524841309,
          "valid": null,
          "coords": [
            [
              [
                659,
                1366
              ],
              [
                1065,
                1366
              ],
              [
                1065,
                1417
              ],
              [
                659,
                1417
              ]
            ]
          ]
        },
        "place_of_birth": {
          "text": "New York city",
          "confidence": 0.9998399019241333,
          "valid": null,
          "coords": [
            [
              [
                643,
                1536
              ],
              [
                745,
                1536
              ],
              [
                745,
                1568
              ],
              [
                643,
                1568
              ]
            ],
            [
              [
                790,
                1536
              ],
              [
                1110,
                1536
              ],
              [
                1110,
                1568
              ],
              [
                790,
                1568
              ]
            ]
          ]
        },
        "sex": {
          "text": "male",
          "confidence": 0.9768308401107788,
          "valid": null,
          "coords": [
            [
              [
                540,
                1449
              ],
              [
                665,
                1449
              ],
              [
                665,
                1500
              ],
              [
                540,
                1500
              ]
            ]
          ]
        },
        "subdivision_code": {
          "text": "292-000",
          "confidence": 0.9457029104232788,
          "valid": null,
          "coords": [
            [
              [
                825,
                416
              ],
              [
                1052,
                416
              ],
              [
                1052,
                464
              ],
              [
                825,
                464
              ]
            ]
          ]
        },
        "surname": {
          "text": "Jhonson",
          "confidence": 0.9971189498901367,
          "valid": null,
          "coords": [
            [
              [
                742,
                1132
              ],
              [
                944,
                1132
              ],
              [
                944,
                1184
              ],
              [
                742,
                1184
              ]
            ]
          ]
        },
        "series_and_number": {
          "text": "1104 000000",
          "confidence": 0.9674372673034668,
          "valid": null,
          "coords": null
        }
      },
      "color": true,
      "error": null
    }
  ],
  "task_id": null,
  "code": null,
  "message": null,
  "errno": null,
  "traceback": null,
  "fake": null
}

Not Done

If task_id is found, but the classification or recognition of the document is not yet complete, the response code is 202.

HTTP-header:

content-length: 162 
content-type: application/json 
date: Tue08 Sep 2020 12:05:32 GMT 
server: nginx/1.15.2 
status: 202

Your possible request using Russian Passport as an example

{
  "detail": [
    {
      "msg": "Async task not done",
      "type": "result_error"
    }
  ],
  "items": null,
  "task_id": null,
  "code": 202,
  "message": "Async task not done",
  "errno": 9,
  "traceback": null
}

Can't Find

If task_id is not found, the response code is 404. Make sure you are requesting the correct task_id.

HTTP-header:

content-length: 164 
content-type: application/json 
date: Tue08 Sep 2020 12:03:22 GMT 
server: nginx/1.15.2 
status: 404

Your possible request using Russian Passport as an example

{
  "detail": [
    {
      "msg": "Async task not found",
      "type": "result_error"
    }
  ],
  "items": null,
  "task_id": null,
  "code": 404,
  "message": "Async task not found",
  "errno": 8,
  "traceback": null
}