AI Support Agent

These endpoints are called by an AI support agent on behalf of a caller. See the AI Support Agent guide for the conversation flow and integration walkthrough. Responses are typed schemas — the same shapes render in the interactive Swagger.

Authentication

Two layers (see Authentication):

X-API-Key: krnl_... — your provider key, which must have the agent_api_access feature enabled. Required on every call.
X-Verified-Session: <token> — a short-lived session obtained via the verify flow, required on the endpoints marked verified below.

Endpoints

Method	Path	Auth	Description
`GET`	`/partner/agent/customers/search`	key	Find a customer; masked matches + `match_count`/`ambiguous`
`GET`	`/partner/agent/customers/{id}`	key + verified	Full customer profile (own provider only)
`GET`	`/partner/agent/customers/{id}/tickets`	key	Customer’s support tickets (comms history)
`POST`	`/partner/agent/verify/issue`	key	Send a one-time code (email or SMS) to the customer
`POST`	`/partner/agent/verify/check`	key	Validate the code → returns a verified session
`GET`	`/partner/agent/customers/{id}/billing-summary`	key + verified	Balance, overdue, AutoPay, invoices
`GET`	`/partner/agent/customers/{id}/payments`	key + verified	Payment history
`GET`	`/partner/agent/customers/{id}/network-health`	key + verified	Read-only service/CPE health
`POST`	`/partner/agent/customers/{id}/notes`	key + verified	Add an internal support note
`PATCH`	`/partner/agent/customers/{id}/contact`	key + verified	Update approved contact fields
`POST`	`/partner/agent/customers/{id}/password-reset`	key + verified	Email password-reset / resend activation
`POST`	`/partner/agent/customers/{id}/invoices/{invoiceId}/resend`	key + verified	Email a copy of an invoice
`POST`	`/partner/agent/customers/{id}/plan-change/preview`	key + verified	Billing-impact preview (no change)
`POST`	`/partner/agent/customers/{id}/plan-change`	key + verified	Apply a plan change (`confirm: true`) — Phase 1.5
`POST`	`/partner/agent/tickets`	key	Create an enriched support ticket / escalate

GET /partner/agent/customers/search

Query params: q (min 2 chars, required), limit (1–100, default 25). Returns masked matches; when ambiguous is true, ask for the service address/unit, append to q, and search again.

{
  "match_count": 1,
  "ambiguous": false,
  "results": [
    { "customer_id": "sub-abc", "display_name": "Anna Beispiel", "company": null,
      "email_masked": "a***@example.com", "phone_masked": "•••00", "invoice_city": "Victoria",
      "service_locations": [ { "location_identifier": "BLDG-12/UNIT-4", "city": "Victoria", "subscription_status": "ACTIVE" } ],
      "matched_on": ["phone"] }
  ]
}

GET /partner/agent/customers/

Requires X-Verified-Session. Returns the slim CustomerProfile — no Stripe IDs, operator notes, MAC or user_id.

{
  "customer_id": "sub-abc",
  "customer_type": "RESIDENTIAL",
  "contract_contact": { "firstname": "Anna", "lastname": "Beispiel", "email": "anna@example.com", "phone": "+1-555-0100", "company": null },
  "invoice_contact": { "firstname": "Anna", "lastname": "Beispiel", "email": "anna@example.com", "phone": "+1-555-0100", "company": null },
  "invoice_address": { "street": "120 Main St", "unitnumber": "4", "postalcode": "V8W 1A1", "city": "Victoria", "province": "BC", "country": "CA", "full_address": "120 Main St, Unit 4, Victoria BC" },
  "service_locations": [ { "location_identifier": "BLDG-12/UNIT-4", "city": "Victoria", "subscription_status": "ACTIVE" } ],
  "subscriptions": [ { "subscription_id": "subn-1", "plan_name": "Fiber 500", "status": "ACTIVE", "is_active": true, "started_at": "2026-01-05T00:00:00Z" } ]
}

POST /partner/agent/verify/issue

channel is email (default) or sms. SMS is delivered via Twilio and is inert until configured (503 dependency_unconfigured).

{ "customer_id": "sub-abc", "channel": "email" }

Response — the code is sent, never returned:

{ "status": "sent", "sent_to": "a***@example.com", "channel": "email" }

POST /partner/agent/verify/check

{ "customer_id": "sub-abc", "code": "123456" }

{ "verified_session": "eyJhbGciOiJIUzI1Ni…", "expires_in": 900, "token_type": "verified-session" }

The token lasts 15 minutes and is bound to one (provider, customer) pair.

GET /partner/agent/customers//billing-summary

Requires X-Verified-Session.

