Endpoint

Score match

Score a (candidate, job) pair. Returns the full ensemble result — 7-component breakdown, sub-models, retention forecast, gaps, transferable-skill bridges.

Authentication

Requires the match scope. Tenant scope (when set) is enforced on both candidate and job.

Endpoint

POST/api/v1/match

Request

candidateIduuidrequired

Candidate to score.

jobIduuidrequired

Job to score against.

curl -X POST https://www.astrishr.com/api/v1/match \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidateId":"…","jobId":"…"}'

Response

{
  "finalScore": 87,
  "recommendation": "strong_match",
  "componentScores": {
    "skills": 92,
    "experience": 88,
    "language": 60,
    "distance": 90,
    "schedule": 95,
    "certification": 50,
    "transportation": 100
  },
  "subModels": [
    { "modelName": "astris-heuristic-v1",            "overallScore": 84 },
    { "modelName": "astris-embedding-similarity-v1", "overallScore": 88, "notes": "pgvector cosine over candidate + job text embeddings" },
    { "modelName": "astris-retention-heuristic-v1",  "overallScore": 89, "notes": "expected stay ≈ 312 days (P(180d) = 0.74)" }
  ],
  "retention": {
    "expectedTenureDays": 312,
    "retention30": 0.91,
    "retention90": 0.83,
    "retention180": 0.74,
    "retention365": 0.61,
    "confidence": 0.85
  },
  "gaps": ["Spanish proficiency would be preferred but not required"],
  "transferableSkills": [
    { "from": "Crop Cultivation", "to": "Inventory Handling", "confidence": 0.78 },
    { "from": "Tractor",          "to": "Forklift",           "confidence": 0.82 }
  ],
  "companyQualityBoost": 1.4
}

How the score is built

The final score is a weighted average across sub-models that have data for this pair. Sub-models that can't run (e.g. embedding similarity when one side is missing an embedding) are dropped from the average — graceful degradation.

Active sub-models + their default weights are listed at /astris-model/models.
Recommendation cutoffs: ≥90 recommended, ≥75 strong, ≥55 moderate, ≥35 weak, <35 not_recommended.
companyQualityBoost is added on top (range [-5, +5]) when the employer has a quality score.