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://jdskillfit.com/api-keys/onboard' \
  -H 'Content-Type: application/json' \
  -d '{
    "emailId": "your-email@example.com"
  }'

2. Existing email onboarding request

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

3. Invalid email request

curl -X POST 'https://jdskillfit.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://jdskillfit.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://jdskillfit.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://jdskillfit.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://jdskillfit.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": 91.4,
  "skillMatchPercentage": 87.3,
  "resumeExperienceYears": 6,
  "requiredExperienceYears": 5,
  "experienceRequirementSpecified": true,
  "experienceSatisfied": true,
  "experienceGapYears": 0,
  "fitCategory": "Strong Match",
  "summary": "Strong Match. Overall score 91.40%. Skill match 87.30% (3 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": "REQUIRED",
      "importanceWeight": 1.5,
      "roleRelevanceWeight": 1.2,
      "toolRelevanceWeight": 1.0,
      "certification": false,
      "combinedWeight": 1.8,
      "decisionSharePercentage": 40.9,
      "weightLabel": "High priority",
      "weightExplanation": "This is a high-priority JD skill. Strong role alignment increases decision weight.",
      "scoreExplanation": "Exact skill match. Resume experience meets the JD expectation and the resume version exceeds the JD version."
    },
    {
      "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": "PRIMARY",
      "importanceWeight": 1.25,
      "roleRelevanceWeight": 1.1,
      "toolRelevanceWeight": 1.0,
      "certification": false,
      "combinedWeight": 1.38,
      "decisionSharePercentage": 31.4,
      "weightLabel": "Important",
      "weightExplanation": "This is an important JD skill. Role relevance slightly increases decision weight.",
      "scoreExplanation": "Exact skill match. Resume version exceeds the JD version."
    },
    {
      "jdSkill": "AWS",
      "resumeSkill": "AWS",
      "matchType": "EXACT",
      "requiredYears": 0.0,
      "resumeYears": 0.0,
      "experienceSatisfied": true,
      "jdVersion": null,
      "resumeVersion": null,
      "versionStatus": "NOT_REQUIRED",
      "score": 100.0,
      "importance": "STANDARD",
      "importanceWeight": 1.0,
      "roleRelevanceWeight": 1.0,
      "toolRelevanceWeight": 1.1,
      "certification": false,
      "combinedWeight": 1.1,
      "decisionSharePercentage": 25.0,
      "weightLabel": "Standard",
      "weightExplanation": "This is a standard JD skill. Tool relevance slightly increases decision weight.",
      "scoreExplanation": "Exact skill match. No specific version was required."
    }
  ],
  "missingSkills": [
    {
      "jdSkill": "Datadog",
      "requiredYears": 0.0,
      "jdVersion": null,
      "importance": "OPTIONAL",
      "importanceWeight": 0.6,
      "roleRelevanceWeight": 1.0,
      "toolRelevanceWeight": 1.1,
      "certification": false,
      "combinedWeight": 0.66,
      "decisionSharePercentage": 15.0,
      "weightLabel": "Nice to have",
      "weightExplanation": "This is a nice-to-have skill. Tool relevance slightly increases decision weight."
    }
  ],
  "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.