Books API Reference

The techlift Books API provides programmatic access to your invoicing, customer management, organizational profiles, and inventory data.

API Base URL: https://techliftdigital.in/api/v1

🔒 Authentication & Security

All API requests must be authenticated using an API Key. You can pass the key in the headers:

x-api-key: your_api_key
Authorization: Bearer your_api_key

App Scoping: API keys generated via the Books UI are strictly scoped to the books application. Requests to other modules (e.g., WhatsApp) will return a 403 Forbidden error.

Rate Limiting

The API enforces a strict rate limit of 100 requests per minute per organization.

If exceeded, a 429 Too Many Requests status is returned.
A retryAfter field in the response body indicates the wait time in seconds.

📄 Invoices API

BASE: /api/v1/books/invoices

Invoices Collection

Method	Endpoint	Description
`GET`	`/`	List invoices with filters (`status`, `search`, `page`, `limit`).
`POST`	`/`	Create a single invoice or an array of invoices (bulk).
`POST`	`/bulk-action`	Perform `delete` or `update_status` on an array of `ids`.

Individual Invoice

BASE: /api/v1/books/invoices/{id}

Method	Endpoint	Description
`GET`	`/`	Retrieve full details of a specific invoice.
`PATCH`	`/`	Update `status`, `notes`, or `terms`.
`DELETE`	`/`	Permanently remove an invoice.
`GET`	`/pdf`	Download the generated PDF document.
`POST`	`/send`	Dispatch the invoice PDF to the customer's email.
`POST`	`/payments`	Record a payment. Updates `balance_due` and `status`.

javascript

// Example: Recording a Payment
POST /invoices/64f1.../payments
{
  "amount": 1500.00,
  "payment_method": "bank_transfer",
  "notes": "Q1 Settlement"
}

📑 Quotes & Estimates

BASE: /api/v1/books/quotes

Quotes Management

Method	Endpoint	Description
`GET`	`/`	List quotes/estimates. Filter by `status` or `customer_id`.
`POST`	`/`	Create quotes (supports bulk).
`GET`	`/{id}`	Get detailed quote data.
`GET`	`/{id}/pdf`	Generate and download Quote PDF.
`POST`	`/{id}/send`	Send Quote to customer email.
`POST`	`/{id}/convert`	Accept Quote: Converts the quote into a drafted Invoice.

👥 Customer Management

BASE: /api/v1/books/customers

Method	Endpoint	Description
`GET`	`/`	List customers. Filter by `type` (B2B/B2C) or `search`.
`POST`	`/`	Register new customers. B2B requires `gstin`.
`GET`	`/{id}`	Fetch customer profile and summary.

📦 Inventory & Catalog

BASE: /api/v1/books/products & /api/v1/books/services

Products: Manage physical inventory with stock tracking.
Services: Catalog-based services for invoicing.
Supports GET list, POST create, and /{id} instance operations.

🏢 Organization Setup

BASE: /api/v1/orgs

Access and manage the parent organization data used for invoice branding.

Method	Endpoint	Description
`GET`	`/`	List all organizations your account has access to.
`GET`	`/{id}`	Get business profile (GSTIN, Address, Bank Details).
`PATCH`	`/{id}`	Update business configuration (Owner Only).

🛠️ Utilities & Validation

BASE: /api/v1/books/validate

Utility endpoints for client-side field validation and session context.

Method	Endpoint	Description
`GET`	`/`	Returns current organization ID and name associated with the API key.
`POST`	`/`	Pre-validates a payload for `invoice`, `customer`, `quote`, `product`, or `service`.

javascript

// Example: Validating a Customer Payload
POST /validate
{
  "type": "customer",
  "payload": {
    "name": "Jane Doe",
    "business_type": "B2B"
  }
}
// Returns 400: ["gstin is required for B2B customers"]

📱 Mobile-Specific API

BASE: /api/v1/books/mobile

Optimized endpoints for lower bandwidth and high-performance mobile dashboards.

GET /mobile/dashboard: Returns aggregated stats (Total Revenue, Receivables) and recent activity in a single call.

⚠️ Important Disclaimers

Live Production Data: This API operates directly on your production environment. There is no trial mode. Errors in PATCH or DELETE operations are irreversible.

Security: Never commit your API keys to version control. Use environment variables.
Validation: All POST payloads are validated against strict Zod schemas. 400 errors will contain a details array of specific field failures.
Payload Limit: Request body limit is 5MB.