> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastcac.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Business monitors

> Watch businesses on CAC's register and get a webhook when one goes inactive or changes its name.

A monitor watches one business on CAC's register. We read it once a day, and when its status or
registered name changes you get a webhook. The usual change is `ACTIVE` to `INACTIVE`, most often
because the business hasn't filed its annual returns.

## Monitor a business

`POST /v1/businesses/monitors` with the number, and your own reference if you like.

```bash theme={null}
curl https://api.fastcac.com/v1/businesses/monitors \
  -H "Authorization: Bearer $FASTCAC_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"number": "RC 7654321", "external_id": "merchant-4471"}'
```

```json Response (201) theme={null}
{
  "object": "business_monitor",
  "id": "mon_5Rfxqm9UQ4xlFxXoJeFCaT",
  "number": "7654321",
  "type": "RC",
  "type_label": "Company",
  "name": "ADA FOODS LIMITED",
  "status": "ACTIVE",
  "active": true,
  "external_id": "merchant-4471",
  "state": "active",
  "paid_through": "2026-11-27T15:16:04Z",
  "last_checked_at": null,
  "last_changed_at": null,
  "amount_charged": "100.00",
  "created_at": "2026-10-28T15:16:04Z"
}
```

| Field | What it is |
| - | - |
| `name`, `status`, `active` | What CAC listed at the last check. |
| `external_id` | Your reference, sent back in every event. |
| `state` | `active`; `paused` when a renewal couldn't be charged; `deleted` once you stop it. |
| `paid_through` | When the current 30 days end. |
| `last_checked_at`, `last_changed_at` | The last read of CAC's register, and the last change. A live monitor counts adding it as its first check; test monitors stay `null`. |

Watching the same business twice is `409 monitor_exists`, with the existing monitor's id in
`details.monitor`. A number CAC doesn't have is `404 cac_record_missing`, not charged. A number in
more than one register needs `type` (`400 type_required`). A wallet that can't cover 30 days is
`402 insufficient_balance`, checked before CAC is searched, and `503 cac_search_unavailable` means
CAC's search didn't answer; neither is charged.

## List, read and stop

* `GET /v1/businesses/monitors` lists them, newest first. Filter with `external_id`, page with
  `starting_after` ([pagination](https://docs.fastcac.com/api-basics/pagination.md)), and add `include_deleted=true` to see
  stopped ones.
* `GET /v1/businesses/monitors/{id}` reads one.
* `DELETE /v1/businesses/monitors/{id}` stops checks and renewals at once. The rest of the 30 days
  isn't refunded.

## Events

Add an endpoint for these on the **Webhooks** page or with the [webhooks API](https://docs.fastcac.com/webhooks/overview.md).
Each carries the monitor, with your `external_id`:

| Event | When |
| - | - |
| `business.status_changed` | CAC's status changed; `previous_status` says what it was. |
| `business.name_changed` | The registered name changed; `previous_name` says what it was. |
| `monitor.paused` | A 30-day renewal couldn't be charged, so checks stopped. |
| `monitor.resumed` | A paused monitor renewed and checks resumed. |

```json business.status_changed theme={null}
{
  "id": "evt_0000000000000000000000",
  "type": "business.status_changed",
  "api_version": "2026-11-01",
  "created_at": "2026-11-03T10:14:22Z",
  "data": {
    "object": "business_monitor",
    "id": "mon_5Rfxqm9UQ4xlFxXoJeFCaT",
    "external_id": "merchant-4471",
    "number": "7654321",
    "type": "RC",
    "name": "ADA FOODS LIMITED",
    "status": "INACTIVE",
    "previous_name": null,
    "previous_status": "ACTIVE",
    "state": "active"
  }
}
```

If CAC's register is down or briefly loses a record, nothing changes and no event is sent; the next
day's check tries again.

## Pricing

Each business costs **₦100 for 30 days** from the wallet of the key's mode, charged when you add it
and again when `paid_through` passes. The current price is on the **Pricing** page; each charge
shows as a `business_monitor_charge` in [your transactions](https://docs.fastcac.com/guides/balance.md#transactions).

When the wallet can't cover a renewal, the monitor pauses (`monitor.paused`, sent once) and isn't
checked. Fund your wallet: the next daily check charges it, starts a fresh 30 days and sends
`monitor.resumed`.

## Test mode

Test monitors watch the test business (ADA FOODS VENTURES for a `BN` number, ADA FOODS LIMITED
otherwise) and are never read from CAC or renewed. Make a change happen with the test helper,
which sends the same events a real change does:

```bash theme={null}
curl https://api.fastcac.com/v1/test_helpers/businesses/monitors/mon_5Rfxqm9UQ4xlFxXoJeFCaT/changes \
  -H "Authorization: Bearer $FASTCAC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "INACTIVE"}'
```

Send `status`, `name` or both; they're upper-cased like CAC's, and a value the monitor already has
sends no event. When creating, `?simulate=cac_record_missing` gives the `404` and
`?simulate=insufficient_balance` the `402`. The helper answers `403 test_mode_only` with a live key and
`409 monitor_deleted` for a monitor you've stopped.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.