Skip to main content

GET /api/IdVerification/list

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

Endpoint​

GET https://api.matchstra.ca/api/IdVerification/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 verifications for your account.

Request Example​

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

const verifications = await response.json();
console.log(verifications);
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/IdVerification/list");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine(result);

Response​

Success Response (200 OK)​

Returns an array of verification objects:

[
  {
    "id": 67890,
    "faceMatch": true,
    "matchConfidence": 96.8,
    "livenessScore": 98.5,
    "status": "Verified",
    "createdAt": "2025-01-02T14:30:00Z",
    "extractedData": {
      "documentType": "Driver License",
      "fullName": "JANE MARY DOE",
      "dateOfBirth": "1990-08-15T00:00:00Z",
      "country": "Canada"
    }
  },
  {
    "id": 67889,
    "faceMatch": false,
    "matchConfidence": 55.2,
    "livenessScore": 92.1,
    "status": "Not Verified",
    "createdAt": "2025-01-02T13:15:00Z",
    "extractedData": {
      "documentType": "Passport",
      "fullName": "JOHN ROBERT SMITH",
      "dateOfBirth": "1985-03-22T00:00:00Z",
      "country": "United States"
    }
  }
]

Response Fields​

FieldTypeDescription
idintegerUnique verification ID
faceMatchbooleanWhether face matched ID
matchConfidencenumberMatch confidence (0-100)
livenessScorenumberLiveness score (0-100, or null)
statusstringVerification status
createdAtstringTimestamp (ISO 8601)
extractedDataobjectSummary of extracted data (may be partial)
note

For complete verification details and full extracted data, use GET /api/IdVerification/{id}.

Empty List Response​

If no verifications 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) are planned for a future release.

Currently returns all results (up to a reasonable limit).

Filtering​

Coming Soon

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

Use Cases​

Display Recent Verifications​

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

// Usage
const recent = await getRecentVerifications(5);
console.table(recent.map(v => ({
  ID: v.id,
  Name: v.extractedData.fullName,
  Status: v.status,
  Confidence: v.matchConfidence + '%',
  Date: new Date(v.createdAt).toLocaleString()
})));

Count Successful Verifications​

async function getVerificationStats() {
  const response = await fetch('https://api.matchstra.ca/api/IdVerification/list', {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  });
  
  const verifications = await response.json();
  
  const stats = {
    total: verifications.length,
    verified: verifications.filter(v => v.faceMatch).length,
    notVerified: verifications.filter(v => !v.faceMatch).length,
    successRate: 0
  };
  
  stats.successRate = ((stats.verified / stats.total) * 100).toFixed(2);
  
  return stats;
}

// Usage
const stats = await getVerificationStats();
console.log(`Success rate: ${stats.successRate}% (${stats.verified}/${stats.total})`);

Filter by Document Type​

async function getVerificationsByDocType(docType = 'Passport') {
  const response = await fetch('https://api.matchstra.ca/api/IdVerification/list', {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  });
  
  const verifications = await response.json();
  
  return verifications.filter(v => 
    v.extractedData.documentType === docType
  );
}

// Usage
const passports = await getVerificationsByDocType('Passport');
console.log(`Found ${passports.length} passport verifications`);

Export to CSV​

async function exportVerificationsToCSV() {
  const response = await fetch('https://api.matchstra.ca/api/IdVerification/list', {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  });
  
  const verifications = await response.json();
  
  const headers = 'ID,Name,Document Type,Face Match,Confidence,Liveness,Status,Date\n';
  const rows = verifications.map(v => 
    `${v.id},"${v.extractedData.fullName}",${v.extractedData.documentType},${v.faceMatch},${v.matchConfidence},${v.livenessScore || 'N/A'},${v.status},${v.createdAt}`
  ).join('\n');
  
  return headers + rows;
}

// Usage
const csv = await exportVerificationsToCSV();
console.log(csv);
// Or save to file:
// fs.writeFileSync('verifications.csv', csv);

Daily Verification Count​

async function getDailyVerificationCount() {
  const response = await fetch('https://api.matchstra.ca/api/IdVerification/list', {
    headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
  });
  
  const verifications = await response.json();
  
  const counts = {};
  
  verifications.forEach(v => {
    const date = new Date(v.createdAt).toISOString().split('T')[0];
    counts[date] = (counts[date] || 0) + 1;
  });
  
  return counts;
}

// Usage
const dailyCounts = await getDailyVerificationCount();
console.log('Daily verification counts:', dailyCounts);
// Output: { '2025-01-02': 15, '2025-01-03': 23, ... }

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 verifications. Typically 100-500ms.
  • Data retention: Verification records are retained indefinitely. Images are stored for 90 days, then deleted.
  • Partial data: List endpoint returns summary data. For full extracted data fields, use the Get by ID endpoint.

See Also​