The AI Support Agent API is a dedicated surface that lets an AI voice or chat agent authenticate a caller and act on their behalf — answering account, billing, plan and service questions, making approved changes, and escalating to a human with full context. It is designed around one principle: the backend is the source of truth. The AI never stores customer data or makes unrestricted changes — it reads and writes only through this authenticated, rate-limited API.
Interactive Swagger — explore and try the agent endpoints live at https://middleware.bso-projects.com/partner/agent/docs. It shows only the /agent surface (spec at /partner/agent/openapi.json).
The base URL is https://middleware.bso-projects.com/partner; every agent path starts with /agent/. All calls require an agent-enabled API key plus, for anything sensitive, a short-lived verified session the agent obtains after the customer passes an email one-time code. See Authentication.

​
The conversation flow

A typical support conversation follows the same shape. Each step maps to one or two calls:
1

Identify the caller

Find the customer by phone, email, service address, unit, or customer ID. GET /agent/customers/search
2

Verify identity

Email a one-time code, then validate it to get a verified session bound to that customer. POST /agent/verify/issue → POST /agent/verify/check
3

Answer questions

Read the customer’s profile, billing summary, network health, and plans. GET /agent/customers/{id} · .../billing-summary · .../network-health
4

Make approved changes

Preview and apply a plan change (with the customer’s confirmation), resend an invoice. POST /agent/customers/{id}/plan-change/preview → .../plan-change
5

Escalate

Open an enriched support ticket for anything the AI can’t resolve. POST /agent/tickets

​
What the API covers today

SMS one-time codes are supported (via Twilio) but inert until Twilio is configured for the provider. Modem reboot / self-heal, technician scheduling, and a knowledge-base content API are later phases and not part of this surface yet.
Plan change is LIVE, not sandboxed. POST /agent/customers/{id}/plan-change applies a real, billing-affecting plan change wherever the key has agent access — there is no sandbox gate on this endpoint. Only send confirm: true deliberately, after the customer has seen the /plan-change/preview cost. Planned controls (signed quote token, Idempotency-Key) are not implemented yet — do not rely on them.

​
Design guarantees

  • Backend-first — the AI is an interface, not a system of record.
  • Provider-scoped — an agent key only ever sees its own provider’s customers.
  • Masked-until-verified — search returns only masked contact detail; the full profile and all account data require a verified session.
  • Verification-gated — sensitive reads and every change require a verified session.
  • Confirmation-gated writes — a plan change only applies with an explicit confirm: true after the customer has seen the previewed cost.
  • Predictable errors — every failure returns a normalized { "error": { "code", "message", "request_id" } } envelope with a stable code set, so the agent branches on the code rather than parsing messages. See Reference.
  • Changes apply immediately — contact edits and plan changes take effect as soon as the call succeeds. A change-confirmation email with a rollback link is planned but not yet implemented — do not rely on it as a mitigation against socially-engineered verification.
  • Partial audit trail — today only the plan-change write records an audit entry (fire-and- forget, so it can be lost on failure); per-call audit logging for the rest of the agent surface is planned, not shipped. Don’t treat the audit log as complete.
Next: Authentication · Endpoint reference.