API Reference

KVL TECH Public API

A REST API for programmatic access to your KVL TECH data — orders, leads, analytics, and clients. All responses are JSON. Authentication is via API keys.

Base URL: https://kvlbusinesssolutions.com/api/v1

Bearer Token Auth

100 req/min rate limit

Introduction

The KVL TECH Public API gives you programmatic access to your business data. It follows REST conventions — resources are addressed by URL, operations map to HTTP verbs, and all responses are JSON.

Base URL

https://kvlbusinesssolutions.com/api/v1

Format

application/json

Authentication

Bearer token (API key)

Rate Limit

100 requests per minute

Authentication

All API requests must be authenticated using an API key. Generate your key in the Admin Panel → API Keys. Two authentication methods are supported:

Method 1: Authorization Header (recommended)

http

Authorization: Bearer kvl_xxxx_your_api_key_here

Method 2: X-Api-Key Header

http

X-Api-Key: kvl_xxxx_your_api_key_here

Keep your API key secret. Do not expose it in client-side code or public repositories. Each key enforces a rate limit of 100 requests per minute. Exceeding this returns HTTP 429.

Scopes

Each API key has a set of scopes that control which endpoints it can access. Assign scopes when creating the key in the admin panel.

Scope	Access
`read:orders`	List and retrieve orders
`read:leads`	List and retrieve contact leads
`read:analytics`	Access analytics summary data
`read:clients`	List and retrieve clients
`admin`	Unrestricted access to all endpoints

Endpoints

GET/api/v1/ordersread:orders

Returns a paginated list of all orders, including client and product information.

Query Parameters

Parameter	Type	Required	Description
`limit`	`integer`	No	Number of records per page (default: 20, max: 100)
`page`	`integer`	No	Page number, 1-indexed (default: 1)
`status`	`string`	No	Filter by order status: PAYMENT_PENDING, ACTIVE, COMPLETED, CANCELLED

Example Request

bash

curl https://kvlbusinesssolutions.com/api/v1/orders \
  -H "Authorization: Bearer kvl_xxxx_your_key" \
  -G \
  -d limit=10 \
  -d page=1

Example Response

json

{
  "data": [
    {
      "id": "clx1abc...",
      "orderNumber": "KVL-2026-0001",
      "status": "ACTIVE",
      "amount": 29900,
      "plan": "PREMIUM",
      "createdAt": "2026-06-01T09:00:00.000Z",
      "client": {
        "name": "Acme Corp",
        "email": "billing@acme.com"
      },
      "product": {
        "name": "E-Commerce Website"
      }
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10
}

GET/api/v1/leadsread:leads

Returns a paginated list of contact leads from the CRM pipeline.

Query Parameters

Parameter	Type	Required	Description
`limit`	`integer`	No	Number of records per page (default: 20, max: 100)
`page`	`integer`	No	Page number, 1-indexed (default: 1)

Example Request

bash

curl https://kvlbusinesssolutions.com/api/v1/leads \
  -H "Authorization: Bearer kvl_xxxx_your_key" \
  -G \
  -d limit=20

Example Response

json

{
  "data": [
    {
      "id": "clx2def...",
      "name": "Jane Doe",
      "phone": "+91 98765 43210",
      "email": "jane@example.com",
      "service": "Logo Design",
      "source": "contact_form",
      "status": "NEW",
      "score": 72,
      "createdAt": "2026-06-05T14:30:00.000Z"
    }
  ],
  "total": 138,
  "page": 1,
  "limit": 20
}

GET/api/v1/analyticsread:analytics

Returns a high-level analytics summary including revenue, order counts, lead totals, conversion rate, and 12-month revenue trend.

Example Request

bash

curl https://kvlbusinesssolutions.com/api/v1/analytics \
  -H "Authorization: Bearer kvl_xxxx_your_key"

Example Response

json

{
  "totalRevenue": 1450000,
  "totalOrders": 86,
  "totalLeads": 312,
  "conversionRate": 15.38,
  "monthlyRevenue": [
    { "month": "2025-07", "revenue": 85000 },
    { "month": "2025-08", "revenue": 120000 },
    { "month": "2025-09", "revenue": 95000 },
    { "month": "...", "revenue": "..." }
  ]
}

GET/api/v1/clientsread:clients

Returns a paginated list of registered clients with their contact and account details.

Query Parameters

Parameter	Type	Required	Description
`limit`	`integer`	No	Number of records per page (default: 20, max: 100)
`page`	`integer`	No	Page number, 1-indexed (default: 1)

Example Request

bash

curl https://kvlbusinesssolutions.com/api/v1/clients \
  -H "Authorization: Bearer kvl_xxxx_your_key" \
  -G \
  -d limit=20 \
  -d page=1

Example Response

json

{
  "data": [
    {
      "id": "clx3ghi...",
      "name": "Ravi Kumar",
      "email": "ravi@startup.in",
      "phone": "+91 99001 12233",
      "company": "Startup India",
      "city": "Bengaluru",
      "isActive": true,
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "total": 94,
  "page": 1,
  "limit": 20
}

Error Codes

All errors return a JSON body with an error field describing the problem.

Status	Code	Meaning
401	`Unauthorized`	Missing or invalid API key. Ensure you are sending a valid key via Authorization: Bearer or X-Api-Key.
403	`Forbidden`	Your API key does not have the required scope for this endpoint. Update the key's scopes in the admin panel.
429	`Too Many Requests`	You have exceeded the rate limit of 100 requests per minute. Wait until the next minute window before retrying.
500	`Server Error`	An unexpected server-side error occurred. These are rare — if they persist, contact support.

Error Response Format

json

{
  "error": "Insufficient scope. Required: read:orders"
}

JavaScript / Node.js SDK

No package needed — use this lightweight wrapper to interact with the API in any JavaScript or Node.js environment.

javascript

// KVL TECH API — JavaScript SDK snippet
const kvl = {
  baseUrl: "https://kvlbusinesssolutions.com/api/v1",
  apiKey: "your_api_key_here",

  async get(path, params = {}) {
    const url = new URL(this.baseUrl + path)
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v))
    const res = await fetch(url, {
      headers: { "Authorization": `Bearer ${this.apiKey}` },
    })
    if (!res.ok) {
      const err = await res.json()
      throw new Error(err.error || `HTTP ${res.status}`)
    }
    return res.json()
  },

  orders:    { list: (p) => kvl.get("/orders",    p) },
  leads:     { list: (p) => kvl.get("/leads",     p) },
  analytics: { get:  ()  => kvl.get("/analytics")   },
  clients:   { list: (p) => kvl.get("/clients",   p) },
}

// Examples:
const { data: orders } = await kvl.orders.list({ limit: 10, page: 1 })
const { data: leads  } = await kvl.leads.list({ limit: 20 })
const analytics        = await kvl.analytics.get()
const { data: clients} = await kvl.clients.list({ limit: 50 })

Node.js Example

javascript

import { kvl } from "./kvl-sdk.js"

// Fetch all orders this month
const result = await kvl.orders.list({ limit: 100, status: "ACTIVE" })
console.log(`${result.total} active orders`)
result.data.forEach(order => {
  console.log(`${order.orderNumber} — ${order.client.name} — ₹${order.amount}`)
})