Bulk Sanctions Check (CSV Upload)

Purpose

This API allows bulk sanctions checks by uploading a CSV file. It simplifies the process of screening large datasets against the sanctions database.

POST /v2/open-sanctions/file/:dataset

Request Format

The request requires a CSV file upload using a multipart/form-data POST request.

Required CSV Format:

The CSV file must include the following headers (case-insensitive):

Field	Description
id	Unique record ID
firstname	Person's First Name
lastname	Person's Last Name
dob	Date of Birth (ISO Format e.g. 1990-01-01)

Sample CSV:

id,firstname,lastname,dob
a32778cf-5563-4b56-be6b-e9ab46c187a8,NIKI,KANUI,1983-04-22
...

Sample cURL Request:

curl --location 'https://api.orchestration.privateid.com/v2/open-sanctions/file/peps' \
--form 'file=@"/path/to/your/file.csv"'

Optional Parameters

You can also provide an optional query parameter scoreThreshold to filter results based on a minimum match score.

Parameter	Type	Default	Description
scoreThreshold	float	0.95	Minimum match score to consider as a valid match

Example:

POST /v2/open-sanctions/file/stations_nevada?scoreThreshold=0.85

API Response

The API returns a JSON response with:

Full list of results for every record.
Summary section for quick review.

Example Response:

{
  "summary": {
    "total": 35,
    "matched": {
      "count": 0,
      "records": []
    },
    "dataset": "stations_nevada"
  },
  "results": [
    {
      "id": "a32778cf-5563-4b56-be6b-e9ab46c187a8",
      "firstname": "JOHN",
      "lastname": "DOE",
      "dob": "2000-04-22",
      "match": "false"
    }
  ]
}

Summary Section

The summary provides:

Total records processed.
Number of matched records.
Full details of matched records (including IDs & scores).

Error Scenarios & Handling

Error Code	Message	Cause
400	Only CSV files are allowed!	Uploaded file isn't a `.csv`
400	Missing required CSV headers	One or more required CSV headers missing
500	Internal Server Error	Unexpected error during processing

Notes

Ensure the uploaded file does not exceed 2MB.
The API is designed to handle concurrent checks efficiently but large files may take longer to process.
Recommended to use a clean, UTF-8 encoded CSV file.

⚠️ Compliance Reminder

Ensure you have legal authorization before submitting personal data for sanctions screening.