REST API · version 1

Connect your system to KH Lead Management

Send leads from your CRM, website or app into KH Lead Management, and pull every new or changed lead back out. Duplicates are matched and merged automatically, exactly like leads captured with the browser extension.

Push leads in

One lead or up to 500 per request. Send your own ID with each lead and repeat sends update the same lead instead of making copies.

Pull changes out

Ask for everything changed since your last sync. Paging is safe even while leads are being edited.

Update and delete

Change the stage, owner, tags or contact details, add notes, or delete a lead.

Base address for every request:

https://lms.kreativehive.ca/api/?r=

The route goes after ?r=. Extra query parameters are added with &, for example https://lms.kreativehive.ca/api/?r=v1/leads&limit=50.

Quick start

  1. Get an API key. An owner or admin opens Settings › API & sync in the dashboard and clicks Create API key. Or call POST v1/auth/token with an owner or admin email and password.
  2. Send a lead.
    curl -X POST 'https://lms.kreativehive.ca/api/?r=v1/leads' \
      -H 'Authorization: Bearer lmsk_your_api_key' \
      -H 'Content-Type: application/json' \
      -d '{"system": "mycrm", "leads": [{"external_id": "1001", "name": "Zephyr Glass Works", "phone": "905-864-2142", "email": "info@zephyrglass.ca"}]}'
  3. Read your leads.
    curl 'https://lms.kreativehive.ca/api/?r=v1/leads&limit=100' \
      -H 'Authorization: Bearer lmsk_your_api_key'

Authentication

Every request sends the API key in the Authorization header:

Authorization: Bearer lmsk_your_api_key
  • A key belongs to one company and sees all of that company's leads.
  • Only an owner or admin can create keys. If that person's account is disabled or they stop being an admin, their keys stop working.
  • Read and write keys can do everything below. Read-only keys can only use GET requests. Use read-only keys for reporting tools.
  • The full key is shown once. We store only a fingerprint of it, so nobody (including us) can show it again. If you lose it, revoke it and create a new one.
  • Keep keys on your server. Never put a key in a public website's JavaScript.

Requests and responses

Send JSON with Content-Type: application/json. Every response is JSON in one of two shapes:

{ "ok": true, "data": { ... } }
{ "ok": false, "error": { "code": "validation", "message": "Readable explanation" } }

Dates are UTC in ISO 8601, for example 2026-11-02T14:05:00Z. PATCH and DELETE also work as POST (shown under each endpoint) for tools that only send GET and POST.

Keeping two systems in sync

A typical two-way sync runs every few minutes:

  1. Push leads that are new or changed in your system with POST v1/leads, each with your own external_id.
  2. Pull leads changed here since your last sync with GET v1/leads and updated_since, page by page with cursor.
  3. Save the server_time from the first page and use it as updated_since next time.

Push leads in

Give each lead the ID it has in your system as external_id, and name your system once with system (for example "hubspot"). Sending the same external_id again updates that same lead. External IDs are not case sensitive.

curl -X POST 'https://lms.kreativehive.ca/api/?r=v1/leads' \
  -H 'Authorization: Bearer lmsk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "system": "mycrm",
    "tags": ["from-crm"],
    "leads": [
      {"external_id": "1001", "name": "Zephyr Glass Works", "phone": "905-864-2142",
       "email": "info@zephyrglass.ca", "website": "zephyrglass.ca",
       "address": "12 Main St, Milton, ON L9T 1N4", "stage": "Contacted",
       "owner_email": "agent@yourcompany.com", "notes": "Asked for a quote"},
      {"external_id": "1002", "name": "Quill & Co Printing", "email": "hello@quillprint.ca"}
    ]
  }'
const res = await fetch('https://lms.kreativehive.ca/api/?r=v1/leads', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + process.env.LMS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    system: 'mycrm',
    leads: contacts.map(c => ({ external_id: String(c.id), name: c.company, phone: c.phone, email: c.email, website: c.website }))
  })
});
const { ok, data, error } = await res.json();
if (!ok) throw new Error(error.message);
for (const r of data.results) console.log(r.external_id, r.result, r.lead_id);
$ch = curl_init('https://lms.kreativehive.ca/api/?r=v1/leads');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('LMS_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['system' => 'mycrm', 'leads' => [
    ['external_id' => '1001', 'name' => 'Zephyr Glass Works', 'phone' => '905-864-2142', 'email' => 'info@zephyrglass.ca'],
  ]]),
]);
$out = json_decode(curl_exec($ch), true);
foreach ($out['data']['results'] as $r) echo $r['external_id'], ' ', $r['result'], ' ', $r['lead_id'], PHP_EOL;
import os, requests
r = requests.post('https://lms.kreativehive.ca/api/?r=v1/leads',
    headers={'Authorization': 'Bearer ' + os.environ['LMS_API_KEY']},
    json={'system': 'mycrm', 'leads': [
        {'external_id': '1001', 'name': 'Zephyr Glass Works', 'phone': '905-864-2142', 'email': 'info@zephyrglass.ca'},
    ]})
