SanctionsKit API examples

Simple sanctions screening API examples in JavaScript, TypeScript, Python, Go, PHP, Ruby, Java, C#, and cURL.

SanctionsKit provides an API for screening people and organizations against selected sanctions and watchlist sources. These examples show how to authenticate, submit a screening, and read the response using your language's HTTP library.

Documentation · API reference · Create an account · Get an API key

Choose your language

Language	HTTP client	Run from the repository root
cURL	cURL	bash curl/screen.sh
JavaScript	Built-in fetch	node javascript/screen.mjs
TypeScript	Built-in fetch	node typescript/screen.mts
Python	urllib.request	python3 python/screen.py
Go	net/http	go run ./go/main.go
PHP	cURL extension	php php/screen.php
Ruby	Net::HTTP	ruby ruby/screen.rb
Java	HttpClient	java java/Screening.java
C#	HttpClient	dotnet run --project csharp

Each directory has setup instructions and one standalone screening example. No SanctionsKit SDK is required.

Workflow integrations

Windmill takes a fictional onboarding contact through a synthetic screening and retrieves the evidence for that same result. It includes a credential resource, importable script, example output, and local tests. Both screening outcomes leave the onboarding decision open for review.

Run its local HTTP tests with Node.js 24 or later:

npm --prefix integrations/windmill test

Node-RED includes an importable flow built with core nodes. Run a fictional screening, retrieve its evidence, and inspect a review record. It keeps credentials in the process environment and reuses a stable request key for manual retries. The README includes setup instructions and local runtime tests.

Kestra submits a fictional batch, waits for its final state, and exports retained evidence and a CSV row summary. It keeps failed and cancelled rows visible for review. The Kestra 2.0.4 flow passed 24 native scenarios against a local HTTP fixture in an isolated container.

Make your first request

1. Create a workspace, then open API keys.
2. Create a sandbox key with screenings:write and results:read scopes.
3. Set your key and a unique request key in your terminal, then run an example.

For example, with Node.js 24 or later:

export SANCTIONSKIT_API_KEY='your-sandbox-api-key'
export REQUEST_KEY="$(node -p 'crypto.randomUUID()')"
node javascript/screen.mjs

Keep API keys in your server environment. Never commit them or include them in browser code. Each language README includes its own setup command; C# also includes PowerShell instructions.

The standalone language examples send this body to https://www.sanctionskit.com/api/v1/screenings:

{
  "subject": {
    "name": "Alex Morgan",
    "entityType": "person",
    "birthDate": "1984"
  },
  "package": "sandbox@1",
  "reference": "example-customer-001",
  "retention": "standard"
}

The person is invented. sandbox@1 uses synthetic records, so this request does not search live sanctions lists. See the quickstart for a walkthrough.

Read the response

A successful screening returns HTTP 201 with a data object. The examples print the full response so you can inspect it.

Field	Meaning
data.id	The screening ID, used to retrieve the saved result.
data.status	potential_match or no_match.
data.matches	Candidate records and the evidence behind each match.
data.coverage	The source versions and freshness used for this screening.
data.versions	The dataset, matching engine, and policy versions.

potential_match means the candidates need review. no_match applies to the selected sources and supplied information; it is not a clearance decision. Keep the coverage and evidence with the result. The screening guide explains the full response and how to retrieve it later.

These scripts display responses for learning. When adapting them to an application, parse the JSON, handle the result status, and store evidence where only authorized people can access it. Keep real subject details out of routine logs.

Retry a request

REQUEST_KEY is sent as the Idempotency-Key header. Generate it once for a new screening. If a request times out or needs a retry, keep the same key and the same body. Rerun the script without repeating the key-generation command. A new subject or changed body needs a new key.

The standalone language examples make one attempt and exit with a nonzero status on an HTTP or network error. They do not retry automatically. An error is an incomplete request, never a no_match result. See idempotency and error handling before adding retries to an application.

Adapt the example

For an organization, change subject to:

{
  "name": "Example Trading Company",
  "entityType": "organization"
}

Create a new request key for the changed body. Optional fields and supported subject types are covered in the API reference.

For production, create a production API key and replace sandbox@1 with a package available to that environment, or remove package and supply sources. Send exactly one coverage selector. Review source availability, plans, and retention first. If your workspace requires an approved policy, include its ID and version as described in the screening guide.

For larger integrations, the docs cover batch screening, monitoring, and webhooks. The cURL examples also show source discovery and result retrieval.

Configuration

Variable	Purpose
SANCTIONSKIT_API_KEY	Required. Your sandbox API key.
REQUEST_KEY	Required. A unique key for one screening operation.
SANCTIONSKIT_BASE_URL	Optional. Defaults to https://www.sanctionskit.com/api/v1. Used by the local tests.

The scripts read environment variables directly; they do not load .env files.

Contributing

Small, runnable examples are welcome. See CONTRIBUTING.md for the local checks. The test suite uses a local HTTP server and never needs an API key or a SanctionsKit account.

For API help, visit the documentation or contact SanctionsKit. For a problem with an example, open a GitHub issue without including credentials or personal data.

License

MIT. The license covers the code in this repository. Use of the hosted API is subject to SanctionsKit's terms.