Document AI API

Extract any concept from any document.

Introduction

With the SmartLens Document AI API, you can automatically convert unstructured information in your documents into actionable structured content. The API harnesses our proprietary AI technology to intelligently extract structured information (such as order totals, line items, and addresses) to be easily organized into a database or ERP. The API accepts an HTTP POST request with a JSON body as its input and returns the extracted items along with the raw text.

API response example

{
  "predictions": [
    {
      "extracted_text": "East Repair Inc.\n\n1912 Harvest Lane\nNew York, NY 12210\nBILL TO\n\nJohn Smith\n\n2 Court Square\nNew York, NV 12210\n\nSHIP TO\n\nJohn Smith\n\n3787 Pingview Drive\nCambridge, MA 12210\n\nINVOICE # us-001\nINVOICE DATE 11/02/2019\nP.O# 2312/2019\n\nDUE DATE 26/02/2019\nInvoice Total $154.06\nary DESCRIPTION UNIT PRICE AMOUNT\n1 Front and rear brake cables 100.00 100.00\n2 New set of pedal arms 15.00 30.00\n3 Labor 3hrs 5.00 15.00\nSubtotal 145.00\n\nSales Tax 6.25% 2.06\nTERMS & CONDITIONS\nPayment is due within 15 days\nPlease make checks payable to: East Repair Inc.",
      "extracted_items": {
        "merchant_name": "East Repair Inc.",
        "due_date": "26/02/2019",
        "issue_date": "11/02/2019",
        "invoice_id": "us-001",
        "total_payment": "$154.06",
        "tax": "6.25%",
        "subtotal": "145.00",
        "billing_address": "1912 Harvest Lane New York, NY 12210",
        "shipping_address": "3787 Pingview Drive Cambridge, MA 12210",
        "items": [
          {
            "description": "Front and rear brake cables",
            "price": "100.00"
          },
          {
            "description": "New set of pedal arms",
            "price": "15.00"
          },
          {
            "description": "Labor",
            "price": "3hrs 5.00"
          }
        ],
        "billing_recipient_name": "John Smith",
        "shipping_recipient_name": "John Smith",
        "payment_terms": "Payment is due within 15 days",
        "po_number": "2312/2019"
      }
    }
  ]
}

Making requests

The SmartLens Document AI API accepts PDF, JPEGand PNG files as inputs, either as a file encoded in base64 or as a URL. Like our other APIs, SmartLens Document AI accepts one input per request. To analyze multiple documents, you'll need to make multiple requests. To call the API, make a HTTP POST request with your API key submitted in the Authorization header. Send your document input using the document parameter in the request body.

SmartLens Document AI will automatically extract many fields by default. For a list, see the Automatic extractions section.

Request body example

{
  "document": "https://smartlens.ai/media-cdn/sample_invoice.png"
}
Optional

If you have unique documents with highly-customized fields, SmartLens Document AI can still extract them with no additional AI training. Simply make a Custom Extraction item and write in natural language the concept you would like the API to extract. Custom Extraction items are JSON dictionaries; add your description of your custom concept/form field using the natural_language_query key and your desired response schema using answer_key.

Let's say, for example, you want to extract the payment terms of a contract. You can create a Custom Extraction item, setting natural_language_query to a natural language string such as "What are the payment terms?" and answer_key to a string such as "payment_terms". Don't worry too much about crafting your natural_language_query in a particular way; SmartLens Document AI knows language well and should understand what you mean, but try to be as specific as possible. What you set answer_key to does not affect the quality of the API results, so set it to the most convenient value for you to parse the response JSON.

You can add up to 20 Custom Extraction items to a single request. We have an example of an API request body with two Custom Extraction items below.

Request body example with Custom Extractions

{
  "document": "https://smartlens.ai/media-cdn/sample_invoice.png",
  "custom_extractions": [
    {
      "natural_language_query": "What are the payment terms",
      "answer_key": "payment_terms"
    },
    {
      "natural_language_query": "Extract the P.O. number",
      "answer_key": "po_number"
    }
  ]
}

Putting the request body and authorization header together, below is a complete HTTP request. As the server expects a standard JSON payload, we must add backslash escape characters around all quotation marks inside the request body.

cURL

curl -X POST "https://api.smartlens.ai/v1/models/document-ai/predict" \
     -H "accept: application/json" \
     -H "Authorization: MY-API-KEY" \
     -H "Content-Type: application/json" \
     -d "{ \"document\": \"https://smartlens.ai/media-cdn/sample_invoice.png\", \"custom_extractions\": [ { \"natural_language_query\": \"What are the payment terms\", \"answer_key\": \"payment_terms\" }, { \"natural_language_query\": \"Extract the P.O. number\", \"answer_key\": \"po_number\" } ]}"

Using a client library

While you can always call our REST API directly, we've built client libraries to make it even easier to integrate SmartLens into your app. Our Python client library is now available, with many more coming soon.

With the SmartLens Python libary -- unlike calling the SmartLens API with cURL -- you also have the option of specifying a path to your file. Otherwise, supply the image payload exactly like you would for a direct HTTP request to the API. See the Making requests section for URL and base64 examples.

Python

import smartlens
smartlens.api_key = "MY_API_KEY"

response = smartlens.runDocumentAI(
   document = "MY-DOCUMENT (can be PDF, JPEG or PNG, submitted as a web URL, a path to a file, or as bytes encoded in base64)",
   customExtractions = [{'natural_language_query': 'What is the salary?', 'answer_key': 'employee_salary'}] # Custom extractions are optional
)

Automatic extractions

SmartLens Document AI extracts many types of concepts by default, and the full list is below. If you have unique documents with highly-customized fields, SmartLens Document AI can still extract them with no additional AI training. Please refer to the Making requests section for information on how to make Custom Extraction items.

  • total_payment - The total amount paid.
  • subtotal - The subtotal paid.
  • tax - The tax paid.
  • tip - The tip paid. Applies mostly to receipts.
  • items - A list of line items.
  • discount - The discount applied.
  • merchant_name - The name of a merchant on a document. Applies mostly to invoices and purchase orders.
  • invoice_id - The unique ID for your document. Applies mostly to invoices and purchase orders.
  • issue_date - The date the document is marked issued.
  • issue_time - The specific time the document is marked issued. Applies mostly to receipts.
  • due_date - The date the document is marked due.
  • contact_info - A phone number or an email contact.
  • billing_address - The billing address of the recipient. Applies mostly to invoices and purchase orders.
  • shipping_address - The shipping address of the recipient. Applies mostly to invoices and purchase orders.
  • merchant_address - The address of the merchant. Applies mostly to invoices and purchase orders.

API playground

We've built an API playground to make it even easier to explore our APIs. Check it out at https://api.smartlens.ai, which is also the base URL for the SmartLens API.

Questions & feedback

Please refer to the sidebar menu for API-specific quickstarts and detailed schema information. If you have any questions or feedback, please reach out to us at [email protected].

Jump to