AI Support Agent

Base URL: https://middleware.bso-projects.com/partner. All calls send X-API-Key; the ones marked verified also require X-Verified-Session (see Authentication). Every response is a typed, documented schema — the same shapes are rendered in the interactive Swagger. Internal fields (Stripe IDs, operator notes, MAC, user_id) are never exposed.

Identify

Search customers

GET /agent/customers/search?q={term}&limit={n} Matches contact name, email, phone, short account id, invoice address, building/unit and service location. Returns masked matches only — enough to identify a caller, not enough to leak PII before verification.

curl "https://middleware.bso-projects.com/partner/agent/customers/search?q=%2B1-555-0100" \
  -H "X-API-Key: krnl_..."

{
  "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", "street": "120 Main St", "city": "Victoria",
          "postalcode": "V8W 1A1", "province": "BC", "country": "CA", "subscription_status": "ACTIVE" }
      ],
      "matched_on": ["phone"]
    }
  ]
}

Disambiguation. When ambiguous is true (match_count > 1), ask the caller for their service address or unit, append it to q, and search again — service_locations on each candidate is the discriminator. Never auto-select a match; if it stays ambiguous, ask another distinguishing detail or escalate.

Get a customer

GET /agent/customers/{customerId} Full profile — contacts, invoice address, service locations, subscriptions. Requires a verified session (verify the caller first). Returns 404 if the customer is not owned by your provider (no cross-provider enumeration). Internal fields are never returned.

{
  "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", "housenumber": "120", "unitnumber": "4", "floor": null, "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" } ]
}

Verify

See Authentication for POST /agent/verify/issue and POST /agent/verify/check. verify/issue accepts channel: "email" (default) or "sms" (SMS is delivered via Twilio and is inert until configured — returns 503 dependency_unconfigured otherwise).

Answer

Billing summary

GET /agent/customers/{customerId}/billing-summary

curl https://middleware.bso-projects.com/partner/agent/customers/sub-abc/billing-summary \
  -H "X-API-Key: krnl_..." -H "X-Verified-Session: <token>"

{
  "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://…" } ]
}

Payment history

GET /agent/customers/{customerId}/payments The customer’s payments. (kurnl has no separate payments table — a paid invoice with its Stripe payment-intent is the payment record — so this is derived from paid invoices.)

{
  "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" }
}

Network health

GET /agent/customers/{customerId}/network-health Read-only per-subscription provisioning/activation status plus modem (CPE) status from the ACS when available. No switch control, no live-switch queries.

{
  "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" } } ]
}

Communication history

GET /agent/customers/{customerId}/tickets The customer’s support tickets, read by their email on file.

{ "tickets": [ { "id": 4242, "number": "T-4242", "title": "Slow speeds", "state": "open", "priority": "normal", "created_at": "2026-07-01T09:00:00Z", "updated_at": "2026-07-02T10:00:00Z" } ] }

Act

Preview a plan change

POST /agent/customers/{customerId}/plan-change/preview Returns the exact billing impact — recurring change plus the one-time prorated adjustment for the rest of this calendar month — without applying anything. Use it to explain the cost before confirming.

curl -X POST https://middleware.bso-projects.com/partner/agent/customers/sub-abc/plan-change/preview \
  -H "X-API-Key: krnl_..." -H "X-Verified-Session: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "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 the three cases 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 (see below).

one_time_adjustment is nullable. It comes back null, with an explanatory note and a normal 200, in three cases:

the current calendar month has not been invoiced yet — the monthly invoice will simply reflect the new price, so there is nothing to charge or credit today (note: “This month has not been invoiced yet; the monthly invoice will reflect the new price.”)
an invoice exists for the month but its billing-document row is missing (note: “invoice exists, billing document missing — reconcile”)
the billing-document row exists but the invoice record is missing (note: “document exists, invoice record missing — reconcile”)

The last two mean the invoice and the correction-tracking document disagree with each other — read that as an operator-escalation state, not a number to quote to the caller.When it is not null, one_time_adjustment.type is one of:

