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).
All endpoints live under https://middleware.bso-projects.com/partner/agent. They 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. Plan change / AutoPay writes are Phase 1.5: the endpoints exist and are reachable on the sandbox, but are enabled for GA once their quote-token / idempotency / rollback controls land. Modem reboot / self-heal, technician scheduling, and a knowledge-base content API are later phases and not part of this surface yet.

​
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.
  • Change confirmation & rollback — account- and personal-data changes trigger an out-of-band email to the subscriber with a 3-day rollback link (“roll it back if this wasn’t you”) — a guard against socially-engineered verification.
  • Audited — every call is logged and attributable to the agent.
Next: Authentication · Endpoint reference.