# Score a resume against a job post (/docs/guides/score-resume-against-job)

Show a job seeker how well their resume matches a posting, which keywords it misses and what to fix. Then close the gap with one more call.

A job seeker wants one answer before they apply: will this resume get through?
`POST /developer/ats-score` scores resume text against a job posting from 0 to 100.
It names the keywords the resume matches, the ones it misses, and what to change.
Put that in front of your user and they apply with a resume built for the job.

You need an API key. The [Quickstart](/docs/quickstart) shows how to get one.
If you start from a PDF, [Parse a resume to JSON](/docs/guides/parse-resume-to-json) shows how to get its text.

## 1. Send the resume and the posting [#1-send-the-resume-and-the-posting]

Both texts must be 50 to 50,000 characters.

```bash title="curl"
curl https://api.getmattered.com/api/v1/developer/ats-score \
  -H "Authorization: Bearer $GETMATTERED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resumeText": "Maya Patel\nSenior Data Analyst\nAustin, TX | maya.patel@example.com\n\nSenior Data Analyst, Northwind Health, Mar 2021 - Present\nBuilt SQL and Python pipelines for weekly reporting.\nData Analyst, Contoso Retail, Jun 2017 - Feb 2021\nRan A/B testing for pricing changes.\n\nSkills\nSQL, Python, Tableau, Excel, A/B testing", "jobDescription": "We are hiring a Senior Data Analyst to own product analytics. You will write SQL, build dashboards in Looker and run A/B testing with product managers. Experience with dbt and Python is a plus."}'
```

```ts title="TypeScript (fetch)"
const response = await fetch('https://api.getmattered.com/api/v1/developer/ats-score', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.GETMATTERED_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ resumeText, jobDescription }),
});

const body = await response.json();
if (!body.success) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}
const { data } = body;
console.log(data.overallScore, data.missingKeywords);
```

Leave out `jobDescription` to get a general ATS score for the resume on its own.

## 2. Read the score [#2-read-the-score]

A successful call answers `200`:

```json title="POST /developer/ats-score 200 response"
{
  "success": true,
  "data": {
    "overallScore": 74,
    "keywordMatches": ["SQL", "Python", "A/B testing"],
    "missingKeywords": ["Looker", "dbt"],
    "sectionScores": { "skills": 70, "experience": 82, "education": 60, "formatting": 85, "keywords": 68 },
    "suggestions": [
      "Add \"Looker\" to your skills section if you have used it.",
      "Name the dashboards you built and who used them."
    ],
    "usage": { "tokens": 390 }
  },
  "meta": { "requestId": "...", "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" }
}
```

The keywords above come from the two texts in step 1.
The scores and suggestions show the shape only. Yours depend on the texts you send.

| Field | What it holds |
| --- | --- |
| `overallScore` | The match from 0 to 100. |
| `keywordMatches` | Keywords from the posting that the resume has. |
| `missingKeywords` | Keywords from the posting that the resume lacks. |
| `sectionScores` | A score from 0 to 100 for `skills`, `experience`, `education`, `formatting` and `keywords`. |
| `suggestions` | Changes to make, one sentence each. |

## 3. Show the gap [#3-show-the-gap]

Turn the response into a short checklist your user can act on:

```ts title="gap-report.ts"
export function gapReport(score: { overallScore: number; missingKeywords: string[]; suggestions: string[] }) {
  return {
    headline: `Your resume matches this job at ${score.overallScore} out of 100.`,
    missing: score.missingKeywords.map(keyword => `Add "${keyword}" if you have used it.`),
    fixes: score.suggestions,
  };
}

const report = gapReport(data);
```

Ask the person before you add a keyword. They know which skills are true.

## 4. Close the gap in one call [#4-close-the-gap-in-one-call]

`POST /developer/tailor` rewrites the resume for one posting and scores it before and after, in the same call:

```json title="POST /developer/tailor request"
{
  "resumeText": "Maya Patel\nSenior Data Analyst\nAustin, TX | maya.patel@example.com\n\nSenior Data Analyst, Northwind Health, Mar 2021 - Present\nBuilt SQL and Python pipelines for weekly reporting.\nData Analyst, Contoso Retail, Jun 2017 - Feb 2021\nRan A/B testing for pricing changes.\n\nSkills\nSQL, Python, Tableau, Excel, A/B testing",
  "jobDescription": "We are hiring a Senior Data Analyst to own product analytics. You will write SQL, build dashboards in Looker and run A/B testing with product managers. Experience with dbt and Python is a plus.",
  "jobTitle": "Senior Data Analyst",
  "tier": "light"
}
```

The response holds `tailoredResume`, the `keywordsAdded`, a `summary` of the changes, and two full scores: `before` and `after`.
Show both scores side by side, then let the person review the new resume before they send it.
`light` is a quick rewrite. `pro` goes deeper and spends more. The [API reference](/docs/reference/tailor) has the full schema.

## What it costs [#what-it-costs]

Each call spends API tokens from the account that owns the key.
`data.usage.tokens` says how many a call spent.
[Pricing](/docs/pricing) has the usual cost of every call.

## For AI agents [#for-ai-agents]

This guide is also Markdown at [`/docs/guides/score-resume-against-job.md`](/docs/guides/score-resume-against-job.md).
[`/docs/llms-full.txt`](/docs/llms-full.txt) holds every page, and [`/docs/openapi.json`](/docs/openapi.json) the full API.