Skip to main content

GET /api/Screening/list

Retrieve a list of all screening requests made with your API key.

Endpoint​

GET https://api.matchstra.ca/api/Screening/list

Authentication​

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

Request​

Headers​

HeaderValueRequired
X-API-KeyYour API key✅ Yes

Query Parameters​

None currently supported. Returns all screenings for your account.

Request Example​

curl -X GET https://api.matchstra.ca/api/Screening/list \
  -H "X-API-Key: your_api_key_here"
const response = await fetch('https://api.matchstra.ca/api/Screening/list', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
});

const screenings = await response.json();
console.log(screenings);
using System.Net.Http;

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

var response = await client.GetAsync("https://api.matchstra.ca/api/Screening/list");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine(result);

Response​

Success Response (200 OK)​

Returns an array of screening objects:

[
  {
    "id": 12346,
    "name": "John Smith",
    "entityType": "Individual",
    "dateOfBirth": "1980-05-15T00:00:00Z",
    "hasMatch": true,
    "matchCount": 2,
    "highestScore": 95.5,
    "createdAt": "2025-01-02T14:30:00Z",
    "matches": [
      {
        "name": "John A. Smith",
        "score": 95.5,
        "entityType": "Individual",
        "sources": ["OFAC SDN", "UN Sanctions"],
        "dateOfBirth": "1980-05-15",
        "nationality": "US"
      }
    ]
  },
  {
    "id": 12345,
    "name": "Jane Doe",
    "entityType": "Individual",
    "dateOfBirth": "1990-08-22T00:00:00Z",
    "hasMatch": false,
    "matchCount": 0,
    "highestScore": 0,
    "createdAt": "2025-01-02T13:15:00Z",
    "matches": []
  }
]

Response Fields​

FieldTypeDescription
idintegerUnique screening ID
namestringName that was screened
entityTypestring"Individual" or "Organization"
dateOfBirthstringDate of birth (if provided)
hasMatchbooleanWhether matches were found
matchCountintegerNumber of matches
highestScorenumberBest match confidence (0-100)
createdAtstringTimestamp of screening (ISO 8601)
matchesarrayArray of match objects (may be truncated)
note

For complete match details, use the GET /api/Screening/{id} endpoint.

Empty List Response​

If no screenings have been performed:

[]

Error Responses​

401 Unauthorized​

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

Cause: Invalid, missing, or revoked API key.

Pagination​

Coming Soon

Pagination parameters (page, pageSize, sortBy, etc.) are planned for a future release.

Current behavior returns all results (up to a reasonable limit). For large datasets, this may be truncated.

Filtering​

Coming Soon

Filtering by date range, match status, and entity type will be available in a future release.

Use Cases​

Display Recent Screenings​

async function getRecentScreenings(limit = 10) {
  const response = await fetch('https://api.matchstra.ca/api/Screening/list', {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  });
  
  const screenings = await response.json();
  
  // Sort by createdAt descending and take first N
  return screenings
    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
    .slice(0, limit);
}

// Usage
const recent = await getRecentScreenings(5);
console.log('Recent screenings:', recent);

Find All Matches​

async function getAllMatchedScreenings() {
  const response = await fetch('https://api.matchstra.ca/api/Screening/list', {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  });
  
  const screenings = await response.json();
  
  // Filter to only those with matches
  return screenings.filter(s => s.hasMatch);
}

// Usage
const matches = await getAllMatchedScreenings();
console.log(`Found ${matches.length} screenings with matches`);

Export to CSV​

async function exportScreeningsToCSV() {
  const response = await fetch('https://api.matchstra.ca/api/Screening/list', {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  });
  
  const screenings = await response.json();
  
  // Generate CSV
  const headers = 'ID,Name,Entity Type,Has Match,Match Count,Highest Score,Date\n';
  const rows = screenings.map(s => 
    `${s.id},"${s.name}",${s.entityType},${s.hasMatch},${s.matchCount},${s.highestScore},${s.createdAt}`
  ).join('\n');
  
  return headers + rows;
}

// Usage
const csv = await exportScreeningsToCSV();
console.log(csv);

Notes​

  • Ordering: Results are typically returned in reverse chronological order (newest first), but this is not guaranteed. Sort client-side if order matters.
  • Performance: Response time depends on the number of screenings. Expect 100-500ms for typical accounts.
  • Data retention: Screenings are retained indefinitely unless you request deletion.

See Also​