> 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-principal-link.md).

# Business Principal Link

Business Principal Link retrieves the directors and principals associated with a business, along with any other companies those principals are linked to and any adverse observations recorded against the entity. Use it after a Business Search to obtain the full ownership and control picture for a company.

## When to use this

* Identifying the directors and beneficial owners of a business
* Checking what other companies a director is linked to
* Retrieving adverse observations (judgments, defaults) at the director level

## How it works

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

## Authentication

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

## Endpoints

```http
POST /commercial-service/business-principal-link
GET  /commercial-service/business-principal-link/{transaction_id}
```

## Request

### Headers

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

### Body parameters

| Field                          | Type    | Required | Description                                                |
| ------------------------------ | ------- | -------- | ---------------------------------------------------------- |
| `CompanyName`                  | string  | Yes\*    | Registered company name. Required if no `CompanyRegNo`.    |
| `CompanyRegNo`                 | string  | Yes\*    | Company registration number. Required if no `CompanyName`. |
| `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

```json
{
  "CompanyName": "Example Company (Pty) Ltd",
  "CompanyRegNo": "2021/123456/07",
  "EnquiryReason": "CreditInformationQuery",
  "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 `"BUSPRINCLINK"`.                          |
| `searched_name`            | string  | Company name that was searched.                   |
| `searched_registration_no` | string  | Registration number that was searched.            |
| `enquiry_reason`           | string  | Enquiry reason code used.                         |
| `duns_number`              | string  | DUNS number for the business (if available).      |
| `business_name`            | string  | Business name.                                    |
| `principal_count`          | integer | Number of principals/directors returned.          |
| `linked_entity_count`      | integer | Number of linked entities returned.               |
| `observation_count`        | integer | Number of adverse observations returned.          |
| `principals`               | array   | List of directors/principals.                     |
| `linked_entities`          | array   | List of other businesses linked to principals.    |
| `observations`             | array   | Adverse observations recorded against the entity. |

### `principals[]` fields

| Field           | Type   | Description                            |
| --------------- | ------ | -------------------------------------- |
| `surname`       | string | Director surname.                      |
| `forename1`     | string | Director first name.                   |
| `forename2`     | string | Director second name.                  |
| `id_number`     | string | Director identity number.              |
| `date_of_birth` | date   | Director date of birth.                |
| `established`   | string | Date the directorship was established. |

### `linked_entities[]` fields

| Field                 | Type    | Description                                        |
| --------------------- | ------- | -------------------------------------------------- |
| `principal_id_number` | string  | Identity number of the linked principal.           |
| `it_number`           | string  | Internal IT number of the linked business.         |
| `registration_number` | string  | Registration number of the linked business.        |
| `business_name`       | string  | Name of the linked business.                       |
| `business_status`     | string  | Registration status of the linked business.        |
| `registered_date`     | date    | Date the linked business was registered.           |
| `judgement_count`     | integer | Number of judgments against the linked business.   |
| `adverse_count`       | integer | Number of adverse records for the linked business. |

### `observations[]` fields

| Field           | Type   | Description                                           |
| --------------- | ------ | ----------------------------------------------------- |
| `major_product` | string | Data source or product that recorded the observation. |
| `comment_date`  | date   | Date the observation was recorded.                    |
| `comment_text`  | string | Text of the adverse observation.                      |

### Example response

```json
{
  "success": true,
  "transaction_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "product": "BUSPRINCLINK",
  "searched_name": "Example Company (Pty) Ltd",
  "searched_registration_no": "2021/123456/07",
  "enquiry_reason": "01",
  "duns_number": null,
  "business_name": "Example Company (Pty) Ltd",
  "principal_count": 2,
  "linked_entity_count": 1,
  "observation_count": 0,
  "principals": [
    {
      "surname": "Smith",
      "forename1": "John",
      "forename2": null,
      "id_number": "8601015800086",
      "date_of_birth": "1986-01-01",
      "established": "2021-01-15"
    },
    {
      "surname": "Dlamini",
      "forename1": "Sipho",
      "forename2": null,
      "id_number": "9203025800080",
      "date_of_birth": "1992-03-02",
      "established": "2021-01-15"
    }
  ],
  "linked_entities": [
    {
      "principal_id_number": "8601015800086",
      "it_number": "TU987654",
      "registration_number": "2018/055555/07",
      "business_name": "Smith Holdings (Pty) Ltd",
      "business_status": "Active",
      "registered_date": "2018-06-01",
      "judgement_count": 0,
      "adverse_count": 0
    }
  ],
  "observations": []
}
```

## Retrieving results later

```http
GET /commercial-service/business-principal-link/{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"

curl -X POST "$BASE_URL/business-principal-link" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CompanyName": "Example Company (Pty) Ltd",
    "CompanyRegNo": "2021/123456/07",
    "EnquiryReason": "CreditInformationQuery",
    "ConsentObtainedByDataSubject": true
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

response = requests.post(
    f"{BASE_URL}/business-principal-link",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "CompanyName": "Example Company (Pty) Ltd",
        "CompanyRegNo": "2021/123456/07",
        "EnquiryReason": "CreditInformationQuery",
        "ConsentObtainedByDataSubject": True,
    },
)
data = response.json()
```

{% endtab %}

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

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

const response = await fetch(`${BASE_URL}/business-principal-link`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    CompanyName: "Example Company (Pty) Ltd",
    CompanyRegNo: "2021/123456/07",
    EnquiryReason: "CreditInformationQuery",
    ConsentObtainedByDataSubject: true,
  }),
});
const data = await response.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>What is the difference between `principals` and `linked_entities`?</summary>

`principals` lists the current directors/shareholders of the searched business. `linked_entities` lists other businesses that those same principals are or were associated with - useful for understanding the wider business network of the entity.

</details>

## Changelog

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