GET /api/Screening/{id}

Retrieve a specific screening result by its ID.

Endpoint

GET https://api.matchstra.ca/api/Screening/{id}

Authentication

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

Request

Headers

Header	Value	Required
X-API-Key	Your API key	✅ Yes

Path Parameters

Parameter	Type	Required	Description
id	integer	✅ Yes	Screening ID (returned from POST /screen)

Request Example

curl -X GET https://api.matchstra.ca/api/Screening/12345 \
  -H "X-API-Key: your_api_key_here"

const screeningId = 12345;

const response = await fetch(`https://api.matchstra.ca/api/Screening/${screeningId}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
});

const screening = await response.json();
console.log(screening);

using System.Net.Http;

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

int screeningId = 12345;
var response = await client.GetAsync($"https://api.matchstra.ca/api/Screening/{screeningId}");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine(result);

Response

Success Response (200 OK)

Returns complete screening details:

{
  "id": 12345,
  "name": "John Smith",
  "entityType": "Individual",
  "dateOfBirth": "1980-05-15T00:00:00Z",
  "minScore": 70,
  "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"
    },
    {
      "name": "John Anthony Smith",
      "score": 78.2,
      "entityType": "Individual",
      "sources": ["EU Sanctions"],
      "dateOfBirth": "1980-05-20",
      "nationality": "GB"
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	Unique screening ID
name	string	Name that was screened
entityType	string	"Individual" or "Organization"
dateOfBirth	string	Date of birth (if provided in request)
minScore	number	Minimum score threshold used
hasMatch	boolean	Whether matches were found
matchCount	integer	Number of matches
highestScore	number	Best match confidence (0-100)
createdAt	string	Timestamp of screening (ISO 8601)
matches	array	Complete array of all match objects

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 from watchlist (if available)
nationality	string	Country/nationality (if available)

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.

404 Not Found

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Screening with ID 99999 not found"
}

Causes:

• Screening ID doesn't exist
• Screening belongs to a different account
• Screening was deleted

Use Cases

Retrieve Full Match Details

After creating a screening, retrieve complete details:

// Step 1: Create screening
const createResponse = await fetch('https://api.matchstra.ca/api/Screening/screen', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.MATCHSTRA_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Smith',
    entityType: 'Individual'
  })
});

const createData = await createResponse.json();
const screeningId = createData.data.id;

// Step 2: Retrieve full details
const getResponse = await fetch(
  `https://api.matchstra.ca/api/Screening/${screeningId}`,
  {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  }
);

const fullDetails = await getResponse.json();
console.log('Full screening:', fullDetails);

Audit Trail

Retrieve historical screening for compliance audits:

async function getAuditTrail(screeningId) {
  const response = await fetch(
    `https://api.matchstra.ca/api/Screening/${screeningId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to retrieve screening ${screeningId}`);
  }
  
  const screening = await response.json();
  
  return {
    screeningId: screening.id,
    subject: screening.name,
    dateScreened: screening.createdAt,
    result: screening.hasMatch ? 'MATCH FOUND' : 'NO MATCH',
    matchCount: screening.matchCount,
    highestRisk: screening.highestScore,
    sources: screening.matches.flatMap(m => m.sources).filter((v, i, a) => a.indexOf(v) === i)
  };
}

// Usage
const audit = await getAuditTrail(12345);
console.log('Audit record:', audit);

Re-check Old Screening

Verify if an old screening would have different results today:

async function recheckScreening(oldScreeningId) {
  // Get original screening
  const oldResponse = await fetch(
    `https://api.matchstra.ca/api/Screening/${oldScreeningId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  const oldScreening = await oldResponse.json();
  
  // Run new screening with same parameters
  const newResponse = await fetch('https://api.matchstra.ca/api/Screening/screen', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.MATCHSTRA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: oldScreening.name,
      dateOfBirth: oldScreening.dateOfBirth,
      entityType: oldScreening.entityType,
      minScore: oldScreening.minScore
    })
  });
  
  const newScreening = await newResponse.json();
  
  // Compare results
  return {
    original: {
      id: oldScreening.id,
      date: oldScreening.createdAt,
      hasMatch: oldScreening.hasMatch,
      matchCount: oldScreening.matchCount
    },
    current: {
      id: newScreening.data.id,
      date: new Date().toISOString(),
      hasMatch: newScreening.data.hasMatch,
      matchCount: newScreening.data.matchCount
    },
    changed: oldScreening.hasMatch !== newScreening.data.hasMatch
  };
}

// Usage
const comparison = await recheckScreening(12345);
if (comparison.changed) {
  console.log('⚠️  Screening results have changed!');
} else {
  console.log('✅ Results remain consistent');
}

Generate Report

Create a detailed report for a screening:

async function generateScreeningReport(screeningId) {
  const response = await fetch(
    `https://api.matchstra.ca/api/Screening/${screeningId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  const screening = await response.json();
  
  const report = `
SCREENING REPORT
================
ID: ${screening.id}
Date: ${new Date(screening.createdAt).toLocaleString()}

SUBJECT INFORMATION
-------------------
Name: ${screening.name}
Type: ${screening.entityType}
Date of Birth: ${screening.dateOfBirth || 'Not provided'}

SCREENING RESULTS
-----------------
Status: ${screening.hasMatch ? '⚠️  MATCHES FOUND' : '✅ NO MATCHES'}
Matches Found: ${screening.matchCount}
Highest Risk Score: ${screening.highestScore}%

${screening.matches.length > 0 ? `
MATCH DETAILS
-------------
${screening.matches.map((m, i) => `
Match #${i + 1}:
  Name: ${m.name}
  Confidence: ${m.score}%
  Type: ${m.entityType}
  Sources: ${m.sources.join(', ')}
  DOB: ${m.dateOfBirth || 'Unknown'}
  Nationality: ${m.nationality || 'Unknown'}
`).join('\n')}
` : ''}

RECOMMENDATION
--------------
${screening.highestScore > 90 ? 'HIGH RISK - Reject and escalate' :
  screening.highestScore > 75 ? 'MEDIUM RISK - Manual review required' :
  screening.hasMatch ? 'LOW RISK - Review recommended' :
  'NO RISK - Approve'}
  `;
  
  return report;
}

// Usage
const report = await generateScreeningReport(12345);
console.log(report);

Notes

• Performance: Average response time 50-200ms
• Caching: Consider caching results client-side if accessed frequently
• Data consistency: Results reflect the screening at the time it was performed. Watchlists are updated regularly, so re-screening may yield different results.

Related Endpoints

• POST /api/Screening/screen - Create new screening
• GET /api/Screening/list - List all screenings

See Also

• Screening Guide - Learn about screening workflows
• Error Handling - Handle errors gracefully