Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

Invoice Processing API

Automated invoice OCR, document processing, three-way matching, and accounts payable workflow automation.

Overview

Attribute	Value
Base Path	`/api/v1/invoices`
Authentication	Bearer Token
Required Roles	`billing_admin`, `finance`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Invoice Upload & OCR

Upload Invoice

Upload an invoice for OCR processing.

POST /api/v1/invoices/upload

Request (multipart/form-data)

file: invoice.pdf
vendor_hint: "Sysco Foods"
po_number_hint: "PO-2026-0042"

Response

{
  "invoice_id": "inv_001",
  "status": "processing",
  "file_info": {
    "name": "invoice.pdf",
    "size_bytes": 245678,
    "pages": 2,
    "type": "application/pdf"
  },
  "processing": {
    "estimated_completion_seconds": 15,
    "ocr_engine": "vision_ai"
  },
  "created_at": "2026-01-24T19:30:00Z"
}

Get Invoice

Retrieve processed invoice with extracted data.

GET /api/v1/invoices/{invoice_id}

Response

{
  "id": "inv_001",
  "status": "extracted",
  "vendor": {
    "id": "vendor_sysco",
    "name": "Sysco Foods",
    "matched": true,
    "confidence": 0.98
  },
  "invoice_details": {
    "invoice_number": "INV-2026-78542",
    "invoice_date": "2026-01-20",
    "due_date": "2026-02-19",
    "payment_terms": "Net 30",
    "po_number": "PO-2026-0042",
    "confidence": 0.95
  },
  "amounts": {
    "subtotal": 2450.00,
    "tax": 196.00,
    "shipping": 0.00,
    "total": 2646.00,
    "currency": "USD",
    "confidence": 0.97
  },
  "line_items": [
    {
      "line_number": 1,
      "description": "Ground Beef 80/20 - 10lb case",
      "sku": "SYS-GB8020",
      "quantity": 5,
      "unit": "case",
      "unit_price": 89.99,
      "total": 449.95,
      "matched_inventory_item": "inv_item_001",
      "confidence": 0.94
    },
    {
      "line_number": 2,
      "description": "Chicken Breast Boneless - 40lb case",
      "sku": "SYS-CB40",
      "quantity": 3,
      "unit": "case",
      "unit_price": 125.00,
      "total": 375.00,
      "matched_inventory_item": "inv_item_002",
      "confidence": 0.96
    }
  ],
  "extracted_fields": {
    "remit_to_address": "P.O. Box 650061, Dallas, TX 75265",
    "ship_to_address": "123 Main St, San Francisco, CA 94105"
  },
  "ocr_metadata": {
    "processed_at": "2026-01-24T19:30:15Z",
    "processing_time_ms": 12500,
    "confidence_overall": 0.95,
    "pages_processed": 2,
    "fields_extracted": 28
  },
  "source_document": {
    "url": "https://storage.example.com/invoices/inv_001.pdf",
    "thumbnail_url": "https://..."
  }
}

Invoice Status Values

Status	Description
`uploaded`	File received
`processing`	OCR in progress
`extracted`	Data extracted
`needs_review`	Manual review required
`approved`	Approved for payment
`rejected`	Invoice rejected
`paid`	Payment processed

List Invoices

GET /api/v1/invoices

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status
`vendor_id`	string	Filter by vendor
`date_from`	date	Invoice date start
`date_to`	date	Invoice date end
`min_amount`	number	Minimum amount
`max_amount`	number	Maximum amount
`needs_review`	boolean	Filter needing review

Update Invoice

Correct or update extracted data.

PUT /api/v1/invoices/{invoice_id}

Request Body

{
  "invoice_details": {
    "invoice_number": "INV-2026-78542-CORRECTED"
  },
  "line_items": [
    {
      "line_number": 1,
      "quantity": 6,
      "total": 539.94
    }
  ],
  "amounts": {
    "subtotal": 2540.00,
    "total": 2743.20
  }
}

