API v1 — Stable

Build on Kolva

RESTful API to integrate your tools with Kolva. Manage clients, deals, visits and contacts programmatically. Real-time webhooks for every event.

AuthenticationEndpointsRate LimitsWebhooksExamples
OpenAPI 3.1 Spec

Authentication

API Key Authentication

Generate API keys from Settings → Developer in your Kolva admin panel. Each key has scoped permissions and can be revoked at any time.

Header Authentication

Recommended method

# Option 1: X-Kolva-Key header
X-Kolva-Key: kolva_sk_abc123...

# Option 2: Bearer token
Authorization: Bearer kolva_sk_abc123...

Available Scopes

Granular permissions

read:clients
write:clients
read:deals
write:deals
read:visits
write:visits
read:finance
* (all)

Endpoints

RESTful Resources

All endpoints follow REST conventions. Responses use JSON. Pagination with ?page= and ?limit= (max 100).

Clients

/api/v1/clients

Manage your client database — list, create, update, deactivate.

GETPOSTPUTDELETE
Scopes: read:clients, write:clients

Contacts

/api/v1/contacts

CRUD contacts within client records (JSONB contacts array).

GETPOSTPUTDELETE
Scopes: read:clients, write:clients

Deals

/api/v1/deals

Orders and deals — create, update status, track revenue.

GETPOSTPUTDELETE
Scopes: read:deals, write:deals

Visits

/api/v1/visits

Field visits — plan, track check-in/out, manage schedules.

GETPOSTPUTDELETE
Scopes: read:visits, write:visits

Rate Limits

Fair Usage Limits

100

requests / minute

429

status when exceeded

Retry-After

header included

Webhooks

Real-time Event Notifications

Subscribe to events from Settings → Developer → Webhooks. Kolva sends POST requests to your URL with HMAC-SHA256 signature verification.

deal_created

Fired when a new deal/order is created

deal_updated

Fired when a deal status or amount changes

client_created

Fired when a new client is added

client_updated

Fired when client details are modified

visit_completed

Fired when a field rep checks out

invoice_created

Fired when an invoice is generated

order_created

Fired when an order is placed

contact_updated

Fired when a client contact is modified

Signature Verification

Every webhook POST includes a X-Kolva-Signature header. Verify it with HMAC-SHA256 using your webhook secret.

// Node.js verification
const crypto = require('crypto');
const signature = req.headers['x-kolva-signature'];
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(signature), Buffer.from(expected)
);

Retry policy: 3 attempts with exponential backoff (1min, 5min, 30min). After 10 consecutive failures, the webhook is auto-disabled.

Examples

Quick Start

cURL — List clients
curl -X GET "https://kolva.ai/api/v1/clients?page=1&limit=10" \
  -H "X-Kolva-Key: kolva_sk_your_key_here"
cURL — Create a deal
curl -X POST "https://kolva.ai/api/v1/deals" \
  -H "X-Kolva-Key: kolva_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "uuid", "total_ht": 1500, "currency": "EUR"}'
JavaScript — List visits
const response = await fetch("https://kolva.ai/api/v1/visits?status=completed", {
  headers: { "X-Kolva-Key": process.env.KOLVA_API_KEY },
});
const { data, total } = await response.json();
console.log(`Found ${total} completed visits`);
JavaScript — Create a visit
const visit = await fetch("https://kolva.ai/api/v1/visits", {
  method: "POST",
  headers: {
    "X-Kolva-Key": process.env.KOLVA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    client_id: "client-uuid",
    commercial_id: "rep-uuid",
    planned_date: "2026-03-15",
    type: "visit",
  }),
});
const { data } = await visit.json();

Ready to integrate?

Create your API key in Kolva settings, or check the OpenAPI spec for the full reference.

Get Started FreeOpenAPI Spec