Parse Invoice

Endpoint Information

• URL: https://documents.teachprotege.ai/parse-invoice
• API Reference: https://documents.teachprotege.ai/docs
• Method: POST
• Summary: This endpoint processes uploaded invoices to extract structured data using advanced parsing techniques. It’s designed to handle various invoice formats efficiently, able to provide both detailed itemized data and summary information.

Core Functionality

Request

The request requires a multipart/form-data submission, which must include the invoice file along with optional settings to customize the parsing process.

Parameters

• file (binary): The invoice file to be parsed. This accepts PDF, JPEG, and PNG files. (required)
• first_page_only (boolean): If true, only the first page of the invoice is processed. This is helpful for optimizing spend when detailed item data is not required, generally the invoice summary data is found on the first page. Default is false.
• pre_process (boolean): If true, applies OCR pre-processing to improve data extraction accuracy. Default is true.
• resolution ("HIGH" | "LOW"): Select the image quality the be used in parsing strategy. Default is HIGH.
• process_items (boolean): If true, extracts detailed items data from the invoice. Default is false.
• process_summary (boolean): If true, extracts summary data from the invoice. Default is true.
• parsing_strategy ("sequential" | "parallel"): Parallel will run all your document's pages at the same time reducing the response time. Sequential adds page by page context extending extending out response times. Default is true.

Obtaining an API Key

Before making a request to the endpoint, you will need an API key for authorization. Please contact your Intuitive Systems account administrator to obtain an API key.

Response

This endpoint is highly opinionated and is built to return specific invoice fields - if you are looking for a more custom experience or additional fields please get in contact with us on how to use our fully customizable document-extract endpoint.

Given that this makes multiple calls to OCR and AI technologies, the response may take up to a minute depending on your settings and file complexity.

The reponse includes detailed usage metrics to help you understand the cost and efficiency of the parsing operation.

Success Response (200 OK)

Provides a JSON object containing the parsed invoice data, including both summary and detailed items, along with usage metrics.

Properties:

• summary: Object containing core summary data like invoice number, dates, sales info, etc.
• items: Array of objects detailing each item listed in the invoice.
• usage: Metrics about the parsing operation (e.g., tokens used, pages processed).

Validation Error (422)

Occurs when there is an error in the data format or missing required fields. The response includes details about the validation errors.

Examples

Request Example

The API is fully documented using OpenAPI 3.0. It is highly recommended to go to the following FastAPI Documentation to interact with the API.

cURL Example

To send a request to the /parse-invoice endpoint, use the following curl command:

curl -X 'POST' \
  'https://documents.teachprotege.ai/parse-invoice' \
  -H 'accept: application/json' \
  -H 'Authorization: <your_api_key>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'first_page_only=true' \
  -F 'pre_process=true' \
  -F 'process_items=true' \
  -F "file=@/path/to/invoice.pdf" \
  -F 'resolution=HIGH' \
  -F 'process_summary=true'

Response Example

{
  "data": {
    "summary": {
      "invoiceNumber": "12345",
      "PON": "PO1234",
      "invoiceDate": "2024-01-01",
      "shipDate": "2024-01-02",
      "soldToName": "Company A",
      "soldToAddress": "123 Business Rd, City, State"
    },
    "items": [
      {
        "itemNumber": "001",
        "itemSerialNumber": "SN001",
        "itemDescription": "Widget A",
        "itemPrice": "500",
        "itemQuantity": "2",
        "itemTotal": "1000"
      }
    ],
    "usage": {
      "input_tokens": 100,
      "output_tokens": 150,
      "num_pages": 1,
      "pre_process": true,
      "process_summary": true,
      "process_items": true,
      "high_res": false,
      "price": 0.045
    }
  }
}