Customers
A Customer is a client of your platform — the business under which you group principals for your own administration, support, and reporting. Entirely opt-in: never set one, and nothing changes.
What a Customer is
Platforms rarely serve principals one at a time — they serve businesses, and each business brings its principals with it. The Customer object gives that relationship a first-class handle: create one per client, group its principals under it, and filter, report, and act on them together.
A Customer changes how you see and manage your principals. It changes nothing about how the scheme sees them — each principal remains individually verified, individually certificated, and individually accountable.
No protocol standing
A Customer has no protocol standing: it is never verified by the Operator, appears in no identity document, certificate, or settlement, and gates no transaction, escrow, dispute, or rating behaviour. Accountability rests with each principal.
Verifying your Customers is your platform’s job — the Operator never does it and cannot. Verification in the scheme attaches to principals; whatever diligence you run on the businesses you serve sits in your own onboarding, where it belongs.
The object and its endpoints
| Call | Does |
|---|---|
POST /v1/customers | Creates a customer. Returns a cust_… id. |
GET /v1/customers | Lists your customers with principal_count and agent_count. |
GET /v1/customers/{cid} | Reads one. |
PATCH /v1/customers/{cid} | Renames, updates external_ref or metadata, or changes status. |
DELETE /v1/customers/{cid} | Soft-deletes. Refused with 409 customer_not_empty while principals remain. |
| Field | Notes |
|---|---|
name | Display name, yours to choose. |
external_ref | Your own id for this customer — a CRM or billing key. Unique per platform when provided. |
status | active or suspended. See below. |
principal_count · agent_count | Live counts of what the customer holds. |
metadata | Free-form key–value, yours. |
Grouping principals
Set customer_id when registering a principal, or assign and move later with
PATCH /v1/principals/{pid}; null ungroups. GET /v1/principals?customer_id=<cid>
scopes a listing to one customer, and ?customer_id=none returns principals not
grouped under any.
Two guardrails: a customer_id referencing an unknown Customer, or one belonging
to another platform, fails with 422 naming the field in field_errors; and your
own tenant principal never groups under a Customer — that attempt returns
409 tenant_principal_field_locked, because the tenant principal is you, not a
customer of yours.
Suspension semantics
Suspending a customer suspends every principal under it, cascading to their agents — one call for a lapsed contract. Reactivating a customer is a label flip only: principals return individually, on the principal, so a customer un-suspend can never silently reactivate something suspended for its own reasons.
The asymmetry is deliberate. Suspension is the emergency lever, so it cascades; reactivation is a judgment, so it does not. After reactivating a customer, review its principals and restore each you intend to.
Deleting
Deletion is soft and refused while the customer still holds principals — reassign or ungroup them first. A label is never deleted out from under live principals.
Customer graduation
A customer whose activity reaches platform scale — $1,000,000 settled in any trailing twelve months, or 10,000 production agents — accredits as a platform in its own right, its principals migrating under protocol identity portability. The rule, its thresholds, and the servicing-continuity terms live in the Terms of Service ↗ and the Operator Rulebook ↗.