> ## 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 lookups

> Search CAC's register by name or number for free, and get a business's full record with its officers.

Two calls: a free search that finds businesses on CAC's register, and a lookup that returns one
business's full record, with its address and officers.

## Search CAC's register

`GET /v1/businesses/search?query=` takes a business name, or a registration number with or without
its prefix (`7654321`, `RC 7654321`, `BN-1234567`). You get up to 50 businesses, best match first.

```bash theme={null}
curl "https://api.fastcac.com/v1/businesses/search?query=Ada%20Foods" \
  -H "Authorization: Bearer $FASTCAC_KEY"
```

```json Response (200) theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "cac_record",
      "number": "7654321",
      "type": "RC",
      "type_label": "Company",
      "name": "ADA FOODS LIMITED",
      "status": "ACTIVE",
      "active": true,
      "registered_on": "2024-03-18"
    },
    {
      "object": "cac_record",
      "number": "1234567",
      "type": "BN",
      "type_label": "Business name",
      "name": "ADA FOODS VENTURES",
      "status": "INACTIVE",
      "active": false,
      "registered_on": "2023-08-02"
    }
  ],
  "has_more": false
}
```

| Field | What it is |
| - | - |
| `number` | The registration number, digits only, as CAC stores it. |
| `type` | The register: `BN` business name, `RC` company, `IT` incorporated trustees, `LP` limited partnership, `LLP` limited liability partnership. The same number can exist in more than one. |
| `status`, `active` | As CAC lists it (`ACTIVE`, `INACTIVE`, `STRUCK OFF`…), and whether that's `ACTIVE`. Businesses usually go inactive for unfiled annual returns. |
| `registered_on` | `YYYY-MM-DD`. |

Search is **free**, with live and test keys alike: test keys search the real register too. It allows
30 searches a minute per organization with a live key and 10 with a test key; live lookups,
verifications and new monitors count towards it too, since each searches CAC. A query shorter than 2
characters is `400 parameter_invalid`. When CAC's search doesn't answer you get
`503 cac_search_unavailable`; try again in a minute.

## Look up a business

`POST /v1/businesses/lookups` with the number returns its full record: name, status, registration
date, address, email and its officers.

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

```json Response (201) theme={null}
{
  "object": "cac_lookup",
  "id": "cacl_7d33or8TF86voj7RKlJoO9",
  "number": "7654321",
  "type": "RC",
  "type_label": "Company",
  "name": "ADA FOODS LIMITED",
  "status": "ACTIVE",
  "active": true,
  "registered_on": "2024-03-18",
  "address": "12 ADMIRALTY WAY, LEKKI, LAGOS",
  "email": "hello@adafoods.ng",
  "officers": [
    {
      "name": "ADA CHIOMA OBI",
      "role": "director",
      "status": "active",
      "nationality": "NIGERIAN",
      "appointed_on": "2024-03-18"
    }
  ],
  "amount_charged": "250.00",
  "transaction_id": "wtx_1wXWimpHA9SSUHix3GJGug",
  "created_at": "2026-10-28T15:16:03Z"
}
```

* **The number** can carry its prefix (`RC 7654321`) or go with `type`. If it exists in more than one
  register and you send neither, you get `400 type_required` with the registers in `details.types`.
* **`officers`** are the proprietors, directors, secretaries and persons with significant control
  (`psc`), with name, role, status, nationality and appointment date only. Presenters and witnesses on
  CAC's filing are left out, and so are dates of birth, ID numbers, phones, emails and home addresses.
* **`status`** is always read fresh from CAC's register.

`GET /v1/businesses/lookups/{id}` returns it again, free. Only your organization, in the same mode,
can read it. We keep the record encrypted.

## Pricing

Search is free. A lookup costs **₦250** from the wallet of the key's mode; the current price is on
the **Pricing** page. It shows as a `cac_lookup_charge` in [your transactions](https://docs.fastcac.com/guides/balance.md#transactions).

| Outcome | Charged |
| - | - |
| The record | Yes |
| `404 cac_record_missing`: CAC has no business with that number. We check this first. | No |
| `503 lookup_unavailable`: CAC's records didn't answer | No: charged, then refunded (`cac_lookup_refund`) |
| `503 cac_search_unavailable`: CAC's search didn't answer. Checked before any charge. | No |
| `402 insufficient_balance`: the wallet can't cover it. Checked first, so nothing is searched or looked up. | No |
| `400`: the number or `type` isn't valid | No |

Send an `Idempotency-Key`: a retry with the same key gets the first answer and isn't charged again.
Live lookups allow 60 a minute per organization.

## Test mode

Test lookups never reach CAC. Every number returns the same test business: ADA FOODS VENTURES when
`type` is `BN`, ADA FOODS LIMITED otherwise, with ADA CHIOMA OBI as its proprietor or director.
`?simulate=cac_record_missing` gives the `404`, `lookup_unavailable` the `503` and
`insufficient_balance` the `402`. Search answers from the real register in test mode;
`?simulate=cac_search_unavailable` gives its `503`.


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