Name: Invoice PO Matching API: Match Invoices to Purchase Orders
Brand: td-data-systems
SKU: api-td-data-systems-invoice-purchase-order-matching-api
Availability: InStock
Author: API Market

Tddatasystems

# Invoice Purchase Order Matching API

## Overview

The Invoice Purchase Order Matching API compares a supplier invoice with the purchase order it was raised against and tells you whether the two agree. It checks the supplier, currency and document totals, then pairs each invoice line with a purchase order line and compares quantities, unit prices and line totals. Every call returns a top-level `MATCH` or `REVIEW` decision, a line-by-line breakdown, and a list of exceptions with codes such as `PRICE_VARIANCE` and `TOTAL_VARIANCE`. There are two endpoints that return the same result shape: `/v1/po-match` takes invoice and purchase order data you have already structured as JSON, and `/v1/po-match-file` takes the two source documents (PDF, scanned PDF, PNG, JPG or text) and extracts the data itself before matching.

It is built for accounts payable teams, procurement and ERP integrations, and finance workflow tools that need to approve clean invoices automatically and send the rest to a person. The response gives you booleans for supplier, currency and totals checks, each matched line with its ordered and invoiced quantity, PO and invoice unit price, quantity and price variance and a per-line result, plus a confidence score, a `validation_status`, and an `ingestion` block that shows how each document was read (structured input, PDF text layer or OCR). Amounts are returned as decimal strings so they can be compared without floating point rounding.

## Features

*   **2 endpoints**: Match structured JSON data, or upload the invoice and purchase order files and match them in one call.
*   **JSON, PDF and image input**: The file endpoint accepts PDF, scanned PDF, PNG, JPG/JPEG and text documents, up to 7 MiB per file and 10 pages per PDF.
*   **Line-level matching**: Lines are paired by normalized SKU where available, with description matching as a fallback. Each PO line is matched only once.
*   **Clear decision**: Every response has `decision` set to `MATCH` or `REVIEW`, plus a `validation_status` of `PASSED` or `REVIEW_REQUIRED`.
*   **Structured exceptions**: Each discrepancy is returned with a code, a message and, for line issues, the invoice line and PO line involved.
*   **Deterministic arithmetic**: Price, quantity and total comparisons use decimal arithmetic. Responses report `external_ai_used`, which was `false` in all our tests.
*   **Extraction details**: The `ingestion` block reports the input type, page count, and whether the PDF text layer or OCR was used for each document.
*   **Rate limit**: 10 requests per second on every plan (Basic, Pro, Ultra and Mega).

## Use Cases

*   **Accounts payable automation**: Auto-approve invoices that come back `MATCH` and queue `REVIEW` results for an AP clerk.
*   **Two-way PO matching in ERPs**: Add an invoice-to-PO check to an ERP or procurement system before an invoice is posted for payment.
*   **Supplier overcharge detection**: Catch unit price increases, extra items and over-invoiced quantities before payment.
*   **Document intake pipelines**: Send scanned or emailed invoices and POs straight to the file endpoint without building your own extraction step.
*   **Exception routing**: Route each exception code to the right team, for example price variances to procurement and currency mismatches to finance.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/td-data-systems/invoice-purchase-order-matching-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Match Invoice to Purchase Order

Compares structured invoice and purchase order data and returns `MATCH` or `REVIEW` with line matches and exception details. Send each document as `{"data": {"header": {...}, "lines": [...]}}`. Amounts can be strings or numbers; strings such as `"55.00"` keep the exact decimal value.

**Method:** `POST`

**Endpoint:** `/v1/po-match`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `invoice` | body | The invoice, as an object with a `data` object holding `header` and `lines`. | object | Yes | - | - |
| `invoice.data.header` | body | Invoice header: `supplier_name`, `document_number`, `currency` (for example `GBP`) and `total`. | object | Yes | - | - |
| `invoice.data.lines` | body | Invoice lines. Each line has `sku`, `description`, `quantity`, `unit_price` and `line_total`. | array | Yes | - | - |
| `purchase_order` | body | The purchase order, in the same shape as `invoice`. | object | Yes | - | - |
| `purchase_order.data.header` | body | PO header: `supplier_name`, `document_number`, `currency` and `total`. | object | Yes | - | - |
| `purchase_order.data.lines` | body | PO lines, with the same fields as the invoice lines. | array | Yes | - | - |

