> 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-most-wanted.md).

# Business Watchlist Crime

Business Watchlist Crime screens a company against crime and most-wanted databases using Fraudcheck's internal watchlist infrastructure. It returns match records for any hits found against entities listed on crime or law enforcement most-wanted lists. Use it to detect associations between a business and individuals or entities subject to active criminal investigation or prosecution.

## When to use this

* Screening businesses for links to criminal or most-wanted entities
* Supplementing sanctions screening with domestic and international crime list checks
* Meeting onboarding due diligence requirements that include criminal risk checks

## How it works

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

**Data sources:** Fraudcheck crime and most-wanted watchlist database

## Authentication

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

## Endpoints

```http
POST /commercial-service/watchlist/most-wanted
GET  /commercial-service/watchlist/most-wanted/{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 `"WATCHLISTCRIMECOM"`.              |
| `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  | Associated sanctions or charges.          |
| `program_ids`      | string  | Program 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": "d6e7f8a9-b0c1-2345-defa-456789012345",
  "product": "WATCHLISTCRIMECOM",
  "company_name": "Example Company (Pty) Ltd",
  "company_reg_no": "2021/123456/07",
  "screening_result": "ACCEPT",
  "match_count": 0,
  "results": []
}
```

### Example response - reject

```json
{
  "transaction_id": "e7f8a9b0-c1d2-3456-efab-567890123456",
  "product": "WATCHLISTCRIMECOM",
  "company_name": "Example Company (Pty) Ltd",
  "company_reg_no": "2021/123456/07",
  "screening_result": "REJECT",
  "match_count": 1,
  "results": [
    {
      "row_id": 8823,
      "source_table": "crime_most_wanted",
      "dataset_title": "Fraudcheck Crime Watchlist",
      "name": "Example Company (Pty) Ltd",
      "aliases": null,
      "countries": "ZA",
      "match_score": 96.0,
      "match_percentage": 96.0
    }
  ]
}
```

## Retrieving results later

```http
GET /commercial-service/watchlist/most-wanted/{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/most-wanted" \
  -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/most-wanted",
    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/most-wanted`, {
  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 for audit purposes.
* 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>How often is the crime/most-wanted database updated?</summary>

Fraudcheck updates the internal watchlist databases on a regular schedule. Contact your account manager for the latest update frequency information.

</details>

## Changelog

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