API key

You can use the REST API using your unique API key.

A tipical REST URL will look like this:


Notice your api key in the URL which is:


Any search on documents and their metadata may be done with the search operator, an example is shown bellow


Which will return a list of document identifiers in JSON format, like the example below:

[123, 456]

Search may be done also by specific metadata values, next two examples show how to search using one metadata and two metadatas, respectively:


You must replace metadata.name with the metadata type name. Notice the format is metadata.name/value to search

Query and download

This example shows how to search a file and download:

import requests
url = 'http://dev.se.athento.comfile/api/search//VALUESEARCH'
r = requests.get(url, auth=('youruser', 'yourpassword'))
ids = eval(r.text)
if len(ids) == 1:
    url = 'http://dev.se.athento.comfile/api/download//' + str(ids[0])
    r = requests.get(url, auth=('youruser', 'yourpassword'))
    with open(r.headers['filename'], 'wb') as f:
        for chunk in r.iter_content(1024):

Upload and update

Uploading files

To upload files using REST, just POST to the next URL adding the file as file parameter and using BasicAuthentication:


A Python example is shown below using requests library:

import requests
url = 'http://dev.se.athento.comseries/api/serie/1/upload_file/?apikey='
files = {'file': open('path/to/your/file.pdf', 'rb')}
r = requests.post(url, files=files, auth=('youruser', 'yourpassword'))

Document and metadata values may be retrieved and updated with next REST services:

Getting metadata values


Updating metadata values



Next you can find the essence of document analysis. Operations are all type of "things" you can do with a document from extracting metadata, extracting pages, recognizing colors, classifying, etc. Here you can find how to use operations from the REST api.

Operations run over documents and the API returns the result of each one of them. If you run the operation to extract a metadata, the value extracted is returned, if you run the operation to classify a document the result of the classification is returned.

CAVEAT: Calling API also takes effect in the saved data, the result of each operation is saved as information of documents.

Extracting OCR

import requests
url = http://dev.se.athento.comseries/api/serie/SERIEID/upload_file/?apikey=
files = {'file': open('path/to/your/file.pdf', 'rb')}
resp = requests.post(url, files=files, auth=(YOURUSER, YOURPASS))
file_id = resp.text
url = 'http://dev.se.athento.comfile/api//getop/' + file_id + '/' + 'op_extract_ocr_athento'
r = requests.get(url, auth=(YOURUSER, YOURPASS))
ocr = r.text


url = 'http://dev.se.athento.comfile/api//getop/FILEID/op_autotagging'
r = requests.get(url, auth=(YOURUSER, YOURPASS))
tags = r.text

Extracting codes

url = 'http://dev.se.athento.comfile/api//getop/FILEID/op_characterize_codes'
r = requests.get(url, auth=(YOURUSER, YOURPASS))
tags = r.text

Change life cycle stages

Your documents may be in certain stages of what is called their life cycle, these operations allow you to move your documents forward and backward their life cycle stages.

Moving to next life cycle stage


Moving to previous life cycle state


Exporting data

To export metadata for a given document type, just do a GET call to this URL: http://dev.se.athento.comdoctypes/export/csv/DOCTYPEID/STARTDATE/ENDDATE/ where STARTDATE and ENDDATE use format %d/%m/%y. For example, to export metadata of documents created between 15 of december of 2014 and 20 of december of 2014 the dates will be 15/12/14 and 20/12/14.

A .csv file will be returned as result of the call which will use | as separator between values.

It is also possible to filter by state and by given series URL: http://dev.se.athento.comdoctypes/export/csv/DOCTYPEID/STARTDATE/ENDDATE/STATE/SERIEID,SERIEID where STATE is the state of a document, for example

and SERIEID is the identifier of a given serie. Following the same example, to filter by validated of the series with identifiers 23, and 56 the URL to use will look like this: http://dev.se.athento.comdoctypes/export/csv/DOCTYPEID/15/12/14/20/12/14/validated/23,56

If you want to export a CSV file to import in an accouting system such as SAGE, SAP or other, use this URL: http://dev.se.athento.comdoctypes/export/csv/accounting/all/15/12/14/20/12/14