Skip to main content

Quickstart Guide

Get started with the Matchstra API in under 5 minutes. This guide will walk you through making your first API call.

Prerequisites​

Before you begin, ensure you have:

  1. ✅ A Matchstra account (sign up at app.matchstra.ca)
  2. ✅ An active API key (generate one in your dashboard)
  3. ✅ A valid license plan with available request quota

Step 1: Get Your API Key​

  1. Log in to your Matchstra Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New API Key
  4. Give it a descriptive name (e.g., "Production API Key")
  5. Copy and securely store your API key
Security Warning

Never expose your API key in client-side code, public repositories, or logs. Treat it like a password.

Step 2: Make Your First Request​

Let's perform a PEP & Sanctions screening check.

Using cURL​

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",
    "entityType": "Individual",
    "minScore": 70
  }'

Using JavaScript (fetch)​

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',
    entityType: 'Individual',
    minScore: 70
  })
});

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

Using C# (.NET)​

using System.Net.Http;
using System.Net.Http.Headers;
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",
    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();
Console.WriteLine(result);

Step 3: Understanding the Response​

A successful response will look like this:

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

Response Fields:

  • success: Boolean indicating if the request was successful
  • message: Human-readable status message
  • data: The screening result object
    • id: Unique ID for this screening (use to retrieve later)
    • hasMatch: Boolean indicating if matches were found
    • matchCount: Number of potential matches
    • highestScore: Confidence score of the best match (0-100)
    • matches: Array of matched entities (empty if no matches)
    • remainingRequests: Your remaining API quota
  • errors: Array of error messages (null on success)

Step 4: Try ID Verification​

Upload an ID card and selfie for verification:

curl -X POST https://api.matchstra.ca/api/IdVerification/verify \
  -H "X-API-Key: your_api_key_here" \
  -F "IdCardImage=@/path/to/id-card.jpg" \
  -F "SelfieImage=@/path/to/selfie.jpg"

Common Response Codes​

CodeMeaningAction
200SuccessRequest completed successfully
400Bad RequestCheck your request payload
401UnauthorizedVerify your API key
404Not FoundCheck the endpoint URL
429Too Many RequestsSlow down, respect rate limits
500Server ErrorContact support if persists

Next Steps​

Now that you've made your first API call:

Need Help?​