for res in r.json()['data']['results']:
    print(res['external_id'], res['result'], res['lead_id'])

The answer tells you, for each lead, what happened and its lead_id here. Save the lead_id in your system if you want to update the lead later by ID.

{
  "ok": true,
  "data": {
    "results": [
      { "index": 0, "external_id": "1001", "result": "new", "lead_id": 146, "match": null },
      { "index": 1, "external_id": "1002", "result": "merged", "lead_id": 88,
        "match": { "rule": "email", "score": 94, "into": "Quill & Co Printing" } }
    ],
    "summary": { "new": 1, "merged": 1 },
    "run_id": 31,
    "quota": { "used": 412, "limit": 1000, "left": 588, "month": "2026-11" }
  }
}

By default a lead that already exists keeps the details it has and only fills empty fields, so your push never wipes out data your team improved. Send "overwrite": true to replace details with the ones you send. Tags are always added, and notes are always added as a note.

Pull changes out

Ask for leads changed since your last sync. Leads come oldest change first. When has_more is true, call again with the next_cursor you received.

async function pullChanges(since) {
  let cursor = '', serverTime = null, leads = [];
  do {
    const url = 'https://lms.kreativehive.ca/api/?r=v1/leads&limit=500&include_removed=1&updated_since=' + encodeURIComponent(since) + (cursor ? '&cursor=' + cursor : '');
    const { data } = await (await fetch(url, { headers: { Authorization: 'Bearer ' + process.env.LMS_API_KEY } })).json();
    serverTime ??= data.server_time;
    leads.push(...data.leads);
    cursor = data.has_more ? data.next_cursor : '';
  } while (cursor);
  return { leads, nextSince: serverTime }; // save nextSince for the next run
}
import requests
def pull_changes(since, key):
    url = 'https://lms.kreativehive.ca/api/?r=v1/leads'
    params = {'limit': 500, 'include_removed': 1, 'updated_since': since}
    leads, server_time = [], None
    while True:
        d = requests.get(url, params=params, headers={'Authorization': 'Bearer ' + key}).json()['data']
        server_time = server_time or d['server_time']
        leads += d['leads']
        if not d['has_more']:
            return leads, server_time   # save server_time for the next run
        params['cursor'] = d['next_cursor']
function pull_changes(string $since, string $key): array {
  $leads = []; $cursor = ''; $serverTime = null;
  do {
    $url = 'https://lms.kreativehive.ca/api/?r=v1/leads&limit=500&include_removed=1&updated_since=' . urlencode($since) . ($cursor ? '&cursor=' . $cursor : '');
    $ctx = stream_context_create(['http' => ['header' => 'Authorization: Bearer ' . $key]]);
    $d = json_decode(file_get_contents($url, false, $ctx), true)['data'];
    $serverTime ??= $d['server_time'];
    array_push($leads, ...$d['leads']);
    $cursor = $d['has_more'] ? $d['next_cursor'] : '';
  } while ($cursor);
  return [$leads, $serverTime]; // save $serverTime for the next run
}
curl 'https://lms.kreativehive.ca/api/?r=v1/leads&updated_since=2026-11-01T00:00:00Z&limit=500' \
  -H 'Authorization: Bearer lmsk_your_api_key'

Deleted and merged leads

Add include_removed=1 when you pull, so your system also hears about leads that were deleted or merged into another one. Each lead has a status:

NameTypeDescription
activestatusA normal lead.
deletedstatusDeleted here. Delete or archive it in your system.
mergedstatusFound to be a duplicate and merged into the lead in merged_into. Point your record at that lead.

How duplicates are handled

Every lead you push goes through the same duplicate matcher as the browser extension. The result of each lead is one of:

NameTypeDescription
newresultA new lead was created.
knownresultThe same external_id was sent before. That lead was updated.
mergedresultIt matched a lead that already exists (same phone at the same place, same email, same website at the same address, and so on). Details were added to that lead; match says why.
reviewresultCreated, but it looks like a possible duplicate. Someone confirms it in the Review Queue.
quotaresultNot created: the company reached its monthly new-lead limit. Updates to existing leads still work.
errorresultNot saved. error.message says why, for example a missing name or an unknown stage. Other leads in the same request are still saved.

Endpoints

