---
title: "ZeroInvoice API"
description: "Invoice, billing, time tracking, and customer management API with Stripe payments, QuickBooks sync, and semantic search"
canonical: "https://docs.ainative.studio/docs/business-ops/zeroinvoice"
last-updated: "2026-09-23T01:51:08.820Z"
---

# ZeroInvoice API

Source: https://docs.ainative.studio/docs/business-ops/zeroinvoice

> Invoice, billing, time tracking, and customer management API with Stripe payments, QuickBooks sync, and semantic search

## ZeroInvoice API

**Base URL:** `https://zeroinvoice.ainative.studio`  
**API Prefix:** `/api`  
**Auth:** JWT Bearer (httpOnly cookie or `Authorization: Bearer <token>`)  
**Source:** [github.com/AINative-Studio/ZeroInvoice](https://github.com/AINative-Studio/ZeroInvoice)

ZeroInvoice is a full invoice management platform with Stripe payments, QuickBooks sync, semantic search via ZeroDB, real-time WebSocket notifications, customer portals, and 2FA support.

:::tip Health Check
```bash
curl https://zeroinvoice.ainative.studio/api/health
## {"status":"healthy","service":"ZeroInvoice API"}
```
:::

---

## Authentication

ZeroInvoice uses **OAuth2 password flow** — login is form-encoded (not JSON).

### Register

```http
POST /api/auth/register
Content-Type: application/json

{"email": "user@example.com", "password": "securepassword", "full_name": "Jane Dev"}
```

### Login

```bash
curl -X POST https://zeroinvoice.ainative.studio/api/auth/login \
  -F "username=user@example.com" \
  -F "password=securepassword"
```

Returns a JWT token. Pass it as `Authorization: Bearer <token>` on subsequent requests.

### Auth Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/auth/register` | Register new user |
| `POST` | `/api/auth/login` | Login (form-encoded `username` + `password`) |
| `POST` | `/api/auth/logout` | Logout |
| `POST` | `/api/auth/refresh` | Refresh JWT |
| `GET` | `/api/auth/me` | Current user profile |
| `POST` | `/api/auth/request-password-reset` | Initiate password reset |
| `POST` | `/api/auth/reset-password` | Complete password reset |
| `POST` | `/api/auth/forgot-password` | Send reset email |
| `GET` | `/api/auth/ainative/authorize` | OAuth 2.0 redirect (AINative SSO) |
| `GET` | `/api/auth/ainative/callback` | OAuth 2.0 callback |

### Two-Factor Authentication

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/auth/2fa/setup` | Initialize 2FA (returns QR code) |
| `POST` | `/api/auth/2fa/verify` | Verify TOTP code |
| `POST` | `/api/auth/2fa/disable` | Disable 2FA |
| `POST` | `/api/auth/2fa/backup-codes` | Generate backup codes |
| `POST` | `/api/auth/2fa/verify-backup` | Verify backup code |

---

## Clients

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/clients/` | List clients |
| `POST` | `/api/clients/` | Create client |
| `GET` | `/api/clients/{client_id}` | Get client |
| `PUT` | `/api/clients/{client_id}` | Update client |
| `DELETE` | `/api/clients/{client_id}` | Delete client |
| `GET` | `/api/clients/search` | Semantic client search |
| `GET` | `/api/clients/{client_id}/payment-settings` | Get payment settings |
| `PATCH` | `/api/clients/{client_id}/payment-settings` | Update payment settings |
| `GET` | `/api/clients/{client_id}/analytics` | Client revenue analytics |
| `POST` | `/api/clients/merge` | Merge duplicate clients |
| `POST` | `/api/clients/merge/undo` | Undo client merge |
| `GET` | `/api/clients/{client_id}/merge-history` | Merge history |

**Create Client:**
```json
{
  "name": "Acme Corp",
  "email": "billing@acme.com",
  "phone": "+1-555-0100",
  "address": "123 Main St, San Francisco, CA 94102",
  "currency": "USD"
}
```

---

## Invoices

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/invoices/` | List invoices |
| `POST` | `/api/invoices/` | Create invoice |
| `GET` | `/api/invoices/{invoice_id}` | Get invoice |
| `PUT` | `/api/invoices/{invoice_id}` | Update invoice |
| `DELETE` | `/api/invoices/{invoice_id}` | Delete invoice |
| `PATCH` | `/api/invoices/{invoice_id}/status` | Update status |
| `GET` | `/api/invoices/search` | Semantic invoice search |
| `GET` | `/api/invoices/client/{client_id}` | Invoices by client |
| `GET` | `/api/invoices/overdue` | List overdue invoices |

**Status values:** `draft` → `sent` → `paid` / `overdue` / `cancelled`

**Create Invoice:**
```json
{
  "client_id": "uuid",
  "line_items": [
    {"description": "API integration", "quantity": 10, "unit_price": 150.00}
  ],
  "due_date": "2026-06-01",
  "currency": "USD",
  "notes": "Net 30"
}
```

---

## Customers (Extended Client Data)

These endpoints extend the `/api/clients/` resource with deeper customer management.

### Contact Persons

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/customers/{id}/contacts` | Add contact person |
| `GET` | `/api/customers/{id}/contacts` | List contacts |
| `GET` | `/api/customers/{id}/contacts/{contact_id}` | Get contact |
| `PUT` | `/api/customers/{id}/contacts/{contact_id}` | Update contact |
| `DELETE` | `/api/customers/{id}/contacts/{contact_id}` | Delete contact |
| `PATCH` | `/api/customers/{id}/contacts/{contact_id}/primary` | Set primary contact |

### Bank Accounts

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/customers/{id}/bank-accounts` | Add bank account (encrypted) |
| `GET` | `/api/customers/{id}/bank-accounts` | List bank accounts |
| `PATCH` | `/api/customers/{id}/bank-accounts/{account_id}` | Update bank account |
| `DELETE` | `/api/customers/{id}/bank-accounts/{account_id}` | Delete bank account |

### Credits

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/customers/{id}/credits` | List credits |
| `POST` | `/api/customers/{id}/credits` | Issue credit |
| `GET` | `/api/customers/{id}/credits/{credit_id}` | Get credit |
| `POST` | `/api/customers/{id}/credits/{credit_id}/apply` | Apply credit to invoice |
| `POST` | `/api/customers/{id}/credits/{credit_id}/refund` | Refund credit |
| `GET` | `/api/customers/{id}/credits/balance/total` | Total credit balance |

### Receivables & Portal

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/customers/{id}/receivables` | Receivables dashboard |
| `POST` | `/api/customers/{id}/portal/invite` | Send portal invitation |
| `POST` | `/api/customers/{id}/portal/resend-invite` | Resend invitation |
| `PATCH` | `/api/customers/{id}/portal/status` | Enable/disable portal access |
| `GET` | `/api/customers/{id}/portal/access-logs` | Portal access log |

---

## Payments

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/payments/` | List payments |
| `POST` | `/api/payments/` | Record payment |
| `GET` | `/api/payments/{payment_id}` | Get payment |
| `PUT` | `/api/payments/{payment_id}` | Update payment |
| `DELETE` | `/api/payments/{payment_id}` | Delete payment |
| `GET` | `/api/payments/search` | Search payments |
| `GET` | `/api/payments/invoice/{invoice_id}` | Payments for invoice |
| `GET` | `/api/payments/client/{client_id}` | Payments by client |
| `GET` | `/api/payments/invoice/{invoice_id}/total` | Total paid on invoice |
| `GET` | `/api/payments/summary` | Payment analytics |

---

## Payment Links

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/payment-links/` | List payment links |
| `POST` | `/api/payment-links/` | Create payment link |
| `GET` | `/api/payment-links/{id}` | Get payment link |
| `GET` | `/api/payment-links/{id}/stats` | Payment link stats |
| `PUT` | `/api/payment-links/{id}` | Update payment link |
| `DELETE` | `/api/payment-links/{id}` | Delete payment link |

---

## Estimates

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/estimates/` | List estimates |
| `POST` | `/api/estimates/` | Create estimate |
| `GET` | `/api/estimates/{id}` | Get estimate |
| `PUT` | `/api/estimates/{id}` | Update estimate |
| `DELETE` | `/api/estimates/{id}` | Delete estimate |
| `PATCH` | `/api/estimates/{id}/status` | Update status |
| `GET` | `/api/estimates/client/{client_id}` | Estimates by client |
| `GET` | `/api/estimates/status/expired` | Expired estimates |
| `POST` | `/api/estimates/convert-to-invoice` | Convert estimate to invoice |
| `GET` | `/api/estimates/analytics/summary` | Estimate analytics |
| `POST` | `/api/estimates/templates` | Create estimate template |
| `GET` | `/api/estimates/templates` | List estimate templates |
| `PATCH` | `/api/estimates/bulk/status` | Bulk status update |

---

## Recurring Invoices

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/recurring-invoices/` | List recurring invoices |
| `POST` | `/api/recurring-invoices/` | Create recurring invoice |
| `GET` | `/api/recurring-invoices/{id}` | Get recurring invoice |
| `PUT` | `/api/recurring-invoices/{id}` | Update recurring invoice |
| `DELETE` | `/api/recurring-invoices/{id}` | Delete recurring invoice |
| `PATCH` | `/api/recurring-invoices/{id}/status` | Pause / resume |
| `POST` | `/api/recurring-invoices/{id}/generate` | Generate next invoice now |
| `POST` | `/api/recurring-invoices/bulk-generate` | Bulk generate due invoices |
| `GET` | `/api/recurring-invoices/due-for-generation` | List due recurring invoices |
| `GET` | `/api/recurring-invoices/{id}/preview` | Preview next invoice |
| `GET` | `/api/recurring-invoices/{id}/generated-invoices` | History of generated invoices |
| `GET` | `/api/recurring-invoices/analytics/summary` | Recurring invoice analytics |
| `GET` | `/api/recurring-invoices/analytics/revenue-forecast` | Revenue forecast |
| `GET` | `/api/recurring-invoices/client/{client_id}` | Recurring invoices by client |

**Frequency values:** `weekly`, `monthly`, `quarterly`, `annually`

---

## Time Tracking

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/time-tracking/timer/start` | Start timer |
| `POST` | `/api/time-tracking/timer/{id}/stop` | Stop timer |
| `POST` | `/api/time-tracking/timer/{id}/pause` | Pause timer |
| `GET` | `/api/time-tracking/timer/running` | Get running timers |
| `POST` | `/api/time-tracking/entries` | Create time entry |
| `GET` | `/api/time-tracking/entries` | List time entries |
| `GET` | `/api/time-tracking/entries/{id}` | Get time entry |
| `PUT` | `/api/time-tracking/entries/{id}` | Update time entry |
| `DELETE` | `/api/time-tracking/entries/{id}` | Delete time entry |
| `PUT` | `/api/time-tracking/entries/bulk` | Bulk update entries |
| `GET` | `/api/time-tracking/report` | Time report |
| `POST` | `/api/time-tracking/convert-to-invoice` | Convert time entries to invoice |
| `GET` | `/api/time-tracking/analytics/by-client` | Time analytics by client |
| `GET` | `/api/time-tracking/analytics/by-project` | Time analytics by project |
| `GET` | `/api/time-tracking/suggestions` | AI-powered entry suggestions |

---

## Expenses

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/expenses/` | List expenses |
| `POST` | `/api/expenses/` | Create expense |
| `GET` | `/api/expenses/{id}` | Get expense |
| `PUT` | `/api/expenses/{id}` | Update expense |
| `DELETE` | `/api/expenses/{id}` | Delete expense |
| `GET` | `/api/expenses/categories` | List expense categories |
| `GET` | `/api/expenses/vendors` | List vendors |
| `POST` | `/api/expenses/{id}/receipt` | Upload receipt |
| `POST` | `/api/expenses/{id}/approve` | Approve expense |
| `POST` | `/api/expenses/{id}/reject` | Reject expense |
| `POST` | `/api/expenses/{id}/submit` | Submit for approval |
| `POST` | `/api/expenses/{id}/mark-reimbursed` | Mark reimbursed |
| `GET` | `/api/expenses/reports/summary` | Expense summary report |
| `GET` | `/api/expenses/reports/by-category` | Breakdown by category |
| `GET` | `/api/expenses/reports/by-vendor` | Breakdown by vendor |

---

## Projects

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/projects` | List projects |
| `POST` | `/api/projects` | Create project |
| `GET` | `/api/projects/{id}` | Get project |
| `PUT` | `/api/projects/{id}` | Update project |
| `DELETE` | `/api/projects/{id}` | Delete project |
| `GET` | `/api/projects/client/{client_id}` | Projects by client |
| `GET` | `/api/projects/summary` | Project summary |

---

## Invoice Templates

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/invoice-templates` | List templates |
| `POST` | `/api/invoice-templates` | Create template |
| `GET` | `/api/invoice-templates/default` | Get default template |
| `GET` | `/api/invoice-templates/{id}` | Get template |
| `PUT` | `/api/invoice-templates/{id}` | Update template |
| `DELETE` | `/api/invoice-templates/{id}` | Delete template |
| `POST` | `/api/invoice-templates/{id}/preview` | Preview rendered template |
| `POST` | `/api/invoice-templates/{id}/set-default` | Set as default |
| `POST` | `/api/invoice-templates/upload-logo` | Upload logo |

---

## Dashboard & Search

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/dashboard/metrics` | KPIs: MRR, outstanding, paid count |
| `POST` | `/api/search/` | Global semantic search |
| `POST` | `/api/search/invoices` | Search invoices |
| `POST` | `/api/search/clients` | Search clients |
| `POST` | `/api/search/line-items` | Search line items |
| `GET` | `/api/search/suggestions` | Search suggestions |

---

## Notifications

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/notifications` | List notifications |
| `GET` | `/api/notifications/{id}` | Get notification |
| `POST` | `/api/notifications/send` | Send notification |
| `POST` | `/api/notifications/{id}/retry` | Retry failed notification |
| `GET` | `/api/notifications/templates` | List templates |
| `POST` | `/api/notifications/templates` | Create template |
| `PUT` | `/api/notifications/templates/{id}` | Update template |
| `DELETE` | `/api/notifications/templates/{id}` | Delete template |
| `POST` | `/api/notifications/templates/initialize` | Initialize default templates |
| `WS` | `/api/notifications/ws` | Real-time WebSocket feed |

**Event triggers:**

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/notifications/trigger/invoice-created` | Fire invoice-created event |
| `POST` | `/api/notifications/trigger/invoice-sent` | Fire invoice-sent event |
| `POST` | `/api/notifications/trigger/invoice-paid` | Fire invoice-paid event |
| `POST` | `/api/notifications/trigger/payment-received` | Fire payment-received event |
| `POST` | `/api/notifications/trigger/reminder-sent` | Fire reminder-sent event |

---

## Reminders

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/reminders/check-and-send` | Run reminder check cycle |
| `POST` | `/api/reminders/send-immediate/{invoice_id}` | Send reminder immediately |
| `GET` | `/api/reminders/overdue-summary` | Overdue invoice summary |
| `GET` | `/api/reminders/schedule` | Get reminder schedule config |
| `PUT` | `/api/reminders/schedule` | Update reminder schedule |
| `GET` | `/api/reminders/status` | Reminder system status |
| `POST` | `/api/reminders/test-reminder/{invoice_id}` | Send test reminder |
| `GET` | `/api/reminders/history` | Reminder history |
| `DELETE` | `/api/reminders/{id}` | Delete reminder |

---

## Tasks (Scheduler)

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/tasks/start-scheduler` | Start background scheduler |
| `POST` | `/api/tasks/stop-scheduler` | Stop scheduler |
| `GET` | `/api/tasks/scheduler-status` | Scheduler status |
| `POST` | `/api/tasks/trigger-reminder-check` | Trigger reminder check now |
| `GET` | `/api/tasks/next-scheduled-run` | Next scheduled run time |
| `GET` | `/api/tasks/task-history` | Task execution history |

---

## Reports & Export

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/reports/tax-summary` | Tax summary |
| `GET` | `/api/reports/tax-by-client` | Tax breakdown by client |
| `GET` | `/api/reports/tax-export` | Export tax data |
| `GET` | `/api/reports/receivables-aging` | Aging receivables report |
| `GET` | `/api/export/invoices` | Export invoices (CSV/PDF) |
| `GET` | `/api/export/clients` | Export clients |
| `GET` | `/api/export/payments` | Export payments |

---

## Tax Reports

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/tax-reports` | List tax reports |
| `POST` | `/api/tax-reports/generate` | Generate tax report |
| `GET` | `/api/tax-reports/{id}` | Get tax report |
| `GET` | `/api/tax-reports/{id}/download` | Download tax report |
| `GET` | `/api/tax-reports/verify-sequence` | Verify invoice sequence (gap analysis) |
| `DELETE` | `/api/tax-reports/{id}` | Delete tax report |

---

## Import

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/import/invoices/validate` | Validate invoice import file |
| `POST` | `/api/import/invoices` | Import invoices |
| `POST` | `/api/import/clients/validate` | Validate client import file |
| `POST` | `/api/import/clients` | Import clients |

---

## Audit

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/audit/logs` | Full audit log |
| `GET` | `/api/audit/search` | Search audit log |
| `GET` | `/api/audit/user/{user_id}/activity` | Activity by user |
| `GET` | `/api/audit/resource/{type}/{id}/history` | Resource change history |
| `GET` | `/api/audit/statistics` | Audit statistics |
| `GET` | `/api/audit/my-activity` | Current user activity |
| `GET` | `/api/audit/compliance-report` | Compliance report |

---

## Activity Timeline

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/activity` | Activity feed |
| `GET` | `/api/activity/ws-stats` | WebSocket connection stats |
| `POST` | `/api/activity/track/invoice-created` | Track invoice-created event |
| `POST` | `/api/activity/track/payment-received` | Track payment-received event |

---

## Client Portal

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/client-portal/...` | Client-facing portal endpoints |

---

## QuickBooks Integration

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/integrations/quickbooks/status` | QuickBooks sync status |
| `POST` | `/api/integrations/quickbooks/sync` | Trigger bidirectional sync |
| `POST` | `/api/integrations/quickbooks/webhook` | QuickBooks webhook handler |

---

## Public Endpoints (No Auth)

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/public/quotes/{token}` | View public quote/estimate |
| `GET` | `/api/health` | Health check |