# Parse a resume to JSON (/docs/guides/parse-resume-to-json)

Turn a resume into clean JSON with contact details, work history, education and skills. Each contact fact comes with the line of the resume it came from.

Your users upload a resume. Your product needs fields: a name, an email, past jobs, skills.
`POST /developer/parse` turns resume text into that JSON in one call.
Each contact fact comes with the exact resume line behind it.
So your product fills a form with what the person wrote, never with a guess.

You need an API key. The [Quickstart](/docs/quickstart) shows how to get one.

## 1. Get the text out of the file [#1-get-the-text-out-of-the-file]

The API reads text: plain text or Markdown, 50 to 50,000 characters.
For a PDF, pull the text out on your server first.
In Node.js or Bun, the open source `unpdf` package does it in one call:

```ts title="pdf-to-text.ts"
import { extractText } from 'unpdf';

export async function pdfToText(file: ArrayBuffer) {
  const { text } = await extractText(new Uint8Array(file), { mergePages: true });
  return text;
}
```

A scanned PDF holds a picture of the page and no text layer, so it gives back little or no text.
Check the length before you call the API. Text under 50 characters gets a `422`. See [Errors](/docs/errors).

## 2. Send the text [#2-send-the-text]

```bash title="curl"
curl https://api.getmattered.com/api/v1/developer/parse \
  -H "Authorization: Bearer $GETMATTERED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resumeText": "Maya Patel\nSenior Data Analyst\nAustin, TX | maya.patel@example.com | +1 512 555 0142\nlinkedin.com/in/mayapatel-example\n\nExperience\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\nEducation\nB.S. Statistics, University of Texas at Austin, 2017\n\nSkills\nSQL, Python, Tableau, Excel, A/B testing"}'
```

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

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

## 3. Read the response [#3-read-the-response]

A successful call answers `200`. This is the response for the resume in step 2, trimmed for space:

```json title="POST /developer/parse 200 response"
{
  "success": true,
  "data": {
    "fullName": "Maya Patel",
    "firstName": "Maya",
    "lastName": "Patel",
    "email": "maya.patel@example.com",
    "phone": "+1 512 555 0142",
    "city": "Austin",
    "state": "TX",
    "country": null,
    "zipCode": null,
    "linkedinUrl": "linkedin.com/in/mayapatel-example",
    "githubUrl": null,
    "portfolioUrl": null,
    "currentJobTitle": "Senior Data Analyst",
    "professionalSummary": null,
    "workExperience": [
      {
        "title": "Senior Data Analyst",
        "company": "Northwind Health",
        "startDate": "Mar 2021",
        "endDate": null,
        "current": true,
        "description": "Built SQL and Python pipelines for weekly reporting."
      },
      {
        "title": "Data Analyst",
        "company": "Contoso Retail",
        "startDate": "Jun 2017",
        "endDate": "Feb 2021",
        "current": false,
        "description": "Ran A/B testing for pricing changes."
      }
    ],
    "education": [
      { "degree": "B.S. Statistics", "institution": "University of Texas at Austin", "year": "2017" }
    ],
    "skills": ["SQL", "Python", "Tableau", "Excel", "A/B testing"],
    "fieldEvidence": [
      { "field": "city", "quote": "Austin, TX | maya.patel@example.com | +1 512 555 0142", "confidence": "high" },
      { "field": "email", "quote": "Austin, TX | maya.patel@example.com | +1 512 555 0142", "confidence": "high" },
      { "field": "phone", "quote": "Austin, TX | maya.patel@example.com | +1 512 555 0142", "confidence": "high" },
      { "field": "linkedinUrl", "quote": "linkedin.com/in/mayapatel-example", "confidence": "high" },
      { "field": "currentEmployer", "quote": "Senior Data Analyst, Northwind Health, Mar 2021 - Present", "confidence": "high" },
      { "field": "educationLevel", "quote": "B.S. Statistics, University of Texas at Austin, 2017", "confidence": "low" }
    ],
    "experienceLevel": "senior",
    "educationLevel": "bachelor",
    "yearsOfExperience": 9,
    "industries": ["Healthcare", "Retail"],
    "jobTypes": ["full_time"],
    "companySize": [],
    "suggestedJobTitles": ["Senior Data Analyst", "Analytics Engineer"],
    "suggestedLocations": ["Austin, TX", "Remote"],
    "usage": { "tokens": 530 }
  },
  "meta": { "requestId": "...", "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" }
}
```

The fields fall into three groups:

| Group | Fields | What to do with them |
| --- | --- | --- |
| Read from the resume | `fullName`, `email`, `phone`, `city`, `linkedinUrl`, `currentJobTitle`, `workExperience`, `education`, `skills` and the other contact fields | Use them. A fact the resume does not print is `null` or an empty list. |
| Inferred from the whole resume | `experienceLevel`, `educationLevel`, `yearsOfExperience`, `industries`, `jobTypes`, `companySize`, `suggestedJobTitles`, `suggestedLocations` | Show them as suggestions the person can change. |
| Evidence | `fieldEvidence` | Check a contact fact before you fill a form with it. See step 4. |

Dates stay as the resume prints them, such as `Mar 2021`.
The [API reference](/docs/reference/parse) lists every field, including the ones this example leaves out.

## 4. Fill a form only with what the resume says [#4-fill-a-form-only-with-what-the-resume-says]

Each `fieldEvidence` entry names a field, quotes the resume text that holds its value, and rates it.
`high` and `medium` mean the value is printed in the resume. `low` means it was inferred.

Prefill a contact field only when the resume prints it:

```ts title="printed-fields.ts"
type Evidence = { field: string; quote: string | null; confidence: 'high' | 'medium' | 'low' };

export function printedFields(evidence: Evidence[]) {
  return new Set(
    evidence
      .filter(item => item.confidence !== 'low' && item.quote !== null)
      .map(item => item.field),
  );
}

const printed = printedFields(data.fieldEvidence ?? []);
const prefill = {
  email: printed.has('email') ? data.email : null,
  phone: printed.has('phone') ? data.phone : null,
  city: printed.has('city') ? data.city : null,
  linkedinUrl: printed.has('linkedinUrl') ? data.linkedinUrl : null,
};
```

Show the quote next to the field in your form.
The person sees where each value came from and fixes it in one tap.

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

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

## Next [#next]

- [Score a resume against a job post](/docs/guides/score-resume-against-job) with the same text.
- Read [Errors](/docs/errors) so your code handles `401`, `402`, `422` and `429`.