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": 1721400000000 } } ]
}

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 charge/credit — 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,
  "proration_factor": 0.5,
  "one_time_adjustment": { "type": "charge", "amount": 15.00, "due_in_days": 7, "description": "Prorated upgrade charge to the end of the current cycle (due in 7 days)" },
  "note": "Recurring monthly price changes to the new plan from your next billing date; the one-time adjustment covers the remainder of the current cycle."
}

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 and AutoPay are Phase 1.5: the endpoints exist and are reachable on the sandbox, but before general availability they gain a signed quote_token (preview→apply), an Idempotency-Key, and the change-confirmation/rollback flow below. 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. Triggers the change-confirmation email.

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 activation/invite link (72-h token). 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 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

Any account- or personal-data change the agent makes is applied immediately and triggers an out-of-band confirmation email to the subscriber’s address on file: “We’re confirming change request #XYZ — click here to roll it back if this wasn’t you.” The link is valid for 3 days; clicking it reverses the change and opens a provider ticket. This guarantees the real account holder is always notified through a channel the caller doesn’t control — a guard against socially-engineered verification. Applies to contact/personal-data edits (Phase 1) and plan-change / AutoPay (Phase 1.5). Password resets already deliver to the inbox by nature.

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

Every /agent error returns 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`.

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

Integration Guides

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