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

# Principal Link by ID

Principal Link by ID looks up an individual (director or principal) by their South African identity number and returns their consumer bureau profile, recent enquiry history, and the list of businesses they are or were linked to. Use it to perform due diligence on a director or beneficial owner as part of a commercial onboarding or fraud check.

## When to use this

* Verifying a director's identity and credit history during commercial onboarding
* Identifying all companies a specific individual is associated with
* Checking enquiry patterns and adverse records against a principal

## How it works

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

## Authentication

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

## Endpoints

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

## Request

### Headers

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

### Body parameters

| Field                          | Type    | Required | Description                             |
| ------------------------------ | ------- | -------- | --------------------------------------- |
| `FirstName`                    | string  | Yes      | Principal's first name.                 |
| `LastName`                     | string  | Yes      | Principal's last name.                  |
| `IdentityNo`                   | string  | Yes      | South African identity number.          |
| `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
{
  "FirstName": "John",
  "LastName": "Smith",
  "IdentityNo": "8601015800086",
  "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 `"PRINLINKID"`.                         |
| `enquiry_reason`         | string  | Enquiry reason code used.                      |
| `first_name`             | string  | First name from the request.                   |
| `last_name`              | string  | Last name from the request.                    |
| `id_number`              | string  | Identity number from the request.              |
| `ticket_number`          | string  | Bureau ticket number.                          |
| `consumer_number`        | string  | Bureau consumer number.                        |
| `principal_name`         | string  | Full name as found on the bureau record.       |
| `consumer_enquiry_count` | integer | Number of enquiries returned.                  |
| `linked_business_count`  | integer | Number of linked businesses returned.          |
| `consumer_enquiries`     | array   | Recent enquiries made against this individual. |
| `consumer_header`        | object  | Consumer profile header from the bureau.       |
| `linked_businesses`      | array   | Businesses this individual is linked to.       |

### `consumer_enquiries[]` fields

| Field           | Type   | Description                                |
| --------------- | ------ | ------------------------------------------ |
| `major_product` | string | Data source that made the enquiry.         |
| `consumer_no`   | string | Consumer number referenced in the enquiry. |
| `enquiry_date`  | date   | Date the enquiry was made.                 |
| `subscriber`    | string | Name of the enquiring subscriber.          |
| `contact`       | string | Contact at the subscriber.                 |
| `type`          | string | Enquiry type.                              |
| `trans_type`    | string | Transaction type.                          |

### `consumer_header` fields

| Field               | Type   | Description                                        |
| ------------------- | ------ | -------------------------------------------------- |
| `consumer_number`   | string | Bureau consumer number.                            |
| `surname`           | string | Surname.                                           |
| `forename1`         | string | First name.                                        |
| `forename2`         | string | Second name.                                       |
| `date_of_birth`     | string | Date of birth.                                     |
| `id_no1`            | string | Primary identity number.                           |
| `address1`          | string | Most recent address.                               |
| `address2`          | string | Previous address.                                  |
| `employer1`         | string | Most recent employer.                              |
| `occupation1`       | string | Most recent occupation.                            |
| `remarks`           | string | Remarks or notes on the consumer record.           |
| `dispute_date`      | string | Date of any active dispute.                        |
| `debt_council_date` | string | Date referred to debt counselling (if applicable). |

### `linked_businesses[]` fields

| Field               | Type    | Description                                |
| ------------------- | ------- | ------------------------------------------ |
| `major_product`     | string  | Data source.                               |
| `consumer_no`       | string  | Consumer number.                           |
| `it_number`         | string  | Internal IT number of the linked business. |
| `registered_number` | string  | Company registration number.               |
| `registered_status` | string  | Registration status.                       |
| `business_name`     | string  | Name of the linked business.               |
| `registered_date`   | string  | Date the business was registered.          |
| `judgement_counter` | integer | Number of judgments against this business. |
| `default_counter`   | integer | Number of defaults against this business.  |

### Example response

```json
{
  "success": true,
  "transaction_id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
  "product": "PRINLINKID",
  "enquiry_reason": "01",
  "first_name": "John",
  "last_name": "Smith",
  "id_number": "8601015800086",
  "ticket_number": "TKT20260421001",
  "consumer_number": "CON12345678",
  "principal_name": "Smith John",
  "consumer_enquiry_count": 2,
  "linked_business_count": 1,
  "consumer_enquiries": [
    {
      "major_product": "PRINLINKID",
      "consumer_no": "CON12345678",
      "enquiry_date": "2026-01-15",
      "subscriber": "ABC Bank",
      "contact": "Credit Department",
      "type": "Credit",
      "trans_type": "01"
    }
  ],
  "consumer_header": {
    "consumer_number": "CON12345678",
    "surname": "Smith",
    "forename1": "John",
    "date_of_birth": "1986-01-01",
    "id_no1": "8601015800086",
    "address1": "1 Main Road, Sandton, Johannesburg, 2196",
    "employer1": "Example Company (Pty) Ltd",
    "occupation1": "Director",
    "remarks": null
  },
  "linked_businesses": [
    {
      "major_product": "PRINLINKID",
      "it_number": "TU123456",
      "registered_number": "2021/123456/07",
      "registered_status": "Active",
      "business_name": "Example Company (Pty) Ltd",
      "registered_date": "2021-01-15",
      "judgement_counter": 0,
      "default_counter": 0
    }
  ]
}
```

## Retrieving results later

```http
GET /commercial-service/principal-link-id/{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/principal-link-id" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "FirstName": "John",
    "LastName": "Smith",
    "IdentityNo": "8601015800086",
    "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}/principal-link-id",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "FirstName": "John",
        "LastName": "Smith",
        "IdentityNo": "8601015800086",
        "EnquiryReason": "01",
        "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}/principal-link-id`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    FirstName: "John",
    LastName: "Smith",
    IdentityNo: "8601015800086",
    EnquiryReason: "01",
    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.
* This service accesses personal consumer credit data - ensure your use case has a permissible purpose under the NCA and POPIA.
* 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>Does this service run a credit enquiry that affects the subject's credit score?</summary>

This is a soft enquiry used for verification and fraud prevention purposes. It is recorded on the consumer's bureau file as specified by your `EnquiryReason` code but does not negatively affect the individual's credit score.

</details>

## Changelog

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