Three-Way Matching

Match Invoice

Perform three-way matching (Invoice, PO, Receipt).

POST /api/v1/invoices/{invoice_id}/match

Request Body

{
  "po_id": "po_001",
  "receiving_id": "recv_001",
  "options": {
    "tolerance_percent": 2,
    "allow_partial_match": true
  }
}

Response

{
  "invoice_id": "inv_001",
  "match_result": "partial_match",
  "overall_confidence": 0.92,
  "po_match": {
    "po_id": "po_001",
    "po_number": "PO-2026-0042",
    "status": "matched",
    "vendor_match": true,
    "line_items_matched": 8,
    "line_items_total": 10
  },
  "receiving_match": {
    "receiving_id": "recv_001",
    "status": "partial",
    "quantities_match": false,
    "discrepancies": [
      {
        "line_item": 3,
        "description": "Tomatoes - 25lb case",
        "ordered_qty": 10,
        "received_qty": 8,
        "invoiced_qty": 10,
        "variance": -2,
        "suggestion": "Adjust invoice to received quantity"
      }
    ]
  },
  "amount_match": {
    "po_amount": 2650.00,
    "invoice_amount": 2646.00,
    "variance": -4.00,
    "variance_percent": -0.15,
    "within_tolerance": true
  },
  "exceptions": [
    {
      "type": "quantity_mismatch",
      "severity": "warning",
      "line_item": 3,
      "message": "Invoiced quantity exceeds received quantity"
    }
  ],
  "recommended_action": "approve_with_adjustment",
  "adjustment_amount": -25.00
}

Match Result Values

Result	Description
`full_match`	All items match within tolerance
`partial_match`	Some discrepancies found
`no_match`	Significant discrepancies
`no_po`	No purchase order found
`no_receipt`	No receiving record found

Get Match History

GET /api/v1/invoices/{invoice_id}/match-history

Approval Workflow

Submit for Approval

POST /api/v1/invoices/{invoice_id}/submit

Request Body

{
  "approver_id": "user_001",
  "notes": "Rush order - approved by manager",
  "bypass_match": false
}

Response

{
  "invoice_id": "inv_001",
  "approval_status": "pending",
  "submitted_at": "2026-01-24T19:35:00Z",
  "approvers": [
    {
      "user_id": "user_001",
      "name": "Finance Manager",
      "required": true,
      "status": "pending"
    }
  ],
  "routing_rule": "amount_over_1000"
}

Approve Invoice

POST /api/v1/invoices/{invoice_id}/approve

Request Body

{
  "notes": "Approved - quantities verified with receiving",
  "payment_date": "2026-02-15",
  "gl_coding": [
    {
      "line_item": 1,
      "account": "5100-Food-Meat",
      "department": "Kitchen",
      "amount": 449.95
    }
  ]
}

Reject Invoice

POST /api/v1/invoices/{invoice_id}/reject

Request Body

{
  "reason": "price_discrepancy",
  "notes": "Unit price does not match agreed contract price",
  "request_credit": true
}

Get Approval Queue

GET /api/v1/invoices/approval-queue

Query Parameters

Parameter	Type	Description
`approver_id`	string	Filter by approver
`priority`	string	`high`, `normal`, `low`
`aging`	string	`today`, `this_week`, `overdue`

Payment Processing

Schedule Payment

POST /api/v1/invoices/{invoice_id}/schedule-payment

Request Body

{
  "payment_date": "2026-02-15",
  "payment_method": "ach",
  "bank_account_id": "bank_001"
}

Mark as Paid

POST /api/v1/invoices/{invoice_id}/mark-paid

Request Body

{
  "payment_date": "2026-02-15",
  "payment_reference": "ACH-2026-0042",
  "amount_paid": 2646.00
}

Get Payment Status

GET /api/v1/invoices/{invoice_id}/payment-status