**Example Request:**

In this example the invoice charges 55.00 per Blue Widget against a PO price of 50.00, so the invoice total is 130.00 against a PO total of 120.00.

```bash
curl -X POST "https://prod.api.market/api/v1/td-data-systems/invoice-purchase-order-matching-api/v1/po-match" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": {
      "data": {
        "header": {"supplier_name": "Northgate Supplies Ltd", "document_number": "INV-1001", "currency": "GBP", "total": "130.00"},
        "lines": [
          {"sku": "ABC-101", "description": "Blue Widget", "quantity": "2", "unit_price": "55.00", "line_total": "110.00"},
          {"sku": "XYZ-9", "description": "Delivery", "quantity": "1", "unit_price": "20.00", "line_total": "20.00"}
        ]
      }
    },
    "purchase_order": {
      "data": {
        "header": {"supplier_name": "Northgate Supplies Ltd", "document_number": "PO-5001", "currency": "GBP", "total": "120.00"},
        "lines": [
          {"sku": "ABC-101", "description": "Blue Widget", "quantity": "2", "unit_price": "50.00", "line_total": "100.00"},
          {"sku": "XYZ-9", "description": "Delivery", "quantity": "1", "unit_price": "20.00", "line_total": "20.00"}
        ]
      }
    }
  }'
```

**Example Response (200 OK):**

```json
{
  "decision": "REVIEW",
  "invoice_number": "INV-1001",
  "po_number": "PO-5001",
  "supplier_match": true,
  "currency_match": true,
  "totals_match": false,
  "line_matches": [
    {
      "invoice_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "55.00",
        "line_total": "110.00"
      },
      "po_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "50.00",
        "line_total": "100.00"
      },
      "match_basis": "SKU",
      "description_similarity": null,
      "ordered_quantity": "2",
      "invoiced_quantity": "2",
      "po_unit_price": "50.00",
      "invoice_unit_price": "55.00",
      "quantity_variance": "0",
      "price_variance": "5.00",
      "result": "REVIEW"
    },
    {
      "invoice_line": {
        "sku": "XYZ-9",
        "description": "Delivery",
        "quantity": "1",
        "unit_price": "20.00",
        "line_total": "20.00"
      },
      "po_line": {
        "sku": "XYZ-9",
        "description": "Delivery",
        "quantity": "1",
        "unit_price": "20.00",
        "line_total": "20.00"
      },
      "match_basis": "SKU",
      "description_similarity": null,
      "ordered_quantity": "1",
      "invoiced_quantity": "1",
      "po_unit_price": "20.00",
      "invoice_unit_price": "20.00",
      "quantity_variance": "0",
      "price_variance": "0.00",
      "result": "MATCH"
    }
  ],
  "exceptions": [
    {
      "code": "TOTAL_VARIANCE",
      "message": "Invoice total differs from purchase order total beyond tolerance"
    },
    {
      "code": "PRICE_VARIANCE",
      "message": "Invoice unit price differs from PO unit price beyond tolerance",
      "invoice_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "55.00",
        "line_total": "110.00"
      },
      "po_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "50.00",
        "line_total": "100.00"
      }
    }
  ],
  "confidence": 0.66,
  "validation_status": "REVIEW_REQUIRED",
  "ingestion": {
    "invoice": {
      "input_type": "structured",
      "page_count": null,
      "ocr_used": false,
      "text_layer_used": false
    },
    "purchase_order": {
      "input_type": "structured",
      "page_count": null,
      "ocr_used": false,
      "text_layer_used": false
    }
  },
  "job_id": "fb1b26f2-a2cf-4281-9a5c-1159b97aeecb",
  "external_ai_used": false
}
```

When the invoice and purchase order agree on supplier, currency, totals and every line, the same call returns `"decision": "MATCH"`, `"validation_status": "PASSED"`, an empty `exceptions` array and `"confidence": 1.0`.

