This tutorial will walk you through the process of parsing a basic invoice using extract API.

1

Create a document template

Create a document template by either using our pre-defined invoice templates or by uploading an example of your invoice.

Create Invoice Template
2

Build an extraction schema

Build a extraction schema to parse the invoice. Let’s extract the following fields:

  • totals object - invoice totals, including tax, subtotal, and total
  • vendor object - vendor details, including name and address
  • invoice object - invoice details, including date and number
  • line_items array - line items, including amount, quantity, unit price, and description
3

Test the template

Run the template on an example invoice to ensure it’s working as expected. You can also upload multiple invoices to test the template on different invoices.

Invoice Extraction Results
4

Using the API

Once you’ve tested the template and confirmed it’s working as expected, you can use the API to parse invoices.

You can retrieve your API keys from the settings page.

Basic usage of the API:

  1. Create an extraction using POST /extract
  2. Get the extraction jobId from the response
  3. Poll for results with a maximum duration using GET /extract?jobId

The following code demonstrates how to parse an invoice using the API.

import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config();

// Replace with your own values
const url = '<file-url>';
const templateId = '<template-id>';

const OMNI_API_URL = 'https://api.getomni.ai';
const options = {
  headers: {
    'x-api-key': process.env.OMNI_API_KEY,
    'Content-Type': 'application/json',
  },
};

const createExtraction = async (url: string, templateId: string) => {
  const data = { url, templateId };
  const response = await axios.post(`${OMNI_API_URL}/extract`, data, options);
  return response.data;
};

const getExtractionResult = async (extractionId: string) => {
  const response = await axios.get(`${OMNI_API_URL}/extract?jobId=${extractionId}`, options);
  return response.data;
};

const runExtraction = async (url: string, templateId: string) => {
  try {
    // Step 1: Initiate the extraction
    const extractionData = await createExtraction(url, templateId);

    // Step 2: Get the extraction jobId
    const extractionId = extractionData.jobId;

    // Step 3: Poll for results with a maximum duration
    let result;
    const pollingInterval = 2000; // 2 seconds between attempts
    const maxDurationMs = 1800000; // 3 minutes maximum polling duration
    const startTime = Date.now();

    while (Date.now() - startTime < maxDurationMs) {
      // Wait for the specified polling interval
      await new Promise((resolve) => setTimeout(resolve, pollingInterval));
      result = await getExtractionResult(extractionId);

      if (result.status === 'COMPLETE' || result.status === 'ERROR') {
        break;
      }
    }

    return result;
  } catch (error) {
    throw error;
  }
};

runExtraction(url, templateId)
  .then((result) => console.log(JSON.stringify(result, null, 2)))
  .catch((error) => console.error(error));