Vendor Management

Get Vendor Invoice Summary

GET /api/v1/invoices/vendors/{vendor_id}/summary

Response

{
  "vendor_id": "vendor_sysco",
  "vendor_name": "Sysco Foods",
  "summary": {
    "invoices_ytd": 45,
    "total_spend_ytd": 125000.00,
    "avg_invoice_amount": 2777.78,
    "invoices_pending": 3,
    "pending_amount": 8500.00,
    "invoices_overdue": 0
  },
  "payment_terms": "Net 30",
  "avg_payment_days": 28,
  "early_payment_discount": {
    "terms": "2/10 Net 30",
    "savings_ytd": 1250.00
  },
  "price_accuracy": {
    "match_rate": 0.95,
    "common_discrepancies": ["quantity_variance", "tax_calculation"]
  }
}

Analytics

Get AP Analytics

GET /api/v1/invoices/analytics

Query Parameters

Parameter	Type	Description
`period`	string	`month`, `quarter`, `year`
`location_id`	uuid	Filter by location

Response

{
  "period": "month",
  "summary": {
    "total_invoices": 125,
    "total_amount": 85000.00,
    "avg_processing_time_hours": 4.2,
    "auto_match_rate": 0.78,
    "exception_rate": 0.12
  },
  "by_vendor": [
    {
      "vendor": "Sysco Foods",
      "invoices": 12,
      "amount": 32000.00,
      "match_rate": 0.92
    }
  ],
  "by_category": [
    {"category": "Food", "amount": 45000.00, "percent": 53},
    {"category": "Beverages", "amount": 15000.00, "percent": 18},
    {"category": "Supplies", "amount": 12000.00, "percent": 14}
  ],
  "aging": {
    "current": 25000.00,
    "1_30_days": 35000.00,
    "31_60_days": 15000.00,
    "over_60_days": 10000.00
  },
  "savings_opportunities": {
    "early_payment_available": 2500.00,
    "duplicate_invoices_detected": 2,
    "price_variances_flagged": 8
  }
}

Webhooks

Event	Description
`invoice.uploaded`	Invoice file uploaded
`invoice.processed`	OCR extraction complete
`invoice.needs_review`	Manual review required
`invoice.approved`	Invoice approved
`invoice.rejected`	Invoice rejected
`invoice.paid`	Payment processed
`invoice.match_exception`	Three-way match exception

Error Responses

Status	Code	Description
400	`invalid_file`	File format not supported
400	`extraction_failed`	OCR extraction failed
404	`invoice_not_found`	Invoice ID not found
404	`po_not_found`	Purchase order not found
409	`already_approved`	Invoice already approved
422	`match_failed`	Three-way match failed

Inventory API - Inventory management
Vendor Management - Vendor setup
AP Workflow Guide - AP automation

Overview​

Invoice Upload & OCR​

Upload Invoice​

Get Invoice​

Invoice Status Values​

List Invoices​

Update Invoice​

Three-Way Matching​

Match Invoice​

Match Result Values​

Get Match History​

Approval Workflow​

Submit for Approval​

Approve Invoice​

Reject Invoice​

Get Approval Queue​

Payment Processing​

Schedule Payment​

Mark as Paid​

Get Payment Status​

Vendor Management​

Get Vendor Invoice Summary​

Analytics​

Get AP Analytics​

Webhooks​

Error Responses​

Related Documentation​

Overview

Invoice Upload & OCR

Upload Invoice

Get Invoice

Invoice Status Values

List Invoices

Update Invoice

Three-Way Matching

Match Invoice

Match Result Values

Get Match History

Approval Workflow

Submit for Approval

Approve Invoice

Reject Invoice

Get Approval Queue

Payment Processing

Schedule Payment

Mark as Paid

Get Payment Status

Vendor Management

Get Vendor Invoice Summary

Analytics

Get AP Analytics

Webhooks

Error Responses

Related Documentation