GET /api/IdVerification/{id}

Retrieve a specific ID verification result by its ID.

Endpoint

GET https://api.matchstra.ca/api/IdVerification/{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	Verification ID (returned from POST /verify)

Request Example

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

const verificationId = 67890;

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

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

using System.Net.Http;

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

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

Console.WriteLine(result);

Response

Success Response (200 OK)

Returns complete verification details:

{
  "id": 67890,
  "faceMatch": true,
  "matchConfidence": 96.8,
  "livenessScore": 98.5,
  "status": "Verified",
  "createdAt": "2025-01-02T14:30:00Z",
  "extractedData": {
    "documentType": "Driver License",
    "documentNumber": "D1234567",
    "fullName": "JANE MARY DOE",
    "dateOfBirth": "1990-08-15T00:00:00Z",
    "expiryDate": "2028-08-15T00:00:00Z",
    "country": "Canada",
    "region": "Ontario",
    "address": "123 Main St, Toronto, ON M5V 1A1",
    "nationality": "Canadian",
    "sex": "F"
  }
}

Response Fields

Field	Type	Description
`id`	integer	Unique verification ID
`faceMatch`	boolean	Whether face matched ID document
`matchConfidence`	number	Face match confidence (0-100)
`livenessScore`	number	Liveness detection score (0-100, or null)
`status`	string	`"Verified"`, `"Not Verified"`, or `"Manual Review Required"`
`createdAt`	string	Timestamp of verification (ISO 8601)
`extractedData`	object	Complete extracted data from ID document

Extracted Data Fields

Field	Type	Description
`documentType`	string	Type of document (e.g., "Driver License", "Passport")
`documentNumber`	string	ID/document number
`fullName`	string	Full name as on document
`dateOfBirth`	string	Date of birth (ISO 8601)
`expiryDate`	string	Document expiry date (ISO 8601)
`country`	string	Issuing country
`region`	string	State/province (if applicable)
`address`	string	Address on document (if present)
`nationality`	string	Nationality/citizenship
`sex`	string	Gender marker ("M", "F", "X", etc.)

note

Some fields may be null if not present on the document or not readable.

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": "Verification with ID 99999 not found"
}

Causes:

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

Use Cases

Retrieve Full Details After Verification

// Step 1: Perform verification
const formData = new FormData();
formData.append('IdCardImage', idCardFile);
formData.append('SelfieImage', selfieFile);

const verifyResponse = await fetch('https://api.matchstra.ca/api/IdVerification/verify', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY },
  body: formData
});

const verifyData = await verifyResponse.json();
const verificationId = verifyData.data.id;

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

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

Pre-fill Registration Form

