DEV Community

Cover image for Smarter Scoring, Sharper Hiring: A Major Update to the CV Match Score API
Dawid Makowski
Dawid Makowski

Posted on • Originally published at sharpapi.com

Smarter Scoring, Sharper Hiring: A Major Update to the CV Match Score API

#hrtech #resumeparsing #cvparsing #hrapi

We've just shipped one of the most requested improvements to the Resume/CV & Job Description Compatibility Scoring endpoint. If you're building ATS integrations, candidate-screening tools, or HR analytics dashboards on top of SharpAPI, this update unlocks a whole new level of control over how matches are scored.

Here's everything that's new, why it matters, and how to start using it today.

TL;DR

  • The context parameter is now a formal directive contract, not a free-form note.
  • You get three simple directive shapes: EMPHASIZE, DEEMPHASIZE, and CREDIT.
  • Directives now influence the overall_match score — not just the individual metrics.
  • Role-family standard credentials (think Excel / SQL / Power BI for finance roles) are credited automatically even when the job description forgets to mention them.
  • Maximum context length is formally set to 5000 characters.

👉 Jump straight to the product page: sharpapi.com/en/catalog/ai/hr-tech/resume-cv-job-match-score

The problem we were solving

When we first launched the CV Match Score endpoint, it scored every resume against every job description using a fixed weighting table: skills, experience, and technical stack at the top; education, certifications, and soft skills as supporting signals. That works beautifully for the average hiring scenario — but hiring is never average.

A startup hiring a fresher values education and credentials far more than ten years of experience. A contract-hiring desk cares about skills, not tenure. A remote-first company doesn't want location pulling the score down at all. And sometimes, the job description simply forgets to list the obvious credentials — like Excel for a finance analyst — leaving the scoring engine to assume they don't matter.

Customers kept asking the same question:

"How do we tell the engine that **for this role, education matters more than experience?"

Now you can.

✨ What's new

1. A formal directive contract for the context parameter

The context field already existed, but its behaviour was fuzzy — long prose instructions often had unpredictable effects. We've replaced that with a clean, predictable contract built around three directive shapes.

Directive What it does Example
🔼 EMPHASIZE: <topic> Increases the weight of the matching metric(s) by one step EMPHASIZE: skills
🔽 DEEMPHASIZE: <topic> Decreases the weight of the matching metric(s) by one step (never zero) DEEMPHASIZE: experience
➕ `CREDIT: <skill \ tool \ cert>`

Directives can be mixed freely in a single context string:

EMPHASIZE: skills. EMPHASIZE: education. DEEMPHASIZE: experience. CREDIT: Excel and Analytics certificates.
Enter fullscreen mode Exit fullscreen mode

You don't need to memorise the full schema of 20 metrics, either. Topics accept plain-English categories like skills, experience, education, certificates, location, management, or tenure, and the engine maps them onto the related metrics internally.

2. context now moves the overall_match score

Before this update, the overall_match was computed from a hardcoded weighted average of the 20 individual metrics — meaning even if context shifted individual scores, the final overall number often stayed stubbornly still.

Not anymore. Directives now adjust the internal weighting table before the weighted average is computed. A single EMPHASIZE: skills now propagates all the way through to the final score.

Here's what that looks like conceptually:

Baseline weights:       skills=3, experience=3, education=1, certifications=1 ...
After EMPHASIZE: skills + DEEMPHASIZE: experience + EMPHASIZE: education:
Adjusted weights:       skills=4, experience=2, education=2, certifications=1 ...
overall_match = Σ(score × adjusted_weight) / Σ(adjusted_weights)
Enter fullscreen mode Exit fullscreen mode

Same resume. Same job description. Different scoring lens. That's the magic.

3. Role-family standard credentials are now credited

Here's a real example from customer feedback:

A finance JD said "Required: Excel, Python, analytics skills" but didn't list any specific certifications. A candidate with Advanced Excel, SQL, and Power BI certifications was getting certifications_match: 0 — because the JD was silent about certs.

That's obviously wrong. Those certifications are industry-standard for finance roles, and the engine should have credited them.

With this update, when the job description doesn't enumerate required certifications but the resume lists credentials that are commonly expected for the role family, the engine now credits them proportionally in the 40–70 range, with the reasoning noted in the explanations field.

