Konverto API

The customers your key can see. A customer key returns exactly one record, its own. A partner key returns every active customer under the partnership.

{
  "data": [
    {
      "id": "8f2c...",
      "company_name": "Murer & Søn ApS",
      "contact_person": "Jens Hansen",
      "email": "jens@murerogsoen.dk",
      "phone": "+4520304050",
      "industry": "Murer",
      "website": "https://murerogsoen.dk",
      "active": true,
      "booking_enabled": true,
      "created_at": "2026-03-11T09:14:02Z"
    }
  ],
  "next_cursor": null
}

Inbound leads across every customer your key can see. Each lead carries the customer_id it belongs to, so a partner key can route them without a second call.

curl "https://pkmeytthmqthhyoiicnv.supabase.co/functions/v1/api-v1/v1/leads?limit=50&created_since=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer kv_live_your_secret_key"

{
  "data": [
    {
      "id": "3a91...",
      "customer_id": "8f2c...",
      "name": "Mette Sørensen",
      "email": "mette@example.dk",
      "phone": "+4530405060",
      "address": "Nørregade 4, 8000 Aarhus",
      "status": "new",
      "source": "website",
      "channel": "form",
      "is_test": false,
      "meeting_status": null,
      "created_at": "2026-07-04T08:22:11Z"
    }
  ],
  "next_cursor": "MjAyNi0wNy0wNFQwODoyMjoxMVp8M2E5MQ=="
}

Pagination

Lists are ordered newest first and paginated with an opaque cursor. Keep requesting until next_cursor comes back as null, which means you have reached the end. Cursors stay correct even when new leads arrive while you are paging, which is why there is no page number.

What "newest" means depends on the query. Normally lists are ordered by created_at. When you pass updated_since they are ordered by updated_at instead, so a lead created last year but edited today shows up at the top rather than buried deep in your history.

Because of that, a cursor belongs to the query that produced it. Keep updated_since present or absent consistently across every page of one run. Switching midway returns 400 rather than quietly giving you the wrong page.

For incremental sync, store the newest updated_at you have seen and pass it as updated_since on your next run. That catches both new leads and changes to existing ones. Use created_since only when you genuinely want new leads and nothing else. If you would rather not poll at all, register a webhook and we will call you instead.

A single lead. Returns the lead object directly, not wrapped in a list. A lead outside your scope returns 404, the same answer as a lead that does not exist, so a key cannot probe for which ids are real.

The full conversation with one lead: emails and SMS in one timeline, newest first, paginated like any other list. Each message carries a channel of email or sms and a direction of inbound or outbound. SMS has no subject, so that field is null.

{
  "data": [
    {
      "id": "9c11...",
      "customer_id": "8f2c...",
      "lead_id": "3a91...",
      "channel": "sms",
      "direction": "inbound",
      "subject": null,
      "body": "Kan I komme på tirsdag?",
      "from_address": "+4530405060",
      "to_address": "+4520304050",
      "created_at": "2026-07-04T09:01:44Z"
    }
  ],
  "next_cursor": null
}

Bookings across every customer your key can see. Konverto books in three ways and this endpoint returns all of them in one shape. The source field tells you which: online (booked on the website), phone (booked by the phone assistant) or route (a planned on-site visit).

starts_at and ends_at are always absolute timestamps, already resolved from the customer's own timezone, so you never have to guess it. For a route booking they describe the arrival window, not a meeting length: a "we will be there between 9 and 11" is a two hour window, not a two hour job.

Filter with status, source, customer_id, updated_since and the usual limit/cursor.

{
  "data": [
    {
      "id": "b7f0...",
      "customer_id": "8f2c...",
      "lead_id": "3a91...",
      "source": "phone",
      "lead_name": "Mette Sørensen",
      "lead_email": "mette@example.dk",
      "lead_phone": "+4530405060",
      "starts_at": "2026-07-20T07:00:00Z",
      "ends_at": "2026-07-20T07:30:00Z",
      "duration_minutes": 30,
      "status": "scheduled",
      "booking_format": "phone",
      "created_at": "2026-07-04T09:12:00Z",
      "updated_at": "2026-07-04T09:12:00Z"
    }
  ],
  "next_cursor": null
}

Push a lead from your own system into Konverto. Requires a key with the write scope, which is not granted by default. Send name, email, phone, message, ad and page_url. At least one of email or phone is required, because that is how we recognise a person you have sent us before. If your key covers more than one customer, name the one you are creating for with customer_id.

An Idempotency-Key header is required. Choose any unique string per lead, keep it if you retry, and a repeated call returns the original response instead of creating a second lead. We keep the answer for 24 hours and mark the repeat with an Idempotent-Replay header.

