# Business Verification (KYB)

> CAC company verification through NIBSS CIV: status, registration, directors, shareholders, share capital and winding-up.

Verifies a company or business name on the Corporate Affairs Commission (CAC) register through NIBSS CIV: registration status, type and date, and optionally directors, shareholders, share capital, affiliates and winding-up records.

`POST /v1/verify/business`

- **Availability:** Sandbox and live
- **Indicative price:** ₦500.00 per completed check
- **Consent:** Not needed: CAC records are a public registry (`public_registry`).
- **MCP tool:** `verify_business`

## Request

**Body parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rc_number` | string | No | CAC RC or BN number, e.g. RC1234567. At least 3 characters. |
| `tin` | string | No | At least 5 characters. |
| `company_name` | string | No | At least 2 characters. |
| `include` | array of strings | No | Each one of: `directors`, `shareholders`, `share_capital`, `line_of_business`, `affiliates`, `status_report`, `winding_up`, `certificate`. Defaults to `["directors","shareholders","share_capital","status_report"]`. |
| `reason` | string | No | Purpose of the check. One of the 38 NIMC purpose codes. See the [purpose code list](https://speedmap-delta.vercel.app/docs/compliance#purpose-codes). |
| `match` | object | No |  |
| `match.company_name` | string | No | At least 2 characters. |

- Provide **exactly one** of `rc_number`, `tin` or `company_name`. Live CAC lookups need `rc_number` or `tin`; `company_name` search is sandbox only.
- `company_type` is optional: Speedmap reads it from the RC prefix (`RC` company, `BN` business name, `IT` incorporated trustee, `LP` / `LLP` partnerships). Send it when the number has no prefix.
- `reason` is optional for business checks.
- `match` is `true` when the company is `ACTIVE` and, if you sent `match.company_name`, the names agree (case, punctuation and suffixes such as LIMITED, LTD and PLC are ignored).
- The sections in `include` decide what the full record (`data`) contains.

Send an `Idempotency-Key` header so a retried request is never billed twice. See [Idempotency](https://speedmap-delta.vercel.app/docs/idempotency).

_cURL_

```bash
curl -X POST http://localhost:4000/v1/verify/business \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "rc_number": "RC1234567",
  "include": [
    "directors",
    "shareholders",
    "share_capital",
    "status_report"
  ]
}'
```

_Node.js_

```javascript
const res = await fetch("http://localhost:4000/v1/verify/business", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPEEDMAP_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "rc_number": "RC1234567",
    "include": [
      "directors",
      "shareholders",
      "share_capital",
      "status_report"
    ]
  }),
});

const verification = await res.json();
if (!res.ok) throw new Error(verification.error.message);
console.log(verification.status, verification.match);
```

_Python_

```python
import os, uuid, requests

