InvoiceXT API Documentation v1.0

Programmatic access to invoice extraction, bank reconciliation, and accounting integrations.

Getting Started

Base URL

All API requests are made to the following base URL:

Base URL

https://app.invoicext.com/api/v1

Creating an API Key

Navigate to Settings → API Keys in the InvoiceXT dashboard. Click Create Key, assign a name, select the required scopes, and copy the key. The key is shown only once.

Quick Start

Upload an invoice and extract structured data in one call:

curl

# Extract data from an invoice PDF
curl -X POST https://app.invoicext.com/api/v1/invoices/extract \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -F "file=@invoice.pdf"

Authentication

Authenticate every request by including your API key as a Bearer token in the Authorization header.

Header

Authorization: Bearer sk_live_your_key_here

API keys beginning with sk_live_ are production keys. Use sk_test_ keys for development and testing.

Code Examples

curl

curl https://app.invoicext.com/api/v1/invoices \
  -H "Authorization: Bearer sk_live_your_key_here"

JavaScript (fetch)

const res = await fetch("https://app.invoicext.com/api/v1/invoices", {
  headers: {
    "Authorization": `Bearer ${API_KEY}`
  }
});
const data = await res.json();
console.log(data);

Python (requests)

import requests

headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get("https://app.invoicext.com/api/v1/invoices", headers=headers)
data = resp.json()
print(data)

Response Format

All successful responses follow this envelope:

JSON

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_abc123"
  }
}

Error responses use this format:

JSON — Error

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message",
    "docs_url": "https://docs.invoicext.com/errors/error_code"
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_abc123"
  }
}

Rate Limits

Rate limits are enforced per API key on a rolling one-hour window.

Plan	Requests / hour
Starter	100
Pro	1,000
Business	10,000
Enterprise	100,000

Rate Limit Headers

Every response includes these headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

429 Too Many Requests

JSON — 429 Response

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 42 seconds.",
    "docs_url": "https://docs.invoicext.com/errors/rate_limit_exceeded"
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_abc123"
  }
}

Invoices

POST /api/v1/invoices/extract invoices:write

Upload an invoice file (PDF, PNG, JPG) and extract structured data using AI.

Request Body

Content-Type: multipart/form-data

Field	Type	Required	Description
`file`	File	Yes	Invoice file (PDF, PNG, JPG). Max 20 MB.

Example

curl

curl -X POST https://app.invoicext.com/api/v1/invoices/extract \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -F "file=@invoice.pdf"

Response 200

JSON

{
  "success": true,
  "data": {
    "id": "inv_8xKp2mNq",
    "status": "processed",
    "supplier": {
      "name": "Acme Supplies Ltd",
      "address": "123 Commerce St, London EC1A 1BB",
      "tax_id": "GB123456789"
    },
    "invoice_number": "INV-2026-0042",
    "invoice_date": "2026-04-01",
    "due_date": "2026-05-01",
    "currency": "GBP",
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 50,
        "unit_price": 12.00,
        "amount": 600.00
      },
      {
        "description": "Widget B",
        "quantity": 20,
        "unit_price": 25.50,
        "amount": 510.00
      }
    ],
    "totals": {
      "subtotal": 1110.00,
      "tax_rate": 20,
      "tax_amount": 222.00,
      "total": 1332.00
    },
    "confidence": 0.97,
    "created_at": "2026-04-14T12:30:00Z"
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_abc123"
  }
}

GET /api/v1/invoices invoices:read

Retrieve a paginated list of invoices.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`supplier`	string	—	Filter by supplier name (partial match)
`date_from`	string	—	Start date (YYYY-MM-DD)
`date_to`	string	—	End date (YYYY-MM-DD)
`currency`	string	—	Filter by ISO 4217 currency code

Example

curl

curl "https://app.invoicext.com/api/v1/invoices?page=1&limit=10&currency=USD" \
  -H "Authorization: Bearer sk_live_your_key_here"

Response 200

JSON

{
  "success": true,
  "data": {
    "invoices": [ /* array of invoice objects */ ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 47,
      "total_pages": 5
    }
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_def456"
  }
}

GET /api/v1/invoices/:invoiceId invoices:read

Retrieve a single invoice by its ID.

Path Parameters

Parameter	Type	Description
`invoiceId`	string	The invoice ID (e.g. `inv_8xKp2mNq`)

Example

curl

curl https://app.invoicext.com/api/v1/invoices/inv_8xKp2mNq \
  -H "Authorization: Bearer sk_live_your_key_here"

DELETE /api/v1/invoices/:invoiceId invoices:delete

Permanently delete an invoice and its extracted data.

Path Parameters

Parameter	Type	Description
`invoiceId`	string	The invoice ID

Example

curl

curl -X DELETE https://app.invoicext.com/api/v1/invoices/inv_8xKp2mNq \
  -H "Authorization: Bearer sk_live_your_key_here"

Response 200

JSON

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "inv_8xKp2mNq"
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_ghi789"
  }
}

POST /api/v1/invoices/:invoiceId/publish publish:qb publish:xero

Publish a processed invoice to QuickBooks or Xero.

Path Parameters

Parameter	Type	Description
`invoiceId`	string	The invoice ID

Request Body

Field	Type	Required	Description
`target`	string	Yes	`"quickbooks"` or `"xero"`

Example

curl

curl -X POST https://app.invoicext.com/api/v1/invoices/inv_8xKp2mNq/publish \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"target": "quickbooks"}'

Response 200

JSON

