Inboxes

An inbox is a collection of documents that should be processed in the same way. You can think of an inbox as a container for specific type of documents, for example invoices, which helps you define and organize your document processing. Every inbox is associated with a document processing pipeline which performs data extraction from inbox documents.

Typically you would first create an inbox based on a specific pipeline, upload documents to it for processing and finally download the extracted information in a structured format.

Note

Many of the inbox management operations below are also available from smartextract's web interface. To programatically manipulate an existing inbox, you can find its id in the inbox settings screen (⚙).

Creating an inbox

To create an inbox, you first need to know the id of the processing pipeline want to associate to it. You may want to create a dedicated pipeline for your new inbox; see here for instructions on how to do that. Once the pipeline id is available, create an inbox with a POST request to /inboxes:

curlPython

curl -X 'POST' 'https://api.smartextract.ai/inboxes' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer API_TOKEN' \
  -d '{
    "name": "INBOX_NAME",
    "pipeline_id": "PIPELINE_ID",
  }'

import httpx
response = httpx.post(
    url='https://api.smartextract.ai/inboxes/',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer API_TOKEN'
    },
    json={
        'name': 'INBOX_NAME',
        'pipeline_id': 'PIPELINE_ID'
    }
)
print(response.json())

The response contains the id of the new inbox.

It is a good practice to give your inbox clear and descriptive name reflecting the type of documents you are going to upload to it.

Uploading documents to an inbox

There are two different methods of uploading the document to an inbox: via API requests or via email. Uploading documents to an API endpoint is a simpler option for developers because it requires no prior setup. Uploading the documents via email on the other hand is only possible once this option is activated but then you don't have to call API anymore. Let's look at both of these options in detail.

Upload a document via REST API

Assuming you have the right permissions for the inbox, you can upload a document to an inbox with a POST request to /inboxes/INBOX_ID:

curlPython

curl -X 'POST' 'https://api.smartextract.ai/inboxes/INBOX_ID' \
  -H 'Authorization: Bearer API_TOKEN' \
  -F 'document=@DOCUMENT_PATH;type=application/pdf'

import httpx
with open('DOCUMENT_PATH', 'rb') as file:
    response = httpx.post(
        url='https://api.smartextract.ai/inboxes/INBOX_ID',
        headers={
            'Accept': 'application/json',
            'Authorization': 'Bearer API_TOKEN'
        },
        files={
            'document': (
                file.name, 
                file, 
                'application/pdf'
            )
        }
    )
    print(response.json())

This example assumes that your document is a PDF file. If you want to submit an image, adjust the media type accordingly.

Email document ingestion

To enable uploading documents via email you first have to activate an inbox email address. This is done with a POST request on /inboxes/INBOX_ID/emails:

curlPython

curl -X 'POST' 'https://api.smartextract.ai/inboxes/INBOX_ID/emails' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer API_TOKEN' \
  -d ''

import httpx
response = httpx.post(
    url='https://api.smartextract.ai/inboxes/INBOX_ID/emails',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer API_TOKEN'
    }
)
print(response.json())

The response contains a generated inbox email address. You can also view the inbox email address with a GET request to /inboxes/INBOX_ID/emails:

curlPython

curl -X 'GET' 'https://api.smartextract.ai/inboxes/INBOX_ID/emails' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer API_TOKEN'

import httpx
response = httpx.get(
    url='https://api.smartextract.ai/inboxes/INBOX_ID/emails',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer API_TOKEN'
    }
)
print(response.json())

After that, you will be able to add one or more documents to your inbox by sending a message with PDF attachments to the given email address. Note that only PDF attachments will be ingested via email; documents in image format must be uploaded through the REST API.

Downloading document extractions

When you upload the documents to an inbox, they are automatically processed and the relevant information is extracted in a structured format. You can download the extraction results of all inbox documents in JSON or in CSV format with a GET request to /inboxes/INBOX_ID/extractions. To receive the extraction in JSON format include Accept: application/json header:

curlPython

curl -X 'GET' 'https://api.smartextract.ai/inboxes/INBOX_ID/extractions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer API_TOKEN'

import httpx
response = httpx.get(
    url='https://api.smartextract.ai/inboxes/INBOX_ID/extractions',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer API_TOKEN'
    }
)
print(response.json())

To receive the extraction in CSV format include Accept: text/csv header:

curlPython

curl -X 'GET' 'https://api.smartextract.ai/inboxes/INBOX_ID/extractions' \
  -H 'Accept: text/csv' \
  -H 'Authorization: Bearer API_TOKEN'

import httpx
response = httpx.get(
    url='https://api.smartextract.ai/inboxes/INBOX_ID/extractions',
    headers={
        'Accept': 'text/csv',
        'Authorization': 'Bearer API_TOKEN'
    }
)
print(response.text)

By default, this request returns the extraction of the 100 most recent inbox documents. You can use pagination parameters to modify this behavior.

You can also download the extraction information of an individual document. To do that, you first have to determine the document id and then send a GET request to /documents/DOCUMENT_ID/extraction:

curlPython

curl -X 'GET' 'https://api.smartextract.ai/documents/DOCUMENT_ID/extraction' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer API_TOKEN'

import httpx
response = httpx.get(
    url='https://api.smartextract.ai/documents/DOCUMENT_ID/extraction',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer API_TOKEN'
    }
)
print(response.json())

Managing inboxes

Listing inbox content

To list the documents in an inbox, send a GET request to /inboxes/INBOX_ID/documents:

curlPython

curl -X 'GET' 'https://api.smartextract.ai/inboxes/INBOX_ID/documents' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer API_TOKEN'

import httpx
response = httpx.get(
    url='https://api.smartextract.ai/inboxes/INBOX_ID/documents',
    headers={
        'Accept': 'application/json',
        'Authorization': 'Bearer API_TOKEN'
    }
)
print(response.json())

This request supports pagination and sorting with query parameters.

Delete a document from an inbox

If you want to remove a document from your inbox you first need to identify the document id. This can be achieved by listing the documents in your inbox.

Provided you know the document id, the document can be removed with a DELETE request on /documents/DOCUMENT_ID:

curlPython

curl -X 'DELETE' 'https://api.smartextract.ai/documents/DOCUMENT_ID' \
  -H 'Accept: */*' \
  -H 'Authorization: Bearer API_TOKEN'

import httpx
httpx.delete(
    url='https://api.smartextract.ai/documents/DOCUMENT_ID',
    headers={
        'Authorization': 'Bearer API_TOKEN'
    }
)

Warning

This operation cannot be undone.

An inbox you own can be shared with another smartextract user using the following POST request on /resources/INBOX_ID/permissions:

curlPython

curl -X 'POST' 'https://api.smartextract.ai/resources/INBOX_ID/permissions' \
  -H 'Accept: */*' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "user": "USER_EMAIL",
    "level": "view"
  }'

import httpx
httpx.post(
    url='https://api.smartextract.ai/resources/INBOX_ID/permissions',
    headers={
        'Authorization': 'Bearer API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'user': 'USER_EMAIL',
        'level': 'view'
    }
)

Inboxes

Creating an inbox

Uploading documents to an inbox

Upload a document via REST API

Email document ingestion

Downloading document extractions

Managing inboxes

Listing inbox content

Delete a document from an inbox

Share the inbox with another user