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

# LLMs / AI Reference

> REST API for commercial fraud prevention, AML compliance, and business verification in South Africa. All services are synchronous and return results inline. Supports transaction-based result retrieval on most endpoints.

## Authentication

Tokens are obtained from the shared authentication endpoint:

```
POST https://commercial-service-api.fraudcheckonline.co.za/auth/login
Body: { "email": "...", "password": "..." }
Response: { "access_token": "...", "token_type": "bearer" }
```

All API calls require `Authorization: Bearer {access_token}`.

## Base URL

```
https://commercial-service-api.fraudcheckonline.co.za/commercial-service
```

## Key conventions

* All POST request bodies are JSON. Set `Content-Type: application/json`.
* `ConsentObtainedByDataSubject: true` (boolean) is required on every request.
* Some services require an `EnquiryReason` code.
* Most services return a `transaction_id` which can be used with a GET endpoint to retrieve the result again.
* Screening results: `ACCEPT` (clear), `REVIEW` (possible match), `REJECT` (confirmed match). These return HTTP `200` - they are not errors.
* Credit and financial risk services return `match` + `result` objects with PascalCase field names.

## Identity

Services for finding and verifying business entities and their principals.

| Method | Endpoint                                      | Product        | Description                                                                    |
| ------ | --------------------------------------------- | -------------- | ------------------------------------------------------------------------------ |
| POST   | `/business-search`                            | `BUSMOD`       | Search businesses by company name.                                             |
| POST   | `/business-search/registration`               | `BUSMOD`       | Search businesses by registration number.                                      |
| GET    | `/business-search/{transaction_id}`           | `BUSMOD`       | Retrieve business search result.                                               |
| POST   | `/business-principal-link`                    | `BUSPRINCLINK` | Retrieve directors and linked entities for a business.                         |
| GET    | `/business-principal-link/{transaction_id}`   | `BUSPRINCLINK` | Retrieve principal link result.                                                |
| POST   | `/principal-link-id`                          | `PRINLINKID`   | Look up individual by ID - bureau profile, enquiry history, linked businesses. |
| GET    | `/principal-link-id/{transaction_id}`         | `PRINLINKID`   | Retrieve principal link ID result.                                             |
| POST   | `/principal-details`                          | `PRINDETAILS`  | Current and historical directors for a business.                               |
| GET    | `/principal-details/{transaction_id}`         | `PRINDETAILS`  | Retrieve principal details result.                                             |
| POST   | `/statutory-details-on-file`                  | `STDONFILE`    | Statutory filing history and directors for a business.                         |
| GET    | `/statutory-details-on-file/{transaction_id}` | `STDONFILE`    | Retrieve statutory details result.                                             |

**Business endpoints required fields:** `CompanyName` or `CompanyRegNo`, `EnquiryReason`, `ConsentObtainedByDataSubject`

**Principal endpoints required fields:** `FirstName`, `LastName`, `IdentityNo`, `EnquiryReason`, `ConsentObtainedByDataSubject`

## AML + Watchlist Screening

| Method | Endpoint                                    | Product             | Description                                                                             |
| ------ | ------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------- |
| POST   | `/watchlist/comprehensive`                  | `WATCLISTCOM`       | Decision engine: sanctions, PEPs, adverse media. Returns scored outcome + reason codes. |
| GET    | `/watchlist/comprehensive/{transaction_id}` | `WATCLISTCOM`       | Retrieve comprehensive watchlist result.                                                |
| POST   | `/watchlist/lite`                           | `WATCHLISTLITECOM`  | FIC TFS + UN Sanctions screening.                                                       |
| GET    | `/watchlist/lite/{transaction_id}`          | `WATCHLISTLITECOM`  | Retrieve lite watchlist result.                                                         |
| POST   | `/watchlist/most-wanted`                    | `WATCHLISTCRIMECOM` | Crime and most-wanted list screening.                                                   |
| GET    | `/watchlist/most-wanted/{transaction_id}`   | `WATCHLISTCRIMECOM` | Retrieve most-wanted result.                                                            |
| POST   | `/watchlist/extensive`                      | `WATCHLISTEXTCOM`   | AML extensive: sanctions, PEPs, enforcement, financial crime.                           |
| GET    | `/watchlist/extensive/{transaction_id}`     | `WATCHLISTEXTCOM`   | Retrieve extensive watchlist result.                                                    |

**Required fields (all watchlist):** `CompanyName`, `ConsentObtainedByDataSubject`

**Comprehensive also requires:** `EnquiryReason`

## Credit and Financial Risk

| Method | Endpoint                                          | Product        | Description                                                                                                |
| ------ | ------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| POST   | `/quickvet`                                       | `PREVETCOM`    | Quick vetting: match business + brief adverse/turnover report. No GET retrieval.                           |
| POST   | `/commercial-detail-turnover`                     | `FULLBUSCHKTO` | Full commercial report: registration, judgments, property, directors, turnover, scoring. No GET retrieval. |
| POST   | `/principal-deeds-comprehensive`                  | `PRIDEEDSCOMP` | Property deeds records for an individual.                                                                  |
| GET    | `/principal-deeds-comprehensive/{transaction_id}` | `PRIDEEDSCOMP` | Retrieve deeds result.                                                                                     |
| GET    | `/principal-deeds-comprehensive/existing`         | `PRIDEEDSCOMP` | Look up cached deeds by `firstName`, `lastName`, `identityNo` query params.                                |

**QuickVet / Commercial Detail required fields:** `CompanyName` or `CompanyRegNo`, `ConsentObtainedByDataSubject`

**Principal Deeds required fields:** `FirstName`, `LastName`, `IdentityNo`, `EnquiryReason`, `ConsentObtainedByDataSubject`

## Result retrieval

Most services support result re-fetching by transaction ID:

```
GET /commercial-service/{service-path}/{transaction_id}
Authorization: Bearer {access_token}
```

`/quickvet` and `/commercial-detail-turnover` do not have GET retrieval endpoints.

## Common response envelope

```json
{
  "success": true,
  "transaction_id": "uuid",
  "product": "PRODUCT_CODE",
  ...service-specific fields...
}
```

Watchlist Lite, Most Wanted, and Extensive responses omit `success` and use `transaction_id`, `product`, `company_name`, `company_reg_no`, `screening_result`, `match_count`, `results[]`.