> 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/quickvet.md).

# Business Credit Score

Business Credit Score performs a fast two-step commercial vetting check. It first matches the business by name or registration number, then retrieves a brief report covering registration status, adverse events, principal summary, and turnover data. Use it for pre-screening a business before onboarding or as a quick fraud indicator during an application.

## When to use this

* Pre-screening a business before opening an account or extending credit
* Quickly verifying that a company exists and is actively registered
* Checking for judgments, defaults, or business rescue at the point of application

## How it works

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

## Authentication

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

## Endpoints

```http
POST /commercial-service/quickvet
```

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

### Example request

```json
{
  "CompanyName": "Example Company (Pty) Ltd",
  "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 `"PREVETCOM"`.               |
| `match`          | object  | Business match result.              |
| `result`         | object  | Full quick-vet report.              |

### `match` fields

| Field            | Type   | Description                                  |
| ---------------- | ------ | -------------------------------------------- |
| `Status`         | string | `"Match"` or `"No Match"`.                   |
| `ListCommercial` | array  | Matched business records. Empty if no match. |

### `match.ListCommercial[]` fields

| Field             | Type   | Description                  |
| ----------------- | ------ | ---------------------------- |
| `CommercialID`    | string | Internal commercial ID.      |
| `RegistrationNo`  | string | Company registration number. |
| `Businessname`    | string | Business name as registered. |
| `EnquiryID`       | string | Enquiry identifier.          |
| `EnquiryResultID` | string | Enquiry result identifier.   |
| `Reference`       | string | Reference.                   |

### `result` fields

| Field        | Type   | Description                                        |
| ------------ | ------ | -------------------------------------------------- |
| `Status`     | string | `"Success"` or an error description.               |
| `Commercial` | object | Report data. Present when `Status` is `"Success"`. |

### `result.Commercial` fields

| Field                           | Type   | Description                                 |
| ------------------------------- | ------ | ------------------------------------------- |
| `Statutory`                     | object | Registration status information.            |
| `CommercialBusinessInformation` | object | Core business details.                      |
| `PrincipalAdverse`              | object | Summary of adverse events for directors.    |
| `Turnover`                      | object | Revenue trend data.                         |
| `BusinessAdverse`               | object | Summary of adverse events for the business. |
| `SubscriberInputDetails`        | object | Metadata about this enquiry.                |

### `result.Commercial.Statutory` fields

| Field              | Type   | Description                                             |
| ------------------ | ------ | ------------------------------------------------------- |
| `CommercialStatus` | string | Registration status, e.g. `"Active"`, `"Deregistered"`. |

### `result.Commercial.CommercialBusinessInformation` fields

| Field              | Type   | Description                            |
| ------------------ | ------ | -------------------------------------- |
| `DisplayText`      | string | Formatted display label.               |
| `CommercialName`   | string | Registered company name.               |
| `RegistrationNo`   | string | Company registration number.           |
| `CommercialStatus` | string | Registration status.                   |
| `CommercialType`   | string | Entity type, e.g. `"Private Company"`. |
| `RegistrationDate` | string | Date the company was registered.       |
| `BusinessDesc`     | string | Business description / SIC category.   |

### `result.Commercial.PrincipalAdverse` fields

| Field                | Type   | Description                            |
| -------------------- | ------ | -------------------------------------- |
| `NumberofPrincipals` | string | Total number of directors/principals.  |
| `NoofDebtReview`     | string | Directors currently under debt review. |
| `NumberofJudgements` | string | Judgments recorded against directors.  |
| `NumberofDefault`    | string | Defaults recorded against directors.   |

### `result.Commercial.Turnover` fields

| Field                | Type   | Description                           |
| -------------------- | ------ | ------------------------------------- |
| `FinancialYear`      | string | Most recent financial year on record. |
| `AnnualRevenueShift` | string | Revenue trend, e.g. `"Up"`, `"Down"`. |

### `result.Commercial.BusinessAdverse` fields

| Field                    | Type   | Description                                    |
| ------------------------ | ------ | ---------------------------------------------- |
| `BusinessRescue`         | string | Whether the business is in rescue proceedings. |
| `NoofDefaults`           | string | Defaults recorded against the business.        |
| `NoofJudgements`         | string | Judgments recorded against the business.       |
| `NoofPossibleJudgements` | string | Possible judgments on record.                  |

### Example response - match found

```json
{
  "success": true,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "product": "PREVETCOM",
  "match": {
    "Status": "Match",
    "ListCommercial": [
      {
        "CommercialID": "12345678",
        "RegistrationNo": "2021/123456/07",
        "Businessname": "Example Company (Pty) Ltd",
        "EnquiryID": "ENQ20260421001",
        "EnquiryResultID": "RES20260421001",
        "Reference": ""
      }
    ]
  },
  "result": {
    "Status": "Success",
    "Commercial": {
      "Statutory": {
        "CommercialStatus": "Active"
      },
      "CommercialBusinessInformation": {
        "DisplayText": "Business Information",
        "CommercialName": "Example Company (Pty) Ltd",
        "RegistrationNo": "2021/123456/07",
        "CommercialStatus": "Active",
        "CommercialType": "Private Company",
        "RegistrationDate": "2021-01-15",
        "BusinessDesc": "Technology Services"
      },
      "PrincipalAdverse": {
        "NumberofPrincipals": "2",
        "NoofDebtReview": "0",
        "NumberofJudgements": "0",
        "NumberofDefault": "0"
      },
      "Turnover": {
        "FinancialYear": "2023",
        "AnnualRevenueShift": "Up"
      },
      "BusinessAdverse": {
        "BusinessRescue": "No",
        "NoofDefaults": "0",
        "NoofJudgements": "0",
        "NoofPossibleJudgements": "0"
      }
    }
  }
}
```

### Example response - no match

```json
{
  "success": true,
  "transaction_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "product": "PREVETCOM",
  "match": {
    "Status": "No Match",
    "ListCommercial": []
  },
  "result": null
}
```

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

{% hint style="info" %}
A business that cannot be matched returns HTTP `200` with `match.Status: "No Match"` - it is a valid API response, not an error.
{% endhint %}

## Code examples

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

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

curl -X POST "$BASE_URL/quickvet" \
  -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}/quickvet",
    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}/quickvet`, {
  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.

</details>

<details>

<summary>Can I search by registration number only?</summary>

Yes. Provide `CompanyRegNo` without `CompanyName`. Providing both increases match accuracy.

</details>

<details>

<summary>What does a "No Match" result mean?</summary>

The business could not be found in the commercial database. This may indicate the company is not registered or the name or registration number was entered incorrectly.

</details>

## Changelog

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