> 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/credit-and-financial-risk/commercial-detail-turnover.md).

# Business Credit Report

Business Credit Report retrieves a comprehensive business report covering company registration details, financial information, judgments, property, trade references, credit circles, principal (director) records, turnover history, and scoring data. Use it when you need the full picture on a business entity before making a credit or onboarding decision.

## When to use this

* Full commercial due diligence before extending credit or entering a contract
* Retrieving detailed financial and adverse history for a business
* Obtaining director property and business interests alongside entity-level risk data

## How it works

| Property              | Value           |
| --------------------- | --------------- |
| Response type         | `Synchronous`   |
| Typical response time | < 10s           |
| Result retrieval      | Returned inline |
| Consent required      | `Yes`           |
| Region                | South Africa    |

## Authentication

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

## Endpoints

```http
POST /commercial-service/commercial-detail-turnover
```

## 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`. |
| `TradingName`                  | string  | No       | Trading or DBA name.                                       |
| `PrescribedPurpose`            | string  | No       | Legal purpose for the data access.                         |
| `ReferenceNo`                  | string  | No       | Your own reference.                                        |
| `ConsentObtainedByDataSubject` | boolean | Yes      | Must be `true`. Confirms POPIA consent.                    |

### Example request

```json
{
  "CompanyName": "Example Company (Pty) Ltd",
  "CompanyRegNo": "2021/123456/07",
  "ConsentObtainedByDataSubject": true
}
```

## Response

The response contains a `match` object (the initial business match) and a `result` object (the full report). The `result` object is deeply nested and covers multiple data sections.

### Top-level response fields

| Field            | Type    | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `success`        | boolean | `true` if the API call succeeded.   |
| `transaction_id` | string  | Unique identifier for this request. |
| `product`        | string  | Always `"FULLBUSCHKTO"`.            |
| `match`          | object  | Business match result.              |
| `result`         | object  | Full commercial report.             |

### `match` fields

| Field               | Type   | Description              |
| ------------------- | ------ | ------------------------ |
| `CommercialDetails` | object | Matched business record. |

### `match.CommercialDetails` fields

| Field             | Type   | Description                     |
| ----------------- | ------ | ------------------------------- |
| `CommercialID`    | string | Internal commercial ID.         |
| `RegistrationNo`  | string | Company registration number.    |
| `Businessname`    | string | Business name as registered.    |
| `BonusXML`        | string | Raw XML payload (internal use). |
| `TempReference`   | string | Temporary reference.            |
| `EnquiryID`       | string | Enquiry identifier.             |
| `EnquiryResultID` | string | Enquiry result identifier.      |
| `Reference`       | string | Reference.                      |

### `result` report sections

The `result` object contains the following top-level sections. Each section is an object or array of objects.

| Section                          | Description                                              |
| -------------------------------- | -------------------------------------------------------- |
| `CommercialBusinessInformation`  | Core registration details, addresses, capital structure. |
| `CommercialAuditorInformation`   | Registered auditor details and history.                  |
| `CommercialVATInformation`       | VAT registration number and status.                      |
| `CommercialJudgmentSummary`      | Judgment type counts.                                    |
| `CommercialJudgments`            | Individual judgment records.                             |
| `CommercialPropertyInformation`  | Property holdings and bond information.                  |
| `CommercialTradeReferences`      | Trade reference records.                                 |
| `CommercialBankCodeHistory`      | Bank code history.                                       |
| `CommercialCreditCircles`        | Credit circle (trade payment) records.                   |
| `CommercialEnquiryAnalysis`      | Summary of enquiries made against this business.         |
| `CommercialPrincipalInformation` | Current director/principal records.                      |
| `CommercialPrincipalInfoSummary` | Summary counts for principal adverse events.             |
| `CommercialTurnover`             | Annual turnover history.                                 |
| `CommercialScoring`              | Risk score and scorecard data.                           |
| `BusinessEnquiryHistory`         | Historical enquiries.                                    |
| `DirectorBusinessInterests`      | Other businesses linked to directors.                    |
| `DirectorPropertyInterests`      | Properties linked to directors.                          |
| `AddressHistory`                 | Historical addresses for the business.                   |

