REST API · v1

Kanvo API Reference

Integrate Kanvo with your own systems. Create and update records, manage tasks, and subscribe to real-time events via webhooks.

Base URL: https://kanvocrm.com/api/v1Auth: Bearer token

Overview

The Kanvo API is a REST API that allows external systems to read and write data in your Kanvo workspace. All requests must be authenticated with an API key generated in Settings → Advanced → API Keys.

All endpoints return JSON. The base URL for all API requests is:

text

https://kanvocrm.com/api/v1

The API follows conventional REST patterns — GET to read, POST to create, PATCH to update, and DELETE to remove.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token. Create and manage API keys at Settings → Advanced → API Keys inside your dashboard.

Each key has an assigned scope that controls what it can do:

Name	Type	Description
`read`	scope	Fetch records, tasks, and schema. Cannot create, update, or delete.
`write`	scope	All read permissions, plus create, update, and delete access for records and tasks.
`admin`	scope	All write permissions, plus webhook management.

bash

curl https://kanvocrm.com/api/v1/records \
  -H "Authorization: Bearer kv_live_your_api_key_here"

🔒 Keep your API keys secret. Never expose them in client-side code or public repositories. Rotate compromised keys immediately from the dashboard.

Errors & Status Codes

All error responses use standard HTTP status codes and return a consistent JSON body.

Name	Type	Description
`200`	OK	Request succeeded.
`400`	Bad Request	Missing or invalid parameters.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	API key lacks the required scope for this operation.
`404`	Not Found	Resource doesn't exist or belongs to a different workspace.
`500`	Server Error	Unexpected error. Contact support if it persists.

json

{
  "success": false,
  "error": "Object type 'lead' not found"
}

Pagination

List endpoints are paginated. Use page and per_page query parameters.

Name	Type	Description
`page`	integer	Page number, starting at 1. Defaults to 1.
`per_page`	integer	Results per page. Defaults to 50, max 100.

json

{
  "success": true,
  "data": [...],
  "meta": {
    "total": 237,
    "page": 2,
    "per_page": 50
  }
}

Records

Records are the central data object in Kanvo — leads, jobs, estimates, clients, and any custom object types you create. Each record belongs to an object type identified by its slug, and optionally sits in a pipeline stage.

List records

GEThttps://kanvocrm.com/api/v1/records

Name	Type	Description
`type`	string	Filter by object type slug (e.g. lead, job, estimate).
`search`	string	Case-insensitive title search.
`assignee_id`	uuid	Filter by assigned team member UUID.
`page`	integer	Page number. Defaults to 1.
`per_page`	integer	Results per page. Defaults to 50.

bash

curl "https://kanvocrm.com/api/v1/records?type=lead&per_page=10" \
  -H "Authorization: Bearer kv_live_..."

json

{
  "success": true,
  "data": [
    {
      "id": "b3e1a2f4-...",
      "title": "Johnson Property - Lawn Care",
      "object_type_id": "a1b2c3d4-...",
      "stage_id": "f5e6d7c8-...",
      "assignee_id": null,
      "data": { "phone": "555-123-4567" },
      "created_at": "2026-03-14T18:30:00.000Z",
      "updated_at": "2026-03-14T18:30:00.000Z",
      "object_types": { "name": "Lead", "slug": "lead", "icon": "👤" }
    }
  ],
  "meta": { "total": 84, "page": 1, "per_page": 10 }
}

Get a record

GEThttps://kanvocrm.com/api/v1/records/:id

bash

curl "https://kanvocrm.com/api/v1/records/b3e1a2f4-..." \
  -H "Authorization: Bearer kv_live_..."

Create a record

POSThttps://kanvocrm.com/api/v1/records

Name	Type	Description
`type`required	string	Object type slug. Must match a type in your workspace (e.g. lead, job).
`title`	string	Display name of the record. Defaults to 'Untitled'.
`data`	object	Free-form JSONB data for any custom fields.
`assignee_id`	uuid	UUID of the team member to assign this record to.
`stage_id`	uuid	Direct stage UUID. Use this or pipeline + stage, not both.
`pipeline`	string	Pipeline name, slug, or UUID. Places the record in the first stage unless stage is also specified.
`stage`	string	Stage name, slug, or UUID within the specified pipeline.

bash

curl -X POST https://kanvocrm.com/api/v1/records \
  -H "Authorization: Bearer kv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "lead",
    "title": "Smith Residence - Spring Cleanup",
    "pipeline": "main-sales",
    "stage": "new",
    "data": {
      "phone": "555-999-0001",
      "address": "42 Elm Street, Hartford CT"
    }
  }'

Fires the record.created webhook event. If a pipeline stage is specified, also fires pipeline.stage_changed.

Update a record

PATCHhttps://kanvocrm.com/api/v1/records/:id

Only include fields you want to change. Omitted fields are left untouched.

Name	Type	Description
`title`	string	New display name.
`data`	object	Replaces the entire data object. Fetch first if you need to merge.
`assignee_id`	uuid	Reassign the record. Pass null to unassign.
`stage_id`	uuid	Move to a new pipeline stage.

bash

curl -X PATCH https://kanvocrm.com/api/v1/records/b3e1a2f4-... \
  -H "Authorization: Bearer kv_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "c9d0e1f2-..." }'

Fires record.updated. If stage_id changed, also fires pipeline.stage_changed.

Delete a record

DELETEhttps://kanvocrm.com/api/v1/records/:id

Soft-deletes the record by setting deleted_at. Excluded from all future list queries.

bash