**Response fields:**

| Field | Description |
|---|---|
| `decision` | `MATCH` when every check passed, `REVIEW` when at least one discrepancy was found. |
| `invoice_number`, `po_number` | Document numbers taken from the invoice and PO headers. |
| `supplier_match`, `currency_match`, `totals_match` | Header checks. `true` or `false`, or `null` when the value could not be compared. |
| `line_matches` | One entry per paired line, with `match_basis` (for example `SKU`), quantities, unit prices, `quantity_variance`, `price_variance` and a per-line `result`. |
| `exceptions` | Discrepancies found, each with a `code` and `message`. Line-level exceptions also include the `invoice_line` and `po_line`. |
| `confidence` | Score from 0 to 1. It was 1.0 for a clean match and lower when exceptions were raised. |
| `validation_status` | `PASSED` or `REVIEW_REQUIRED`. |
| `ingestion` | How each document was read: `input_type`, `page_count`, `ocr_used`, `text_layer_used`. |
| `job_id` | Unique ID for this matching job. |
| `external_ai_used` | Whether an external AI service was used to process the request. |

**Discrepancy codes:**

| Code | Meaning |
|---|---|
| `TOTAL_VARIANCE` | The invoice total differs from the purchase order total beyond tolerance. |
| `PRICE_VARIANCE` | An invoice unit price differs from the PO unit price beyond tolerance. The exception includes both lines. |
| `QUANTITY_EXCEEDED` | More units were invoiced than were ordered on the PO line. |
| `NOT_ON_PO` | An invoice line has no matching line on the purchase order. |
| `MISSING_ON_INVOICE` | A purchase order line does not appear on the invoice. |
| `SUPPLIER_MISMATCH` | The supplier on the invoice does not match the supplier on the PO. |
| `CURRENCY_MISMATCH` | The invoice and PO are in different currencies. |
| `DUPLICATE_LINE_MATCH` | More than one invoice line points at the same PO line. Each PO line is matched only once. |
| `AMBIGUOUS_LINE_MATCH` | A line could match more than one candidate, so it is reported rather than guessed. |
| `EXTRACTION_INCOMPLETE` | Data needed for the comparison could not be fully extracted from a document. |

`TOTAL_VARIANCE` and `PRICE_VARIANCE` are the codes returned in our tests. The other codes are listed by the provider.

#### 2. Match Invoice and Purchase Order Files

Uploads the invoice and purchase order documents as multipart form data, extracts their headers and lines, and returns the same result shape as endpoint 1. PDFs with a text layer are read directly; scanned PDFs and images are read with local OCR. The `ingestion` block tells you which method was used for each file.

**Method:** `POST`

**Endpoint:** `/v1/po-match-file`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `invoice_file` | form | The invoice document: PDF, scanned PDF, PNG, JPG/JPEG or text. | file | Yes | - | 7 MiB, 10 PDF pages |
| `purchase_order_file` | form | The purchase order document, in any of the same formats. | file | Yes | - | 7 MiB, 10 PDF pages |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/td-data-systems/invoice-purchase-order-matching-api/v1/po-match-file" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -F "invoice_file=@invoice.pdf" \
  -F "purchase_order_file=@po.pdf"
