> 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-extensive.md).

# Business Watchlist Extensive

Business Watchlist Extensive screens a company against a comprehensive AML watchlist database covering a broad range of international sanctions, PEPs, adverse enforcement actions, financial crime lists, and regulatory blacklists. It returns match records for any hits, scored by confidence. Use it when your AML compliance programme requires the most thorough watchlist coverage available through the Fraudcheck platform.

## When to use this

* Comprehensive AML onboarding screening requiring broad international coverage
* Periodic re-screening against a wide-coverage AML dataset
* High-risk customer segments where standard sanctions screening is insufficient

## How it works

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

**Data sources:** AML extensive watchlist database (sanctions, PEPs, enforcement actions, financial crime, regulatory blacklists)

## Authentication

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

## Endpoints

```http
POST /commercial-service/watchlist/extensive
GET  /commercial-service/watchlist/extensive/{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.      |
| `CompanyRegNo`                 | string  | No       | Company registration number (optional). |
| `ConsentObtainedByDataSubject` | boolean | Yes      | Must be `true`. Confirms POPIA consent. |
| `ReferenceNo`                  | string  | No       | Your own reference.                     |

### Example request

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

## Response

### Response fields

| Field              | Type    | Description                                |
| ------------------ | ------- | ------------------------------------------ |
| `transaction_id`   | string  | Unique identifier for this request.        |
| `product`          | string  | Always `"WATCHLISTEXTCOM"`.                |
| `company_name`     | string  | Company name that was screened.            |
| `company_reg_no`   | string  | Company registration number (if provided). |
| `screening_result` | string  | `ACCEPT`, `REVIEW`, or `REJECT`.           |
| `match_count`      | integer | Number of matches found.                   |
| `results`          | array   | Match records. Empty if no hits.           |

### `results[]` fields

| Field              | Type    | Description                                      |
| ------------------ | ------- | ------------------------------------------------ |
| `row_id`           | integer | Internal record ID.                              |
| `source_table`     | string  | Watchlist source table name.                     |
| `source_entity_id` | string  | Entity identifier on the source list.            |
| `dataset_code`     | string  | Dataset code.                                    |
| `dataset_title`    | string  | Dataset name.                                    |
| `dataset_url`      | string  | URL to the source dataset.                       |
| `schema_type`      | string  | Entity schema type.                              |
| `name`             | string  | Name of the matched entity.                      |
| `aliases`          | string  | Known aliases of the matched entity.             |
| `countries`        | string  | Associated countries.                            |
| `addresses`        | string  | Known addresses.                                 |
| `identifiers`      | string  | Associated identifiers.                          |
| `sanctions`        | string  | Sanctions programmes the entity is listed under. |
| `phones`           | string  | Associated phone numbers (if available).         |
| `emails`           | string  | Associated email addresses (if available).       |
| `program_ids`      | string  | Specific programme identifiers.                  |
| `match_score`      | float   | Raw match score.                                 |
| `match_percentage` | float   | Match confidence as a percentage (0–100).        |

### Screening result values

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

### Example response - accept

```json
{
  "transaction_id": "f8a9b0c1-d2e3-4567-fabc-678901234567",
  "product": "WATCHLISTEXTCOM",
  "company_name": "Example Company (Pty) Ltd",
  "company_reg_no": "2021/123456/07",
  "screening_result": "ACCEPT",
  "match_count": 0,
  "results": []
}
```

### Example response - review (possible PEP link)

```json
{
  "transaction_id": "a9b0c1d2-e3f4-5678-abcd-789012345678",
  "product": "WATCHLISTEXTCOM",
  "company_name": "Example Company (Pty) Ltd",
  "company_reg_no": "2021/123456/07",
  "screening_result": "REVIEW",
  "match_count": 1,
  "results": [
    {
      "row_id": 12201,
      "source_table": "aml_extensive",
      "dataset_code": "PEPLIST",
      "dataset_title": "Politically Exposed Persons - AML Extensive",
      "name": "Example Company Ltd",
      "aliases": "Example Co",
      "countries": "ZA",
      "sanctions": null,
      "match_score": 83.5,
      "match_percentage": 83.5
    }
  ]
}
```

## Retrieving results later

```http
GET /commercial-service/watchlist/extensive/{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/extensive" \
  -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}/watchlist/extensive",
    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}/watchlist/extensive`, {
  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.
* Document all `REVIEW` and `REJECT` outcomes and the manual 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.

</details>

<details>

<summary>How does Extensive differ from Lite and Most Wanted?</summary>

**Lite** covers FIC TFS and UN Sanctions only. **Most Wanted** covers crime and law enforcement lists. **Extensive** covers all of those plus a broader AML dataset including PEPs, adverse enforcement actions, additional international sanctions, and financial crime lists. Use Extensive when you need maximum coverage for high-risk or regulated customer segments.

</details>

<details>

<summary>Can I run Lite and Extensive together?</summary>

Yes. You can call both endpoints in parallel using the same `CompanyName`. Extensive is a superset of Lite's coverage, so for most use cases a single Extensive call is sufficient.

</details>

## Changelog

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