> 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/aml-+-watchlist-screening/watchlist-comprehensive.md).

# Business Watchlist Comprehensive

Business Watchlist Comprehensive runs a company through a commercial decision engine, screening it against a broad set of watchlists including global sanctions, politically exposed persons (PEPs), adverse media, and regulatory lists. The decision engine returns a scored outcome (`ACCEPT`, `REVIEW`, or `REJECT`) together with detailed match records for news & media and watchlist hits. Use it when you need a single comprehensive AML and fraud screening call with a scored, auditable outcome.

## When to use this

* Full AML and sanctions screening for business onboarding
* Regulatory compliance checks requiring a scored, auditable outcome
* Screening that needs both negative news and watchlist results in one call

## How it works

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

## Authentication

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

## Endpoints

```http
POST /commercial-service/watchlist/comprehensive
GET  /commercial-service/watchlist/comprehensive/{transaction_id}
```

## 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 to screen.      |
| `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
{
  "CompanyName": "Example Company (Pty) Ltd",
  "EnquiryReason": "01",
  "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 `"WATCLISTCOM"`.                                   |
| `company_name`       | string  | Company name that was screened.                           |
| `screening_result`   | string  | Decision Engine outcome: `ACCEPT`, `REVIEW`, or `REJECT`. |
| `status`             | string  | Raw status from the Decision Engine.                      |
| `watchlist_decision` | string  | Decision text from the Decision Engine.                   |
| `match_count`        | integer | Total number of hits (news & media + watchlist combined). |
| `time_of_request`    | string  | Timestamp of the Decision Engine request.                 |
| `ds_success`         | boolean | Whether the Decision Engine call succeeded.               |
| `ds_outcome`         | string  | Raw outcome string from the Decision Engine.              |
| `reason_codes`       | array   | Reason codes returned by the Decision Engine.             |
| `nm_count`           | integer | Number of news & media results.                           |
| `wls_count`          | integer | Number of watchlist results.                              |
| `nm_results`         | array   | News and media match records.                             |
| `wls_results`        | array   | Watchlist match records.                                  |

### `reason_codes[]` fields

| Field  | Type   | Description                                    |
| ------ | ------ | ---------------------------------------------- |
| `code` | string | Reason code identifier.                        |
| `type` | string | Type of reason code (e.g. `"WLS"`, `"NM"`).    |
| `desc` | string | Human-readable description of the reason code. |

### `nm_results[]` fields (news & media)

| Field           | Type    | Description                                              |
| --------------- | ------- | -------------------------------------------------------- |
| `product_id`    | string  | Product identifier.                                      |
| `result_id`     | integer | Result record ID.                                        |
| `score`         | float   | Match confidence score.                                  |
| `category`      | string  | Adverse media category (e.g. `"Fraud"`, `"Corruption"`). |
| `subject`       | string  | Subject of the article.                                  |
| `text`          | string  | Article excerpt.                                         |
| `url`           | string  | URL of the source article.                               |
| `article_title` | string  | Title of the article.                                    |
| `article_date`  | string  | Date the article was published.                          |
| `sentiment`     | string  | Sentiment of the article (`"Negative"`, etc.).           |

### `wls_results[]` fields (watchlist)

| Field                  | Type      | Description                                          |
| ---------------------- | --------- | ---------------------------------------------------- |
| `product_id`           | string    | Product identifier.                                  |
| `result_id`            | integer   | Result record ID.                                    |
| `score`                | float     | Match confidence score.                              |
| `category`             | string    | Watchlist category (e.g. `"Sanctions"`, `"PEP"`).    |
| `subject`              | string    | Subject name on the list.                            |
| `source_agency`        | string    | Agency that issued the listing.                      |
| `source_agency_code`   | string    | Agency code.                                         |
| `source_list_type`     | string    | List type (e.g. `"Sanctions"`, `"Law Enforcement"`). |
| `source_parent_agency` | string    | Parent agency of the source.                         |
| `source_region`        | string    | Geographic region of the source list.                |
| `source_country`       | string    | Country of the source list.                          |
| `caution`              | string    | Caution notes from the source.                       |
| `identifier`           | string    | Unique identifier on the source list.                |
| `remarks`              | string    | Remarks from the source.                             |
| `text`                 | string    | Full text of the watchlist entry.                    |
| `url`                  | string    | URL to the source listing.                           |
| `highlights`           | string\[] | Matching terms highlighted in the result.            |
| `entity_name`          | string    | Entity name as it appears on the watchlist.          |
| `date_of_birth`        | string    | Date of birth (if listed).                           |
| `nationality`          | string    | Nationality (if listed).                             |
| `address`              | string    | Address (if listed).                                 |
| `program`              | string    | Sanctions or regulatory program name.                |
| `gender`               | string    | Gender (if listed).                                  |

### Screening result values

| Value    | Meaning                                        |
| -------- | ---------------------------------------------- |
| `ACCEPT` | No significant matches found - proceed.        |
| `REVIEW` | Possible match found - route to manual review. |
| `REJECT` | Confirmed match found - decline or escalate.   |

### Example response - accept

```json
{
  "success": true,
  "transaction_id": "f2a3b4c5-d6e7-8901-fabc-012345678901",
  "product": "WATCLISTCOM",
  "company_name": "Example Company (Pty) Ltd",
  "screening_result": "ACCEPT",
  "status": "Completed",
  "watchlist_decision": "No Matches Found",
  "match_count": 0,
  "time_of_request": "2026-04-21T10:30:00",
  "ds_success": true,
  "ds_outcome": "ACCEPT",
  "reason_codes": [],
  "nm_count": 0,
  "wls_count": 0,
  "nm_results": [],
  "wls_results": []
}
```

### Example response - review (watchlist hit)

```json
{
  "success": true,
  "transaction_id": "a3b4c5d6-e7f8-9012-abcd-123456789012",
  "product": "WATCLISTCOM",
  "company_name": "Example Company (Pty) Ltd",
  "screening_result": "REVIEW",
  "status": "Completed",
  "watchlist_decision": "Possible Match",
  "match_count": 1,
  "time_of_request": "2026-04-21T10:31:00",
  "ds_success": true,
  "ds_outcome": "REVIEW",
  "reason_codes": [
    {
      "code": "WLS001",
      "type": "WLS",
      "desc": "Possible sanctions list match"
    }
  ],
  "nm_count": 0,
  "wls_count": 1,
  "nm_results": [],
  "wls_results": [
    {
      "result_id": 1,
      "score": 78.5,
      "category": "Sanctions",
      "subject": "Example Company Ltd",
      "source_agency": "OFAC",
      "source_list_type": "Sanctions",
      "source_country": "United States",
      "entity_name": "Example Company Ltd",
      "program": "SDN List",
      "highlights": ["Example", "Company"]
    }
  ]
}
```

## Retrieving results later

```http
GET /commercial-service/watchlist/comprehensive/{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 |

{% hint style="info" %}
A `REVIEW` or `REJECT` result returns HTTP `200` - it is a successful API call with a negative screening outcome, 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/watchlist/comprehensive" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CompanyName": "Example Company (Pty) Ltd",
    "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}/watchlist/comprehensive",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "CompanyName": "Example Company (Pty) Ltd",
        "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}/watchlist/comprehensive`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    CompanyName: "Example Company (Pty) Ltd",
    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.
* Document all `REVIEW` outcomes and the disposition decision for AML audit purposes.
* Retain proof of consent in line with POPIA requirements.

## FAQ

<details>

<summary>What client timeout should I configure?</summary>

Up to 90 seconds. The Decision Engine can take longer than standard services when processing multiple watchlists.

</details>

<details>

<summary>What is the difference between `nm_results` and `wls_results`?</summary>

`nm_results` are adverse media and news article matches. `wls_results` are structured watchlist matches (sanctions, PEP lists, law enforcement lists). Both are returned in a single call.

</details>

<details>

<summary>What happens when `ds_success` is `false`?</summary>

The Decision Engine call failed. The `screening_result` may not be reliable. Retry the request; contact support if the issue persists.

</details>

## Changelog

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