async function prefillFormFromVerification(verificationId) {
  const response = await fetch(
    `https://api.matchstra.ca/api/IdVerification/${verificationId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  const verification = await response.json();
  
  if (!verification.faceMatch) {
    throw new Error('Verification failed - cannot prefill form');
  }
  
  const { extractedData } = verification;
  
  // Split name
  const nameParts = extractedData.fullName.split(' ');
  const firstName = nameParts[0];
  const lastName = nameParts.slice(1).join(' ');
  
  return {
    firstName,
    lastName,
    dateOfBirth: extractedData.dateOfBirth.split('T')[0],
    address: extractedData.address || '',
    country: extractedData.country,
    region: extractedData.region,
    verificationId: verification.id
  };
}

// Usage
const formData = await prefillFormFromVerification(67890);
console.log('Form data:', formData);

Audit Trail

async function generateAuditRecord(verificationId) {
  const response = await fetch(
    `https://api.matchstra.ca/api/IdVerification/${verificationId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  const verification = await response.json();
  
  return {
    verificationId: verification.id,
    timestamp: verification.createdAt,
    subject: verification.extractedData.fullName,
    documentType: verification.extractedData.documentType,
    documentNumber: verification.extractedData.documentNumber,
    result: verification.faceMatch ? 'VERIFIED' : 'NOT VERIFIED',
    matchConfidence: verification.matchConfidence,
    livenessScore: verification.livenessScore,
    status: verification.status,
    documentExpiry: verification.extractedData.expiryDate
  };
}

// Usage
const auditRecord = await generateAuditRecord(67890);
console.log('Audit record:', auditRecord);

Compliance Report

async function generateComplianceReport(verificationId) {
  const response = await fetch(
    `https://api.matchstra.ca/api/IdVerification/${verificationId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  const v = await response.json();
  
  const report = `
IDENTITY VERIFICATION REPORT
============================
Verification ID: ${v.id}
Date: ${new Date(v.createdAt).toLocaleString()}

SUBJECT INFORMATION
-------------------
Name: ${v.extractedData.fullName}
Date of Birth: ${new Date(v.extractedData.dateOfBirth).toLocaleDateString()}
Nationality: ${v.extractedData.nationality}

DOCUMENT INFORMATION
--------------------
Type: ${v.extractedData.documentType}
Number: ${v.extractedData.documentNumber}
Issuing Country: ${v.extractedData.country}
${v.extractedData.region ? `Region: ${v.extractedData.region}` : ''}
Expiry Date: ${new Date(v.extractedData.expiryDate).toLocaleDateString()}

VERIFICATION RESULTS
--------------------
Status: ${v.status}
Face Match: ${v.faceMatch ? '✅ YES' : '❌ NO'}
Match Confidence: ${v.matchConfidence.toFixed(1)}%
Liveness Score: ${v.livenessScore !== null ? v.livenessScore.toFixed(1) + '%' : 'N/A'}

RISK ASSESSMENT
---------------
${v.faceMatch ? '✅ APPROVED' : '❌ REJECTED'}
${v.matchConfidence >= 90 ? 'High confidence verification' :
  v.matchConfidence >= 75 ? 'Moderate confidence - acceptable' :
  'Low confidence - review required'}
${v.livenessScore !== null && v.livenessScore < 70 ? '⚠️  Potential spoof detected' : ''}
${new Date(v.extractedData.expiryDate) < new Date() ? '⚠️  Document has expired' : ''}

COMPLIANCE NOTES
----------------
- Identity verification performed in accordance with KYC regulations
- Biometric facial recognition utilized
- Liveness detection applied to prevent fraud
- Document authenticity verified via OCR
- Record retained for audit purposes
  `;
  
  return report;
}

// Usage
const report = await generateComplianceReport(67890);
console.log(report);

Age Verification

async function verifyAge(verificationId, minimumAge = 18) {
  const response = await fetch(
    `https://api.matchstra.ca/api/IdVerification/${verificationId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  const verification = await response.json();
  
  if (!verification.faceMatch) {
    throw new Error('Identity not verified - cannot verify age');
  }
  
  const dob = new Date(verification.extractedData.dateOfBirth);
  const today = new Date();
  
  let age = today.getFullYear() - dob.getFullYear();
  const monthDiff = today.getMonth() - dob.getMonth();
  
  if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < dob.getDate())) {
    age--;
  }
  
  return {
    verificationId: verification.id,
    name: verification.extractedData.fullName,
    dateOfBirth: verification.extractedData.dateOfBirth,
    age,
    minimumAge,
    isOldEnough: age >= minimumAge,
    verified: verification.faceMatch
  };
}

// Usage
const ageCheck = await verifyAge(67890, 21);
console.log(`${ageCheck.name} is ${ageCheck.age} years old`);
console.log(ageCheck.isOldEnough ? '✅ Access granted' : '❌ Access denied');

Check Document Expiry

async function checkDocumentValidity(verificationId) {
  const response = await fetch(
    `https://api.matchstra.ca/api/IdVerification/${verificationId}`,
    {
      headers: { 'X-API-Key': process.env.MATCHSTRA_API_KEY }
    }
  );
  
  const verification = await response.json();
  const expiryDate = new Date(verification.extractedData.expiryDate);
  const today = new Date();
  
  const daysUntilExpiry = Math.ceil((expiryDate - today) / (1000 * 60 * 60 * 24));
  
  return {
    documentNumber: verification.extractedData.documentNumber,
    expiryDate: verification.extractedData.expiryDate,
    isExpired: expiryDate < today,
    daysUntilExpiry,
    expiresWithin30Days: daysUntilExpiry > 0 && daysUntilExpiry <= 30,
    status: expiryDate < today ? 'EXPIRED' :
            daysUntilExpiry <= 30 ? 'EXPIRING SOON' :
            'VALID'
  };
}

// Usage
const validity = await checkDocumentValidity(67890);
console.log(`Document status: ${validity.status}`);
if (validity.expiresWithin30Days) {
  console.log(`⚠️  Expires in ${validity.daysUntilExpiry} days`);
}

Notes

Images not returned: The API does not return the original images. Only extracted data and verification results are provided.
Performance: Average response time 50-200ms.
Data retention: Verification records are stored indefinitely. Images are deleted after 90 days.
Privacy: All data is encrypted in transit and at rest.

POST /api/IdVerification/verify - Create new verification
GET /api/IdVerification/list - List all verifications

Endpoint​

Authentication​

Request​

Headers​

Path Parameters​

Request Example​

Response​

Success Response (200 OK)​

Response Fields​

Extracted Data Fields​

Error Responses​

401 Unauthorized​

404 Not Found​

Use Cases​

Retrieve Full Details After Verification​

Pre-fill Registration Form​

Audit Trail​

Compliance Report​

Age Verification​

Check Document Expiry​

Notes​

Related Endpoints​

See Also​