AlgoDocs
API Reference
Contact us by sending an e-mail for any questions you may have related to this API.

Overview

The AlgoDocs API v1 is a set of HTTP endpoints that help your app integrate with AlgoDocs. This API Documentation will be helpful for any language of your choice.

On the right panel you will find commands along with their response messages.

To use this API, you need a Secret API key. Please register at https://algodocs.com/register to get your own API key if you haven't done so yet.

Authentication

All requests to AlgoDocs API are made with one of the authentications below. Every authentication method requires the use of an API key that you can obtain at your AlgoDocs account here.

  • Basic Auth
  • API Key

For testing your authentication method use the endpoint given below by setting appropriate parameters for each type of authentications as explained in the next sections.
GET https://api.algodocs.com/v1/me

In remaining sections we will use Basic Auth for demonstrating requests to the API.

Basic Auth


# CURL Request Example:

curl \
https://api.algodocs.com/v1/me \
--user '<email_address>:<api_key>'

With Basic Auth you can make requests to AlgoDocs API by passing two parameters as shown in the table below. These parameters are encoded in base64:
base64('<email_address>:<api_key>')

A sample response is shown on the right, which contains your full name and email address.


    JSON Response Example:

    {
        "fullName": "John Doe",
        "email": "john@example.com"
    }

HEADER PARAMETERS

Field Type Description
email_address String Your AlgoDocs account email address.
api_key String Your secret API key.

API Key


# CURL Request Example:

curl \
https://api.algodocs.com/v1/me \
-H 'x-api-key: <api_key>'

With API Key authentication you can make requests to AlgoDocs API by passing API Key only.

A sample response is shown on the right, which contains your full name and email address.



    JSON Response Example:

    {
        "fullName": "John Doe",
        "email": "john@example.com"
    }

HEADER PARAMETERS

Field Type Description
api_key String Your secret API key.

List Document Data Extractors


# CURL Request Example:

curl \
https://api.algodocs.com/v1/extractors \
--user '<email_address>:<api_key>'


    JSON Response Example:

    [
        {
            "id": "6d86215bf9cb4fc6ac1f6967",
            "name": "Invoice Extractor"
        },
        {
            "id": "6a0cdd3949444cf189e62416",
            "name": "Bank Statement Extractor"
        },
        {
            "id": "98b8a0332f39424e883bea24",
            "name": "Medical Reports Extractor"
        },
        ...
    ]

In order to get a list of extarctors from your account you can call an API with the endpoint shown on the right. This returns a list of extractors with id and name fields. The id field will be used in the following API calls.

GET https://api.algodocs.com/v1/extractors

A sample response is shown on the right, which contains a list of extractors you created in your account.

List Folders


# CURL Request Example:

curl \
https://api.algodocs.com/v1/folders \
--user '<email_address>:<api_key>'


    JSON Response Example:

    [
        {
            "id": "1a5e2f9c624b",
            "parentId": null,
            "name": "root"
        },
        {
            "id": "c40daa5550d9",
            "parentId": "1a5e2f9c624b",
            "name": "Invoices"
        },
        {
            "id": "tksa9ndu1p2f",
            "parentId": "1a5e2f9c624b",
            "name": "Bank Statements"
        },
        ...
    ]

AlgoDocs provides a file manager in which you can create folders and subfolders for organizing your documents. This API endpoint returns a list of folders with id, parentId and name fields. Where parentId is the id of the parent folder. The id field will be used in the following API calls when importing documents to AlgoDocs for specifying the folder under which to save the document.

GET https://api.algodocs.com/v1/folders

A sample response is shown on the right, which contains a list of folders you created in your file manager.

Import Documents

Using AlgoDocs API you can import documents to AlgoDocs by either one of the following two options:

  • Upload Document From Local Path
  • Upload Document From URL

Upload Document From Local Path


    
# CURL Request Example:
curl \
"https://api.algodocs.com/v1/document/upload_local/<extractor_id>/<folder_id>" \
-F "file=@path/to/your/file.pdf" \
--user '<email_address>:<api_key>'



    JSON Response Example:

    {
        "id": 182609,
        "fileSize": 136925,
        "fileMD5CheckSum": "955C30272DC75F119F17023683A787D5",
        "uploadedAt": "2017-06-18T14:03:24Z"
    }

With this endpoint you can upload your local file to AlgoDocs.

This endpoint requires extractor_id and folder_id that are obtained when getting a list of extractors and folders from your AlgoDocs account. See Extractors and Folders sections respectively above.
In addition to these, a file parameter is set to the path of your file that is stored in your hard drive or network.

POST "https://api.algodocs.com/v1/document/upload_local/<extractor_id>/<folder_id>"

A sample response is shown on the right, which contains a document id and other related fields. Note that this id will be used in the following sections when extracting data, which is used as document_id.

QUERY PARAMETERS

Field Type Description
file String Local path of your file.

Upload Document From URL


    
# CURL Request Example:
curl \
"https://api.algodocs.com/v1/document/upload_url/<extractor_id>/<folder_id>" \
-F "url=https://api.algodocs.com/content/SampleInvoice.pdf" \
--user '<email_address>:<api_key>'



    JSON Response Example:

    {
        "id": 182610,
        "fileSize": 136925,
        "fileMD5CheckSum": "955C30272DC75F119F17023683A787D5",
        "uploadedAt": "2017-06-18T14:44:11Z"
    }

With this endpoint you can upload your file to AlgoDocs by fetching it from publicly available url.

This endpoint requires extractor_id and folder_id that are obtained when getting a list of extractors and folders from your AlgoDocs account. See Extractors and Folders sections respectively above.
In addition to these, a url parameter is set to the publicly available url of your file.