next_invoice_line — an upgrade. Nothing is charged today; the amount appears as a labelled line on the customer’s next monthly invoice.
credit — a downgrade. The amount is credited now and applied to the next invoice.
none — the correction rounds to less than $0.50 and is skipped rather than issued; amount is 0.00. It isn’t lost — it’s folded into whichever correction runs next.

days / days_in_period replace the old proration_factor: the billing period is the calendar month, so the adjustment is price difference x days / days in that month. There is no due_in_days any more — an upgrade is never billed on its own; it always rides the next monthly invoice. 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.

Apply a plan change

POST /agent/customers/{customerId}/plan-change Applies the change. Requires confirm: true — call it only after the customer has seen the preview and agreed. Proration is handled automatically.

Plan-change apply is live wherever your key has access — there is no sandbox gate: a call with confirm: true applies a real, billing-affecting change in production. Use it deliberately. Planned-but-not-shipped hardening: a signed quote_token (preview→apply), an Idempotency-Key, and a change-confirmation/rollback flow (all planned, none shipped). Validate the read + verify + escalate loop first.

curl -X POST https://middleware.bso-projects.com/partner/agent/customers/sub-abc/plan-change \
  -H "X-API-Key: krnl_..." -H "X-Verified-Session: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "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; port bandwidth updated to 500 Mbps", "manual_provisioning_required": false }

Without confirm: true the call returns 400 confirmation_required.

Update contact fields

PATCH /agent/customers/{customerId}/contact Update the customer’s approved contract or invoice contact fields. Benign write — no billing or network impact. Applies immediately — there is no confirmation email or rollback yet (see Change confirmation & rollback).

curl -X PATCH https://middleware.bso-projects.com/partner/agent/customers/sub-abc/contact \
  -H "X-API-Key: krnl_..." -H "X-Verified-Session: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "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 } }

contact_type: contract (default) | invoice. Only the fields you send are changed.

Password reset / resend activation

POST /agent/customers/{customerId}/password-reset Emails the customer a self-service portal link — a password-reset link (15-min token) or a re-sent account set-up link (14-day token; the provider’s “Account setup email” template). The customer completes it themselves.

curl -X POST https://middleware.bso-projects.com/partner/agent/customers/sub-abc/password-reset \
  -H "X-API-Key: krnl_..." -H "X-Verified-Session: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "password_reset" }'

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

action: password_reset (default) | resend_activation.
resend_activation only applies while the customer has not yet chosen a password; afterwards it answers 409 already_activated — send a password_reset instead.

Resend an invoice

POST /agent/customers/{customerId}/invoices/{invoiceId}/resend Emails a copy of the invoice to the customer.

{ "status": "sent", "invoice_number": "INV-2" }

Add a support note

POST /agent/customers/{customerId}/notes Append an internal, operator-visible note to the customer’s record, attributed to the AI agent. Never shown to the customer.

curl -X POST https://middleware.bso-projects.com/partner/agent/customers/sub-abc/notes \
  -H "X-API-Key: krnl_..." -H "X-Verified-Session: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Caller reported intermittent drops; advised ONT reboot, resolved on call." }'

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

Escalation

Create a ticket

POST /agent/tickets Opens an enriched support ticket routed to the provider’s support group. Not verification-gated, so it works even when the caller can’t be verified — the primary escalation path on repeated auth failure or any downstream error. Provide customer_id (must be your provider’s) or a contact_email.

curl -X POST https://middleware.bso-projects.com/partner/agent/tickets \
  -H "X-API-Key: krnl_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "sub-abc",
    "subject": "Internet down after activation",
    "body": "Customer reports 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: low | normal | high.
ai_summary and ai_diagnosis go into the customer-facing article; transcript is stored as an internal note.

Change confirmation & rollback

Not yet implemented. Contact/personal-data changes are applied immediately with no confirmation email and no rollback link — do not present this as a safeguard to callers or rely on it as a mitigation against socially-engineered verification. An out-of-band confirmation + rollback flow is planned; until it ships, treat every agent-initiated change as final and escalate doubtful requests to a human instead.

Rate limits

