POST /api/Screening/screen

Screen an individual or organization against global PEP and sanctions lists.

Endpoint

POST https://api.matchstra.ca/api/Screening/screen

Authentication

Requires API key in the X-API-Key header.

Request

Headers

Header	Value	Required
X-API-Key	Your API key	✅ Yes
Content-Type	application/json	✅ Yes

Body Parameters

Parameter	Type	Required	Description
name	string	✅ Yes	Name of person or entity to screen (max 200 characters)
entityType	string	✅ Yes	Type of entity: "Individual" or "Organization"
dateOfBirth	string	❌ No	Date of birth in ISO 8601 format (e.g., "1980-05-15T00:00:00Z"). Improves match accuracy.
minScore	number	❌ No	Minimum match confidence score (0-100). Default: 70

Request Example

curl -X POST https://api.matchstra.ca/api/Screening/screen \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "dateOfBirth": "1980-05-15T00:00:00Z",
    "entityType": "Individual",
    "minScore": 70
  }'

const response = await fetch('https://api.matchstra.ca/api/Screening/screen', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Smith',
    dateOfBirth: '1980-05-15T00:00:00Z',
    entityType: 'Individual',
    minScore: 70
  })
});

const data = await response.json();

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "your_api_key_here");

var payload = new
{
    name = "John Smith",
    dateOfBirth = "1980-05-15T00:00:00Z",
    entityType = "Individual",
    minScore = 70
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://api.matchstra.ca/api/Screening/screen",
    content
);

var result = await response.Content.ReadAsStringAsync();

Response

Success Response (200 OK)

No Matches Found

{
  "success": true,
  "message": "Screening completed successfully",
  "data": {
    "id": 12345,
    "hasMatch": false,
    "matchCount": 0,
    "highestScore": 0,
    "matches": [],
    "remainingRequests": 485
  },
  "errors": null
}

Matches Found

{
  "success": true,
  "message": "Screening completed successfully",
  "data": {
    "id": 12346,
    "hasMatch": true,
    "matchCount": 2,
    "highestScore": 95.5,
    "matches": [
      {
        "name": "John A. Smith",
        "score": 95.5,
        "entityType": "Individual",
        "sources": ["OFAC SDN", "UN Sanctions"],
        "dateOfBirth": "1980-05-15",
        "nationality": "US"
      },
      {
        "name": "John Anthony Smith",
        "score": 78.2,
        "entityType": "Individual",
        "sources": ["EU Sanctions"],
        "dateOfBirth": "1980-05-20",
        "nationality": "GB"
      }
    ],
    "remainingRequests": 484
  },
  "errors": null
}

Response Fields

Field	Type	Description
success	boolean	true if request succeeded
message	string	Human-readable status message
data	object	Screening result data
data.id	integer	Unique screening ID (use to retrieve later)
data.hasMatch	boolean	true if potential matches found
data.matchCount	integer	Number of matches found
data.highestScore	number	Confidence score of best match (0-100)
data.matches	array	Array of match objects
data.remainingRequests	integer	Remaining API quota
errors	array	Error messages (null on success)

Match Object Fields

Field	Type	Description
name	string	Name from watchlist
score	number	Match confidence (0-100)
entityType	string	"Individual" or "Organization"
sources	array	Data sources (e.g., "OFAC SDN", "UN Sanctions")
dateOfBirth	string	Date of birth (if available)
nationality	string	Country/nationality (if available)

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    "The Name field is required.",
    "EntityType must be 'Individual' or 'Organization'."
  ]
}

Common causes:

• Missing required fields (name, entityType)
• Invalid entityType value
• minScore out of range (0-100)
• Invalid date format for dateOfBirth

401 Unauthorized

{
  "success": false,
  "message": "Unauthorized",
  "data": null,
  "errors": ["Invalid or missing API key"]
}

Cause: Invalid, missing, or revoked API key.

429 Too Many Requests

{
  "success": false,
  "message": "Rate limit exceeded",
  "data": null,
  "errors": ["Request quota exhausted"]
}

Cause: API quota limit reached. Check Retry-After header for reset time.

Notes

• Performance: Average response time is 1-3 seconds
• Idempotency: Not idempotent - each call creates a new screening record
• Data sources: Searches OFAC, UN, EU, UK, Canadian sanctions, PEP databases, and Interpol lists
• Name matching: Uses fuzzy matching to catch variations and transliterations
• Storage: Results are stored and retrievable via the List and Get endpoints

Related Endpoints

• GET /api/Screening/list - List all screenings
• GET /api/Screening/{id} - Get specific screening

See Also

• Screening Guide - Comprehensive guide with examples
• Error Handling - Handle errors gracefully
• Rate Limits - Manage API quota