POST /leads

When to call it. Your storefront checked an address — for example with POST /serviceability/check — the answer was not orderable, and the shopper asked to be kept informed. Send their details here; your sales team finds them in the Provider Portal under Leads, stage Waitlist.

Endpoint

POST /partner/leads

Auth: X-API-Key: krnl_... with the leads:write scope. Keys created before this scope existed don’t carry it — create a key with leads:write on the dashboard API Keys page. A key that can provision does not automatically write leads, and a leads:write key cannot provision.

Request body

{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone": "+1 250 555 0100",
  "service_address": "12 Main St, Unit 4, Victoria",
  "postal_code": "V9A 0B7",
  "marketing_consent": "granted",
  "notes": "Asked about 1 Gbit"
}

Field	Required	Limits and notes
`first_name`	yes	1–100 characters
`last_name`	yes	1–100 characters
`email`	`email` or `phone`	Up to 254 characters; must contain `@` and no spaces
`phone`	`email` or `phone`	Up to 40 characters, any format
`service_address`	yes	1–300 characters, free text — the address the shopper wants service at, including the unit if they gave one
`postal_code`	no	Up to 20 characters, stored as sent
`marketing_consent`	no	`granted` or `denied`. Omit it when you didn’t ask — the lead is then stored as `unknown`. A lead stored as `unknown` or `denied` receives no marketing campaigns from the provider.
`notes`	no	Up to 2000 characters — anything else the shopper told you

At least one of email and phone must be present. Leading and trailing spaces are trimmed, and an empty or blank optional field counts as not sent. Any field not listed above — including stage, source or a provider id — is rejected with 422: the provider always comes from your API key, and the stage is always Waitlist.

Response — 201 Created

{
  "lead_id": "6f1c2a7e-0b9d-4c51-9e3f-2d8a41c7b5e0",
  "stage": "waitlist"
}

Field	Meaning
`lead_id`	The id of the new lead in your Provider Portal.
`stage`	Always `waitlist`.

What happens — and what doesn’t

The lead is stored with stage Waitlist, source Partner, and creation method API / integration, so your team can tell storefront leads from ones they entered by hand.
The address is stored exactly as you send it. kurnl does not look it up or attach it to a building.
Every request creates a new lead. There is no de-duplication on e-mail or phone — two identical requests give you two leads. Guard your submit button against double clicks.
kurnl sends no e-mail to the shopper and no notification to your staff. Show the shopper your own confirmation.

Errors

Status	Detail
401	Missing or invalid `X-API-Key`
403	API access disabled for your account, or the key is missing the `leads:write` scope
422	Validation failed — a required field is missing or blank, neither `email` nor `phone` was sent, a value is too long, `marketing_consent` is not `granted`/`denied`, or the body has an unknown field. The body is FastAPI’s standard `detail` array; each entry’s `loc` names the field, or just `body` for the email-or-phone rule.
429	Rate limit exceeded — 60 requests / minute per API key
500	The lead could not be saved. Nothing was stored; it is safe to retry.

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Endpoint

Request body

Response — 201 Created

What happens — and what doesn’t

Errors

​Endpoint

​Request body

​Response — 201 Created

​What happens — and what doesn’t

​Errors

Endpoint

Request body

Response — 201 Created

What happens — and what doesn’t

Errors