> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vlm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Parsing Invoices

> Extract structured data from invoices.

<Card title="Invoice Parsing Demo" icon="file-invoice" href="https://app.vlm.run/playground/document.invoice" cta="Try now">
  Navigate over to the invoice-parsing playground in our [playground](https://app.vlm.run/playground/document.invoice) to see the invoice parsing in action.
</Card>

`vlm-1` can extract structured data from invoices, along with their [visual grounding](/guides/doc-ai/guide-visual-grounding) in PDF or image format. Here's a step-by-step guide on how to parse an invoice:

Here is a visualization of the parsed invoice along with the visual grounding that `vlm-1` can extract from an invoice. Notice that only the specific items requested in the schema are retrieved and visualized, unlike OCR which returns all text in the document with no context:

<Frame caption="Parsing an invoice with visual grounding enabled">
  <img src="https://mintcdn.com/autonomiai/hv1ZFyEZ1wMYWx0b/guides/doc-ai/images/sample-invoice-w-grounding.jpg?fit=max&auto=format&n=hv1ZFyEZ1wMYWx0b&q=85&s=8e140aab429a1681c4897151f0f9e358" style={{ display: "block", margin: "0 auto" }} width="80%" data-path="guides/doc-ai/images/sample-invoice-w-grounding.jpg" />
</Frame>

<Tip>
  For higher-quality results, we recommend enabling [Visual Grounding](/guides/doc-ai/guide-visual-grounding) to help the model understand the invoice and extract more accurate information. See [High-Accuracy Parsing with Grounding](#high-accuracy-parsing-with-grounding) for more details.
</Tip>

## Parsing Invoices in 2 Steps

<Steps>
  <Step title="Submit an Invoice Parsing Job">
    <CodeGroup>
      ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
      from pathlib import Path
      from vlmrun.client import VLMRun
      from vlmrun.client.types import FileResponse

      # Initialize the client
      client = VLMRun(api_key="<your-api-key>")

      # Submit the invoice for parsing
      response: PredictionResponse = client.document.generate(
          file=Path("<path/to/invoice.pdf>"),
          domain="document.invoice",
          batch=True,
      )
      print(f"Job submitted:\n {response.model_dump()}")
      ```

      ```typescript Node.js SDK theme={"theme":{"light":"github-light","dark":"dark-plus"}}
      import { VlmRun } from "vlmrun";

      // Initialize the client
      const client = new VlmRun({
        apiKey: "<your-api-key>",
      });

      // Submit the invoice for parsing
      const response = await client.document.generate({
        file: "<path/to/invoice.pdf>",
        domain: "document.invoice",
        batch: true,
      });

      // Wait for the job to complete
      const job = await client.predictions.wait(response.id);
      console.log(job);
      ```
    </CodeGroup>

    You should see a response like this:

    ```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    Job submitted:
    {
      "id": "052cf2a8-2b84-45f5-a385-ccac2aae13bb",
      "created_at": "2024-08-15T02:22:09.157788",
      "response": null,
      "status": "pending"
    }
    ```
  </Step>

  <Step title="Wait for the Job to Complete">
    You can now wait for the job to complete by calling the `predictions.wait` method:

    <CodeGroup>
      ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
      # Wait for the job to complete
      response: PredictionResponse = client.predictions.wait(
          id=response.id,
          timeout=120,
      )
      print(f"Job completed:\n {response.model_dump()}")
      ```

      ```typescript Node.js SDK theme={"theme":{"light":"github-light","dark":"dark-plus"}}
      // Wait for the job to complete
      const job = await client.predictions.wait(response.id);
      console.log(job);
      ```
    </CodeGroup>
  </Step>
</Steps>

You should see a response like this:

```json [expandable] theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
    "id": "052cf2a8-2b84-45f5-a385-ccac2aae13bb",
    "created_at": "2024-08-15T02:22:09.157788",
    "status": "completed",
    "response": {
    "currency": "USD",
    "currency_metadata": {
      "bboxes": [
        {
          "content": "$19,647.68",
          "bbox": {
            "xywh": [0.843, 0.611, 0.084, 0.014]
          },
          "page": 0
        }
      ]
    },
    "customer": "Jane Smith",
    "customer_billing_address": {
      "city": "Mountain View",
      "city_metadata": {
        "bboxes": [
          {
            "content": "Mountain View, CA 94043",
            "bbox": {
              "xywh": [0.080, 0.194, 0.190, 0.014]
            },
            "page": 0
          }
        ]
      },
      "country": null,
      "country_metadata": null,
      "postal_code": "94043",
      "postal_code_metadata": {
        "bboxes": [
          {
            "content": "Mountain View, CA 94043",
            "bbox": {
              "xywh": [0.080, 0.194, 0.190, 0.014]
            },
            "page": 0
          }
        ]
      },
    }
    ...
    "items": [...],   // List of items in the invoice
    ...
    "total": 19647.68,
    "total_metadata": {
      "bboxes": [
        {
          "content": "$19,647.68",
          "bbox": {
            "xywh": [...]
          },
          "page": 0
        }
      ]
    }
  }
}
```

## High-Accuracy Parsing with Grounding

For higher-quality results, you can enable [Visual Grounding](/guides/doc-ai/guide-visual-grounding) to help the model understand the invoice and extract more accurate information. You can do this by setting the `config=GenerationConfig(grounding=True)` parameter when submitting the job (as shown below).

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  from vlmrun.client.types import GenerationConfig

  # Enable grounding when submitting the job
  response: PredictionResponse = client.document.generate(
      file=Path("<path/to/invoice.pdf>"),
      domain="document.invoice",
      batch=True,
      config=GenerationConfig(grounding=True),
  )
  ```

  ```typescript Node.js SDK theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  // Enable grounding when submitting the job
  const response = await client.document.generate({
    file: "<path/to/invoice.pdf>",
    domain: "document.invoice",
    batch: true,
    config: { grounding: true },
  });
  ```
</CodeGroup>

## Try our Document -> JSON API today

Head over to our [Document -> JSON](/api-reference/v1/post-document-generate) to start building your own document processing pipeline with [VLM Run](https://vlm.run). Sign-up for access on our [platform](https://app.vlm.run).