{
  "customer_id": "sub-abc", "currency": "CAD", "balance": 50.00, "overdue_amount": 30.00,
  "next_due_date": "2026-08-01", "open_invoice_count": 2, "auto_pay_enabled": true,
  "payment_method_on_file": true,
  "last_payment": { "amount": 40.00, "date": "2026-06-01", "invoice_number": "INV-1" },
  "recent_invoices": [ { "invoice_number": "INV-2", "invoice_date": "2026-07-01", "due_date": "2026-08-01", "amount": 30.00, "paid": false, "status": "open", "pdf_url": "https://…" } ]
}

GET /partner/agent/customers//payments

Requires X-Verified-Session. Derived from paid invoices (no separate payments table).

{
  "customer_id": "sub-abc", "currency": "CAD",
  "payments": [ { "invoice_number": "INV-1", "amount": 40.00, "paid_on": "2026-06-01", "method": "card", "invoice_status": "paid" } ],
  "total_paid": 40.00,
  "last_payment": { "amount": 40.00, "date": "2026-06-01", "invoice_number": "INV-1" }
}

GET /partner/agent/customers//network-health

Requires X-Verified-Session.

{ "customer_id": "sub-abc", "acs_configured": true, "subscriptions": [ { "subscription_id": "subn-1", "status": "ACTIVE", "is_active": true, "started_at": "2026-01-05T00:00:00Z", "cpe": { "acs_configured": true, "registered": true, "last_inform": "2026-08-14T09:12:41.000Z" } } ] }

POST /partner/agent/customers//notes

Requires X-Verified-Session. Adds an internal, operator-visible note (attributed to the AI).

{ "body": "Caller reported intermittent drops; advised ONT reboot." }

{ "id": "note-1", "body": "Caller reported intermittent drops…", "created_at": "2026-07-24T14:02:00Z", "author_email": "ai-support-agent (Retell)" }

PATCH /partner/agent/customers//contact

Requires X-Verified-Session. contact_type is contract (default) or invoice; only the fields you send change. Applies immediately — no confirmation email or rollback exists yet (see Overview).

{ "contact_type": "contract", "email": "new@example.com", "phonenumber": "+1-555-0142" }

{ "status": "updated", "contact": { "firstname": "Anna", "lastname": "Beispiel", "email": "new@example.com", "phone": "+1-555-0142", "company": null } }

POST /partner/agent/customers//password-reset

Requires X-Verified-Session. action is password_reset (default, 15-min token) or resend_activation (the account set-up mail with a 14-day token; 409 already_activated once the customer has chosen a password — use password_reset then).

{ "action": "password_reset" }

{ "status": "sent", "detail": "Password reset link emailed to a***@example.com" }

POST /partner/agent/customers//plan-change/preview

Requires X-Verified-Session. Read-only quote of the billing impact of an upgrade or downgrade for the rest of the current calendar month — nothing is applied.

{ "subscription_id": "subn-1", "plan_version_id": "pv-2" }

{
  "subscription_id": "subn-1",
  "current_plan": { "name": "Basic", "monthly_price": 50.00 },
  "new_plan": { "name": "Pro", "plan_version_id": "pv-2", "monthly_price": 80.00 },
  "monthly_price_change": 30.00,
  "days": 15,
  "days_in_period": 31,
  "one_time_adjustment": {
    "type": "next_invoice_line",
    "amount": 14.52,
    "description": "Prorated upgrade for the rest of this month, added as a line on your next monthly invoice — nothing is charged today",
    "due_in_days": null
  },
  "note": "Your monthly price changes to the new plan from your next billing date. The one-time adjustment covers the rest of this calendar month: a downgrade is credited now, an upgrade is added to your next invoice.",
  "proration_factor": 0.4839
}

Breaking change (September 2026): one_time_adjustment may now come back null (see below); its type value that used to read charge now reads next_invoice_line. proration_factor (on the response) and due_in_days (inside one_time_adjustment) are deprecated and will be removed in the next release — read days / days_in_period instead. one_time_adjustment is null (with an explanatory note, still a 200) in three cases: the current calendar month has not been invoiced yet, or the invoice and the correction-tracking document disagree (one exists without the other — an operator-escalation state, not a number to quote to the caller). Otherwise type is next_invoice_line (upgrade — nothing charged today, a line on the next monthly invoice), credit (downgrade — credited now, applied to the next invoice), or none (the correction is under $0.50 and is skipped, folded into whichever correction runs next; amount is 0.00). days / days_in_period replace the old proration_factor; there is no due_in_days any more, since an upgrade never bills on its own. A second plan change on the same calendar DAY is refused with 409 — a change day is billed at the new price, so the next change is possible from tomorrow; only a kurnl platform admin can override that, and the AI cannot.

POST /partner/agent/customers//plan-change

