> For the complete documentation index, see [llms.txt](https://developer.fraudcheck.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.fraudcheck.co.za/commercial-service/identity/business-search.md).

# Business Search

Business Search queries the commercial database to find businesses by name or registration number. It returns a list of matching entities with addresses, registration status, and contact details. Use it to identify and confirm the correct record for a business before calling deeper services that require an `it_number`.

## When to use this

* Locating a business in the database before running principal or watchlist checks
* Confirming a company's registration status and address details
* Resolving ambiguity when only a partial name is known

## How it works

| Property              | Value                                                      |
| --------------------- | ---------------------------------------------------------- |
| Response type         | `Synchronous`                                              |
| Typical response time | < 5s                                                       |
| Result retrieval      | `GET /commercial-service/business-search/{transaction_id}` |
| Consent required      | `Yes`                                                      |
| Region                | South Africa                                               |

## Authentication

```http
Authorization: Bearer {your_access_token}
```

## Endpoints

```http
POST /commercial-service/business-search
POST /commercial-service/business-search/registration
GET  /commercial-service/business-search/{transaction_id}
```

Use the `POST /business-search` endpoint to search by company name. Use `POST /business-search/registration` to search by registration number.

## Request

### Headers

| Header          | Required | Value              |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer {token}`   |
| `Content-Type`  | Yes      | `application/json` |

### Body parameters

| Field                          | Type    | Required              | Description                                                                  |
| ------------------------------ | ------- | --------------------- | ---------------------------------------------------------------------------- |
| `CompanyName`                  | string  | Yes (name endpoint)   | Company name to search. Used by `POST /business-search`.                     |
| `CompanyRegNo`                 | string  | Yes (reg no endpoint) | Registration number to search. Used by `POST /business-search/registration`. |
| `EnquiryReason`                | string  | Yes                   | Reason code for the enquiry.                                                 |
| `ConsentObtainedByDataSubject` | boolean | Yes                   | Must be `true`. Confirms POPIA consent.                                      |
| `ReferenceNo`                  | string  | No                    | Your own reference.                                                          |

### Example request - search by name

```json
{
  "CompanyName": "Example Company",
  "ConsentObtainedByDataSubject": true
}
```

### Example request - search by registration number

```json
{
  "CompanyRegNo": "2021/123456/07",
  "ConsentObtainedByDataSubject": true
}
```

## Response

### Response fields

| Field                      | Type    | Description                                                |
| -------------------------- | ------- | ---------------------------------------------------------- |
| `success`                  | boolean | `true` if the API call succeeded.                          |
| `transaction_id`           | string  | Unique identifier for this request.                        |
| `product`                  | string  | Always `"BUSMOD"`.                                         |
| `search_type`              | string  | `"Name"` or `"RegNo"` - how the search was performed.      |
| `searched_name`            | string  | The company name that was searched.                        |
| `searched_registration_no` | string  | The registration number that was searched (if applicable). |
| `result_count`             | integer | Number of records returned.                                |
| `results`                  | array   | List of matched business records.                          |

### `results[]` fields

| Field              | Type   | Description                                       |
| ------------------ | ------ | ------------------------------------------------- |
| `it_number`        | string | Internal IT number. Used in principal link calls. |
| `name`             | string | Business name.                                    |
| `name_type`        | string | Name type classification.                         |
| `business_name`    | string | Registered business name.                         |
| `reg_no`           | string | Company registration number.                      |
| `reg_status`       | string | Registration status, e.g. `"Active"`.             |
| `reg_status_code`  | string | Status code.                                      |
| `trading_number`   | string | Trading number (if applicable).                   |
| `physical_address` | string | Physical address.                                 |
| `suburb`           | string | Suburb.                                           |
| `town`             | string | Town or city.                                     |
| `country`          | string | Country.                                          |
| `post_code`        | string | Postal code.                                      |
| `postal_address`   | string | Postal address.                                   |
| `postal_suburb`    | string | Postal suburb.                                    |
| `postal_town`      | string | Postal town.                                      |
| `postal_country`   | string | Postal country.                                   |
| `postal_post_code` | string | Postal code for postal address.                   |
| `phone_no`         | string | Business telephone number.                        |
| `fax_no`           | string | Business fax number.                              |

### Example response - results found

```json
{
  "success": true,
  "transaction_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "product": "BUSMOD",
  "search_type": "Name",
  "searched_name": "Example Company",
  "searched_registration_no": null,
  "result_count": 2,
  "results": [
    {
      "it_number": "IT123456",
      "name": "Example Company (Pty) Ltd",
      "business_name": "Example Company (Pty) Ltd",
      "reg_no": "2021/123456/07",
      "reg_status": "Active",
      "physical_address": "1 Main Road",
      "suburb": "Sandton",
      "town": "Johannesburg",
      "country": "South Africa",
      "post_code": "2196",
      "phone_no": "0112345678"
    },
    {
      "it_number": "IT234567",
      "name": "Example Company CC",
      "business_name": "Example Company CC",
      "reg_no": "2005/098765/23",
      "reg_status": "Active",
      "physical_address": "5 Church Street",
      "suburb": "Cape Town CBD",
      "town": "Cape Town",
      "country": "South Africa",
      "post_code": "8001",
      "phone_no": "0219876543"
    }
  ]
}
```

### Example response - no results

```json
{
  "success": true,
  "transaction_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "product": "BUSMOD",
  "search_type": "Name",
  "searched_name": "Nonexistent Company",
  "searched_registration_no": null,
  "result_count": 0,
  "results": []
}
```

## Retrieving results later

```http
GET /commercial-service/business-search/{transaction_id}
```

Use the `transaction_id` from the POST response to retrieve the result again at any time.

## Errors

| HTTP | Code            | Meaning                              | Action                               |
| ---- | --------------- | ------------------------------------ | ------------------------------------ |
| 401  | `unauthorized`  | Token missing or expired             | Refresh your access token            |
| 403  | `forbidden`     | Account lacks access to this service | Contact your account manager         |
| 422  | `invalid_input` | Required field missing or invalid    | See `details.field`                  |
| 500  | `server_error`  | Unexpected error                     | Retry; contact support if persistent |

## Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
BASE_URL="https://commercial-service-api.fraudcheckonline.co.za/commercial-service"

# Search by name
curl -X POST "$BASE_URL/business-search" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CompanyName": "Example Company",
    "EnquiryReason": "01",
    "ConsentObtainedByDataSubject": true
  }'

# Search by registration number
curl -X POST "$BASE_URL/business-search/registration" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CompanyRegNo": "2021/123456/07",
    "EnquiryReason": "01",
    "ConsentObtainedByDataSubject": true
  }'

# Retrieve by transaction ID
curl -X GET "$BASE_URL/business-search/{transaction_id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

BASE_URL = "https://commercial-service-api.fraudcheckonline.co.za/commercial-service"

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

# Search by name
response = requests.post(
    f"{BASE_URL}/business-search",
    headers=headers,
    json={
        "CompanyName": "Example Company",
        "EnquiryReason": "01",
        "ConsentObtainedByDataSubject": True,
    },
)
data = response.json()

# Retrieve by transaction ID
transaction_id = data["transaction_id"]
result = requests.get(f"{BASE_URL}/business-search/{transaction_id}", headers=headers).json()
```

{% endtab %}

{% tab title="JavaScript (Node.js)" %}

```javascript
const BASE_URL = "https://commercial-service-api.fraudcheckonline.co.za/commercial-service";

const headers = {
  Authorization: `Bearer ${accessToken}`,
  "Content-Type": "application/json",
};

// Search by name
const response = await fetch(`${BASE_URL}/business-search`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    CompanyName: "Example Company",
    EnquiryReason: "01",
    ConsentObtainedByDataSubject: true,
  }),
});
const data = await response.json();

// Retrieve by transaction ID
const result = await fetch(`${BASE_URL}/business-search/${data.transaction_id}`, { headers }).then(r => r.json());
```

{% endtab %}
{% endtabs %}

## Compliance & consent

* Obtain explicit consent from the data subject before submitting a request.
* Set `ConsentObtainedByDataSubject` to `true` to confirm consent has been captured.
* Retain proof of consent in line with POPIA requirements.

## FAQ

<details>

<summary>What client timeout should I configure?</summary>

Up to 30 seconds.

</details>

<details>

<summary>Can I search for a company using both name and registration number?</summary>

No. Use `POST /business-search` for name searches and `POST /business-search/registration` for registration number searches. You cannot combine both in a single call.

</details>

<details>

<summary>What is the `it_number` used for?</summary>

The `it_number` is the internal identifier for the business. It is passed as input to the Business Principal Link service to retrieve directors and linked entities.

</details>

## Changelog

| Date       | Version | Change           |
| ---------- | ------- | ---------------- |
| 2026-04-21 | v1.0    | Initial release. |