### `CommercialBusinessInformation` key fields

| Field                  | Type   | Description                            |
| ---------------------- | ------ | -------------------------------------- |
| `CommercialName`       | string | Registered company name.               |
| `RegistrationNo`       | string | Company registration number.           |
| `CommercialStatus`     | string | Registration status.                   |
| `CommercialType`       | string | Entity type, e.g. `"Private Company"`. |
| `BusinessStartDate`    | string | Date business operations began.        |
| `FinancialYearEnd`     | string | Financial year-end month.              |
| `TaxNo`                | string | SARS tax number.                       |
| `PhysicalAddress`      | string | Physical address.                      |
| `PostalAddress`        | string | Postal address.                        |
| `TelephoneNo`          | string | Business telephone number.             |
| `BussEmail`            | string | Business email address.                |
| `AgeofBusiness`        | string | Age of the business in years.          |
| `AuthorisedCapitalAmt` | string | Authorised share capital amount.       |
| `IssuedCapitalAmt`     | string | Issued share capital amount.           |
| `NoOfEnquiries`        | string | Number of credit enquiries on record.  |

### `CommercialScoring` key fields

| Field                  | Type   | Description                             |
| ---------------------- | ------ | --------------------------------------- |
| `Score`                | string | Risk score.                             |
| `ScoreRating`          | string | Rating band, e.g. `"Low Risk"`.         |
| `ScoreInterpretation`  | string | Plain-text interpretation of the score. |
| `ProbabilityOfDefault` | string | Probability of default percentage.      |

### Example response - match found

```json
{
  "success": true,
  "transaction_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "product": "FULLBUSCHKTO",
  "match": {
    "CommercialDetails": {
      "CommercialID": "12345678",
      "RegistrationNo": "2021/123456/07",
      "Businessname": "Example Company (Pty) Ltd",
      "EnquiryID": "ENQ20260421002",
      "EnquiryResultID": "RES20260421002",
      "Reference": ""
    }
  },
  "result": {
    "CommercialBusinessInformation": {
      "CommercialName": "Example Company (Pty) Ltd",
      "RegistrationNo": "2021/123456/07",
      "CommercialStatus": "Active",
      "CommercialType": "Private Company",
      "BusinessStartDate": "2021-01-15",
      "FinancialYearEnd": "February",
      "TaxNo": "9876543210",
      "PhysicalAddress": "1 Main Road, Sandton, Gauteng, 2196",
      "TelephoneNo": "0112345678",
      "AgeofBusiness": "5",
      "NoOfEnquiries": "3"
    },
    "CommercialJudgmentSummary": [],
    "CommercialJudgments": [],
    "CommercialPrincipalInformation": [],
    "CommercialTurnover": [],
    "CommercialScoring": {
      "Score": "720",
      "ScoreRating": "Low Risk",
      "ProbabilityOfDefault": "2.1"
    }
  }
}
```

## 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/commercial-detail-turnover" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CompanyName": "Example Company (Pty) Ltd",
    "CompanyRegNo": "2021/123456/07",
    "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}/commercial-detail-turnover",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "CompanyName": "Example Company (Pty) Ltd",
        "CompanyRegNo": "2021/123456/07",
        "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}/commercial-detail-turnover`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    CompanyName: "Example Company (Pty) Ltd",
    CompanyRegNo: "2021/123456/07",
    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. This service retrieves a full report and may take slightly longer than QuickVet.

</details>

<details>

<summary>How does this differ from QuickVet?</summary>

QuickVet returns a brief summary (status, adverse counts, turnover trend). Commercial Detail & Turnover returns the full report including all judgments, property records, trade references, director details, and scoring data.

</details>

## Changelog

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