```

**Example Response (200 OK, abridged):**

```json
{
  "decision": "REVIEW",
  "invoice_number": "INV-1001",
  "po_number": "01 October 2026",
  "supplier_match": null,
  "currency_match": null,
  "totals_match": null,
  "line_matches": [
    {
      "invoice_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "55.00",
        "line_total": "110.00"
      },
      "po_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "50.00",
        "line_total": "100.00"
      },
      "match_basis": "SKU",
      "description_similarity": null,
      "ordered_quantity": "2",
      "invoiced_quantity": "2",
      "po_unit_price": "50.00",
      "invoice_unit_price": "55.00",
      "quantity_variance": "0",
      "price_variance": "5.00",
      "result": "REVIEW"
    }
  ],
  "exceptions": [
    {
      "code": "PRICE_VARIANCE",
      "message": "Invoice unit price differs from PO unit price beyond tolerance",
      "invoice_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "55.00",
        "line_total": "110.00"
      },
      "po_line": {
        "sku": "ABC-101",
        "description": "Blue Widget",
        "quantity": "2",
        "unit_price": "50.00",
        "line_total": "100.00"
      }
    }
  ],
  "confidence": 0.78,
  "validation_status": "REVIEW_REQUIRED",
  "ingestion": {
    "invoice": {
      "input_type": "pdf",
      "page_count": 1,
      "ocr_used": false,
      "text_layer_used": true
    },
    "purchase_order": {
      "input_type": "pdf",
      "page_count": 1,
      "ocr_used": false,
      "text_layer_used": true
    }
  },
  "job_id": "841f39f7-8ae0-4aba-9f52-d54c3d60b525",
  "external_ai_used": false
}
```

In this test both PDFs were read from their text layer and both lines were paired by SKU.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | Matching completed. Read `decision` and `exceptions` for the result; a `REVIEW` decision is still a 200. |
| 400 | Bad Request | The JSON body or form data is invalid, a required field or file is missing, or the document type is not supported. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path is wrong. Check the base URL and that the path is `/v1/po-match` or `/v1/po-match-file`. |
| 413 | Payload Too Large | An uploaded file is larger than 7 MiB. |
| 415 | Unsupported Media Type | An uploaded file is not a supported format (PDF, PNG, JPG/JPEG or text). |
| 422 | Unprocessable Entity | The documents failed validation or could not be extracted well enough to match. |
| 429 | Too Many Requests | You went over 10 requests per second, or you have used up your plan's request quota. |
| 500 | Internal Server Error | Something failed while matching the documents. Retry after a short delay. |

## Rate Limits

All four plans (Basic, Pro, Ultra and Mega) allow 10 requests per second. Each plan also has a hard request quota: Basic 10, Pro 250, Ultra 1,000 and Mega 3,000 requests. Requests above the per-second limit, or after the quota is used up, return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. In our tests a JSON match took about 0.7 to 1.1 seconds and a two-PDF file match about 1.2 seconds, so a batch job should send requests at a steady pace rather than in bursts.

## FAQ

**What is the difference between the two endpoints?**

`/v1/po-match` takes invoice and PO data you have already extracted, as JSON. `/v1/po-match-file` takes the two documents as files and extracts the data itself. Both return the same response shape.

**Does a REVIEW decision mean the request failed?**

No. A `REVIEW` decision is returned with status 200. It means the documents were compared and at least one discrepancy was found. The `exceptions` array lists what needs checking.

**How are invoice lines paired with PO lines?**

By normalized SKU where one is available, shown as `"match_basis": "SKU"`. When there is no SKU, the description is used. Each PO line is matched only once, and a conflicting SKU is not overridden by a similar description. Lines that cannot be paired cleanly are reported with codes such as `AMBIGUOUS_LINE_MATCH` or `NOT_ON_PO`.

**Should I send amounts as strings or numbers?**

Both are accepted. Strings such as `"55.00"` are safest because they keep the exact decimal value. Amounts in the response are always strings.

**Which file formats can I upload?**

PDF, scanned PDF, PNG, JPG/JPEG and text documents. Each file can be up to 7 MiB, and PDFs are limited to 10 pages. Check `ingestion.ocr_used` and `ingestion.text_layer_used` to see how each file was read.

**Why are `supplier_match`, `currency_match` or `totals_match` null?**

`null` means that check could not be made, usually because the header value was not found in an uploaded document. Treat it as needing review, or send the data through `/v1/po-match` if you already have it.

**Are my documents stored or sent to an AI service?**

The provider states that raw uploaded documents and full extracted text are not stored in its request ledger, and that no external AI service is needed to process requests. Every response includes `external_ai_used`, which was `false` in all our tests.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Invoice PO matching API that compares invoices with purchase orders from JSON, PDF or images and returns MATCH or REVIEW with price and total exceptions.

Invoice PO Matching API: Match Invoices to Purchase Orders

Basic