{
  "success": true,
  "data": {
    "published": true,
    "target": "quickbooks",
    "external_id": "qb_inv_99201",
    "published_at": "2026-04-14T12:31:00Z"
  },
  "meta": {
    "timestamp": "2026-04-14T12:31:00Z",
    "request_id": "req_jkl012"
  }
}

Bank Statements

POST /api/v1/bank/extract bank:write

Upload a bank statement (PDF or CSV) and extract transactions.

Request Body

Content-Type: multipart/form-data

Field	Type	Required	Description
`file`	File	Yes	Bank statement file (PDF, CSV). Max 20 MB.

Example

curl

curl -X POST https://app.invoicext.com/api/v1/bank/extract \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -F "file=@statement.pdf"

Response 200

JSON

{
  "success": true,
  "data": {
    "id": "bs_4rTw9xLm",
    "bank_name": "Chase",
    "account_number_last4": "7890",
    "period": { "from": "2026-03-01", "to": "2026-03-31" },
    "transactions_count": 124,
    "transactions": [ /* array of transaction objects */ ]
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_mno345"
  }
}

POST /api/v1/bank/reconcile bank:write

Reconcile bank transactions against extracted invoices. Matches payments to invoices automatically.

Request Body

Field	Type	Required	Description
`statement_id`	string	Yes	Bank statement ID
`date_from`	string	No	Start date (YYYY-MM-DD)
`date_to`	string	No	End date (YYYY-MM-DD)

Example

curl

curl -X POST https://app.invoicext.com/api/v1/bank/reconcile \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"statement_id": "bs_4rTw9xLm"}'

GET /api/v1/bank/reconciliations bank:read

List all reconciliation results with match summaries.

Example

curl

curl https://app.invoicext.com/api/v1/bank/reconciliations \
  -H "Authorization: Bearer sk_live_your_key_here"

Integrations

GET /api/v1/integrations/status settings:read

Check the connection status of QuickBooks and Xero integrations.

Example

curl

curl https://app.invoicext.com/api/v1/integrations/status \
  -H "Authorization: Bearer sk_live_your_key_here"

Response 200

JSON

{
  "success": true,
  "data": {
    "quickbooks": {
      "connected": true,
      "company_name": "My Company Inc.",
      "last_sync": "2026-04-14T10:00:00Z"
    },
    "xero": {
      "connected": false,
      "company_name": null,
      "last_sync": null
    }
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_pqr678"
  }
}

Usage

GET /api/v1/usage/stats settings:read

Retrieve API usage statistics for the current billing period.

Example

curl

curl https://app.invoicext.com/api/v1/usage/stats \
  -H "Authorization: Bearer sk_live_your_key_here"

Response 200

JSON

{
  "success": true,
  "data": {
    "plan": "pro",
    "billing_period": { "from": "2026-04-01", "to": "2026-04-30" },
    "invoices_processed": 312,
    "invoices_limit": 1000,
    "api_calls": 1847,
    "api_calls_limit": 50000
  },
  "meta": {
    "timestamp": "2026-04-14T12:30:00Z",
    "request_id": "req_stu901"
  }
}

Webhooks Coming Soon

Webhooks are currently in development and will be available in a future release. The following is a preview of the planned API.

Events

Event	Description
`invoice.processed`	Fired when an invoice has been successfully extracted
`invoice.published`	Fired when an invoice is published to QuickBooks or Xero
`bank.reconciled`	Fired when a bank reconciliation completes

Payload Format

JSON — Webhook Payload

{
  "event": "invoice.processed",
  "timestamp": "2026-04-14T12:30:00Z",
  "data": {
    "id": "inv_8xKp2mNq",
    "status": "processed",
    "invoice_number": "INV-2026-0042",
    "supplier": "Acme Supplies Ltd",
    "total": 1332.00,
    "currency": "GBP"
  },
  "webhook_id": "wh_evt_xYz789"
}

Retry Policy

Failed deliveries (non-2xx response) are retried with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry (final)	12 hours

After 5 failed retries, the webhook is marked as failed and can be retried manually from the dashboard.

Error Codes

When a request fails, the response includes an error code, HTTP status, and a human-readable message.

Code	HTTP Status	Description
`authentication_required`	401	No API key was provided in the request
`invalid_api_key`	401	The provided API key is invalid or has been revoked
`insufficient_scope`	403	The API key does not have the required scope for this endpoint
`rate_limit_exceeded`	429	Too many requests; retry after the reset window
`resource_not_found`	404	The requested resource does not exist
`validation_error`	400	The request body or parameters failed validation
`processing_error`	500	An internal error occurred while processing the request
`monthly_limit_reached`	429	Monthly invoice processing limit has been reached for your plan

API Scopes

When creating an API key, assign only the scopes your integration requires.

Scope	Description
`invoices:read`	Read and list invoices
`invoices:write`	Upload and extract invoices
`invoices:delete`	Delete invoices
`publish:qb`	Publish invoices to QuickBooks
`publish:xero`	Publish invoices to Xero
`bank:read`	Read bank statements and reconciliations
`bank:write`	Upload statements and run reconciliation
`settings:read`	Read integration status and usage statistics
`settings:write`	Modify account and integration settings
`team:read`	View team members and roles
`team:write`	Manage team members and roles

Test Your API

Use the ping endpoint to verify connectivity. No authentication is required.

GET /api/v1/ping

Health-check endpoint. Returns server status and API version. No authentication required.

Example

curl

curl https://app.invoicext.com/api/v1/ping

Response 200

JSON

{
  "pong": true,
  "version": "1.0",
  "status": "operational"
}

InvoiceXT API v1.0 — Need help? Contact api-support@invoicext.com