# Customer endpoints

> Read customer records, services, contacts, reports, contracts, invoices and subscriptions over the One API, for your organisation or a partner's customers.

Source: https://docs.vigilbase.com/one/api/customers

A customer is the record Vigilbase keeps for an organisation it serves. Your organisation has one; a partner organisation also manages the customers it brought to Vigilbase. These endpoints read those records. Sign-in, permissions, rate limits and error shapes are on [Vigilbase One API](https://docs.vigilbase.com/one/api).

These are v1 operations, on `https://api.vigilbase.com/one/v1`:

| Method and path | Permission | CLI command |
| --- | --- | --- |
| `GET /customers` | `read:customers` | `vigilbase customers list` |
| `GET /customers/{customerId}` | `read:customers` | `vigilbase customers summary <id>` |
| `GET /customers/{customerId}/services` | `read:services` | `vigilbase customers services <id>` |
| `GET /customers/{customerId}/endpoints` | `read:services` | `vigilbase customers endpoints <id>` |
| `GET /customers/{customerId}/contacts` | `read:customers` | `vigilbase customers contacts <id>` |
| `GET /customers/{customerId}/organization` | `read:customers` | `vigilbase customers organization <id>` |
| `GET /customers/{customerId}/reports` | `read:customers` | |
| `GET /customers/{customerId}/recon-reports` | `read:customers` | `vigilbase customers reports <id>` |
| `GET /customers/{customerId}/recon-reports/{reportId}` | `read:customers` | `vigilbase customers report <id> <report-id>` |
| `GET /customers/{customerId}/contracts` | `read:contracts` | `vigilbase customers contracts <id>` |
| `GET /customers/{customerId}/contracts/{contractId}` | `read:contracts` | |
| `GET /customers/{customerId}/usage-alerts` | `read:contracts` | |
| `GET /customers/{customerId}/billing` | `read:billing` | `vigilbase customers billing <id>` |
| `GET /customers/{customerId}/invoices` | `read:billing` | `vigilbase customers invoices <id>` |
| `GET /customers/{customerId}/subscriptions` | `read:billing` | `vigilbase customers subscriptions <id>` |

This one has no v1 operation yet, and is on `https://one.vigilbase.com`:

| Method and path | Permission | CLI command |
| --- | --- | --- |
| `GET /api/customers/{id}` | `read:customers` | |

Watchdog, monitoring and incident reads for a customer are on [Watchdog and monitoring](https://docs.vigilbase.com/one/api/watchdog-and-monitoring), and Cloudflare reads on [Cloudflare](https://docs.vigilbase.com/one/api/cloudflare).

## Which customers you can read

`{customerId}` is a customer UUID. You can read your own organisation's customer and, in a partner organisation, the customers it manages. Any other ID answers `403`, including an ID that doesn't exist.

Reports are the exception: a partner gets no reports for a managed customer, only for its own record. A customer billed through a partner is refused the contract and billing operations; ask the partner.

Some CLI `customers` commands, such as `investigations` and `projects`, read data reserved for Vigilbase staff; customer sign-ins don't get it.

Lists on these pages are [cursor pages](https://docs.vigilbase.com/one/api#pagination): `{ "items": [ … ], "nextCursor": "…" }`. Times are ISO 8601 strings.

## List customers

`GET /customers` lists the customers you can read, newest first. For a customer organisation that is your own record; for a partner organisation, the customers it manages, which needs `read:partner_customers`. Each item has `id`, `name`, `domain`, `industry`, `lifecycleStatus`, `onboardingStatus`, `accountOwnerName`, `partner` (`id`, `name`, or `null`), `services` (each with `tool` and `status`), `createdAt` and `updatedAt`.

## Customer details

`GET /customers/{customerId}` returns one customer: the list fields without `services`, plus `isPartner` and `serviceCounts` (`active`, `total`, `error`).

```json
{
  "id": "…",
  "name": "Example Ltd",
  "domain": "example.com",
  "industry": null,
  "lifecycleStatus": "active",
  "onboardingStatus": "completed",
  "accountOwnerName": "…",
  "partner": null,
  "isPartner": false,
  "serviceCounts": { "active": 3, "total": 3, "error": 0 },
  "createdAt": "2026-03-02T10:00:00.000Z",
  "updatedAt": "2026-10-30T09:12:44.000Z"
}
```

The other reads of one customer:

| Operation | Each item has |
| --- | --- |
| `GET /customers/{customerId}/services` | `id`, `tool`, `status`, `serviceType`, `billingTier`, `linkedAccountId`, `domain`, `bandwidthLimitTb`, `monthlyAmount`, `currentPeriodStart`, `currentPeriodEnd`, `createdAt`, `updatedAt`. Newest first. `monthlyAmount` is `null` unless you have `read:billing` |
| `GET /customers/{customerId}/endpoints` | `id`, `displayName`, `systemName`, `dnsName`, `deviceType`, `nodeClass`, `integration`, `offline`, `approvalStatus`, `maintenanceStatus`, `ipAddresses`, `publicIp`, `locationName`, `lastLoggedOnUser`, `lastContact`, `lastUpdate`, `createdAt`, `updatedAt`. By display name |
| `GET /customers/{customerId}/contacts` | `name`, `email`, `phone`, `role`, `isTechnicalContact`, `isBillingContact` |

`GET /customers/{customerId}/organization` returns `hasOrganization` and `organizationId`: whether the customer has its Vigilbase Identity organisation, the one its people sign in to.

`GET /api/customers/{id}` on one.vigilbase.com returns the full record in `data`, with `partner`, `services`, `endpoints`, `integrationStatus` and `quotes`. Service prices are left out unless you have `read:billing`.

## Reports

`GET /customers/{customerId}/reports` lists the monthly security reports and quarterly business reviews together, latest period first. Each item has `id`, `kind` (`monthly` or `quarterly`), `period` (`start`, `end`, `label`), `status`, `updatedAt` and `isShared`. You see published quarterly reviews only.

`GET /customers/{customerId}/recon-reports` lists only the monthly security reports, the ones One shows under **Reports**, newest period first. Each item has `id`, `period`, `status` (`pending`, `generating`, `completed` or `failed`), `generatedAt`, `hasPublicLink` and `availableSections`.

`GET /customers/{customerId}/recon-reports/{reportId}` returns one report with its sections: `executiveSummary`, `threatLandscape`, `insights`, `aiAnalysis`, `comparison`, `endpoint`, `backup`, `cloudflare`, `support` and `billing`, plus `period`, `status`, `branding` and `publicLink` (whether a share link exists; the link itself isn't returned). `billing` is `null` unless you have `read:billing`, and always for a customer billed through a partner.

## Contracts

`GET /customers/{customerId}/contracts` lists the contracts the customer owns or that its partner linked to it, newest first.

| Parameter | Description |
| --- | --- |
| `status` | `draft`, `pending`, `active`, `expired` or `terminated` |
| `expiringWithinDays` | 0 to 3650: only contracts expiring between today and that many days ahead |

Each contract has `id`, `reference` (the contract number, such as `C-1001`), `name`, `description`, `status`, `isLinked`, `effectiveDate`, `expirationDate`, `signedDate`, `autoRenewal`, `renewalNoticeDays`, `billingFrequency`, `totalValue`, `currency`, `lineItems`, `invoices`, `createdAt` and `updatedAt`. Contract amounts are in major units (dollars, not cents), and `null` unless you have `read:billing`. A contract with `isLinked: true` belongs to the partner: you get its summary only, and its amounts, line items and invoices come back `null` or empty.

`GET /customers/{customerId}/contracts/{contractId}` returns one contract with the same fields plus `attachments` (each with `id`, `fileName`, `fileSize`, `mimeType`, `attachmentType`, `description`, `version`, `isLatest`, `uploadedAt`).

`GET /customers/{customerId}/usage-alerts` lists active line items whose usage is near or over the contracted limit, over-limit first. Each has `contractId`, `contractName`, `serviceName`, `serviceType`, `usagePercentage` and `status` (`warning`, `critical` or `over_limit`).

## Billing overview

`GET /customers/{customerId}/billing` reads the customer's billing live from Stripe:

| Field | Contents |
| --- | --- |
| `isPartnerBilled` | `true` when the customer is billed through its partner |
| `partner` | The partner's `id` and `name`, or `null` |
| `billingContact` | `name` and `email` on the Stripe customer; `null` when billed through a partner or not set up |
| `monthlyRecurringRevenue` | Recurring revenue per month in minor units (cents), or `null` |
| `currency` | Its currency |
| `subscriptions`, `invoices` | As in the lists below |
| `paymentMethods` | Cards on file: `id`, `brand`, `last4`, `expMonth`, `expYear` |
| `contractCount` | Contracts behind partner billing; `null` otherwise |

A `502` problem with `upstream_unavailable` means Stripe couldn't be reached.

## Invoices and subscriptions

These two read Stripe live. Amounts are in the currency's minor units (cents for USD).

`GET /customers/{customerId}/invoices` lists the customer's most recent invoices, up to 100, newest first. Filter with `status`: `draft`, `open`, `paid`, `uncollectible` or `void`. Each invoice has `id`, `number`, `status`, `amountDue`, `amountPaid`, `amountRemaining`, `currency`, `description`, `subscriptionId`, `lineCount`, `createdAt`, `dueDate`, `paidAt`, `hostedInvoiceUrl` and `invoicePdfUrl`.

`GET /customers/{customerId}/subscriptions` lists the customer's subscriptions. Each has `id`, `status`, `description` (the product names), `currentPeriodStart`, `currentPeriodEnd`, `cancelAtPeriodEnd`, `canceledAt`, `createdAt` and `items`: each item's `id`, `quantity`, `price` (`unitAmount`, `currency`, `interval` and more) and `product` (`id`, `name`, `description`).

## Older paths

Each v1 operation here also answers at an older path on `https://one.vigilbase.com/api`, such as `GET /api/customers/{id}/summary` for `GET /customers/{customerId}`. The older paths are deprecated aliases and will be retired with `410 Gone`. Each operation's page in the [API reference](https://docs.vigilbase.com/one/api/reference) names its older path. See [hosts](https://docs.vigilbase.com/one/api#hosts).