POSTv1/auth/tokenCreate an API key with an owner or admin login

For setting up a connection without opening the dashboard. Creates a new key every time it is called, so call it once and store the key.

NameTypeDescription
emailstringEmail of an owner or admin.
passwordstringTheir password.
namestring, optionalA label you will recognise, for example "HubSpot sync".
scopestring, optionalwrite (default) or read.
curl -X POST 'https://lms.kreativehive.ca/api/?r=v1/auth/token' -H 'Content-Type: application/json' \
  -d '{"email": "admin@yourcompany.com", "password": "...", "name": "HubSpot sync"}'
{ "ok": true, "data": { "api_key": "lmsk_9f2c...", "key": { "id": 4, "name": "HubSpot sync", "prefix": "lmsk_9f2c41d", "scope": "write" }, "workspace": { "id": 3, "name": "Your Company" } } }
GETv1/meCheck the key, your company, limits and usage
{ "ok": true, "data": { "workspace": { "id": 3, "name": "Your Company", "plan": "Pro" }, "user": { "id": 7, "name": "Sara", "role": "admin" },
  "quota": { "used": 412, "limit": 1000, "left": 588, "month": "2026-11" }, "billing": { "status": "active", "locked": false },
  "limits": { "requests_per_minute": 120, "max_batch": 500, "max_page": 500 }, "server_time": "2026-11-02T14:05:00Z" } }
GETv1/leadsList leads, newest change last
NameTypeDescription
updated_sincedateOnly leads changed at or after this time. Use for syncing.
created_sincedateOnly leads created at or after this time.
limitnumberLeads per page, 1 to 500. Default 100.
cursorstringThe next_cursor from the previous page.
include_removed0 or 1Also return deleted and merged leads (see above).
stagestringStage id or name, for example won.
tagstringOnly leads with this tag.
owner_idnumberOnly leads held by this user. 0 = unassigned leads.
qstringSearch in name, email, website and city.
{ "ok": true, "data": { "leads": [ { "id": 146, "name": "Zephyr Glass Works", "...": "..." } ],
  "count": 100, "total": 2380, "has_more": true, "next_cursor": "MjAyNi0xMS0wMiAxNDowNTowMHwxNDY", "server_time": "2026-11-02T14:05:00Z" } }

total is given on the first page only.

GETv1/leads/{id}One lead

Add &include_activities=1 to also get its notes, calls, stage changes and other history. Returns deleted and merged leads too, with their status.

curl 'https://lms.kreativehive.ca/api/?r=v1/leads/146&include_activities=1' -H 'Authorization: Bearer lmsk_your_api_key'
GETv1/leads/lookupFind leads by your ID, email, phone or website
NameTypeDescription
external_id + systemstringYour ID and the system name you used when pushing.
emailstringAny email of the lead.
phonestringAny format: (905) 864-2142, +19058642142.
websitestringAny address on the lead's website.
curl 'https://lms.kreativehive.ca/api/?r=v1/leads/lookup&system=mycrm&external_id=1001' -H 'Authorization: Bearer lmsk_your_api_key'

Returns { "leads": [ ... ] }, empty when nothing matches. A merged lead is followed to the lead it now belongs to.

POSTv1/leadsAdd or update up to 500 leads

Body: { "leads": [ ... ] } or a single { "lead": { ... } }. Options for the whole request:

NameTypeDescription
systemstringName of your system, letters and numbers. Default api. Keeps your IDs apart from other systems' IDs.
overwritebooleanReplace details of existing leads with the ones you send. Default false: only fill empty fields.
tagsarrayTags added to every lead in the request.
owner_email / owner_idstring / numberWho holds new leads. Leave out to put them in the unassigned pool.
list_idnumberAlso add every lead to this static list.

Fields of each lead (only name plus one of phone, email, website or a social link are required):

NameTypeDescription
external_idstringYour ID for this lead. Strongly recommended.
namestringBusiness name. Required.
phone, email, websitestringAny format; they are cleaned up. email may also be an array of emails.
addressstringFull address; street, city, province or state and postal code are worked out from it.
street, city, region, postal, countrystringUse instead of, or together with, address.
categorystringType of business.
socialsobjectfacebook, instagram, linkedin, twitter, youtube, tiktok links.
stagestringStage id or name. Applied to new leads, or to existing ones with overwrite.
owner_email / owner_idstring / numberWho holds this lead. 0 = unassigned.
tagsarrayTags to add.
notesstringAdded as a note on the lead.
deal_valuenumberExpected deal value.
do_not_contactbooleanFlag the lead as do-not-contact.
lat, lng, rating, reviews, urlmixedOptional extras. url is the page the lead came from.