POST "https://api.algodocs.com/v1/document/upload_url/<extractor_id>/<folder_id>"

A sample response is shown on the right, which contains a document id and other related fields. Note that this id will be used in the following sections when extracting data, which is used as document_id.

QUERY PARAMETERS

Field Type Description
url String Publicly available url of your file.

Extracted Data

Using AlgoDocs API you can get extracted data of a single or multiple documents.

Get Extracted Data of a Single Document



# CURL Request Example:
curl \
"https://api.algodocs.com/v1/extracted_data/<document_id>" \
--user '<email_address>:<api_key>'



    JSON Response Example:

    [
        {
            "id": "5fe7608abd59783e98438b3e",
            "documentId": 182608,
            "uploadedAt": "2017-06-20T16:10:21Z",
            "processedAt": "2017-06-20T16:10:50Z",
            "fileName": "Invoice.pdf",
            "folderId": "078f5vn8ocoy",
            "mediaOriginal": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/original",
            "mediaExcel": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/excel",
            "mediaJson": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/json",
            "mediaXml": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/xml",
            "totalPages": 1,
            "pageNumber": 1,

            "InvoiceNumber": "11223344",
            "Date": "2017-04-15",
            "Amount": 1250.0,
            ...
        },
        ...
    ]

This API endpoint returns the extracted data of a single document. However, in cases when a document is split by AlgoDocs into multiple documents, i.e. when, for example, 'Apply to pages' option in extracting rules is set to 'Apply to each remaining page independently', then the returned data will have multiple records. Therefore, the returned data is always a list, not an object.

This endpoint requires document_id parameter that is obtained when uploading a document to AlgoDocs. See Documents section above.

GET "https://api.algodocs.com/v1/extracted_data/<document_id>"

A sample response is shown on the right, which contains a list of extracted data records. Each record in a list contains system generated fields from id to pageNumber. Remaining fields are user defined ones that come from the extractor for which user defines the rules to extract certain fields/data. So, in this response example we have InvoiceNumber, Date and Amount fields that are user defined.

Get Extracted Data of Multiple Documents


# CURL Request Example:
curl \
"https://api.algodocs.com/v1/extracted_data/<extractor_id>" \
--user '<email_address>:<api_key>'

# CURL Request Example (with optional parameters):
curl \
"https://api.algodocs.com/v1/extracted_data/<extractor_id>?folderId=<folder_id>&limit=<limit>&date=<date>" \
--user '<email_address>:<api_key>'



    JSON Response Example:

    [
        {
            "id": "5fe627aabd5978699892bd36",
            "documentId": 182584,
            "uploadedAt": "2017-06-20T17:55:46Z",
            "processedAt": "2017-06-20T17:55:54Z",
            "fileName": "Invoice-3.pdf",
            "folderId": "fi4w58ws7d6a",
            "mediaOriginal": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/original",
            "mediaExcel": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/excel",
            "mediaJson": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/json",
            "mediaXml": "https://api.algodocs.com/v1/media/ZpRcE5Jit37OHUvbXCfkZ2SRYRwuf6JLKDgTwV4guKEnMB6Tvw7IJ3Tw6AOn8OCXUWDDdceB8zqOY5EWkczjyBChkkmwGhHfHh3qx2gTS5aKdE8BvrCvPTYSUWTtpivq/1/xml",
            "totalPages": 1,
            "pageNumber": 1,

            "InvoiceNumber": "45872154",
            "Date": "2017-03-11",
            "Amount": 4750.0,
            ...
        },
        {
            "id": "5fe7608abd59783e98438b3e",
            "documentId": 182608,
            "uploadedAt": "2017-06-20T16:10:21Z",
            "processedAt": "2017-06-20T16:10:50Z",
            "fileName": "Invoice.pdf",
            "folderId": "a8woh6w32rt4",
            "mediaOriginal": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/original",
            "mediaExcel": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/excel",
            "mediaJson": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/json",
            "mediaXml": "https://api.algodocs.com/v1/media/niGNFZgpj655iThANTDhIgE3lQoSagCbsBkw0PRhzAo7DeanCToefGYGdd1pbYOC4udg8l9xBWiHr70HgAQQsXwmceSnn2FammDJAtOQjqdSXROGMUIaIxKGxrDu2mJ8/1/xml",
            "totalPages": 1,
            "pageNumber": 1,

            "InvoiceNumber": "11223344",
            "Date": "2017-04-15",
            "Amount": 1250.0,
            ...
        },
        ...
    ]

This API endpoint returns the extracted data of multiple documents, which is identical to the previous endpoint above, but returns the extracted data for multiple documents instead for a single document.

This endpoint requires extractor_id parameter that can be obtained by calling GET https://api.algodocs.com/v1/extractors endpoint as explained above. All other parameters are optional. If limit parameter is not specified, then the default value for it is 10 000.

Date format
All dates in the API use UTC and are strings in the ISO 8601 "combined date and time representation" format, except that timezone information is excluded, since all dates in AlgoDocs are stored based on user's own timezone. Refer to your Settings in your account to set the proper timezone :
2017-06-21T10:45:52

GET "https://api.algodocs.com/v1/extracted_data/<extractor_id>"

QUERY PARAMETERS

Field Type Description
folder_id String [OPTIONAL] The id of the folder created under file manager of your account. This id can be obtained by calling GET https://api.algodocs.com/v1/folders endpoint.
date String [OPTIONAL] When this parameter is set, then extracted data of documents that are uploaded after this date will be returned. If number of records exceeds the maximum limit, which is 10 000, then only first 10 000 records will be returned starting from the date specified.
limit Integer [OPTIONAL] This parameter limits the number of extracted data records to return. So, if it is set, then returned data will have the extracted data for the last uploaded documents of size limit.