> 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-deeds-comprehensive.md).

# Principal Deeds Comprehensive

Principal Deeds Comprehensive retrieves property deeds records for an individual. It returns registered property transactions, bond (mortgage) records, and co-ownership information for a named principal identified by their South African identity number. Use it to verify asset ownership and assess property exposure during commercial due diligence.

## When to use this

* Verifying property holdings for a director or beneficial owner
* Assessing the asset base of a principal as part of credit or fraud risk scoring
* Checking for multiple bond holders or co-owners on a property

## How it works

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

## Authentication

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

## Endpoints

```http
POST /commercial-service/principal-deeds-comprehensive
GET  /commercial-service/principal-deeds-comprehensive/{transaction_id}
GET  /commercial-service/principal-deeds-comprehensive/existing
```

## Request

### Headers

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

### Body parameters (POST)

| 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.                     |

### Query parameters (GET /existing)

| Parameter    | Type   | Required | Description                    |
| ------------ | ------ | -------- | ------------------------------ |
| `firstName`  | string | Yes      | Principal's first name.        |
| `lastName`   | string | Yes      | Principal's last name.         |
| `identityNo` | string | Yes      | South African identity number. |

Use `GET /existing` to look up a previously retrieved deeds result from cache without incurring a new bureau enquiry.

### 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.        |
| `searched_name`            | string  | Full name searched.                        |
| `searched_registration_no` | string  | Identity number searched.                  |
| `enquiry_reason`           | string  | Enquiry reason code used.                  |
| `deeds_count`              | integer | Number of property deed records returned.  |
| `multiple_owner_count`     | integer | Number of multiple-owner records returned. |
| `multiple_bond_count`      | integer | Number of multiple-bond records returned.  |
| `deeds`                    | array   | Individual property deed records.          |
| `multiple_owners`          | array   | Co-ownership records for properties.       |
| `multiple_bonds`           | array   | Co-bond (mortgage) records for properties. |

### `deeds[]` key fields

Each deed record contains property transaction details. Key fields include:

| Field               | Description                                |
| ------------------- | ------------------------------------------ |
| `erf_no`            | Erf or property number.                    |
| `registration_date` | Date the deed was registered.              |
| `purchase_price`    | Purchase price at time of registration.    |
| `current_value`     | Current estimated property value.          |
| `property_type`     | Type of property.                          |
| `property_address`  | Property address.                          |
| `bond_holder`       | Name of the bond holder (mortgage lender). |
| `bond_amount`       | Bond amount registered.                    |
| `town`              | Town where the property is located.        |
| `province`          | Province where the property is located.    |

### Example response

```json
{
  "success": true,
  "transaction_id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
  "searched_name": "Smith John",
  "searched_registration_no": "8601015800086",
  "enquiry_reason": "01",
  "deeds_count": 1,
  "multiple_owner_count": 0,
  "multiple_bond_count": 0,
  "deeds": [
    {
      "erf_no": "ERF 1234",
      "registration_date": "2019-05-10",
      "purchase_price": "1800000",
      "current_value": "2200000",
      "property_type": "Residential",
      "property_address": "1 Main Road, Sandton",
      "bond_holder": "First National Bank",
      "bond_amount": "1400000",
      "town": "Sandton",
      "province": "Gauteng"
    }
  ],
  "multiple_owners": [],
  "multiple_bonds": []
}
```

### Example response - no deeds found

```json
{
  "success": true,
  "transaction_id": "c9d0e1f2-a3b4-5678-cdef-789012345678",
  "searched_name": "Smith John",
  "searched_registration_no": "8601015800086",
  "enquiry_reason": "01",
  "deeds_count": 0,
  "multiple_owner_count": 0,
  "multiple_bond_count": 0,
  "deeds": [],
  "multiple_owners": [],
  "multiple_bonds": []
}
```

## Retrieving results later

```http
GET /commercial-service/principal-deeds-comprehensive/{transaction_id}
```

Use the `transaction_id` from the POST response to retrieve the result again. Alternatively, use `GET /existing` with the principal's name and identity number to find a cached result without a new transaction ID.

## 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-deeds-comprehensive" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "FirstName": "John",
    "LastName": "Smith",
    "IdentityNo": "8601015800086",
    "EnquiryReason": "01",
    "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-deeds-comprehensive",
    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-deeds-comprehensive`, {
  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.
* Deeds data includes personal property and financial records - ensure you have a permissible purpose under 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>What is the `GET /existing` endpoint for?</summary>

It returns a previously cached result for the same individual without making a new bureau enquiry. This is useful if you need to check the deeds result multiple times in a workflow without incurring additional costs.

</details>

<details>

<summary>What if the principal has no property on record?</summary>

The response returns HTTP `200` with `deeds_count: 0` and empty `deeds`, `multiple_owners`, and `multiple_bonds` arrays.

</details>

## Changelog

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