API Reference

Business plan

Integrate CleverInvo into your workflow. Manage clients, create invoices, and download PDFs programmatically.

Authentication

All API requests require a Bearer token. Create an API key from your dashboard, then include it in the Authorization header.

curl -X GET https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer cinv_your_api_key"

Clients

GET/api/v1/clients

List all active clients. Supports pagination and search.

Response

{
  "data": [
    {
      "id": "clx...",
      "name": "Acme Corp",
      "email": "[email protected]",
      "address": "123 Main St, New York, NY 10001",
      "taxId": "US-123456789",
      "phone": "+1-555-0100",
      "notes": "Net 30 terms",
      "isActive": true,
      "createdAt": "2024-01-15T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

POST/api/v1/clients

Create a new client. Subject to your plan's client limit.

Request body

{
  "name": "Acme Corp",
  "email": "[email protected]",
  "address": "123 Main St, New York, NY 10001",
  "taxId": "US-123456789",
  "phone": "+1-555-0100",
  "notes": "Net 30 terms"
}

Response

{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}

GET/api/v1/clients/:id

Get a single client by ID.

Response

{
  "data": {
    "id": "clx...",
    "name": "Acme Corp",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0100",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-01-15T00:00:00.000Z"
  }
}

PUT/api/v1/clients/:id

Update a client. All fields can be modified.

Request body

{
  "name": "Acme Corporation",
  "email": "[email protected]",
  "phone": "+1-555-0200"
}

Response

{
  "data": {
    "id": "clx...",
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Main St, New York, NY 10001",
    "taxId": "US-123456789",
    "phone": "+1-555-0200",
    "notes": "Net 30 terms",
    "isActive": true,
    "createdAt": "2024-01-15T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
}

DELETE/api/v1/clients/:id

Soft-delete a client. Sets isActive to false. Clients with existing invoices cannot be hard-deleted.

Response

204 No Content

Invoices

GET/api/v1/invoices

List invoices. Supports pagination, search, and filtering by clientId or status.

Response

{
  "data": [
    {
      "id": "clx...",
      "clientId": "clx...",
      "invoiceNumber": "INV-0001",
      "currency": "USD",
      "issueDate": "2024-06-01",
      "dueDate": "2024-07-01",
      "subtotal": 5000.00,
      "taxTotal": 500.00,
      "discountTotal": 0,
      "total": 5500.00,
      "status": "SENT",
      "createdAt": "2024-06-01T00:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "[email protected]"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

POST/api/v1/invoices

Create an invoice and automatically generate the PDF. Subject to plan limits.

Request body

{
  "clientId": "clx...",
  "invoiceNumber": "INV-0042",
  "currency": "USD",
  "issueDate": "2024-06-01",
  "dueDate": "2024-07-01",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Thank you for your business",
  "terms": "Payment due within 30 days"
}

Response

{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 5500.00,
    "status": "DRAFT"
  }
}

GET/api/v1/invoices/:id

Get full invoice details including line items and client info.

Response

{
  "data": {
    "id": "clx...",
    "clientId": "clx...",
    "invoiceNumber": "INV-0042",
    "currency": "USD",
    "issueDate": "2024-06-01",
    "dueDate": "2024-07-01",
    "lineItems": [
      {
        "description": "Web Development",
        "quantity": 40,
        "unitPrice": 125.00,
        "amount": 5000.00,
        "taxRate": 10
      }
    ],
    "subtotal": 5000.00,
    "taxTotal": 500.00,
    "discountTotal": 0,
    "total": 5500.00,
    "status": "SENT",
    "notes": "Thank you for your business",
    "terms": "Payment due within 30 days",
    "sentViaEmail": true,
    "sentAt": "2024-06-01T12:00:00.000Z",
    "paidAt": null,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "client": {
      "name": "Acme Corp",
      "email": "[email protected]"
    }
  }
}

PUT/api/v1/invoices/:id

Update an invoice. Only DRAFT invoices can be modified.

Request body

{
  "dueDate": "2024-07-15",
  "lineItems": [
    {
      "description": "Web Development",
      "quantity": 50,
      "unitPrice": 125.00,
      "taxRate": 10
    }
  ],
  "notes": "Updated scope"
}

Response

{
  "data": {
    "id": "clx...",
    "invoiceNumber": "INV-0042",
    "total": 6875.00,
    "status": "DRAFT"
  }
}

DELETE/api/v1/invoices/:id

Permanently delete an invoice and its generated PDF.

Response

204 No Content

GET/api/v1/invoices/:id/pdf

Download the invoice as a PDF file. Returns binary PDF with Content-Disposition header.

Response

Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-0042.pdf"

<binary PDF data>

Pagination

List endpoints accept the following query parameters:

Parameter	Default	Description
page	1	Page number (min: 1)
limit	20	Items per page (1–100)
search	—	Filter by name, email, or invoice number (max 255 chars)
clientId	—	Filter invoices by client (invoices only)
status	—	Filter by status: DRAFT, SENT, VIEWED, PAID, PARTIALLY_PAID, OVERDUE

GET /api/v1/clients?page=2&limit=10&search=acme

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with an error field.

Status	Description
400	Bad Request — invalid parameters or missing required fields
401	Unauthorized — invalid or missing API key
403	Forbidden — plan limit reached (clients, invoices, or feature)
404	Not Found — resource does not exist or is not accessible
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — unexpected failure, try again later

{
  "error": "Missing required field: name"
}

Rate Limits

API requests are rate-limited to 120 requests per minute per API key.

When the limit is exceeded, requests return 429 Too Many Requests. Wait before retrying.