# Cross-Border Restricted Party Evidence (`civicdataforge/cross-border-restricted-party-evidence`) Actor

Screen up to 100 party names against the official U.S. ITA Consolidated Screening List with exact or conservative fuzzy review, source hashes, change monitoring, caller-owned dispositions, and decision and batch receipts. No legal-clearance claim.

- **URL**: https://apify.com/civicdataforge/cross-border-restricted-party-evidence.md
- **Developed by:** [Bryan](https://apify.com/civicdataforge) (community)
- **Categories:** Automation, Other
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Cross-Border Restricted Party Evidence

Review-oriented party-name evidence from the official U.S. International Trade Administration (ITA) Consolidated Screening List (CSL). The Actor accepts up to 100 party queries, compares each name against published primary names and aliases, and returns reproducible evidence rows with source identity, source fetch time, match score, published addresses and identifiers, change states, caller-asserted review disposition, and SHA-256 decision and batch receipts.

This product is useful to U.S. teams and to India- and China-facing suppliers, sourcing teams, marketplaces, and compliance operations that participate in U.S.-regulated transactions. Its coverage is the **U.S. ITA CSL**. It does not claim to cover every U.S., Indian, Chinese, or international restriction, and it never issues legal clearance.

### Evidence decisions

- `POTENTIAL_MATCH_REVIEW_REQUIRED`: an exact or threshold-meeting fuzzy primary-name or alias candidate exists. Every candidate requires human due diligence against the cited official list.
- `NO_CSL_NAME_MATCH`: no name or alias in the completely downloaded source snapshot met the configured rule. This is not clearance or proof that the party is unrestricted.
- `SOURCE_UNAVAILABLE`: the official source could not be fetched or could not be validated as a complete CSL payload. This is deliberately distinct from a no-match.

Optional country and address values are consistency checks only. They never increase a candidate's name score or suppress a name match. A country or address conflict is evidence for review, not a reason to silently discard a candidate.

### Input

```json
{
  "queries": [
    {
      "reference": "supplier-1042",
      "name": "China Telecom Corporation Limited",
      "country": "CN",
      "address": "Beijing",
      "previousRecordFingerprints": ["sha256:..."],
      "previousDecisionReceiptHash": "sha256:...",
      "reviewDisposition": "NOT_REVIEWED",
      "reviewReference": "case-1042"
    }
  ],
  "matchMode": "fuzzy",
  "minimumScore": 92,
  "maxCandidatesPerQuery": 5,
  "previousSourceSha256": "sha256:...",
  "batchReference": "supplier-refresh-2026-08-23"
}
```

- `queries`: 1-100 objects. `name` is required. `reference`, ISO alpha-2 `country`, and `address` are optional.
- `matchMode`: `exact` or `fuzzy` (default `fuzzy`). Exact mode uses normalized full-name/alias equality.
- `minimumScore`: integer 85-100 (default 92).
- `maxCandidatesPerQuery`: integer 1-10 (default 5).

The deterministic fuzzy score is this Actor's candidate-retrieval score. It is not an ITA risk rating, recommendation, endorsement, or legal conclusion.

### Monitoring and review workflow

- Re-submit the prior `record_fingerprint` values and `decision_receipt_hash` with each query to classify the observation as first-seen, unchanged, changed, or no-longer-present.
- Re-submit the prior `source_sha256` once per batch to detect whether the complete official CSL snapshot changed.
- A caller may attach `NOT_REVIEWED`, `CLEARED_FALSE_POSITIVE`, `CONFIRMED_MATCH`, or `ESCALATED`. The output labels this `CALLER_ASSERTED`; it never overwrites the Actor's screening decision.
- Every output row carries one decision receipt and the entire batch shares one batch receipt, making partial or reordered exports detectable.
- The Actor does not retain the submitted portfolio. Schedule and persist prior receipts in your own controlled system when continuous monitoring is required.

### Output evidence

Each row includes the query, decision and reasons; matched name, basis, score, and rank; published CSL record ID, entity number, party name, aliases, addresses, identifiers, programs, remarks, and source-list links; source URL, fetch time, snapshot SHA-256 and record count; a stable matched-record fingerprint; source/change health; review disposition; and decision and batch receipt hashes. `legal_clearance` is always `false`.

### Responsible use

Use this Actor as a screening aid and audit trail, not as an autonomous approval, denial, onboarding, credit, employment, housing, or other consequential-decision engine. Resolve potential matches using the official Federal Register and the responsible agency's current list. Apply appropriate human review, legal advice, privacy controls, and retention limits. Do not treat a score as identity proof, wrongdoing, or an instruction to transact or refuse to transact.

ITA's own CSL guidance says the tool is an aid to electronic screening, possible matches require additional due diligence, and users should check the Federal Register and official agency lists before taking action.

### Official source

- CSL information and responsible-use guidance: <https://www.trade.gov/consolidated-screening-list>
- Official downloadable JSON: <https://data.trade.gov/downloadable_consolidated_screening_list/v1/consolidated.json>
- ITA developer terms: <https://developer.trade.gov/terms-of-service>

See [SOURCE-POLICY.md](SOURCE-POLICY.md) for the fail-closed source contract.

### Tests

```bash
npm test
npm run test:live
```

The unit suite uses fixtures and failure injection. The bounded live suite performs three queries against one current, completely downloaded official snapshot: exact, fuzzy typo, and a synthetic no-match. It makes no account, publication, pricing, or outreach mutations.

# Actor input Schema

## `queries` (type: `array`):

One to 100 party-name queries. Country and address are review context and never turn a name candidate into legal clearance.

## `matchMode` (type: `string`):

Exact normalized-name matching, or exact matching plus conservative fuzzy review candidates.

## `minimumScore` (type: `integer`):

Candidate threshold from 85 to 100. The score is a review aid, never an ITA endorsement or legal determination.

## `maxCandidatesPerQuery` (type: `integer`):

Hard cap from one to ten review candidates returned for each submitted party name.

## `previousSourceSha256` (type: `string`):

Optional SHA-256 from a prior run. The output reports whether the complete official CSL snapshot changed.

## `batchReference` (type: `string`):

Optional non-sensitive caller reference bound into the batch receipt.

## Actor input object example

```json
{
  "queries": [
    {
      "reference": "supplier-001",
      "name": "China Telecom Corporation Limited",
      "country": "CN"
    }
  ],
  "matchMode": "fuzzy",
  "minimumScore": 92,
  "maxCandidatesPerQuery": 5
}
```

# Actor output Schema

## `results` (type: `string`):

API URL for the default dataset rows.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        {
            "reference": "supplier-001",
            "name": "China Telecom Corporation Limited",
            "country": "CN"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("civicdataforge/cross-border-restricted-party-evidence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "queries": [{
            "reference": "supplier-001",
            "name": "China Telecom Corporation Limited",
            "country": "CN",
        }] }

# Run the Actor and wait for it to finish
run = client.actor("civicdataforge/cross-border-restricted-party-evidence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    {
      "reference": "supplier-001",
      "name": "China Telecom Corporation Limited",
      "country": "CN"
    }
  ]
}' |
apify call civicdataforge/cross-border-restricted-party-evidence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,civicdataforge/cross-border-restricted-party-evidence"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/c8kc65IZxqSTdCrRD/builds/BTwNFyapfIZzuYGhI/openapi.json