res = requests.post(
    "http://localhost:4000/v1/verify/business",
    headers={
        "Authorization": f"Bearer {os.environ['SPEEDMAP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "rc_number": "RC1234567",
        "include": [
            "directors",
            "shareholders",
            "share_capital",
            "status_report"
        ]
    },
    timeout=30,
)
res.raise_for_status()
verification = res.json()
print(verification["status"], verification["match"])
```

## Response

A completed check returns `200` with a [verification object](https://speedmap-delta.vercel.app/docs/verifications). `status` is `verified` or `not_found`. If the provider has not answered in time you get `202` with `status: "pending"`; [retrieve it later](https://speedmap-delta.vercel.app/docs/verifications#pending-verifications) or wait for the `verification.completed` [webhook](https://speedmap-delta.vercel.app/docs/webhooks).

**200 OK · assertion**

```json
{
  "reference_id": "spm_8171f3a87cbe221341f7185f",
  "object": "verification",
  "product": "business",
  "method": "cac_rc",
  "status": "verified",
  "match": true,
  "field_matches": null,
  "field_confidence": null,
  "mode": "sandbox",
  "reason": null,
  "subject": null,
  "summary": {
    "company_name": "SPEEDILY SERVICES LIMITED",
    "rc_number": "RC1234567",
    "status": "ACTIVE",
    "active": true,
    "type": "Private Company Limited by Shares",
    "registered_at": "2016-05-12",
    "state": "FCT",
    "name_match": null
  },
  "consent": {
    "mechanism": "public_registry",
    "consent_id": null,
    "timestamp": "2026-10-19T09:41:07.512Z"
  },
  "source": "api",
  "error": null,
  "billing": {
    "amount_kobo": 0,
    "currency": "NGN"
  },
  "latency_ms": 640,
  "created_at": "2026-10-19T09:41:07.512Z",
  "updated_at": "2026-10-19T09:41:07.874Z"
}
```

**summary**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `company_name` | string | No | Registered name. |
| `rc_number` | string | No | RC or BN number. |
| `status` | string | No | CAC status as registered, e.g. `ACTIVE` or `WOUND UP`. |
| `active` | boolean | No | Whether the status is `ACTIVE`. |
| `type` | string | No | Company type. |
| `registered_at` | string | No | Registration date, `YYYY-MM-DD`. |
| `state` | string | No | State of the registered address. |
| `name_match` | boolean \| null | No | Result of `match.company_name`; `null` when not requested. |
| `name_match_confidence` | number \| null | No | How close `match.company_name` is to the registered name, 0 to 100. |

Full-tier accounts calling the REST API also receive `provider`, `provider_reference` and `data`, the normalized record. MCP, webhooks, lists and bulk results never include it. See [Response shaping](https://speedmap-delta.vercel.app/docs/response-shaping).

**Full tier only**

```json
{
  "provider": "sandbox",
  "provider_reference": "SBX6CB753DB2C",
  "data": {
    "company_name": "SPEEDILY SERVICES LIMITED",
    "rc_number": "RC1234567",
    "tin": "12345678-0001",
    "type": "Private Company Limited by Shares",
    "status": "ACTIVE",
    "registered_at": "2016-05-12",
    "address": {
      "street": "12 Adetokunbo Ademola Crescent, Wuse II",
      "city": "Abuja",
      "state": "FCT"
    },
    "email": "info@speedily.ng",
    "share_capital": {
      "authorized": 10000000,
      "issued": 10000000,
      "currency": "NGN"
    },
    "directors": [
      {
        "name": "THELONIOUS JAHA",
        "role": "Director",
        "appointedAt": "2016-05-12"
      }
    ],
    "shareholders": [
      "…"
    ],
    "status_report": {
      "status": "ACTIVE",
      "active": true,
      "last_checked": "2026-10-19T09:41:07.512Z"
    }
  }
}
```

## Test values

Send these bodies with a sandbox key. More outcome triggers are on the [Sandbox](https://speedmap-delta.vercel.app/docs/sandbox) page.

**Active company**

```json
{
  "rc_number": "RC1234567"
}
```

**Wound-up company**

```json
{
  "rc_number": "RC1111111",
  "include": [
    "directors",
    "winding_up"
  ]
}
```

**Business name**

```json
{
  "rc_number": "BN2345678"
}
```

**By TIN**

```json
{
  "tin": "23456789-0001"
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | The body failed validation. `details` lists each field. |
| 401 | `unauthorized` | Missing or invalid API key. |
| 402 | `insufficient_balance` | Live only: wallet balance is below the check price. |
| 403 | `not_entitled` | Your workspace is not enabled for this product or method. |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used with a different body. |
| 422 | `provider_rejected_request` | The upstream registry rejected the request. |
| 503 | `verification_unavailable` | Temporary failure. Retry, with the same or a new `Idempotency-Key`. |

All errors share one shape. See [Errors](https://speedmap-delta.vercel.app/docs/errors) for the full list.

---

Source: https://speedmap-delta.vercel.app/docs/products/business