GET /api/agent/contacts/summary
Population-level rollup of XeroContact + TrendBaseline. Use FIRST for any 'how many customers do we have?', 'who are my top 10 customers?', 'what's the ABC tier distribution?' question. Counts (byType, abcDistribution) reconcile against the operator's contact ledger regardless of scope. unclassified in the ABC distribution surfaces warming customers so the agent knows the count of we don't know yet rows.
Auth
- Required scope:
READ_SUMMARY - Header:
Authorization: Bearer cr_live_<prefix>_<secret>
Query parameters
| Name | Type | Required | Notes |
|---|---|---|---|
topN | integer | no | Cap on topByRevenue / topBySpend length. |
Responses
200 — Aggregate contacts summary
Body: ContactsSummaryResponse
| Field | Type | Required | Notes |
|---|---|---|---|
asOfDate | string (date) | yes | |
currency | string | yes | |
byType | object | yes | |
abcDistribution | object | yes | |
topByRevenue | array of SummaryTopContact | yes | Top customers by TrendBaseline.ltvCumulative (cumulative gross-profit LTV). |
topBySpend | array of SummaryTopContact | yes | Top suppliers by aggregate XERO_BILL gross amounts. The per-supplier spend baseline isn't materialised in TrendBaseline yet; v1 computes this in-memory at request time. |
redactedItemCount | integer | yes | Aggregate count of topByRevenue + topBySpend rows whose name was rewritten to Sensitive contact. Always 0 with READ_SENSITIVE. |
billingAlert | BillingAlert | no | |
xeroAlert | XeroAlert | no |
401 — Unauthorized
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
403 — Key lacks the required scope
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
429 — Rate-limited or quota-exhausted
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
Response headers
Every successful response carries X-CashRunway-Subscription, X-CashRunway-Plan, X-CashRunway-Quota-Remaining, and X-CashRunway-Quota-Reset. Trialing subscriptions also include X-CashRunway-Trial-Days-Remaining. See the overview for details.