Requires X-Verified-Session. Must include confirm: true (call /plan-change/preview first). Live — no sandbox gate. With confirm: true this applies a real, billing-affecting plan change wherever the key has access. Planned hardening (quote_token, Idempotency-Key, rollback) has not shipped.

{ "subscription_id": "subn-1", "plan_version_id": "pv-2", "confirm": true }

{ "subscription_id": "subn-1", "old_plan_version_id": "pv-1", "new_plan_version_id": "pv-2", "change_type": "UPGRADE", "message": "Plan changed successfully", "manual_provisioning_required": false }

POST /partner/agent/tickets

Not verification-gated (so escalation works for unverified callers). Provide customer_id (own provider) or contact_email.

{
  "customer_id": "sub-abc",
  "subject": "Internet down after activation",
  "body": "No connection since this morning.",
  "priority": "high",
  "ai_summary": "Line appears down; no outage on record.",
  "ai_diagnosis": "Possible port/provisioning issue.",
  "transcript": "caller: my internet stopped working…"
}

{ "id": 4242, "number": "T-4242", "title": "Internet down after activation", "state": "new" }

priority is low | normal | high; transcript is stored as an internal note.

Rate limits

Limit	Endpoints
120/min	search · customer · billing-summary · payments
60/min	customer tickets · network-health · plan-change/preview · notes · tickets (create)
30/min	invoice resend · contact
20/min	verify/check · plan-change
10/min	verify/issue · password-reset

Exceeding a limit returns 429 (standard rate-limit response; back off and retry).

Errors

Most errors use a normalized envelope with a stable code and a request_id — but the plan-change endpoint’s delegated validation errors and unhandled 500s return plain {"detail": "…"} without a code, and a disabled account surfaces as 403 invalid_api_key (see the reference’s envelope-gaps warning):

{ "error": { "code": "verification_required", "message": "…", "request_id": "a1b2c3d4e5f6" } }

`code`	HTTP	Meaning / agent behaviour
`invalid_api_key`	401	Missing/invalid `X-API-Key` — config error, cannot proceed
`agent_access_disabled`	403	Key lacks `agent_api_access` — config error
`verification_required`	401	No verified session — run the verify flow
`verification_invalid`	401	Session expired / wrong customer — re-verify
`otp_invalid`	401	Wrong/expired code — re-send; escalate after repeats
`no_verification_channel`	422	No email/phone on file — try other channel or escalate
`not_found`	404	Not found or not owned by your provider
`validation_error`	422	Bad request shape / missing fields
`confirmation_required`	400	Plan change without `confirm: true`
`downstream_unavailable`	502	Ticketing/billing/ACS unreachable — don’t retry blindly; hand over (ticket + callback)
`dependency_unconfigured`	503	Capability not configured (e.g. SMS) — hand over
`bad_request`	400	Generic bad request
`server_error`	500	Unexpected — transient; never auto-retry a write; hand over, quote `request_id`

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

Provider Operations (Internal API)

AI Support Agent

Authentication

Endpoints

GET /partner/agent/customers/search

GET /partner/agent/customers/

POST /partner/agent/verify/issue

POST /partner/agent/verify/check

GET /partner/agent/customers//billing-summary

GET /partner/agent/customers//payments

GET /partner/agent/customers//network-health

POST /partner/agent/customers//notes

PATCH /partner/agent/customers//contact

POST /partner/agent/customers//password-reset

POST /partner/agent/customers//plan-change/preview

POST /partner/agent/customers//plan-change

POST /partner/agent/tickets

Rate limits

Errors

​Authentication

​Endpoints

​GET /partner/agent/customers/search

​GET /partner/agent/customers/

​POST /partner/agent/verify/issue

​POST /partner/agent/verify/check

​GET /partner/agent/customers//billing-summary

​GET /partner/agent/customers//payments

​GET /partner/agent/customers//network-health

​POST /partner/agent/customers//notes

​PATCH /partner/agent/customers//contact

​POST /partner/agent/customers//password-reset

​POST /partner/agent/customers//plan-change/preview

​POST /partner/agent/customers//plan-change

​POST /partner/agent/tickets

​Rate limits

​Errors

Authentication

Endpoints

GET /partner/agent/customers/search

GET /partner/agent/customers/

POST /partner/agent/verify/issue

POST /partner/agent/verify/check

GET /partner/agent/customers//billing-summary

GET /partner/agent/customers//payments

GET /partner/agent/customers//network-health

POST /partner/agent/customers//notes

PATCH /partner/agent/customers//contact

POST /partner/agent/customers//password-reset

POST /partner/agent/customers//plan-change/preview

POST /partner/agent/customers//plan-change

POST /partner/agent/tickets

Rate limits

Errors