Endpoint	Limit
`customers/search`, `customers/{id}`, `billing-summary`, `payments`	120 / min
`customers/{id}/tickets`, `network-health`, `plan-change/preview`, `notes`, `tickets` (create)	60 / min
`invoices/{id}/resend`, `contact`	30 / min
`verify/check`, `plan-change`	20 / min
`verify/issue`, `password-reset`	10 / min

Exceeding a limit returns 429 (standard rate-limit response; not the error envelope below). Back off and retry.

Errors

Most /agent errors return a normalized envelope with a stable, machine-readable code and a request_id you can quote to support — so your agent branches on the code, not the message:

{ "error": { "code": "verification_required", "message": "Customer verification required — verify identity (email/SMS OTP) first", "request_id": "a1b2c3d4e5f6" } }

`code`	HTTP	When	Recommended agent behaviour
`invalid_api_key`	401	Missing/invalid `X-API-Key`	Integration/config error — cannot proceed; alert the integration owner.
`agent_access_disabled`	403	Key lacks `agent_api_access`	Config error; alert the integration owner.
`verification_required`	401	Protected call without a session	Run the verify flow, then retry.
`verification_invalid`	401	Session expired / wrong customer	Re-verify the caller.
`otp_invalid`	401	Wrong or expired code	Re-read / re-send the code; escalate after repeated failures.
`no_verification_channel`	422	No email/phone on file to verify	Try the other channel, or escalate.
`not_found`	404	Not found or not owned by your provider	Treat as not found (no enumeration).
`validation_error`	422	Bad request shape / missing fields	Fix the request.
`confirmation_required`	400	Plan change without `confirm: true`	Show the preview, resend with `confirm: true`.
`downstream_unavailable`	502	Ticketing / billing / ACS unreachable	Do not retry blindly — tell the caller it’s temporarily unavailable and hand over (create a ticket / offer a callback).
`dependency_unconfigured`	503	Capability not configured (e.g. SMS, ticketing)	Treat that capability as unavailable; hand over.
`bad_request`	400	Generic bad request	Fix the request.
`server_error`	500	Unexpected error	Transient; never auto-retry a write. Hand over and quote `request_id`.

Envelope gaps — handle plain {"detail": "…"} bodies too: the plan-change apply endpoint delegates internally and returns plain HTTPException bodies without a code (400 “Only active subscriptions…”, 400 same-plan, 404 “New plan version not found”, 400 cross-provider); truly unhandled errors return FastAPI’s default 500 {"detail": "Internal Server Error"}; and an account with API access disabled surfaces as 403 with code: invalid_api_key (not agent_access_disabled) because auth errors are re-wrapped. Branch on code when present, fall back to detail + status otherwise.

Recommended default on downstream (502/503) and server (500) errors: graceful handover — create an escalation ticket and offer a human callback rather than retrying. Back off on 429, re-verify on session errors. These behaviours are configurable to your agent design.

Getting Started

Operator Guides

Partner Integration

Changelog

AI Support Agent — Endpoint Reference

Identify

Search customers

Get a customer

Verify

Answer

Billing summary

Payment history

Network health

Communication history

Act

Preview a plan change

Apply a plan change

Update contact fields

Password reset / resend activation

Resend an invoice

Add a support note

Escalation

Create a ticket

Change confirmation & rollback

Rate limits

Errors

​Identify

​Search customers

​Get a customer verified

​Verify

​Answer

​Billing summary verified

​Payment history verified

​Network health verified

​Communication history

​Act

​Preview a plan change verified

​Apply a plan change verified

​Update contact fields verified

​Password reset / resend activation verified

​Resend an invoice verified

​Add a support note verified

​Escalation

​Create a ticket

​Change confirmation & rollback

​Rate limits

​Errors

Identify

Search customers

Get a customer

Verify

Answer

Billing summary

Payment history

Network health

Communication history

Act

Preview a plan change

Apply a plan change

Update contact fields

Password reset / resend activation

Resend an invoice

Add a support note

Escalation

Create a ticket

Change confirmation & rollback

Rate limits

Errors