Sending an image for analysis via API ​

You can use our API for quite a lot of things. But it all starts with the need of a simple analysis of a receipt.

Through this documentation we will simply send an image and get back analysis extracted from it. It will be the perfect place to also explain all the concepts you could use if you need to scale your receipt analysis process (going industrial 🏭) and / or use our rules validations tools.

Sending an image for analysis ​

We will cover here the basic workflow with an introduction to the basic concepts

Preparing the request ​

• In order to send a receipt you need to be authenticated on our API. If you did not, please read carefully our guide on how to connect to our API before going further.
• You also need to have an image of a receipt on your computer ready to be analyzed. Do not forget to follow our guidelines 📷.
• In order for you to retrieve the receipt analysis after sending the image, you need to name your receipt. Make sure this name is unique

Making the request ​

Here is a request example:

POST https://api.omen-data.io/v2/documents?name={your_unique_document_name}&dominantLanguage=fr-FR
Authorization: Bearer {your_access_token}

{path_to_your_file.jpg}

POST https://api.omen-data.io/v2/documents?name={your_unique_document_name}&dominantLanguage=fr-FR
Authorization: Bearer {your_access_token}

{path_to_your_file.jpg}

You have to specify a dominant language to get a correct analysis, you can find more information at the end of this article.

You should get a response like this:

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "WAITING_FOR_PROCESS" //Meaning that your image is in queue for being processed,
    [...]
}

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "WAITING_FOR_PROCESS" //Meaning that your image is in queue for being processed,
    [...]
}

We do not wait for receipt to be analyzed to launch the HTTP response, because it is a bad practice (for security and performance issues) to let a connection open for a long time.

Status and results ​

From now, you have to monitor when the data are actually extracted from the receipt.

You can make a request to get the data of this document:

GET https://api.omen-data.io/v2/documents?filter=name:{document_identifier}
Authorization: bearer {your_access_token}

GET https://api.omen-data.io/v2/documents?filter=name:{document_identifier}
Authorization: bearer {your_access_token}

You should get a response like this:

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "PROCESSING" //Meaning that your image is currently being process
    [...]
}

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "PROCESSING" //Meaning that your image is currently being process
    [...]
}

So until you get a status with the value PROCESSED it means that your receipt is not ready yet. When PROCESSED is set you can start interpreting the results, and exploring data extracted from the image.

Finally, if you try again the request after a few seconds, you should have the final analysis:

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "PROCESSED", //The analysis is done, you can browse the data
    "data" : {}, //Extracted data from receipt image
    [...]
}

HTTP/1.1 200 OK
{
    "name": "document_identifier", //A reminder of the id you specified (name)
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED", //universal unique id generated by our system.
    "status": "PROCESSED", //The analysis is done, you can browse the data
    "data" : {}, //Extracted data from receipt image
    [...]
}

This is the simplest way to send image and get back results.

Browsing your receipts ​

You will probably send more than one receipt. So we built some routes to browse and search through them. You can read our API documentation to learn more about all possible routes.

Keep in mind that you can only use the /documents/ routes if you do not create any endpoint or campaign.

Endpoints & Campaigns ​

Endpoints and Campaign are two abstractions we have made to fill the needs of our clients who have to deal with a lot of receipts from different sources.

On the previous part of this guide, we sent the receipt directly on the /documents route, which removes the layer of endpoints / campaigns and makes it easier to use. But it quickly becomes a mess to browse and retrieve receipts without these layers.

You can use the API with many receipts and receipts sources, from mobile apps to servers. But also for different purposes, from just data extraction to marketing promotion validation. So we have designed some ways to organize and manage your receipts and other features offered by our API.

Endpoints and Campaigns are ways to organize and put some meta processing to your receipts.

Endpoints ​

Endpoints are simply anchors to retrieve a set of receipts. They are for you a unique URL under which some receipts coming from a given source are grouped.

For example, you may receive receipts from a mobile application, and you want them to be forwarded to a specific point in your back-end. That's what endpoints are used for.

To get the data of a document belonging to an endpoint:

GET https://api.omen-data.io/v2/endpoints/{endpoint_id}/documents?filter=name:{document_name}
Authorization: bearer {your_access_token}

GET https://api.omen-data.io/v2/endpoints/{endpoint_id}/documents?filter=name:{document_name}
Authorization: bearer {your_access_token}

Browse our API Documentation for Endpoints here and read our documentation concerning the usage of Endpoints with the API.

Campaign ​

Campaigns are also anchors to retrieve a set of receipts. They differ from Endpoints because they also carry a rules' validation logic.

To get the data of a document belonging to a campaign:

GET https://api.omen-data.io/v2/campaign/{campaign_id}/documents?filter=name:{document_name}
Authorization: bearer {your_access_token}

GET https://api.omen-data.io/v2/campaign/{campaign_id}/documents?filter=name:{document_name}
Authorization: bearer {your_access_token}

Browse our API Documentation for Campaigns here and read our documentation concerning the usage of Campaigns with the API..

Understanding extracted data from a receipt ​

When you get the analysis back to your system, there are numerous fields from the data, it can be hard to understand every field. Thankfully we have documented each field on the API Documentation.

We encourage you to read it carefully.

Here is a quick summary of what you can get:

• Global information about the receipt
  • Sign
  • City
  • Postal Code
  • Address
  • Total Amount
  • Currency
  • Barcode
  • Date & Hour of purchase
  • Number of products
  • Phone of the store
• On the product part and for each product
  • Raw label (As read on receipt)
  • Short Label (A Cleaner label without extra data)
  • Quantity
  • Price
  • Unit Price
  • Mass
  • Brand
  • Category

We are able to "understand" the receipt data out of a mere receipt image.

Dominant language ​

The dominant language is used to specify in which language the system should analyze the receipt. Depending on this information, the system will use country-specific data to do the analysis like brands, signs or shops.

This way, a spanish receipt analyzed with dominant language set to fr-FR (French language) will not be correctly analyzed.

You can find the list of supported countries on the dedicated page.