We answer 201 when a new lead was created and 200 when we matched the email or phone to a lead the customer already had. In the second case the enquiry is added to that existing lead rather than duplicating the person. The body is a lead object, exactly as GET /v1/leads/{id} returns it.

A lead created this way is treated like any other lead the customer receives: it appears in their pipeline and notifies them. If the customer's account is paused or cannot take leads, we create nothing and answer 409.

curl -X POST https://pkmeytthmqthhyoiicnv.supabase.co/functions/v1/api-v1/v1/leads \
  -H "Authorization: Bearer kv_live_..." \
  -H "Idempotency-Key: your-unique-id-per-lead" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mette Sørensen",
    "email": "mette@example.dk",
    "phone": "+45 30 40 50 60",
    "message": "Vil gerne have et tilbud på nyt tag",
    "page_url": "https://kunde.dk/kontakt"
  }'

Update a lead's status. Also requires the write scope. Status is the only writable field, and it takes the same Danish values the read endpoints return: Kontaktet, aktiv, kold or inaktiv. No Idempotency-Key is needed, since setting the same status twice changes nothing. Returns the updated lead.

Register an https endpoint and we will POST to it whenever something happens, instead of you polling for it. Creating and deleting a subscription requires the write scope; listing does not. A subscription belongs to the same owner as the key that created it, so one partner subscription covers every customer that key can see.

Nine events exist. Name the ones you want in events. Leaving the field out subscribes you to all nine: not choosing is not the same as choosing lead.created, and if you have not said what you want, you want to know what happens to your leads. An unknown name is refused outright, so a typo cannot silently cost you half a subscription.

A subscription created before this expansion keeps the events it already had, usually just lead.created. There is no backfill: saying yes to new leads was not saying yes to a stream of messages, calls and status changes. The events on an existing subscription cannot be changed either, so to widen one you delete it and create a new one, with a new secret.

curl -X POST "https://pkmeytthmqthhyoiicnv.supabase.co/functions/v1/api-v1/v1/webhooks" \
  -H "Authorization: Bearer kv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.example/hooks/konverto",
    "events": ["lead.created", "lead.message", "lead.handover"]
  }'

The response contains a secret field. That is the only time you will ever see it. We store it encrypted and cannot read it back out to you, so if you lose it, delete the subscription and create a new one.

{
  "id": "6f1c0f2e-0b9a-4d4a-9d20-2f8f6a1b7c33",
  "url": "https://your-system.example/hooks/konverto",
  "events": ["lead.created", "lead.message", "lead.handover"],
  "enabled": true,
  "created_at": "2026-07-22T09:14:03.221Z",
  "disabled_at": null,
  "disabled_reason": null,
  "last_success_at": null,
  "last_error": null,
  "last_error_at": null,
  "consecutive_failures": 0,
  "secret": "whsec_9f0c...shown once"
}

Headers

The source block

The last four fields are left out when the value is missing, not set to null. The block is a whitelist, not a filter: there are no tokens, no thread or customer ids, no raw mail headers and never a full call transcript, whatever else the row happens to hold.

Verifying the signature

Sign <timestamp>.<raw body> with your secret using HMAC-SHA256 and compare the hex digest to the header. Use the raw request body, not a re-serialised object: re-encoding changes whitespace and key order, and the signature will not match.

Reject anything where the timestamp is more than five minutes old. Without that check, someone who captured one valid delivery could replay it later and the signature would still verify. Compare digests in constant time.

import crypto from "node:crypto";

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const received = (headers["x-webhook-signature"] || "").replace(/^v1=/, "");

  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!timestamp || age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Webhook-Timestamp", "")
    received = headers.get("X-Webhook-Signature", "").removeprefix("v1=")
    if not timestamp or abs(int(time.time()) - int(timestamp)) > 300:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, received)

Retries

Answer with any 2xx as soon as you have the body safely stored. We wait at most ten seconds for your response, and we do not follow redirects: a 30x counts as a failure, because a signed body carrying personal data should only ever go to the address the subscription names.

A delivery is attempted eight times in all: the first attempt and then seven retries with doubling backoff, starting at one minute (1m, 2m, 4m, 8m, 16m, 32m, 64m), so roughly two hours from the first attempt to the last. After that the delivery is given up. Five given-up deliveries in a row disable the subscription, and GET /v1/webhooks will show enabled: false together with the last error we saw. Delete it and create a new one once your endpoint is healthy again.

Deliveries are at least once, not exactly once. If your endpoint answers slowly and we time out after you already stored the lead, you will see the same X-Webhook-Id again. Treat that id as the deduplication key. The payload is built at delivery time, so a lead that changed between the event and the delivery arrives in its current state.