This applies across role families:

  • 💼 Finance / analyst roles → Advanced Excel, SQL, Power BI, Tableau
  • 👨‍💻 Software engineering → Git, CI/CD, cloud platform certs
  • 📊 Project management → PMP, PRINCE2, Scrum, Agile
  • 🏥 Healthcare → CPR, BLS, specialty certifications

No more zero-scores on obvious credentials just because the JD was lazy.

4. Formalised 5000-character limit on context

We've set a clean, generous upper bound of 5000 characters for the context field. That's comfortably above any realistic directive payload — enough room for dozens of directives plus explanatory notes — while keeping the full prompt within safe token budgets.

Requests exceeding the limit return an HTTP 422 validation error.

Recommended patterns

These are the context recipes that performed best in our internal validation. Drop them in as starting points and tune from there.

Pattern 1 — Entry-level / fresher hiring

Prioritise credentials and potential over years of experience.

EMPHASIZE: skills. EMPHASIZE: education. DEEMPHASIZE: experience. CREDIT: Excel and Analytics certificates.
Enter fullscreen mode Exit fullscreen mode

Pattern 2 — Senior technical hiring

Stack match is critical; formal education is secondary.

EMPHASIZE: skills. EMPHASIZE: technical_stack_match. DEEMPHASIZE: education.
Enter fullscreen mode Exit fullscreen mode

Pattern 3 — Leadership / management hiring

Management experience outweighs hands-on technical skills.

EMPHASIZE: management. EMPHASIZE: experience. DEEMPHASIZE: technical_stack_match.
Enter fullscreen mode Exit fullscreen mode

Pattern 4 — Remote-first hiring

Location should not penalise candidates at all.

DEEMPHASIZE: location. EMPHASIZE: skills.
Enter fullscreen mode Exit fullscreen mode

Best practices

  • Be specific. CREDIT: Excel, SQL, Power BI moves the needle. Abstract framing like "practical competency outweighs formal credentials" does not.
  • Use contrast pairs. Combine EMPHASIZE with DEEMPHASIZE in the same request — contrast is a strong signal.
  • Name tools and credentials explicitly. Avoid vague qualities like "talent" or "potential".
  • Skip percentage instructions. Directives like "reduce weight by 50%" are interpreted conservatively as a single DEEMPHASIZE step. Use discrete directives — they're more reliable.
  • Keep context focused. A handful of targeted directives outperforms long prose paragraphs.

⚠️ What context can and can't do

✅ context can change ❌ context cannot change
Weights of any of the 20 metrics in overall_match Arithmetic metrics like stability_score or location_preference_match (scores are computed from dates/geography)
Credit for role-family-standard skills and certifications The JSON schema or the number of metrics
Scoring emphasis across individual dimensions Personal-data protection rules (resume anonymisation is non-negotiable)

Note on arithmetic metrics: context still adjusts their weight in overall_match — it just doesn't rewrite the individual score itself. If a candidate has a 1-year average tenure, stability_score reflects that fact regardless of directives, but you can make it count for more or less in the overall outcome.

A full request example 

POST /api/v1/hr/resume_job_match_score
Content-Type: multipart/form-data
Authorization: Bearer <YOUR_API_KEY>

file:     <resume.pdf>
content:  "Junior Finance Associate — entry-level role.
           Required: Excel, Python, financial modelling, analytics."
language: English
context:  "EMPHASIZE: skills. EMPHASIZE: education.
           DEEMPHASIZE: experience. CREDIT: Excel and Analytics certificates."
Enter fullscreen mode Exit fullscreen mode

The response structure is unchanged — you still get the 20 scored metrics plus explanations for the most important ones — but the numbers will now reflect the directive-adjusted weights.

A word on non-determinism

The context parameter is our primary lever for steering the engine, and we tune it continuously based on the real-world cases our customers bring us. If you hit a scenario where the output doesn't match your expectations, send us the exact request/response — that's the single most valuable feedback we can get.

Get started

Ready to try it? Here's your shortlist:

  1. Read the product details: Resume/CV & Job Description Compatibility Scoring
  2. See it live: CVMatchScore.com — a fully working product built on this exact endpoint
  3. Grab an API key from your SharpAPI dashboard and send your first request
  4. Tell us what's missing — every directive pattern we've shipped started as customer feedback

Happy matching. 🎯

👉 Try the Resume/CV & Job Description Compatibility Scoring API today:
sharpapi.com/en/catalog/ai/hr-tech/resume-cv-job-match-score

Resume Stock photos by Vecteezy

Top comments (0)