Callback feature (document state notification)

The callback is a platform feature that informs the client about the state of is uploaded documents.

Currently there are 2 phases where we notify the state of the document:

After ML (Machine Learning algorithms) have classified and extracted the data from the document

In this phase the callback is made with state=30&stateText=RECEIVEDMACHINELEARN, but keep in mind that in this phase the document is still being processed, which means that the data extracted could be incomplete or have some misalignments with your expected results.

After all process have being done - final state

In this phase the callback could be made with one of the 3 final states:

state=91&stateText=ANNOTATED - When all the extractions and revisions are successfully done.
state=92&stateText=REJECTED - When the document was rejected due to some known reasons also available in the results data.
state=999&stateText=ERROR - When we could not processed the document or the process was interrupted unexpectedly.

Note: If the document was uploaded synchronously there are only the final state callback (as phase 2 above).

What do I need to do to be notified?

In order to be notified by this callback feature the client must have an API service available from their side as the following URI example:

https://<www.customer_api_url.com>?documentId=<document_identifier>&state=&stateText=

That service could be called using the “GET” or “POST” method.
We call your service with “GET” method by default. To call it with the “POST” method instead, you must fill the parameter callback_method=POST of the (submit service).

That service could be anonymously open or authenticated. To be authenticated the “POST” method must be used and you can pass your http authentication headers filling the parameter callback_headers of the (submit service) with a strings dictionary, like the following examples:
Example 1: callback_headers[Authorization] = API_KEY 7017f86c-6ea3-xxxx-xxxx-...
Example 2: callback_headers[User] = john, callback_headers[Password] = 123

The mandatory query string parameters are:

documentId: id of the document
state: state of the document (integer)
stateText: state of the document (string)

Having your service available from the internet you can start using immediately, just provide us your uri when submit a new file through our submit service. Please note that you only be notified about the documents uploaded with the callback information fulfilled.

The information that you need to provide are in the following fields:

callbackUrl: the uri of your service, like "https://myapiurl.com". This is mandatory.
callback_method: "GET" or "POST". We keep with GET by default if no info provided.
callback_headers: the strings dictionary as seen above. This is mandatory only if your service needs authentication.

I didn't receive any callback. Why?

It could be due to 1) your document is still in process (accordingly with your SLA), or 2) we tried but found something wrong while calling your service, or 3) we call your service but you didn't notice. However you can always call the get document service, and look for the callbackLog field, where you will find a log of the callbacks we did or tried for your document, as showed bellow.