API Documentation

Developer-facing reference for onboarding, protected matching, supported input combinations, and current usage limits.

The onboarding endpoint POST /api-keys/onboard is public. The matching endpoint POST /match requires x-api-key.

Open onboarding Open match page

Public API Endpoint

POST /api-keys/onboard: accepts an email address and starts API key onboarding.

Protected Endpoint

POST /match with x-api-key

Usage Limits

10 calls per day
100 calls per month

Supported Input Modes

Resume text + job description text
Resume text + job description file
Resume file + job description text
Resume file + job description file

Input Rules

Provide exactly one input mode for the resume.
Provide exactly one input mode for the job description.
Resume text limit: 10,000 characters.
Job description text limit: 10,000 characters.
Maximum uploaded file size: 1 MB per file.
Supported file types: PDF, DOC, DOCX, TXT.

Onboarding Request

1. First-time onboarding request

curl -X POST 'https://resumescorer-db8r.onrender.com/api-keys/onboard' \
  -H 'Content-Type: application/json' \
  -d '{
    "emailId": "your-email@example.com"
  }'

2. Existing email onboarding request

curl -X POST 'https://resumescorer-db8r.onrender.com/api-keys/onboard' \
  -H 'Content-Type: application/json' \
  -d '{
    "emailId": "your-email@example.com"
  }'

3. Invalid email request

curl -X POST 'https://resumescorer-db8r.onrender.com/api-keys/onboard' \
  -H 'Content-Type: application/json' \
  -d '{
    "emailId": "not-an-email"
  }'

Onboarding Response Examples

Success: new API key created and emailed

{
  "userId": "your-email@example.com",
  "emailId": "your-email@example.com",
  "message": "Tech Resume JD Matcher API key generated and sent to your email address.",
  "dailyLimit": 10,
  "monthlyLimit": 100,
  "generatedAt": "2026-08-01T07:25:14.182Z"
}

Success: API key already exists for this email

{
  "userId": "your-email@example.com",
  "emailId": "your-email@example.com",
  "message": "API key already exists for this email. Please check your earlier email.",
  "dailyLimit": 10,
  "monthlyLimit": 100,
  "generatedAt": "2026-07-30T03:42:11.368Z"
}

Error: invalid email format

{
  "timestamp": "2026-08-01T07:26:40.114Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api-keys/onboard"
}

Error: onboarding rate limit reached

{
  "timestamp": "2026-08-01T07:28:05.771Z",
  "status": 429,
  "error": "Too Many Requests",
  "message": "Too many onboarding requests from this IP. Please try again later.",
  "path": "/api-keys/onboard"
}

Matching Request

1. Resume text + job description text

curl -X POST 'https://resumescorer-db8r.onrender.com/match' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: rsk_your_api_key' \
  -d '{
    "resumeText": "Java Spring Boot AWS Kafka",
    "jobDescriptionText": "Java Spring Boot AWS Kafka"
  }'

2. Resume text + job description file

curl -X POST 'https://resumescorer-db8r.onrender.com/match' \
  -H 'x-api-key: rsk_your_api_key' \
  -F 'resumeText=Java Spring Boot AWS Kafka Microservices' \
  -F 'jobDescriptionFile=@/path/to/job-description.pdf'

3. Resume file + job description text

curl -X POST 'https://resumescorer-db8r.onrender.com/match' \
  -H 'x-api-key: rsk_your_api_key' \
  -F 'resumeFile=@/path/to/resume.pdf' \
  -F 'jobDescriptionText=Java Spring Boot AWS Kafka Microservices'

4. Resume file + job description file

curl -X POST 'https://resumescorer-db8r.onrender.com/match' \
  -H 'x-api-key: rsk_your_api_key' \
  -F 'resumeFile=@/path/to/resume.pdf' \
  -F 'jobDescriptionFile=@/path/to/job-description.docx'

Response Example

{
  "overallScore": 93.6,
  "skillMatchPercentage": 96.0,
  "resumeExperienceYears": 6,
  "requiredExperienceYears": 5,
  "experienceRequirementSpecified": true,
  "experienceSatisfied": true,
  "experienceGapYears": 0,
  "fitCategory": "Excellent Match",
  "summary": "Excellent Match. Overall score 93.60%. Skill match 96.00% (24 matched, 1 missing). Experience 6/5 years.",
  "matchedSkills": [
    {
      "jdSkill": "Java",
      "resumeSkill": "Java",
      "matchType": "EXACT",
      "requiredYears": 5.0,
      "resumeYears": 6.0,
      "experienceSatisfied": true,
      "jdVersion": "17",
      "resumeVersion": "21",
      "versionStatus": "HIGHER",
      "score": 100.0,
      "importance": "CRITICAL",
      "importanceWeight": 1.5,
      "roleRelevanceWeight": 1.2,
      "toolRelevanceWeight": 1.0,
      "certification": false,
      "combinedWeight": 1.8
    },
    {
      "jdSkill": "Spring Boot",
      "resumeSkill": "Spring Boot",
      "matchType": "EXACT",
      "requiredYears": 0.0,
      "resumeYears": 0.0,
      "experienceSatisfied": true,
      "jdVersion": "3",
      "resumeVersion": "3.2",
      "versionStatus": "HIGHER",
      "score": 100.0,
      "importance": "STANDARD",
      "importanceWeight": 1.0,
      "roleRelevanceWeight": 1.1,
      "toolRelevanceWeight": 1.0,
      "certification": false,
      "combinedWeight": 1.1
    },
    {
      "jdSkill": "Platform Reliability",
      "resumeSkill": "REST API",
      "matchType": "RELATED",
      "requiredYears": 0.0,
      "resumeYears": 0.0,
      "experienceSatisfied": true,
      "jdVersion": null,
      "resumeVersion": null,
      "versionStatus": "NOT_REQUIRED",
      "score": 50.0,
      "importance": "OPTIONAL",
      "importanceWeight": 0.7,
      "roleRelevanceWeight": 1.0,
      "toolRelevanceWeight": 1.0,
      "certification": false,
      "combinedWeight": 0.7
    }
  ],
  "missingSkills": [
    {
      "jdSkill": "Datadog",
      "requiredYears": 0.0,
      "jdVersion": null,
      "importance": "STANDARD",
      "importanceWeight": 1.0,
      "roleRelevanceWeight": 1.0,
      "toolRelevanceWeight": 1.1,
      "certification": false,
      "combinedWeight": 1.1
    }
  ],
  "limits": {
    "dailyRemaining": 9,
    "monthlyRemaining": 99
  }
}

Response Fields

overallScore: final weighted match score.
skillMatchPercentage: percentage of total JD weight covered by matched skills.
resumeExperienceYears and requiredExperienceYears: extracted experience values.
experienceRequirementSpecified: indicates whether the job description explicitly yielded an experience requirement.
fitCategory: one of Limited Match, OK Match, Good Match, Strong Match, or Excellent Match.
matchedSkills: individual skill matches with match type, version status, experience comparison, per-skill score, and weight components.
missingSkills: required job description skills that were not matched, including their weight components.
limits: remaining daily and monthly quota for tracked API keys.

Scoring Notes

Each matched skill starts with a base score from matchType: EXACT, CHILD_TO_PARENT, PARENT_TO_CHILD, SIBLING, or RELATED.
The base score is adjusted by experience fit and version fit to produce the skill score.
combinedWeight is the product of importanceWeight, roleRelevanceWeight, and toolRelevanceWeight.
overallScore is the weighted average of matched skill scores.
skillMatchPercentage measures coverage of total JD weight, not just a raw matched-skill count.