Each push also shows in the dashboard under Scrape Runs as "API sync", so your team can see what came in.

PATCHv1/leads/{id}Change one lead

Also available as POST v1/leads/{id}. Send only the fields you want to change.

NameTypeDescription
name, phone, email, website, address, street, city, region, postal, country, categorystringNew values.
socialsobjectSocial links to change.
stagestringStage id or name.
owner_email / owner_idstring / numberGive the lead to someone. 0 = unassigned pool.
tagsarrayReplace all tags.
add_tagsarrayAdd tags, keep the rest.
notestringAdd a note.
deal_value, do_not_contactnumber, booleanAs above.
external_id + systemstringLink this lead to a record in your system.
curl -X PATCH 'https://lms.kreativehive.ca/api/?r=v1/leads/146' -H 'Authorization: Bearer lmsk_your_api_key' -H 'Content-Type: application/json' \
  -d '{"stage": "won", "add_tags": ["vip"], "note": "Signed the contract", "owner_email": "sara@yourcompany.com"}'

Returns { "lead": { ... } }. If the lead was merged into another one you get 409 merged; update the lead named in the message.

DELETEv1/leads/{id}Delete one lead

Also available as POST v1/leads/{id}/delete. The lead is hidden everywhere but kept in the database (not erased), so it can be restored if it was a mistake. Pulls with include_removed=1 report it as deleted.

GETv1/stagesPipeline stages of the company
{ "ok": true, "data": { "stages": [ { "id": "new", "name": "New", "color": "#64748b" }, { "id": "contacted", "name": "Contacted", "color": "#2563eb" } ] } }
GETv1/usersPeople who can hold leads
{ "ok": true, "data": { "users": [ { "id": 7, "name": "Sara Khan", "email": "sara@yourcompany.com", "role": "agent", "reports_to": 5 } ] } }

The lead object

{
  "id": 146,
  "status": "active",
  "merged_into": null,
  "name": "Zephyr Glass Works",
  "category": "Glass & Mirror Shop",
  "phone": "(905) 864-2142",
  "phone_e164": "+19058642142",
  "email": "info@zephyrglass.ca",
  "email_status": "valid",
  "emails": ["info@zephyrglass.ca", "sales@zephyrglass.ca"],
  "website": "https://zephyrglass.ca",
  "domain": "zephyrglass.ca",
  "address": "12 Main St, Milton, ON L9T 1N4",
  "street": "12 Main St", "city": "Milton", "region": "ON", "postal": "L9T 1N4", "country": "CA",
  "lat": 43.5183, "lng": -79.8774,
  "rating": 4.7, "reviews": 128,
  "socials": { "facebook": "", "instagram": "https://instagram.com/zephyrglass", "linkedin": "", "twitter": "", "youtube": "", "tiktok": "" },
  "stage": "contacted", "stage_name": "Contacted",
  "owner": { "id": 7, "name": "Sara Khan", "email": "sara@yourcompany.com" },
  "captured_by": { "id": 7, "name": "Sara Khan", "email": "sara@yourcompany.com" },
  "deal_value": 2500,
  "score": 82,
  "tags": ["vip", "from-crm"],
  "sources": ["gmaps", "yelp", "api"],
  "do_not_contact": false,
  "external_ids": [ { "system": "mycrm", "external_id": "1001" } ],
  "created_at": "2026-11-01T18:22:10Z",
  "updated_at": "2026-11-02T14:05:00Z"
}

email_status is valid, risky, invalid or unknown (checked against the email domain). owner is null for unassigned leads. sources lists every directory the lead was found on.

Errors

NameTypeDescription
401 authHTTPThe key is missing, wrong or revoked, or its creator is no longer an admin.
402 payment_requiredHTTPThe company's subscription is paused. It works again as soon as the bill is paid.
403 forbiddenHTTPNot allowed, for example writing with a read-only key.
404 not_foundHTTPNo lead with that id in your company.
409 merged / conflictHTTPThe lead was merged into another, or the external_id already belongs to another lead.
413 validationHTTPMore than 500 leads in one request.
422 validationHTTPSomething in the request is wrong. The message says what.
429 rate_limitHTTPToo many requests. Wait the number of seconds in the Retry-After header.
500 serverHTTPOur side failed. Try again; if it keeps happening, contact support.

Limits

  • 120 requests per minute per key. Every response has X-RateLimit-Remaining.
  • 500 leads per push and 500 leads per page.
  • New leads count toward the company's monthly lead limit, the same as captures from the extension. Merges and updates are free.
  • Calls from a browser are allowed (CORS), but keep keys secret: call the API from your server.

Questions? Email info@kreativehive.ca.