curl -X DELETE https://kanvocrm.com/api/v1/records/b3e1a2f4-... \
  -H "Authorization: Bearer kv_live_..."

json

{ "success": true, "data": { "deleted": true, "id": "b3e1a2f4-..." } }

Tasks

Tasks can be standalone or linked to a specific record via record_id.

List tasks

GEThttps://kanvocrm.com/api/v1/records/tasks

Name	Type	Description
`record_id`	uuid	Filter to tasks attached to a specific record.
`assignee_id`	uuid	Filter by assigned team member.
`completed`	boolean	true returns completed tasks only; false returns open tasks only.
`page`	integer	Page number.
`per_page`	integer	Results per page.

bash

curl "https://kanvocrm.com/api/v1/records/tasks?record_id=b3e1a2f4-...&completed=false" \
  -H "Authorization: Bearer kv_live_..."

Get a task

GEThttps://kanvocrm.com/api/v1/records/tasks/:id

Create a task

POSThttps://kanvocrm.com/api/v1/records/tasks

Name	Type	Description
`title`required	string	Task title.
`record_id`	uuid	Link to a record.
`assignee_id`	uuid	Assign to a team member.
`due_date`	ISO 8601	Due date, e.g. 2026-06-30.
`notes`	string	Optional notes or description.

bash

curl -X POST https://kanvocrm.com/api/v1/records/tasks \
  -H "Authorization: Bearer kv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Follow up on estimate",
    "record_id": "b3e1a2f4-...",
    "due_date": "2026-07-01"
  }'

Update a task

PATCHhttps://kanvocrm.com/api/v1/records/tasks/:id

Name	Type	Description
`title`	string	New title.
`completed`	boolean	true to mark complete, false to reopen.
`assignee_id`	uuid	Reassign.
`due_date`	ISO 8601	Update due date.
`notes`	string	Update notes.

Delete a task

DELETEhttps://kanvocrm.com/api/v1/records/tasks/:id

Webhooks

Webhooks let Kanvo push real-time event notifications to your server. Register an HTTPS endpoint and subscribe to specific events. Webhook management requires the admin scope.

List webhooks

GEThttps://kanvocrm.com/api/v1/webhooks

json

{
  "success": true,
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://your-app.com/hooks/kanvo",
      "events": ["record.created", "pipeline.stage_changed"],
      "is_active": true,
      "last_triggered_at": "2026-06-17T14:20:00Z",
      "last_status": 200,
      "failure_count": 0,
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Register a webhook

POSThttps://kanvocrm.com/api/v1/webhooks

Name	Type	Description
`url`required	string	HTTPS endpoint URL to receive event payloads.
`events`required	string[]	Array of event names to subscribe to.

bash

curl -X POST https://kanvocrm.com/api/v1/webhooks \
  -H "Authorization: Bearer kv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/kanvo",
    "events": ["record.created", "record.updated", "pipeline.stage_changed"]
  }'

The signing secret is only returned once — in the response to this creation request. Store it securely to verify future payloads.

Delete a webhook

DELETEhttps://kanvocrm.com/api/v1/webhooks?id=:id

bash

curl -X DELETE "https://kanvocrm.com/api/v1/webhooks?id=wh_abc123" \
  -H "Authorization: Bearer kv_live_..."

Event reference

All subscribable event names:

record.createdrecord.updatedrecord.deletedtask.createdtask.updatedtask.deletedtask.completedpipeline.stage_changedcontract.createdcontract.signedform.submittedcontact.createdcontact.updated

Payload signing

Every delivery includes a X-Kanvo-Signature header — an HMAC-SHA256 signature of the raw request body using your endpoint's signing secret. Verify it to confirm the request originated from Kanvo.

javascript

import { createHmac } from "crypto";

function verifyKanvoWebhook(rawBody, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

// In your request handler:
const rawBody = await request.text();
const sig = request.headers.get("x-kanvo-signature");

if (!verifyKanvoWebhook(rawBody, sig, process.env.KANVO_WEBHOOK_SECRET)) {
  return new Response("Forbidden", { status: 403 });
}

const event = JSON.parse(rawBody);
console.log(event.event, event.data);

Payload shape for all events:

json

{
  "event": "record.created",
  "workspace_id": "ws_abc123",
  "timestamp": "2026-06-17T14:20:00.000Z",
  "data": {
    "id": "b3e1a2f4-...",
    "title": "Smith Residence",
    "object_type_id": "...",
    "stage_id": "...",
    "assignee_id": null,
    "data": {},
    "created_at": "2026-06-17T14:20:00.000Z"
  }
}

Schema

Fetch your workspace's object types and pipeline structure. Useful when building integrations that need to know which types and stages exist before creating records.

GEThttps://kanvocrm.com/api/v1/schema

bash

curl https://kanvocrm.com/api/v1/schema \
  -H "Authorization: Bearer kv_live_..."

json

{
  "success": true,
  "data": {
    "object_types": [
      { "id": "a1b2...", "name": "Lead", "slug": "lead", "icon": "👤" },
      { "id": "c3d4...", "name": "Job", "slug": "job", "icon": "🔧" },
      { "id": "e5f6...", "name": "Estimate", "slug": "estimate", "icon": "📋" }
    ],
    "pipelines": [
      {
        "id": "p1q2...",
        "name": "Main Sales",
        "slug": "main-sales",
        "stages": [
          { "id": "s1t2...", "name": "New", "slug": "new", "position": 0 },
          { "id": "s3t4...", "name": "Contacted", "slug": "contacted", "position": 1 },
          { "id": "s5t6...", "name": "Won", "slug": "won", "position": 2 }
        ]
      }
    ]
  }
}