Endpoint

List matches

Read persisted matches for your tenant. Use this to poll for new matches or to back a 'recent matches' view in your own UI.

Authentication

Requires the match scope. Employer-scoped keys see only matches on their jobs; organization-scoped keys see only matches involving their candidates.

Endpoint

GET/api/v1/matches

Query parameters

candidateIduuid

Restrict to one candidate.

jobIduuid

Restrict to one job.

minScorenumber

Drop matches below this score. Default 0.

limitnumber

Max results, default 50, max 200.

curl "https://www.astrishr.com/api/v1/matches?minScore=75&limit=10" \
  -H "Authorization: Bearer $KEY"

Response

{
  "matches": [
    {
      "matchId": "…",
      "candidateId": "…",
      "candidateName": "Mohammed K.",
      "jobId": "…",
      "jobTitle": "Warehouse Lead",
      "employerName": "Harbor Logistics",
      "finalScore": 87,
      "recommendation": "strong_match",
      "componentScores": {
        "skills": 92, "experience": 88, "language": 60,
        "distance": 90, "schedule": 95, "certification": 50,
        "transportation": 100
      },
      "gaps": [],
      "transferableSkills": [],
      "modelVersion": "v1-ensemble",
      "modelRunAt": "2026-06-08T17:30:00Z",
      "reviewed": false,
      "employerRating": null
    }
  ]
}

Polling vs webhooks

For new-match alerts, subscribe to match.created via webhooks instead of polling — payloads are HMAC-signed and arrive within seconds of the match being persisted.