# Application states (/docs/application-states) Every state an application started by API can be in, what each one means for you, and which webhook event fires. `POST /developer/apply`, `GET /developer/applications/{id}` and `GET /developer/applications` answer with a `status`. It is one of six states. Reads are free and work with any key. ## The states [#the-states] | `status` | What it means | What to do | | --- | --- | --- | | `in_progress` | GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. | Wait. Poll every few minutes, or listen for a webhook. | | `held_for_review` | It is ready and waits for the account owner to approve it. | The owner approves it in GetMattered. A key with the [`apply` scope](/docs/key-scopes) can approve or cancel it by API. | | `needs_you` | It waits on the account owner for something else, such as a detail only they can give. | Ask the owner to open `trackingUrl` in GetMattered. | | `landed` | The employer confirmed it. `landedEvidence` says how. | Nothing. The application is done. | | `held` | It stopped, and a mail may be the employer's answer, so GetMattered will not send it again. | Do not retry. Calling apply again does not send it. | | `not_landed` | It stopped without the employer confirming it. | Call `POST /developer/apply` for the same posting to send it again. | ## Landed needs the employer's proof [#landed-needs-the-employers-proof] An application reads `landed` only on proof from the employer. `landedEvidence` lists it: | Evidence | What it is | | --- | --- | | `receipt` | The employer's confirmation email. | | `screenshot` | The employer's confirmation page, captured after the send. | A click, a sent form or our own status never counts as landed. The proof can come well after the send, so an application can stay `in_progress` for a while. Once the proof arrives, the application reads `landed`, whatever state it was in before. ## Stopped applications [#stopped-applications] `held` and `not_landed` both mean GetMattered stopped. They differ in what a retry does: - `not_landed`: `POST /developer/apply` for the same posting starts it again. - `held`: GetMattered will not send it again. A mail arrived that may be the employer's answer. An application the owner cancelled reads `not_landed`, and apply does not send it again. ## Webhook events [#webhook-events] A webhook endpoint gets one event each time an application enters one of four states: | `status` | Event | | --- | --- | | `in_progress` | none | | `held_for_review` | `application.held_for_review` | | `needs_you` | `application.needs_you` | | `landed` | `application.landed` | | `held` | none | | `not_landed` | `application.not_landed` | Events usually arrive within two minutes. `in_progress` and `held` send no event, so read them with `GET /developer/applications/{id}`. An application can enter the same state twice, for example `needs_you` again after the owner answered once. Each entry sends a new event. See [Receive webhooks](/docs/guides/receive-webhooks). ## Filter by state [#filter-by-state] `GET /developer/applications` takes a `status` query with one of these states. It answers only the applications in that state, newest first. See [List applications](/docs/reference/applications). # Authentication (/docs/authentication) Create a key in the dashboard and send it as a Bearer token. Every request sends your key in the `Authorization` header: ```http Authorization: Bearer gm_live_... ``` This header is the only place the API reads the key. A key in a query string or a cookie does not authenticate. ## Create a key [#create-a-key] 1. Sign in to GetMattered. 2. Open [Developers](https://getmattered.com/dashboard/developers) in the dashboard. 3. Choose **Create key** and give it a name, like `Production`. 4. Copy the key. We show it once. We store only a hash of the key, so we cannot show it to you again. We email you each time a key is created on your account. Create and manage your keys at https://getmattered.com/dashboard/developers. ## Keys [#keys] - A key starts with `gm_live_`. - A key acts as you. Its calls spend your API tokens, and its applications go out from your account. - A key sends applications only if you ticked **Can send applications** when you made it. See [Key scopes](/docs/key-scopes). - An account can have up to 5 active keys. Revoke one to create another. - Each key has its own per-minute rate limit. See [Rate limits](/docs/rate-limits). - The dashboard and your usage report list each key by its name and its first characters, like `gm_live_AbCd`. Keep keys on your server. Never put a key in browser code, a mobile app or a public repository. ## Revoke a key [#revoke-a-key] Open [Developers](https://getmattered.com/dashboard/developers) and choose **Revoke** next to the key. The key stops working at once, on its next call. A revoked key never comes back. Create a new one to replace it. ## Enterprise volume [#enterprise-volume] Need more than self-serve, such as high volume, applications for your own candidates or custom terms? Send the enterprise form in the same [Developers](https://getmattered.com/dashboard/developers) section. We reply by email. ## When authentication fails [#when-authentication-fails] A missing, malformed, unknown or revoked key gets `401` with the code `UNAUTHORIZED`: ```json { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing API key. Send it as `Authorization: Bearer gm_live_...`.", "context": { "errorType": "authentication", "failureReason": "missing_token" } }, "meta": { "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" } } ``` A refused call runs no work and spends no tokens. # Data and privacy (/docs/data-and-privacy) Who the API is for, and how calls with personal data run. ## Use it for job seekers [#use-it-for-job-seekers] The API is for products that help job seekers: resume builders, career tools, coaching and career services. Use it on resumes that their owners give you, to help those people apply. Do not use it to screen, rank, score or reject candidates for an employer or a recruiter. That includes applicant tracking systems and hiring tools. ## Personal data [#personal-data] Our AI providers, through OpenRouter, process every call. We send every request with OpenRouter's data policy setting that allows only providers that do not collect user data. Some of these providers keep requests for abuse monitoring, under their own terms. We do not sell the data you send, and we do not use it to train AI. ## Applications [#applications] `POST /developer/apply` sends an application from your own account, with the resume and answers you keep in GetMattered. The application, the employer's confirmation and its status stay in your account, the same as an application sent from the app. You see each one at its `trackingUrl`. ## Questions [#questions] Email [support@getmattered.com](mailto:support@getmattered.com) with any question about data. # Errors (/docs/errors) The error envelope, the HTTP status codes and the error codes. Every response is JSON with a `success` field. A successful call has `"success": true` and its result in `data`. A failed call has `"success": false` and an `error` object: ```json { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing API key. Send it as `Authorization: Bearer gm_live_...`.", "context": { "errorType": "authentication", "failureReason": "missing_token" } }, "meta": { "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" } } ``` | Field | Always present | What it holds | | --- | --- | --- | | `error.code` | Yes | A stable code. Branch on this. | | `error.message` | Yes | A sentence for people. It can change, so do not parse it. | | `error.context` | No | The kind of error in `errorType`, with fields for that kind. | | `error.details` | No | Extra data. For a `429`, the limit and `resetTime`. | | `error.validation` | No | For a `422`, one entry per invalid field. | | `meta.requestId` | No | Our ID for the request. Send it to us when you report a problem. | ## Codes [#codes] | HTTP status | `error.code` | Meaning | What to do | | --- | --- | --- | --- | | `400` | `BAD_REQUEST` | Apply only. The account has no resume, or the posting was flagged as suspicious. | Read `error.message`. Nothing was sent. | | `401` | `UNAUTHORIZED` | The key is missing, malformed, unknown or revoked. | Check the `Authorization` header. See [Authentication](/docs/authentication). | | `402` | none: `"error": "limit_reached"` | The account that owns the key has no API tokens left. | Buy an API token pack, then retry. The call spent nothing. | | `403` | `FORBIDDEN` | Apply, approve and cancel only. The key was made without "Can send applications". | Create a key with it ticked. Nothing was sent. See [Key scopes](/docs/key-scopes). | | `404` | `NOT_FOUND` | No application with that id on your account. | Use the id `POST /developer/apply` answered with. | | `422` | `VALIDATION_ERROR` | The request body or query does not match the schema. | Read `error.validation` and fix the fields it names. | | `422` | none: `"outcome": "not_applied"` | Apply only. GetMattered cannot apply to this posting. `reason` says why. | See [Apply to a job by API](/docs/guides/apply-to-a-job). Nothing was sent or spent. | | `429` | `RATE_LIMIT_EXCEEDED` | The key made more than 60 requests in a minute. | Retry after `error.details.resetTime`. | | `429` | `APPLIES_IN_FLIGHT_LIMIT` | Apply only. 5 applications started by API are already in progress. | Call again once one is sent or held for review. | | `503` | `SERVICE_UNAVAILABLE` | Apply only. The posting is still being read. | Retry after the `Retry-After` header. | | `5xx` | varies | The call failed on our side. | Retry with backoff. The call spent the work it used and the request fee. | ## Out of tokens [#out-of-tokens] The account that owns the key pays for every call in API tokens, from its API balance. The API balance is separate from the GetMattered app plans. When it has no API tokens left, the call runs no work and gets `402` with the `limit_reached` body: ```json { "success": false, "error": "limit_reached", "limit": { "action": "ai_tokens", "current": 0, "max": 560, "period": "balance", "planTier": null }, "message": "This account is out of API tokens. Buy API tokens at https://getmattered.com/dashboard/developers#api-balance, then call again." } ``` `limit.current` is what the account could spend. `limit.max` is what the call needed to start. Do not retry until the account has API tokens again. `GET /developer/balance` tells you when it does. See [Pricing](/docs/pricing). ## Key cannot apply [#key-cannot-apply] A key made without "Can send applications" gets `403` with `error.code` `FORBIDDEN` from `POST /developer/apply`, approve and cancel. Nothing was sent. A key's powers are fixed when it is made, so create a new key with the box ticked. See [Key scopes](/docs/key-scopes). ## Validation errors [#validation-errors] A field that fails validation gets `422` and one entry per field in `error.validation`: ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "validation": [ { "code": "too_small", "field": "resumeText", "message": "Too small: expected string to have >=50 characters" } ] }, "meta": { "timestamp": "2026-11-17T12:00:00.000Z" } } ``` Request bodies are strict. The API also rejects a field the schema does not list. # Apply to a job by API (/docs/guides/apply-to-a-job) Send a job link. GetMattered fills the employer's form from your account, sends it, and tells you when the employer confirmed it landed. `POST /developer/apply` applies to one job posting from the account that owns the key. It uses that account's resume, profile and answers, the same way GetMattered applies from the app. `GET /developer/applications/{id}` tells you where the application stands. It reads `landed` only when the employer confirmed it. ## Before you start [#before-you-start] - Create a key with **Can send applications** ticked, in the dashboard at [getmattered.com/dashboard/developers](https://getmattered.com/dashboard/developers). See [Key scopes](/docs/key-scopes). - Upload a resume to the account in GetMattered. Without one, the call answers `400` and sends nothing. - Use a posting on a hiring system GetMattered supports. Any other posting answers `422` with a reason, and nothing is sent. The API applies for the account that owns the key, and for no one else. To apply for your own candidates or at high volume, send the enterprise form in the same dashboard section. ## 1. Start the application [#1-start-the-application] Send the posting URL. It can be the employer's own posting or a job-board link to it. ```bash title="curl" curl https://api.getmattered.com/api/v1/developer/apply \ -H "Authorization: Bearer $GETMATTERED_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "postingUrl": "https://job-boards.greenhouse.io/acme/jobs/4012345", "mode": "review" }' ``` `mode` decides who presses send: | `mode` | What happens | | --- | --- | | `auto` | GetMattered sends the application once it is ready. | | `review` | GetMattered prepares it and holds it. The account owner approves it in GetMattered. | | left out | The account's own setting decides. `auto` never overrides an account set to review. | The call answers at once with `202`. The application keeps going after the answer: ```json title="POST /developer/apply 202 response" { "success": true, "data": { "id": 2481, "status": "in_progress", "trackingUrl": "https://getmattered.com/dashboard/applications/2481" }, "meta": { "requestId": "...", "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" } } ``` The same posting twice answers with the same application. A retry never sends a second one. `trackingUrl` opens the application in GetMattered, behind the account owner's sign-in. ## 2. Read where it stands [#2-read-where-it-stands] `GET /developer/applications/{id}` answers with one of six states. [Application states](/docs/application-states) says what each one means and which webhook event it sends. | `status` | What it means | | --- | --- | | `in_progress` | GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. | | `held_for_review` | It is ready and waits for the account owner to approve it in GetMattered. | | `needs_you` | It waits on the account owner for something else, such as a detail only they can give. | | `landed` | The employer confirmed it. `landedEvidence` says how. | | `held` | It stopped, and a mail may be the employer's answer, so GetMattered will not send it again. Do not retry. | | `not_landed` | It stopped without the employer confirming it. | An application lands only on the employer's own proof. `landedEvidence` lists it: `receipt` is the employer's confirmation email, and `screenshot` is the employer's confirmation page. A click, a sent form or our own status never counts as landed. The proof comes from the employer, so it can come well after the send. Poll every few minutes, not every second. Reads are free. ```ts title="TypeScript (fetch)" const headers = { 'Authorization': `Bearer ${process.env.GETMATTERED_API_KEY}`, 'Content-Type': 'application/json', }; const started = await fetch('https://api.getmattered.com/api/v1/developer/apply', { method: 'POST', headers, body: JSON.stringify({ postingUrl: 'https://job-boards.greenhouse.io/acme/jobs/4012345', mode: 'review' }), }); const startBody = await started.json(); if (started.status !== 202) { throw new Error(`Not started (${started.status}): ${JSON.stringify(startBody)}`); } const id = startBody.data.id; console.log(`Started ${id}: ${startBody.data.trackingUrl}`); const FIVE_MINUTES = 5 * 60 * 1000; let status = startBody.data.status; while (status === 'in_progress') { await new Promise(resolve => setTimeout(resolve, FIVE_MINUTES)); const read = await fetch(`https://api.getmattered.com/api/v1/developer/applications/${id}`, { headers }); const readBody = await read.json(); status = readBody.data.status; if (status === 'landed') { console.log(`${readBody.data.jobTitle} at ${readBody.data.company} landed`, readBody.data.landedEvidence); } } console.log(`Application ${id} is ${status}`); ``` Stop polling on `held_for_review` or `needs_you` until the account owner acts in GetMattered. ## 3. When nothing is sent [#3-when-nothing-is-sent] A posting GetMattered cannot apply to answers `422` with `"outcome": "not_applied"`. Nothing was sent and nothing was spent. ```json title="POST /developer/apply 422 response" { "success": false, "outcome": "not_applied", "reason": "unsupported_host" } ``` | `reason` | What it means | | --- | --- | | `unsupported_host` | GetMattered does not apply on that hiring system. | | `posting_not_found` | The employer has no open posting at that link. | | `import_failed` | The posting could not be read. | | `already_applied` | This job already has an application. | | `no_employer_posting` | The job-board posting was read, and no employer posting GetMattered applies on was found. | | `account_only_board` | The employer takes this job only behind a job board's own account. | A `422` with `error.code` `VALIDATION_ERROR` is a different case: the request body does not match the schema. Check `outcome` first. Other answers that send nothing: | Status | Body | What to do | | --- | --- | --- | | `400` | `error.code` `BAD_REQUEST` | Read `error.message`. The account has no resume, or the posting was flagged as suspicious. | | `402` | `"error": "limit_reached"`, `limit.action` `ai_tokens` | The account is out of API tokens. Buy a pack, then call again. See [Pricing](/docs/pricing). | | `403` | `error.code` `FORBIDDEN` | The key was made without "Can send applications". Create a key with it ticked. See [Key scopes](/docs/key-scopes). | | `429` | `error.code` `APPLIES_IN_FLIGHT_LIMIT` | 5 applications started by API are already in progress. Call again once one is sent or held for review. | | `429` | `error.code` `RATE_LIMIT_EXCEEDED` | The key made more than 60 calls this minute. See [Rate limits](/docs/rate-limits). | | `503` | `error.code` `SERVICE_UNAVAILABLE` | The posting is still being read. Call again after the `Retry-After` header. | ## Tokens [#tokens] Applying spends API tokens from your API balance, plus the request fee. It never spends your GetMattered app plan, and it does not use the app's free applications. A call needs at least the request fee in the API balance to start. An application that is already running always finishes, even when it takes the balance below zero. The next call is then refused until you top up. See [Pricing](/docs/pricing). ## Next [#next] - [Score a resume against a job post](/docs/guides/score-resume-against-job) before you apply. - [Application states](/docs/application-states) lists every state and its webhook event. - Every field of both calls is in the reference: [Apply to a job posting](/docs/reference/apply) and [Read an application](/docs/reference/applications-id). # 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`. # Receive webhooks (/docs/guides/receive-webhooks) Get a signed event when an application lands, stops, needs the account owner or waits for approval, and check the signature before you trust it. A webhook endpoint is a URL on your server. When an application changes state, GetMattered sends it a signed `POST` with the new state. You do not have to poll `GET /developer/applications/{id}`. ## Before you start [#before-you-start] - Create a key in the dashboard at [getmattered.com/dashboard/developers](https://getmattered.com/dashboard/developers). See [Authentication](/docs/authentication). - Your endpoint must be a public `https` URL. GetMattered does not follow redirects. - An account can have up to 5 endpoints. Webhook calls are free: they spend no tokens. You can also add, test and delete endpoints in the dashboard, on the **Webhooks** tab of the Developers page. ## 1. Add an endpoint [#1-add-an-endpoint] ```bash title="curl" curl https://api.getmattered.com/api/v1/developer/webhooks \ -H "Authorization: Bearer $GETMATTERED_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/hooks/getmattered" }' ``` ```json title="POST /developer/webhooks request" { "url": "https://example.com/hooks/getmattered" } ``` The answer holds the signing secret. This is the only time you see it: store it now, next to your API key. Later lists show only its first characters, in `secretPrefix`. ```json title="POST /developer/webhooks 201 response" { "success": true, "data": { "id": 7, "url": "https://example.com/hooks/getmattered", "secret": "whsec_3q2-7wAbCdEfGhIjKlMnOpQrStUvWxYz0123456789", "secretPrefix": "whsec_3q2-7w", "createdAt": "2026-11-19 17:00:00" }, "meta": { "requestId": "...", "timestamp": "2026-11-19T17:00:00.000Z", "version": "v1" } } ``` ## 2. Send a test event [#2-send-a-test-event] `POST /developer/webhooks/{id}/test` queues one `webhook.test` event to the endpoint. It goes out within a minute, signed like every real event. ```ts title="TypeScript (fetch)" const headers = { 'Authorization': `Bearer ${process.env.GETMATTERED_API_KEY}`, 'Content-Type': 'application/json', }; const created = await fetch('https://api.getmattered.com/api/v1/developer/webhooks', { method: 'POST', headers, body: JSON.stringify({ url: 'https://example.com/hooks/getmattered' }), }); const { data: endpoint } = await created.json(); // Store endpoint.secret now: no later answer shows it. const endpointId = endpoint.id; const test = await fetch(`https://api.getmattered.com/api/v1/developer/webhooks/${endpointId}/test`, { method: 'POST', headers, }); const { data } = await test.json(); console.log(data.eventId, data.queued); ``` `GET /developer/webhooks/{id}/deliveries` shows the newest deliveries to the endpoint: the event, its status, the attempts so far and the last HTTP status your endpoint answered. ## 3. What a delivery looks like [#3-what-a-delivery-looks-like] Every delivery is a `POST` with a JSON body and three headers: | Header | What it holds | | --- | --- | | `GetMattered-Signature` | `t=,v1=.">`, under the endpoint secret. | | `GetMattered-Event-Id` | The event id, the same as `id` in the body. | | `GetMattered-Event-Type` | The event type, the same as `type` in the body. | ```json title="Event body" { "id": "evt_3f9c2a7d6b8e4f0a9c1d2e3f4a5b6c7d", "type": "application.landed", "createdAt": "2026-11-19T17:01:00.000Z", "data": { "application": { "id": 2481, "status": "landed", "company": "Acme", "jobTitle": "Senior Frontend Engineer", "postingUrl": "https://job-boards.greenhouse.io/acme/jobs/4012345", "landedEvidence": ["receipt"], "trackingUrl": "https://getmattered.com/dashboard/applications/2481" } } } ``` | `type` | When it is sent | | --- | --- | | `application.landed` | The employer confirmed the application. | | `application.not_landed` | The application stopped without the employer confirming it. | | `application.needs_you` | The application waits on the account owner. | | `application.held_for_review` | The application is ready and waits for approval. | | `webhook.test` | You sent a test event. `data.application` is `null`. | ## 4. Verify the signature [#4-verify-the-signature] Check every delivery before you act on it: 1. Read the raw request body, before any JSON parsing. The signature covers the exact bytes. 2. Split the header into `t` and `v1`. 3. Compute the HMAC-SHA256 of `.` with the endpoint secret, as lowercase hex. 4. Compare it with `v1` in constant time. 5. Refuse a `t` more than five minutes old, so an old delivery cannot be replayed. ```js title="JavaScript (Node.js)" import { createHmac, timingSafeEqual } from 'node:crypto'; const TOLERANCE_SECONDS = 300; export function verifyGetMatteredSignature(rawBody, header, secret) { const parts = Object.fromEntries(header.split(',').map(part => part.split('=', 2))); const timestamp = Number(parts.t); if (!Number.isInteger(timestamp) || typeof parts.v1 !== 'string') { return false; } if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) { return false; } const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex'); const given = Buffer.from(parts.v1, 'utf8'); const wanted = Buffer.from(expected, 'utf8'); return given.length === wanted.length && timingSafeEqual(given, wanted); } // Express: keep the raw body for this route. // app.post('/hooks/getmattered', express.raw({ type: 'application/json' }), (req, res) => { // const ok = verifyGetMatteredSignature(req.body.toString('utf8'), req.get('GetMattered-Signature') ?? '', process.env.GETMATTERED_WEBHOOK_SECRET); // if (!ok) return res.sendStatus(400); // const event = JSON.parse(req.body.toString('utf8')); // res.sendStatus(200); // }); ``` ```python title="Python" import hashlib import hmac import time TOLERANCE_SECONDS = 300 def verify_getmattered_signature(raw_body: bytes, header: str, secret: str) -> bool: parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part) try: timestamp = int(parts["t"]) given = parts["v1"] except (KeyError, ValueError): return False if abs(time.time() - timestamp) > TOLERANCE_SECONDS: return False signed = f"{timestamp}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return hmac.compare_digest(given, expected) # Flask: # @app.post("/hooks/getmattered") # def getmattered_hook(): # if not verify_getmattered_signature(request.get_data(), request.headers.get("GetMattered-Signature", ""), os.environ["GETMATTERED_WEBHOOK_SECRET"]): # abort(400) # event = request.get_json() # return "", 200 ``` ## 5. Answer fast, and expect retries [#5-answer-fast-and-expect-retries] - Answer with any `2xx` within 10 seconds. Do the slow work after you answer. - Any other answer, or no answer, is retried: after 1 minute, 5 minutes, 30 minutes, then 2, 5, 10 and 24 hours. After the last try the delivery is marked failed. - A retry carries the same event id. Store the ids you handled and skip a repeat. - Events can arrive out of order. When the order matters, read the application with `GET /developer/applications/{id}`. See [Apply to a job by API](/docs/guides/apply-to-a-job) for what each application state means. # 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. # GetMattered API (/docs) Apply to jobs by API and know when the employer confirmed each one. Then score, parse and tailor resumes and write cover letters. The GetMattered API gives your code the engine that lands GetMattered users their interviews. Send a job link, and GetMattered fills the employer's form from your account, sends it and tells you when the employer confirmed it. The resume calls score, parse and tailor a resume, and write the cover letter, for any posting. ## Make your first call [#make-your-first-call] 1. [Create a key](https://getmattered.com/dashboard/developers) in the dashboard. It starts with `gm_live_`, and your first key brings 100,000 free API tokens. 2. Keep it on your server: `export GETMATTERED_API_KEY="gm_live_..."`. 3. Send one request. This one scores a resume against a job posting. ```bash tab="curl" curl https://api.getmattered.com/api/v1/developer/ats-score \ -H "Authorization: Bearer $GETMATTERED_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "resumeText": "Jane Doe. Senior Software Engineer. 6 years building React and TypeScript apps at Acme.", "jobDescription": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience." }' ``` ```js tab="JavaScript" // npm i getmattered import { GetMattered } from 'getmattered'; const client = new GetMattered({ apiKey: process.env.GETMATTERED_API_KEY }); const data = await client.tools.atsScore({ resumeText: 'Jane Doe. Senior Software Engineer. 6 years building React and TypeScript apps at Acme.', jobDescription: 'We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience.', }); console.log(data.overallScore, data.missingKeywords); ``` ```python tab="Python" import os import requests response = requests.post( "https://api.getmattered.com/api/v1/developer/ats-score", headers={"Authorization": f"Bearer {os.environ['GETMATTERED_API_KEY']}"}, json={ "resumeText": "Jane Doe. Senior Software Engineer. 6 years building React and TypeScript apps at Acme.", "jobDescription": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience.", }, ) data = response.json()["data"] print(data["overallScore"], data["missingKeywords"]) ``` The JavaScript tab uses the official SDK: install it with `npm i getmattered`, and see [SDKs](/docs/sdks). The answer comes back as JSON, with the result in `data` and the tokens the call spent in `data.usage.tokens`. Every request and response body is JSON, and the base URL is `https://api.getmattered.com/api/v1`. The [Quickstart](/docs/quickstart) goes on to send your first application. ## Browse by resource [#browse-by-resource] ### Candidate Read and update the job seeker: profile, resume and what they are looking for. - [`GET /developer/profile`](/docs/reference/profile-get): Read the candidate profile - [`PATCH /developer/profile`](/docs/reference/profile): Update the candidate profile - [`GET /developer/resume`](/docs/reference/resume-get): Read the resume - [`POST /developer/resume`](/docs/reference/resume): Upload a resume - [`GET /developer/preferences`](/docs/reference/preferences-get): Read job preferences - [`PUT /developer/preferences`](/docs/reference/preferences): Save job preferences ### Jobs Search jobs and read the matches GetMattered found for the candidate. - [`GET /developer/jobs/{id}`](/docs/reference/jobs-id): Read a job - [`GET /developer/jobs/matches`](/docs/reference/jobs/matches): List the candidate's matches - [`GET /developer/jobs/search`](/docs/reference/jobs/search): Search jobs ### Applications Apply to a job by link, then read when the employer confirmed it. Guide: [Apply to a job by API](/docs/guides/apply-to-a-job). - [`POST /developer/apply`](/docs/reference/apply): Apply to a job posting - [`GET /developer/applications`](/docs/reference/applications): List applications - [`GET /developer/applications/{id}`](/docs/reference/applications-id): Read an application - [`POST /developer/applications/{id}/approve`](/docs/reference/applications-id/approve): Approve a held application - [`POST /developer/applications/{id}/cancel`](/docs/reference/applications-id/cancel): Cancel an application ### Resume tools Score, parse and tailor a resume, analyze a posting and write a cover letter. Guide: [Score a resume against a job post](/docs/guides/score-resume-against-job). - [`POST /developer/ats-score`](/docs/reference/ats-score): Score a resume for ATS compatibility - [`POST /developer/parse`](/docs/reference/parse): Parse a resume into structured fields - [`POST /developer/analyze-job`](/docs/reference/analyze-job): Analyze a job posting - [`POST /developer/tailor`](/docs/reference/tailor): Tailor a resume to a job posting - [`POST /developer/cv-pack`](/docs/reference/cv-pack): Parse, score and tailor a resume in one call - [`POST /developer/cover-letter`](/docs/reference/cover-letter): Write a cover letter ### Webhooks Get a signed event when an application changes, instead of polling. Guide: [Receive webhooks](/docs/guides/receive-webhooks). - [`GET /developer/webhooks`](/docs/reference/webhooks-get): List webhook endpoints - [`POST /developer/webhooks`](/docs/reference/webhooks): Add a webhook endpoint - [`DELETE /developer/webhooks/{id}`](/docs/reference/webhooks-id): Delete a webhook endpoint - [`GET /developer/webhooks/{id}/deliveries`](/docs/reference/webhooks-id/deliveries): Read webhook deliveries - [`POST /developer/webhooks/{id}/test`](/docs/reference/webhooks-id/test): Send a test event ### Billing Read your API balance and what each month of calls spent. Guide: [Pricing](/docs/pricing). - [`GET /developer/balance`](/docs/reference/balance): Read your API balance - [`GET /developer/usage`](/docs/reference/usage): Read your monthly usage The [API reference](/docs/reference/apply) lists every endpoint with its full request and response schema, code in curl, JavaScript and Python, and a playground that sends a real request with your key. The OpenAPI 3.1 document is at [`/docs/openapi.json`](/docs/openapi.json). ## Before you go live [#before-you-go-live] 1. [Authentication](/docs/authentication): how to send the key, and how to revoke it. 2. [Pricing](/docs/pricing): API calls spend prepaid API tokens, apart from the app plans. 3. [Rate limits](/docs/rate-limits): how many calls a key can make. 4. [Errors](/docs/errors): the error format and the codes. 5. [Data and privacy](/docs/data-and-privacy): what we keep from each call. ## Guides [#guides] - [Apply to a job by API](/docs/guides/apply-to-a-job): send a job link, then read when the employer confirmed it. - [Parse a resume to JSON](/docs/guides/parse-resume-to-json): contact details, work history, education and skills, with the resume line behind each contact fact. - [Score a resume against a job post](/docs/guides/score-resume-against-job): the match, the missing keywords and the fixes, then a tailored resume in one more call. - [Receive webhooks](/docs/guides/receive-webhooks): get a signed event when an application changes, and verify it in JavaScript or Python. ## Run your job search from an AI assistant [#run-your-job-search-from-an-ai-assistant] The GetMattered MCP server runs the same apply engine from the AI assistant you already use. You ask for jobs in plain words, and it applies for you. Set it up at [getmattered.com/mcps](https://getmattered.com/mcps). ## For AI agents [#for-ai-agents] - [`/docs/llms.txt`](/docs/llms.txt) lists every page with a link to its Markdown. - [`/docs/llms-full.txt`](/docs/llms-full.txt) holds every page in one file. - Add `.md` to any page URL to get that page as Markdown, for example [`/docs/quickstart.md`](/docs/quickstart.md). - An MCP server for these docs runs at `https://getmattered.com/docs/mcp` (Streamable HTTP). Its tools list, read and search the pages. These docs are in English. # Key scopes (/docs/key-scopes) What a key may do, which calls need the apply scope, and how to pick scopes when you create a key. A key's scopes say what it may do in your name. Every key can score, parse and tailor resumes, write cover letters and read your data. One scope, `apply`, adds the power to send real applications. ## The apply scope [#the-apply-scope] In the dashboard, the `apply` scope reads **Can send applications**. These calls need it: | Call | What it does | | --- | --- | | `POST /developer/apply` | Applies to one job posting from your account. See [Apply to a job by API](/docs/guides/apply-to-a-job). | | `POST /developer/applications/{id}/approve` | Approves an application in `held_for_review` and sends it. | | `POST /developer/applications/{id}/cancel` | Cancels an application before GetMattered starts sending it. | A key without the scope gets `403` with `error.code` `FORBIDDEN` from these calls. Nothing is sent and nothing changes. See [Errors](/docs/errors). ## Calls any key can make [#calls-any-key-can-make] Every other call works with any active key. That covers: - Reads: your applications, jobs, profile, resume, preferences, balance and usage. - Resume tools: score, parse, analyze a posting, tailor, cover letter and CV pack. - Your profile, preferences and resume uploads. - Webhook endpoints: add, list, test, read deliveries and delete. Any key can read every application on your account, including one another key started. The states it can be in are on [Application states](/docs/application-states). ## Pick scopes when you create a key [#pick-scopes-when-you-create-a-key] 1. Open [Developers](https://getmattered.com/dashboard/developers) in the dashboard. 2. Choose **Create key** and give it a name. 3. Tick **Can send applications** only if this key will apply to jobs. Leave it off for scoring, tailoring and parsing. 4. Create the key and copy it. We show it once. The key list shows each key's powers: **Can send applications**, or **Scores, parses and tailors**. You choose scopes when you create the key, and you cannot change them later. To add or remove the scope, create a new key and revoke the old one. See [Authentication](/docs/authentication). Give the scope only to the server that applies. A key that only scores or tailors resumes then cannot send an application, even if it leaks. # Pricing (/docs/pricing) API calls spend prepaid API tokens, apart from the GetMattered app plans. Every call spends API tokens from the account that owns the key. API tokens are a balance of their own, the API balance. They are separate from the GetMattered app plans: a call never spends plan tokens, and the app never spends API tokens. You do not need a subscription to use the API. ## Free trial [#free-trial] Your account gets 100,000 free API tokens once, when it creates its first key. ## API token packs [#api-token-packs] After the trial, buy a pack on the [Developers](https://getmattered.com/dashboard/developers#api-balance) page in the dashboard. A pack is a one-time payment, in US dollars, before tax. API tokens never expire, and they cannot move to the app. The two largest packs are sized for a team that runs its own product on the API. For more volume or custom terms, send an enterprise request from the Developers page. ## What a call spends [#what-a-call-spends] A call spends what its work costs, plus a flat request fee of 160 tokens. The table shows what each resume call usually spends, and the high end: | Operation | Spent by | Typical tokens | High tokens | | --- | --- | --- | --- | | `ats_score` | POST /developer/ats-score | 390 | 450 | | `parse` | POST /developer/parse | 530 | 680 | | `analyze_job` | POST /developer/analyze-job | 290 | 410 | | `light_cv_pack` | POST /developer/tailor or /developer/cv-pack, tier light | 1,530 | 1,930 | | `pro_cv_pack` | POST /developer/tailor or /developer/cv-pack, tier pro | 5,980 | 7,240 | | `cover_letter` | POST /developer/cover-letter | 3,640 | 4,170 | `POST /developer/apply` spends the tokens the application uses, plus the request fee. See [Apply to a job by API](/docs/guides/apply-to-a-job). - A resume call that answers `200` spends its work and the request fee. - Every resume call answer has `data.usage.tokens`: the tokens that call spent. - A call that fails on our side after its work started spends the work it used and the request fee. - A call refused before any work (`401`, `422`, `429`) spends nothing. - `GET /developer/usage`, `GET /developer/balance` and `GET /developer/applications/{id}` are free. - `POST /developer/tailor` and `POST /developer/cv-pack` take a `tier`. The default is `light`. `pro` gives a deeper rewrite and spends more. ## Read your balance [#read-your-balance] `GET /developer/balance` returns the API tokens your account can spend now. ```bash curl https://api.getmattered.com/api/v1/developer/balance \ -H "Authorization: Bearer $GETMATTERED_API_KEY" ``` ```json { "success": true, "data": { "balance": 1250000, "currency": "tokens" }, "meta": { "requestId": "...", "timestamp": "2026-11-19T12:00:00.000Z", "version": "v1" } } ``` The balance can be below zero. An application that is already running always finishes, even when it spends past the end of the balance. The next call is refused until you top up. ## At zero tokens [#at-zero-tokens] An account with no API tokens left gets `402` with the `limit_reached` body. The call runs no work and spends nothing: ```json { "success": false, "error": "limit_reached", "limit": { "action": "ai_tokens", "current": 0, "max": 560, "period": "balance", "planTier": null }, "message": "This account is out of API tokens. Buy API tokens at https://getmattered.com/dashboard/developers#api-balance, then call again." } ``` `limit.current` is what the account could spend. `limit.max` is what the call needed to start. `limit.planTier` is always `null`: an app plan never pays for an API call. Buy a pack on the [Developers](https://getmattered.com/dashboard/developers#api-balance) page, then call again. See [Errors](/docs/errors). ## Usage [#usage] The [Developers](https://getmattered.com/dashboard/developers) page in the dashboard shows your API balance and the tokens your keys spent each day. `GET /developer/usage?month=YYYY-MM` returns your calls and the tokens they spent, per key and per operation. Months run on UTC. ```bash curl "https://api.getmattered.com/api/v1/developer/usage?month=2026-11" \ -H "Authorization: Bearer $GETMATTERED_API_KEY" ``` Leave out `month` to get the current month. # Quickstart (/docs/quickstart) Create an API key, send your first application, and score a resume. ## 1. Create a key [#1-create-a-key] Sign in to GetMattered and open [Developers](https://getmattered.com/dashboard/developers) in the dashboard. Choose **Create key** and name it after where it runs, for example `Production`. The key starts with `gm_live_`. We show the key once and store only a hash of it, so copy it now. We also email you that the key was created. An account can have up to 5 active keys. Your first key brings 100,000 free API tokens. API calls spend API tokens, never your GetMattered app plan. `GET /developer/balance` shows how many are left. See [Pricing](/docs/pricing). Create and manage your keys at https://getmattered.com/dashboard/developers. Store the key in an environment variable on your server: ```bash export GETMATTERED_API_KEY="gm_live_..." ``` Call the API from your server only. A key in browser or mobile app code can be read by anyone who uses that app. ## 2. Apply to a job [#2-apply-to-a-job] `POST /developer/apply` applies to one posting from your account, with the resume and answers you keep in GetMattered. Upload a resume in GetMattered first. `"mode": "review"` holds the application so you approve it in GetMattered before it goes out. ```bash title="curl" curl https://api.getmattered.com/api/v1/developer/apply \ -H "Authorization: Bearer $GETMATTERED_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "postingUrl": "https://job-boards.greenhouse.io/acme/jobs/4012345", "mode": "review" }' ``` The call answers `202` at once, with the application's id and status: ```json { "success": true, "data": { "id": 2481, "status": "in_progress", "trackingUrl": "https://getmattered.com/dashboard/applications/2481" }, "meta": { "requestId": "...", "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" } } ``` Read where it stands with `GET /developer/applications/2481`. It reads `landed` only when the employer confirmed the application, by their own email or their confirmation page. [Apply to a job by API](/docs/guides/apply-to-a-job) walks through every state and refusal. ## 3. Score a resume [#3-score-a-resume] `POST /developer/ats-score` scores resume text against a job posting. Both texts must be 50 to 50,000 characters long. Leave out `jobDescription` to get a general ATS score. ```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": "Jane Doe\nSenior Software Engineer\n6 years building React and TypeScript apps at Acme. Led the move to Next.js.", "jobDescription": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience to own our design system." }' ``` ```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: 'Jane Doe\nSenior Software Engineer\n6 years building React and TypeScript apps at Acme. Led the move to Next.js.', jobDescription: 'We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience to own our design system.', }), }); const body = await response.json(); if (!body.success) { throw new Error(`${body.error.code}: ${body.error.message}`); } console.log(body.data.overallScore, body.data.missingKeywords, body.data.usage.tokens); ``` A successful call answers `200` with the result in `data`: ```json { "success": true, "data": { "overallScore": 72, "keywordMatches": ["React", "TypeScript"], "missingKeywords": ["GraphQL"], "sectionScores": { "skills": 70, "experience": 80, "education": 60, "formatting": 75, "keywords": 65 }, "suggestions": ["Add \"GraphQL\" to your skills section."], "usage": { "tokens": 390 } }, "meta": { "requestId": "...", "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" } } ``` The numbers above show the shape only. Your scores depend on the texts you send. `data.usage.tokens` says exactly how many tokens the call spent. See [Pricing](/docs/pricing). ## Next [#next] - Check your usage in the dashboard, or with `GET /developer/usage`. - Read [Errors](/docs/errors) before you go live, so your code handles `401`, `402`, `422` and `429`. - Browse every endpoint in the [API reference](/docs/reference/apply). # Rate limits (/docs/rate-limits) 60 calls a minute per key. Each key can make 60 requests a minute. Every authenticated request counts, `GET /developer/usage` included. A request over that gets `429` with the code `RATE_LIMIT_EXCEEDED`, runs no work and spends no tokens. If the API cannot check the limit, it refuses the call with the same code. There is no monthly call quota. Your API balance is the only cap. See [Pricing](/docs/pricing). ## Applications in progress [#applications-in-progress] An account can have 5 applications started by API in progress at once. A sixth `POST /developer/apply` gets `429` with the code `APPLIES_IN_FLIGHT_LIMIT` and sends nothing. Call again once one of them is sent or held for review. See [Apply to a job by API](/docs/guides/apply-to-a-job). ## Reading a 429 [#reading-a-429] The limit and the reset time are in `error.details`: ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit of 60 requests a minute reached for this API key.", "context": { "errorType": "rate_limit", "limit": 60, "resetTime": "2026-11-17T12:01:00.000Z" }, "details": { "detailType": "rate_limit", "limit": 60, "resetTime": "2026-11-17T12:01:00.000Z", "windowMs": 60000 } }, "meta": { "requestId": "...", "timestamp": "2026-11-17T12:00:00.000Z", "version": "v1" } } ``` Wait until `details.resetTime`, then retry. The response has no `Retry-After` header. Read `details.resetTime` instead. # SDKs (/docs/sdks) The official TypeScript SDK, getmattered on npm. Typed calls for every endpoint, typed errors, retries and the webhook signature check. The `getmattered` package is the official client for TypeScript and JavaScript. It is typed from the [API reference](/docs/reference/apply), so every request and answer has its type. It has no runtime dependencies, and it runs on Node.js 18 or later, Bun, Deno and Cloudflare Workers. ## Install [#install] ```bash tab="npm" npm i getmattered ``` ```bash tab="pnpm" pnpm add getmattered ``` ```bash tab="bun" bun add getmattered ``` Create a key in the dashboard at [getmattered.com/dashboard/developers](https://getmattered.com/dashboard/developers), and keep it on your server. See [Authentication](/docs/authentication). ## Score, apply and follow the application [#score-apply-and-follow-the-application] ```ts title="TypeScript" import { GetMattered } from 'getmattered'; const client = new GetMattered({ apiKey: process.env.GETMATTERED_API_KEY! }); const score = await client.tools.atsScore({ resumeText: 'Jane Doe. Senior Software Engineer. 6 years building React and TypeScript apps at Acme.', jobDescription: 'We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience.', }); console.log(score.overallScore, score.missingKeywords); const started = await client.applications.apply({ postingUrl: 'https://job-boards.greenhouse.io/acme/jobs/4012345', }); let application = await client.applications.get(started.id); while (application.status === 'in_progress') { await new Promise(resolve => setTimeout(resolve, 30_000)); application = await client.applications.get(started.id); } console.log(application.status, application.trackingUrl); ``` Every method returns the `data` of the answer. The client sends your key as `Authorization: Bearer gm_live_...` on every request. [Apply to a job by API](/docs/guides/apply-to-a-job) explains each application state. ## The methods [#the-methods] | Namespace | Methods | | --- | --- | | `candidate` | `getProfile`, `updateProfile`, `getPreferences`, `updatePreferences`, `getResume`, `uploadResume` | | `jobs` | `search`, `matches`, `get` | | `applications` | `apply`, `get`, `list`, `approve`, `cancel` | | `tools` | `atsScore`, `parse`, `analyzeJob`, `tailor`, `coverLetter`, `cvPack` | | `webhooks` | `create`, `list`, `delete`, `test`, `deliveries`, `verifySignature` | | `billing` | `balance`, `usage` | ## Verify a webhook [#verify-a-webhook] `verifySignature` checks the `GetMattered-Signature` header of a delivery in constant time, and refuses one more than five minutes old. Pass the raw request body, before any JSON parsing. ```ts title="TypeScript" import { verifySignature } from 'getmattered'; export async function POST(request: Request) { const rawBody = await request.text(); const valid = await verifySignature(rawBody, request.headers.get('GetMattered-Signature'), process.env.GETMATTERED_WEBHOOK_SECRET!); if (!valid) { return new Response('bad signature', { status: 400 }); } const event = JSON.parse(rawBody); console.log(event.type); return new Response('ok'); } ``` [Receive webhooks](/docs/guides/receive-webhooks) lists the events and the retry schedule. ## Errors and retries [#errors-and-retries] A failed call throws a `GetMatteredError` with `status`, `code`, `message` and `requestId`. When the API balance has no tokens for a call, it throws a `LimitReachedError`, and nothing was spent. Its `topUpUrl` is where the account buys more API tokens. ```ts title="TypeScript" import { LimitReachedError } from 'getmattered'; try { await client.tools.parse({ resumeText: 'Jane Doe. Senior Software Engineer.' }); } catch (error) { if (!(error instanceof LimitReachedError)) { throw error; } console.log(`Buy API tokens at ${error.topUpUrl}, then call again.`); } ``` The client tries a `GET` again after a `429` or a `5xx`, up to two times, and honors `Retry-After`. It never repeats a `POST`, `PUT`, `PATCH` or `DELETE`, because a repeat could start a second application or spend tokens twice. See [Errors](/docs/errors) and [Rate limits](/docs/rate-limits). ## Other languages [#other-languages] Every page of the [API reference](/docs/reference/apply) has code in curl, JavaScript and Python. The OpenAPI 3.1 document at [`/docs/openapi.json`](/docs/openapi.json) works with any OpenAPI client generator. # Analyze a job posting (/docs/reference/analyze-job) `POST https://api.getmattered.com/api/v1/developer/analyze-job` Extracts the keywords a recruiter screens for from a job posting, with category and importance. Spends the tokens it uses plus the request fee, recorded as `analyze_job`. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "jobDescription": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The job posting text, 50 to 50,000 characters.", "example": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience to own our design system..." } }, "required": [ "jobDescription" ], "additionalProperties": false } ``` ## Responses ### 200: The posting keywords. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string", "description": "Keyword or skill term", "example": "React" }, "category": { "type": "string", "enum": [ "technical_skill", "soft_skill", "certification", "tool", "experience", "education", "industry_knowledge" ], "description": "Category of the keyword", "example": "technical_skill" }, "importance": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Importance weight (1-10)", "example": 9 } }, "required": [ "term", "category", "importance" ], "additionalProperties": false }, "description": "The keywords a recruiter screens for, with category and importance." }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "The tokens this call spent from the key owner's account: the work it ran plus the request fee.", "example": 450 } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "keywords", "usage" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance has no tokens for this call. Nothing was spent. ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # List applications (/docs/reference/applications) `GET https://api.getmattered.com/api/v1/developer/applications` Your applications, newest first, with the same states as `GET /developer/applications/{id}`. Filter by `status` and `since`; page with `cursor`. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `cursor` (query): The `nextCursor` of the page before. Omit it for the newest applications. - `limit` (query): Applications per page, 1 to 50. - `since` (query): Only applications started at or after this instant, ISO 8601. - `status` (query): Only applications in this state. A filtered page may hold fewer items than `limit`; keep paging while `nextCursor` is not null. ## Responses ### 200: One page of applications and the cursor for the next. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "applications": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": [ "string", "null" ], "example": "Acme" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The application. The same posting always answers with the same id.", "example": 2481 }, "jobTitle": { "type": [ "string", "null" ], "example": "Senior Frontend Engineer" }, "landedEvidence": { "type": "array", "items": { "type": "string", "enum": [ "receipt", "screenshot" ], "description": "Who authored the evidence that this application reached the employer. `receipt` = the employer emailed a confirmation linked to this row. `screenshot` = a review of the stored post-submit screenshot read the employer's OWN confirmation page. Both are the other side's answer and both count as a proven landing; a row may hold either or both.", "example": "screenshot" }, "description": "The employer's own proof the application landed: `receipt` (their email) and `screenshot` (their confirmation page). Empty unless `status` is `landed`.", "example": [ "receipt" ] }, "postingUrl": { "type": [ "string", "null" ], "example": "https://job-boards.greenhouse.io/acme/jobs/4012345" }, "status": { "type": "string", "enum": [ "in_progress", "held_for_review", "needs_you", "landed", "held", "not_landed" ], "description": "`in_progress`: GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. `held_for_review`: ready, and waiting for the account owner to approve it in GetMattered. `needs_you`: waiting on the account owner for something else. `landed`: the employer confirmed it, by their own email or their confirmation page; `landedEvidence` says which. `held`: it stopped, and a mail may be the employer's answer, so GetMattered will not send it again; do not retry. `not_landed`: it stopped without the employer confirming it. Calling apply again for a stopped posting sends it again, except a `held` one or one the owner cancelled.", "example": "in_progress" }, "tokens": { "type": "integer", "description": "Tokens the call that started this application has spent on it so far, the request fee included. 0 for an application started in GetMattered.", "example": 22130 }, "trackingUrl": { "type": "string", "format": "uri", "description": "The application's page in GetMattered, behind the account owner's sign-in.", "example": "https://getmattered.com/dashboard/applications/2481" } }, "required": [ "company", "id", "jobTitle", "landedEvidence", "postingUrl", "status", "tokens", "trackingUrl" ], "additionalProperties": false } }, "nextCursor": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "description": "Pass it as `cursor` for the next, older page. Null when nothing older is left.", "example": 2461 } }, "required": [ "applications", "nextCursor" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Read an application (/docs/reference/applications-id) `GET https://api.getmattered.com/api/v1/developer/applications/{id}` Where one of your applications stands. `landed` only when the employer confirmed it, by their own email or their confirmation page. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `id` (path, required): The application id `POST /developer/apply` answered with. ## Responses ### 200: The application's status, the employer's proof and the tokens spent. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "company": { "type": [ "string", "null" ], "example": "Acme" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The application. The same posting always answers with the same id.", "example": 2481 }, "jobTitle": { "type": [ "string", "null" ], "example": "Senior Frontend Engineer" }, "landedEvidence": { "type": "array", "items": { "type": "string", "enum": [ "receipt", "screenshot" ], "description": "Who authored the evidence that this application reached the employer. `receipt` = the employer emailed a confirmation linked to this row. `screenshot` = a review of the stored post-submit screenshot read the employer's OWN confirmation page. Both are the other side's answer and both count as a proven landing; a row may hold either or both.", "example": "screenshot" }, "description": "The employer's own proof the application landed: `receipt` (their email) and `screenshot` (their confirmation page). Empty unless `status` is `landed`.", "example": [ "receipt" ] }, "postingUrl": { "type": [ "string", "null" ], "example": "https://job-boards.greenhouse.io/acme/jobs/4012345" }, "status": { "type": "string", "enum": [ "in_progress", "held_for_review", "needs_you", "landed", "held", "not_landed" ], "description": "`in_progress`: GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. `held_for_review`: ready, and waiting for the account owner to approve it in GetMattered. `needs_you`: waiting on the account owner for something else. `landed`: the employer confirmed it, by their own email or their confirmation page; `landedEvidence` says which. `held`: it stopped, and a mail may be the employer's answer, so GetMattered will not send it again; do not retry. `not_landed`: it stopped without the employer confirming it. Calling apply again for a stopped posting sends it again, except a `held` one or one the owner cancelled.", "example": "in_progress" }, "tokens": { "type": "integer", "description": "Tokens the call that started this application has spent on it so far, the request fee included. 0 for an application started in GetMattered.", "example": 22130 }, "trackingUrl": { "type": "string", "format": "uri", "description": "The application's page in GetMattered, behind the account owner's sign-in.", "example": "https://getmattered.com/dashboard/applications/2481" } }, "required": [ "company", "id", "jobTitle", "landedEvidence", "postingUrl", "status", "tokens", "trackingUrl" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Approve a held application (/docs/reference/applications-id/approve) `POST https://api.getmattered.com/api/v1/developer/applications/{id}/approve` Needs a key made with the `apply` scope. Approves an application in `held_for_review` and sends it, the way the account owner approves it in GetMattered. An application GetMattered cannot send stays held or ends `not_landed`; the answer is its state after the approval. An application started in GetMattered is paid by the app plan, one started by API by the API balance. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `id` (path, required): The application id `POST /developer/apply` answered with. ## Responses ### 200: The application after the approval. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "company": { "type": [ "string", "null" ], "example": "Acme" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The application. The same posting always answers with the same id.", "example": 2481 }, "jobTitle": { "type": [ "string", "null" ], "example": "Senior Frontend Engineer" }, "landedEvidence": { "type": "array", "items": { "type": "string", "enum": [ "receipt", "screenshot" ], "description": "Who authored the evidence that this application reached the employer. `receipt` = the employer emailed a confirmation linked to this row. `screenshot` = a review of the stored post-submit screenshot read the employer's OWN confirmation page. Both are the other side's answer and both count as a proven landing; a row may hold either or both.", "example": "screenshot" }, "description": "The employer's own proof the application landed: `receipt` (their email) and `screenshot` (their confirmation page). Empty unless `status` is `landed`.", "example": [ "receipt" ] }, "postingUrl": { "type": [ "string", "null" ], "example": "https://job-boards.greenhouse.io/acme/jobs/4012345" }, "status": { "type": "string", "enum": [ "in_progress", "held_for_review", "needs_you", "landed", "held", "not_landed" ], "description": "`in_progress`: GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. `held_for_review`: ready, and waiting for the account owner to approve it in GetMattered. `needs_you`: waiting on the account owner for something else. `landed`: the employer confirmed it, by their own email or their confirmation page; `landedEvidence` says which. `held`: it stopped, and a mail may be the employer's answer, so GetMattered will not send it again; do not retry. `not_landed`: it stopped without the employer confirming it. Calling apply again for a stopped posting sends it again, except a `held` one or one the owner cancelled.", "example": "in_progress" }, "tokens": { "type": "integer", "description": "Tokens the call that started this application has spent on it so far, the request fee included. 0 for an application started in GetMattered.", "example": 22130 }, "trackingUrl": { "type": "string", "format": "uri", "description": "The application's page in GetMattered, behind the account owner's sign-in.", "example": "https://getmattered.com/dashboard/applications/2481" } }, "required": [ "company", "id", "jobTitle", "landedEvidence", "postingUrl", "status", "tokens", "trackingUrl" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 403: Forbidden ### 404: Not Found ### 409: Conflict ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Cancel an application (/docs/reference/applications-id/cancel) `POST https://api.getmattered.com/api/v1/developer/applications/{id}/cancel` Needs a key made with the `apply` scope. Cancels an application that is queued, being prepared or held for review, before GetMattered starts sending it. 409 once sending started or the application ended. A cancelled application is never sent again by `POST /developer/apply`. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `id` (path, required): The application id `POST /developer/apply` answered with. ## Responses ### 200: The application after the cancel. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "company": { "type": [ "string", "null" ], "example": "Acme" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The application. The same posting always answers with the same id.", "example": 2481 }, "jobTitle": { "type": [ "string", "null" ], "example": "Senior Frontend Engineer" }, "landedEvidence": { "type": "array", "items": { "type": "string", "enum": [ "receipt", "screenshot" ], "description": "Who authored the evidence that this application reached the employer. `receipt` = the employer emailed a confirmation linked to this row. `screenshot` = a review of the stored post-submit screenshot read the employer's OWN confirmation page. Both are the other side's answer and both count as a proven landing; a row may hold either or both.", "example": "screenshot" }, "description": "The employer's own proof the application landed: `receipt` (their email) and `screenshot` (their confirmation page). Empty unless `status` is `landed`.", "example": [ "receipt" ] }, "postingUrl": { "type": [ "string", "null" ], "example": "https://job-boards.greenhouse.io/acme/jobs/4012345" }, "status": { "type": "string", "enum": [ "in_progress", "held_for_review", "needs_you", "landed", "held", "not_landed" ], "description": "`in_progress`: GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. `held_for_review`: ready, and waiting for the account owner to approve it in GetMattered. `needs_you`: waiting on the account owner for something else. `landed`: the employer confirmed it, by their own email or their confirmation page; `landedEvidence` says which. `held`: it stopped, and a mail may be the employer's answer, so GetMattered will not send it again; do not retry. `not_landed`: it stopped without the employer confirming it. Calling apply again for a stopped posting sends it again, except a `held` one or one the owner cancelled.", "example": "in_progress" }, "tokens": { "type": "integer", "description": "Tokens the call that started this application has spent on it so far, the request fee included. 0 for an application started in GetMattered.", "example": 22130 }, "trackingUrl": { "type": "string", "format": "uri", "description": "The application's page in GetMattered, behind the account owner's sign-in.", "example": "https://getmattered.com/dashboard/applications/2481" } }, "required": [ "company", "id", "jobTitle", "landedEvidence", "postingUrl", "status", "tokens", "trackingUrl" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 403: Forbidden ### 404: Not Found ### 409: Conflict ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Apply to a job posting (/docs/reference/apply) `POST https://api.getmattered.com/api/v1/developer/apply` Needs a key made with the `apply` scope. Applies to one job posting for the key owner's own account, the way GetMattered applies from the app: it resolves the link to the employer's posting, prepares the application and sends it, or holds it for the owner's approval. Answers at once; read the outcome from `GET /developer/applications/{id}`. The same posting twice answers with the same application. A stopped application starts again, except one `held` or one the owner cancelled. It spends the API balance, never the app plan, and needs 40,000 API tokens there for each application in progress plus this one to start; a running application finishes even if it takes the balance below zero, and the next call is refused until a top-up. At most 5 applications started by API are in progress at once, and an account reads at most 5 postings a minute across its keys. Spends the tokens the application uses plus the request fee, recorded as `apply`. A call refused before the posting is read spends nothing; once the posting is read, the call pays the request fee whatever it answers. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "review" ], "description": "`auto` sends once the application is ready. `review` holds it for the account owner to approve in GetMattered. Omitted, the account's own setting decides, and `auto` never overrides an account set to review.", "example": "auto" }, "postingUrl": { "type": "string", "maxLength": 2048, "format": "uri", "description": "The job posting to apply to: the employer's own posting, or a job-board link to it. GetMattered applies only on the hiring systems it supports.", "example": "https://job-boards.greenhouse.io/acme/jobs/4012345" } }, "required": [ "postingUrl" ], "additionalProperties": false } ``` ## Responses ### 202: The application, started now or found from an earlier call. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The application. The same posting always answers with the same id.", "example": 2481 }, "status": { "type": "string", "enum": [ "in_progress", "held_for_review", "needs_you", "landed", "held", "not_landed" ], "description": "`in_progress`: GetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet. `held_for_review`: ready, and waiting for the account owner to approve it in GetMattered. `needs_you`: waiting on the account owner for something else. `landed`: the employer confirmed it, by their own email or their confirmation page; `landedEvidence` says which. `held`: it stopped, and a mail may be the employer's answer, so GetMattered will not send it again; do not retry. `not_landed`: it stopped without the employer confirming it. Calling apply again for a stopped posting sends it again, except a `held` one or one the owner cancelled.", "example": "in_progress" }, "trackingUrl": { "type": "string", "format": "uri", "description": "The application's page in GetMattered, behind the account owner's sign-in.", "example": "https://getmattered.com/dashboard/applications/2481" } }, "required": [ "id", "status", "trackingUrl" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance cannot start an application. Nothing was sent. ### 403: The key lacks the `apply` scope its owner grants at creation. Nothing was sent. ### 404: Not Found ### 422: GetMattered cannot apply to this posting; `reason` says why. Nothing was sent; the request fee was spent. ### 429: Too Many Requests ### 500: Internal Server Error ### 503: Service Unavailable Error responses use the envelope in /errors.md. # Score a resume for ATS compatibility (/docs/reference/ats-score) `POST https://api.getmattered.com/api/v1/developer/ats-score` Scores resume text for ATS compatibility, against a job posting when one is sent. Spends the tokens it uses plus the request fee, recorded as `ats_score`. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "jobDescription": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The job posting to score against. Omit it for general ATS compatibility.", "example": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience to own our design system..." }, "resumeText": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The resume as plain text or Markdown, 50 to 50,000 characters.", "example": "Jane Doe\nSenior Software Engineer\n6 years building React and TypeScript apps at Acme. Led the move to Next.js..." } }, "required": [ "resumeText" ], "additionalProperties": false } ``` ## Responses ### 200: The ATS score, matched and missing keywords, section scores and suggestions. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "Overall ATS compatibility score (0-100).", "example": 72 }, "keywordMatches": { "type": "array", "items": { "type": "string" }, "description": "Keywords found in the resume that match the job description.", "example": [ "JavaScript", "React", "Node.js" ] }, "missingKeywords": { "type": "array", "items": { "type": "string" }, "description": "Important keywords from the job description missing from the resume.", "example": [ "TypeScript", "GraphQL" ] }, "sectionScores": { "type": "object", "properties": { "skills": { "type": "number", "minimum": 0, "maximum": 100 }, "experience": { "type": "number", "minimum": 0, "maximum": 100 }, "education": { "type": "number", "minimum": 0, "maximum": 100 }, "formatting": { "type": "number", "minimum": 0, "maximum": 100 }, "keywords": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "skills", "experience", "education", "formatting", "keywords" ], "additionalProperties": false, "description": "Per-section ATS sub-scores derived from the analysis." }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "Actionable improvement suggestions.", "example": [ "Add \"TypeScript\" to your skills section." ] }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "The tokens this call spent from the key owner's account: the work it ran plus the request fee.", "example": 450 } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "overallScore", "keywordMatches", "missingKeywords", "sectionScores", "suggestions", "usage" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance has no tokens for this call. Nothing was spent. ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Read your API balance (/docs/reference/balance) `GET https://api.getmattered.com/api/v1/developer/balance` The API tokens your account can spend now. API calls spend this balance, never your GetMattered plan. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Responses ### 200: The API balance. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "balance": { "type": "integer", "description": "The API tokens the account can spend now. Below zero after a running application finished past the end of the balance; the next call is refused until a top-up.", "example": 1250000 }, "currency": { "type": "string", "enum": [ "tokens" ] } }, "required": [ "balance", "currency" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Write a cover letter (/docs/reference/cover-letter) `POST https://api.getmattered.com/api/v1/developer/cover-letter` Writes a first-person cover letter for a job posting from the resume. Spends the tokens it uses plus the request fee, recorded as `cover_letter`. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "candidateName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The name the letter is signed with. Omit it to use the name on the resume.", "example": "Jane Doe" }, "companyName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The hiring company.", "example": "Acme" }, "jobDescription": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The job posting text, 50 to 50,000 characters.", "example": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience to own our design system..." }, "jobTitle": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The job title of the posting.", "example": "Senior Frontend Engineer" }, "resumeText": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The resume as plain text or Markdown, 50 to 50,000 characters.", "example": "Jane Doe\nSenior Software Engineer\n6 years building React and TypeScript apps at Acme. Led the move to Next.js..." } }, "required": [ "companyName", "jobDescription", "jobTitle", "resumeText" ], "additionalProperties": false } ``` ## Responses ### 200: The cover letter and the themes it leads with. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "coverLetter": { "type": "string", "description": "The cover letter, plain text." }, "keyThemes": { "type": "array", "items": { "type": "string" }, "description": "The themes the letter leads with.", "example": [ "Design systems" ] }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "The tokens this call spent from the key owner's account: the work it ran plus the request fee.", "example": 450 } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "coverLetter", "keyThemes", "usage" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance has no tokens for this call. Nothing was spent. ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Parse, score and tailor a resume in one call (/docs/reference/cv-pack) `POST https://api.getmattered.com/api/v1/developer/cv-pack` Parses the resume, scores it, tailors it to the posting and scores the result, in one call. Spends the tokens it uses plus the request fee, recorded as `light_cv_pack` or `pro_cv_pack` by `tier`. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "jobDescription": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The job posting text, 50 to 50,000 characters.", "example": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience to own our design system..." }, "jobTitle": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The job title of the posting.", "example": "Senior Frontend Engineer" }, "resumeText": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The resume as plain text or Markdown, 50 to 50,000 characters.", "example": "Jane Doe\nSenior Software Engineer\n6 years building React and TypeScript apps at Acme. Led the move to Next.js..." }, "tier": { "type": "string", "enum": [ "light", "pro" ], "default": "light", "description": "Tailoring depth. `light` is a quick rewrite, `pro` a deeper rewrite.", "example": "light" } }, "required": [ "jobDescription", "jobTitle", "resumeText" ], "additionalProperties": false } ``` ## Responses ### 200: The structured resume, the tailored resume and its before and after ATS scores. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "after": { "type": "object", "properties": { "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "Overall ATS compatibility score (0-100).", "example": 72 }, "keywordMatches": { "type": "array", "items": { "type": "string" }, "description": "Keywords found in the resume that match the job description.", "example": [ "JavaScript", "React", "Node.js" ] }, "missingKeywords": { "type": "array", "items": { "type": "string" }, "description": "Important keywords from the job description missing from the resume.", "example": [ "TypeScript", "GraphQL" ] }, "sectionScores": { "type": "object", "properties": { "skills": { "type": "number", "minimum": 0, "maximum": 100 }, "experience": { "type": "number", "minimum": 0, "maximum": 100 }, "education": { "type": "number", "minimum": 0, "maximum": 100 }, "formatting": { "type": "number", "minimum": 0, "maximum": 100 }, "keywords": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "skills", "experience", "education", "formatting", "keywords" ], "additionalProperties": false, "description": "Per-section ATS sub-scores derived from the analysis." }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "Actionable improvement suggestions.", "example": [ "Add \"TypeScript\" to your skills section." ] } }, "required": [ "overallScore", "keywordMatches", "missingKeywords", "sectionScores", "suggestions" ], "additionalProperties": false, "description": "The ATS score of the tailored resume." }, "before": { "allOf": [ { "type": "object", "properties": { "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "Overall ATS compatibility score (0-100).", "example": 72 }, "keywordMatches": { "type": "array", "items": { "type": "string" }, "description": "Keywords found in the resume that match the job description.", "example": [ "JavaScript", "React", "Node.js" ] }, "missingKeywords": { "type": "array", "items": { "type": "string" }, "description": "Important keywords from the job description missing from the resume.", "example": [ "TypeScript", "GraphQL" ] }, "sectionScores": { "type": "object", "properties": { "skills": { "type": "number", "minimum": 0, "maximum": 100 }, "experience": { "type": "number", "minimum": 0, "maximum": 100 }, "education": { "type": "number", "minimum": 0, "maximum": 100 }, "formatting": { "type": "number", "minimum": 0, "maximum": 100 }, "keywords": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "skills", "experience", "education", "formatting", "keywords" ], "additionalProperties": false, "description": "Per-section ATS sub-scores derived from the analysis." }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "Actionable improvement suggestions.", "example": [ "Add \"TypeScript\" to your skills section." ] } }, "required": [ "overallScore", "keywordMatches", "missingKeywords", "sectionScores", "suggestions" ], "additionalProperties": false, "description": "The ATS score of the tailored resume." }, { "description": "The ATS score of the resume as sent." } ] }, "keywordsAdded": { "type": "array", "items": { "type": "string" }, "description": "Posting keywords the tailored resume now carries.", "example": [ "GraphQL" ] }, "summary": { "type": [ "string", "null" ], "description": "What the tailoring emphasized and why.", "example": "Moved the design-system work to the top." }, "tailoredResume": { "type": "string", "description": "The tailored resume, Markdown." }, "tier": { "type": "string", "enum": [ "light", "pro" ], "description": "Tailoring depth. `light` is a quick rewrite, `pro` a deeper rewrite.", "example": "light" }, "parsed": { "type": "object", "properties": { "addressLine1": { "type": [ "string", "null" ], "description": "Street + number exactly as printed, or null", "example": "Hauptstrasse 12" }, "city": { "type": [ "string", "null" ], "description": "City from resume", "example": "San Francisco" }, "companySize": { "type": "array", "items": { "type": "string" }, "description": "AI-inferred company size preferences: startup, small, medium, large, enterprise", "example": [ "startup", "medium" ] }, "country": { "type": [ "string", "null" ], "description": "Country from resume", "example": "United States" }, "currentJobTitle": { "type": [ "string", "null" ], "description": "Current or most recent job title", "example": "Senior Software Engineer" }, "education": { "type": "array", "items": { "type": "object", "properties": { "degree": { "type": "string", "description": "Degree or certification name", "example": "B.S. Computer Science" }, "institution": { "type": "string", "description": "School or institution name", "example": "MIT" }, "year": { "type": [ "string", "null" ], "description": "Graduation year or date range", "example": "2018" } }, "required": [ "degree", "institution", "year" ], "additionalProperties": false }, "description": "Education history extracted from resume" }, "educationLevel": { "type": [ "string", "null" ], "description": "AI-inferred education level: high_school, associate, bachelor, master, doctorate", "example": "bachelor" }, "email": { "type": [ "string", "null" ], "description": "Email address from resume", "example": "john.doe@example.com" }, "experienceLevel": { "type": [ "string", "null" ], "description": "AI-inferred experience level: entry, mid, senior, lead, executive", "example": "senior" }, "fieldEvidence": { "type": "array", "items": { "type": "object", "properties": { "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "How the value was read: high/medium when printed in the resume, low when inferred", "example": "high" }, "field": { "type": "string", "enum": [ "addressLine1", "city", "state", "country", "zipCode", "phone", "email", "linkedinUrl", "githubUrl", "portfolioUrl", "currentEmployer", "educationLevel" ], "description": "A parsed resume fact backed by a verbatim quote from the resume", "example": "city" }, "quote": { "type": [ "string", "null" ], "description": "The exact contiguous resume text that contains the value (<=160 chars), or null", "example": "Berlin, Germany | +49 176 1234 5678" } }, "required": [ "confidence", "field", "quote" ], "additionalProperties": false }, "description": "Verbatim quotes from the resume that back the contact and level facts" }, "firstName": { "type": [ "string", "null" ], "description": "First name parsed from full name", "example": "John" }, "fullName": { "type": [ "string", "null" ], "description": "Full name from resume", "example": "John Doe" }, "githubUrl": { "type": [ "string", "null" ], "description": "GitHub profile URL exactly as printed, or null", "example": "https://github.com/johndoe" }, "industries": { "type": "array", "items": { "type": "string" }, "description": "AI-inferred industries from work history", "example": [ "Software & SaaS", "AI & Machine Learning" ] }, "jobTypes": { "type": "array", "items": { "type": "string" }, "description": "AI-inferred job types: full_time, part_time, contract, freelance, internship, temporary", "example": [ "full_time" ] }, "lastName": { "type": [ "string", "null" ], "description": "Last name parsed from full name", "example": "Doe" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "LinkedIn profile URL exactly as printed, or null", "example": "https://www.linkedin.com/in/johndoe" }, "phone": { "type": [ "string", "null" ], "description": "Phone number from resume", "example": "+1-555-123-4567" }, "portfolioUrl": { "type": [ "string", "null" ], "description": "Personal website / portfolio URL exactly as printed, or null", "example": "https://johndoe.dev" }, "prefill": { "type": "object", "properties": { "addressLine1": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "currentEmployer": { "type": [ "string", "null" ] }, "githubUrl": { "type": [ "string", "null" ] }, "highestEducation": { "type": [ "string", "null" ], "enum": [ "high_school", "associate", "bachelor", "master", "doctorate", "any", null ], "description": "Education level requirement", "example": "any" }, "homeLocation": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ] }, "ownTitles": { "type": "array", "items": { "type": "string" } }, "phone": { "type": [ "string", "null" ] }, "portfolioUrl": { "type": [ "string", "null" ] }, "seeded": { "type": "object", "properties": { "jobPreferences": { "type": "object", "properties": { "locations": { "type": "boolean", "enum": [ true ] }, "experienceLevels": { "type": "boolean", "enum": [ true ] }, "skills": { "type": "boolean", "enum": [ true ] }, "targetRoles": { "type": "boolean", "enum": [ true ] } } }, "profile": { "type": "object", "properties": { "addressLine1": { "type": "boolean", "enum": [ true ] }, "city": { "type": "boolean", "enum": [ true ] }, "state": { "type": "boolean", "enum": [ true ] }, "country": { "type": "boolean", "enum": [ true ] }, "zipCode": { "type": "boolean", "enum": [ true ] }, "phone": { "type": "boolean", "enum": [ true ] }, "linkedinUrl": { "type": "boolean", "enum": [ true ] }, "githubUrl": { "type": "boolean", "enum": [ true ] }, "portfolioUrl": { "type": "boolean", "enum": [ true ] }, "currentEmployer": { "type": "boolean", "enum": [ true ] }, "highestEducation": { "type": "boolean", "enum": [ true ] }, "yearsOfExperience": { "type": "boolean", "enum": [ true ] } } } }, "additionalProperties": false }, "state": { "type": [ "string", "null" ] }, "workHistoryLocations": { "type": "array", "items": { "type": "string" } }, "yearsOfExperience": { "type": [ "integer", "null" ] }, "zipCode": { "type": [ "string", "null" ] } }, "required": [ "addressLine1", "city", "country", "currentEmployer", "githubUrl", "highestEducation", "homeLocation", "linkedinUrl", "ownTitles", "phone", "portfolioUrl", "state", "workHistoryLocations", "yearsOfExperience", "zipCode" ], "additionalProperties": false }, "professionalSummary": { "type": [ "string", "null" ], "description": "Professional summary or objective", "example": "Experienced full-stack engineer with 8 years building scalable web applications." }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Skills extracted from resume", "example": [ "TypeScript", "React", "Node.js", "PostgreSQL" ] }, "state": { "type": [ "string", "null" ], "description": "State/province from resume", "example": "California" }, "suggestedJobTitles": { "type": "array", "items": { "type": "string" }, "description": "Suggested job titles based on experience", "example": [ "Senior Software Engineer", "Full Stack Developer", "Tech Lead" ] }, "suggestedLocations": { "type": "array", "items": { "type": "string" }, "description": "Suggested job search locations based on resume", "example": [ "San Francisco, CA", "Remote" ] }, "workExperience": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string", "description": "Company name", "example": "Acme Corp" }, "current": { "type": "boolean", "description": "Whether this is the current position", "example": false }, "description": { "type": [ "string", "null" ], "description": "Role description or achievements", "example": "Led a team of 5 engineers building microservices" }, "endDate": { "type": [ "string", "null" ], "description": "End date (free-form from resume)", "example": "Dec 2023" }, "location": { "type": [ "string", "null" ], "description": "City of this role exactly as printed on the resume", "example": "Berlin" }, "startDate": { "type": [ "string", "null" ], "description": "Start date (free-form from resume)", "example": "Jan 2020" }, "title": { "type": "string", "description": "Job title", "example": "Senior Software Engineer" } }, "required": [ "company", "current", "description", "endDate", "startDate", "title" ], "additionalProperties": false }, "description": "Work experience history extracted from resume" }, "yearsOfExperience": { "type": [ "integer", "null" ], "description": "Estimated total years of experience (whole number)", "example": 8 }, "zipCode": { "type": [ "string", "null" ], "description": "ZIP/postal code from resume", "example": "94105" } }, "required": [ "city", "companySize", "country", "currentJobTitle", "education", "educationLevel", "email", "experienceLevel", "firstName", "fullName", "industries", "jobTypes", "lastName", "phone", "professionalSummary", "skills", "state", "suggestedJobTitles", "suggestedLocations", "workExperience", "yearsOfExperience", "zipCode" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "The tokens this call spent from the key owner's account: the work it ran plus the request fee.", "example": 450 } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "after", "before", "keywordsAdded", "summary", "tailoredResume", "tier", "parsed", "usage" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance has no tokens for this call. Nothing was spent. ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Read a job (/docs/reference/jobs-id) `GET https://api.getmattered.com/api/v1/developer/jobs/{id}` One of the candidate's matches in full: description, pay, fit and whether GetMattered can apply to it (`canSend`). Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `id` (path, required): The match id from `GET /developer/jobs/matches` or a search `jobMatchId`. ## Responses ### 200: The match. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "canSend": { "type": "boolean", "description": "True when GetMattered can send an application for this match. False for a job it cannot send, such as a job-board posting with no employer posting GetMattered sends on.", "example": true }, "company": { "type": [ "string", "null" ] }, "companyLogoUrl": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "extractedSkills": { "type": [ "array", "null" ], "items": { "type": "string" } }, "id": { "type": "integer" }, "jobType": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "matchScore": { "type": [ "number", "null" ] }, "postedAt": { "type": [ "string", "null" ] }, "salary": { "type": [ "string", "null" ] }, "salaryCurrency": { "type": [ "string", "null" ], "description": "ISO-4217 currency code of the original (pre-normalization) salary range (USD, EUR, GBP, ...). Null when no salary was reported.", "example": "USD" }, "salaryMaxUsd": { "type": [ "integer", "null" ], "description": "Upper bound of the listing salary range normalized to USD/year. Null when no parseable salary range exists.", "example": 180000 }, "salaryMinUsd": { "type": [ "integer", "null" ], "description": "Lower bound of the listing salary range normalized to USD/year. Null when no parseable salary range exists.", "example": 120000 }, "title": { "type": "string" }, "url": { "type": "string" }, "visaSponsorship": { "type": [ "string", "null" ] }, "whyGoodFit": { "type": [ "string", "null" ], "description": "Enrichment-v2: one-paragraph (<=280 chars) neutral third-person blurb describing why a generic candidate might want this role. Null when the description is too thin.", "example": "Remote-first Series B fintech with strong mentorship, modern TypeScript stack, and paid conference budget. Limited on-call and a small team where individual impact is high." }, "workArrangement": { "type": [ "string", "null" ], "description": "Canonical work-arrangement enum (remote_global / remote_country / remote_region / hybrid / onsite / unknown). Drives the \"Remote\" chip + filter. Null only when enrichment hasn't run yet.", "example": "remote_global" } }, "required": [ "company", "companyLogoUrl", "description", "extractedSkills", "id", "jobType", "location", "matchScore", "postedAt", "salary", "salaryCurrency", "salaryMaxUsd", "salaryMinUsd", "title", "url", "visaSponsorship", "whyGoodFit", "workArrangement" ] }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # List the candidate's matches (/docs/reference/jobs/matches) `GET https://api.getmattered.com/api/v1/developer/jobs/matches` The candidate's matches: the jobs GetMattered found for their preferences and has not shown as decided, best fit first, the deck the candidate sees in the app. Reading it changes nothing. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `limit` (query): Matches per page, 1 to 50. - `page` (query): The page, from 1 to 20. ## Responses ### 200: One page of matches. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "hasMore": { "type": "boolean", "description": "True when the next page holds more matches." }, "matches": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": [ "string", "null" ], "example": "Acme" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The match. `POST /developer/apply` takes its `postingUrl`.", "example": 90412 }, "location": { "type": [ "string", "null" ], "example": "Berlin, Germany" }, "matchScore": { "type": [ "number", "null" ], "description": "How well the job fits the candidate, 0 to 100.", "example": 86 }, "postedDate": { "type": [ "string", "null" ], "description": "When the employer posted it, as the source wrote it.", "example": "2026-11-17" }, "postingUrl": { "type": "string", "example": "https://job-boards.greenhouse.io/acme/jobs/4012345" }, "title": { "type": "string", "example": "Senior Frontend Engineer" }, "workArrangement": { "type": [ "string", "null" ], "enum": [ "onsite", "hybrid", "remote_local", "remote_country", "remote_region", "remote_global", "unknown", null ], "description": "How a job can be performed geographically", "example": "remote_country" } }, "required": [ "company", "id", "location", "matchScore", "postedDate", "postingUrl", "title", "workArrangement" ], "additionalProperties": false } }, "page": { "type": "integer", "example": 1 }, "preferencesMissing": { "type": "boolean", "description": "True when the candidate saved no job preferences yet: the deck is empty until `PUT /developer/preferences`." } }, "required": [ "hasMore", "matches", "page", "preferencesMissing" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Search jobs (/docs/reference/jobs/search) `GET https://api.getmattered.com/api/v1/developer/jobs/search` Searches the whole job supply by title and place, beyond the candidate's matches. Answers only jobs GetMattered can apply to now, best first, at most 10: narrow the search rather than page it. Omit `query` and `location` to search the candidate's saved preferences. Pass a result's `jobUrl` to `POST /developer/apply`. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `location` (query): A city or country. Omit it to search the countries in the candidate's preferences. - `needsVisaSponsorship` (query): `true` drops jobs that say they do not sponsor a visa. - `postedWithinDays` (query): Only jobs posted in the last this many days. - `query` (query): A job title. Omit it to search the titles in the candidate's preferences. - `remoteOnly` (query): `true` keeps only remote jobs. - `salaryMin` (query): Lowest yearly pay in US dollars. A job with no stated pay stays in. ## Responses ### 200: Jobs GetMattered can apply to now, best first. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string", "enum": [ "ae", "ar", "at", "au", "bd", "be", "bh", "bo", "br", "ca", "ch", "cl", "cn", "co", "cr", "cu", "cz", "de", "dk", "do", "ec", "eg", "es", "fi", "fr", "gr", "gt", "hk", "hn", "hu", "id", "ie", "il", "in", "ir", "it", "jp", "ke", "kr", "kw", "lu", "mx", "my", "ng", "ni", "nl", "no", "nz", "om", "pa", "pe", "ph", "pk", "pl", "pr", "pt", "py", "qa", "ro", "ru", "sa", "sd", "se", "sg", "sv", "tr", "ua", "ug", "uk", "us", "uy", "ve", "vn", "za", "xx" ], "description": "ISO-3166-1 alpha-2 country code (xx = unknown)", "example": "de" }, "description": "The countries the search read" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string", "example": "Ramp" }, "jobMatchId": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "description": "The candidate's own match for this job, when there is one: `GET /developer/jobs/{id}` reads it.", "example": 90412 }, "jobUrl": { "type": "string", "description": "The employer's own posting. `POST /developer/apply` takes it as `postingUrl`.", "example": "https://jobs.ashbyhq.com/acme/1f2e3d4c" }, "location": { "type": [ "string", "null" ] }, "postedDate": { "type": [ "string", "null" ], "description": "When the employer posted it, as the source wrote it" }, "remote": { "type": "boolean" }, "salaryMaxUsd": { "type": [ "integer", "null" ] }, "salaryMinUsd": { "type": [ "integer", "null" ] }, "system": { "type": "string", "description": "The hiring system name a person reads", "example": "Ashby" }, "title": { "type": "string", "example": "Founding Engineer" } }, "required": [ "company", "jobMatchId", "jobUrl", "location", "postedDate", "remote", "salaryMaxUsd", "salaryMinUsd", "system", "title" ] }, "maxItems": 10 }, "outcome": { "type": "string", "enum": [ "found", "none_found", "no_query", "no_place", "no_remote_country" ], "description": "What the job search found: jobs, none, or why it could not search", "example": "found" }, "titles": { "type": "array", "items": { "type": "string" }, "description": "The job titles the search read" } }, "required": [ "countries", "jobs", "outcome", "titles" ] }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error ### 503: Service Unavailable Error responses use the envelope in /errors.md. # Parse a resume into structured fields (/docs/reference/parse) `POST https://api.getmattered.com/api/v1/developer/parse` Parses resume text into structured fields: contact, work history, education, skills and suggested titles. Spends the tokens it uses plus the request fee, recorded as `parse`. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "resumeText": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The resume as plain text or Markdown, 50 to 50,000 characters.", "example": "Jane Doe\nSenior Software Engineer\n6 years building React and TypeScript apps at Acme. Led the move to Next.js..." } }, "required": [ "resumeText" ], "additionalProperties": false } ``` ## Responses ### 200: The structured resume. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "addressLine1": { "type": [ "string", "null" ], "description": "Street + number exactly as printed, or null", "example": "Hauptstrasse 12" }, "city": { "type": [ "string", "null" ], "description": "City from resume", "example": "San Francisco" }, "companySize": { "type": "array", "items": { "type": "string" }, "description": "AI-inferred company size preferences: startup, small, medium, large, enterprise", "example": [ "startup", "medium" ] }, "country": { "type": [ "string", "null" ], "description": "Country from resume", "example": "United States" }, "currentJobTitle": { "type": [ "string", "null" ], "description": "Current or most recent job title", "example": "Senior Software Engineer" }, "education": { "type": "array", "items": { "type": "object", "properties": { "degree": { "type": "string", "description": "Degree or certification name", "example": "B.S. Computer Science" }, "institution": { "type": "string", "description": "School or institution name", "example": "MIT" }, "year": { "type": [ "string", "null" ], "description": "Graduation year or date range", "example": "2018" } }, "required": [ "degree", "institution", "year" ], "additionalProperties": false }, "description": "Education history extracted from resume" }, "educationLevel": { "type": [ "string", "null" ], "description": "AI-inferred education level: high_school, associate, bachelor, master, doctorate", "example": "bachelor" }, "email": { "type": [ "string", "null" ], "description": "Email address from resume", "example": "john.doe@example.com" }, "experienceLevel": { "type": [ "string", "null" ], "description": "AI-inferred experience level: entry, mid, senior, lead, executive", "example": "senior" }, "fieldEvidence": { "type": "array", "items": { "type": "object", "properties": { "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "How the value was read: high/medium when printed in the resume, low when inferred", "example": "high" }, "field": { "type": "string", "enum": [ "addressLine1", "city", "state", "country", "zipCode", "phone", "email", "linkedinUrl", "githubUrl", "portfolioUrl", "currentEmployer", "educationLevel" ], "description": "A parsed resume fact backed by a verbatim quote from the resume", "example": "city" }, "quote": { "type": [ "string", "null" ], "description": "The exact contiguous resume text that contains the value (<=160 chars), or null", "example": "Berlin, Germany | +49 176 1234 5678" } }, "required": [ "confidence", "field", "quote" ], "additionalProperties": false }, "description": "Verbatim quotes from the resume that back the contact and level facts" }, "firstName": { "type": [ "string", "null" ], "description": "First name parsed from full name", "example": "John" }, "fullName": { "type": [ "string", "null" ], "description": "Full name from resume", "example": "John Doe" }, "githubUrl": { "type": [ "string", "null" ], "description": "GitHub profile URL exactly as printed, or null", "example": "https://github.com/johndoe" }, "industries": { "type": "array", "items": { "type": "string" }, "description": "AI-inferred industries from work history", "example": [ "Software & SaaS", "AI & Machine Learning" ] }, "jobTypes": { "type": "array", "items": { "type": "string" }, "description": "AI-inferred job types: full_time, part_time, contract, freelance, internship, temporary", "example": [ "full_time" ] }, "lastName": { "type": [ "string", "null" ], "description": "Last name parsed from full name", "example": "Doe" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "LinkedIn profile URL exactly as printed, or null", "example": "https://www.linkedin.com/in/johndoe" }, "phone": { "type": [ "string", "null" ], "description": "Phone number from resume", "example": "+1-555-123-4567" }, "portfolioUrl": { "type": [ "string", "null" ], "description": "Personal website / portfolio URL exactly as printed, or null", "example": "https://johndoe.dev" }, "prefill": { "type": "object", "properties": { "addressLine1": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "currentEmployer": { "type": [ "string", "null" ] }, "githubUrl": { "type": [ "string", "null" ] }, "highestEducation": { "type": [ "string", "null" ], "enum": [ "high_school", "associate", "bachelor", "master", "doctorate", "any", null ], "description": "Education level requirement", "example": "any" }, "homeLocation": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ] }, "ownTitles": { "type": "array", "items": { "type": "string" } }, "phone": { "type": [ "string", "null" ] }, "portfolioUrl": { "type": [ "string", "null" ] }, "seeded": { "type": "object", "properties": { "jobPreferences": { "type": "object", "properties": { "locations": { "type": "boolean", "enum": [ true ] }, "experienceLevels": { "type": "boolean", "enum": [ true ] }, "skills": { "type": "boolean", "enum": [ true ] }, "targetRoles": { "type": "boolean", "enum": [ true ] } } }, "profile": { "type": "object", "properties": { "addressLine1": { "type": "boolean", "enum": [ true ] }, "city": { "type": "boolean", "enum": [ true ] }, "state": { "type": "boolean", "enum": [ true ] }, "country": { "type": "boolean", "enum": [ true ] }, "zipCode": { "type": "boolean", "enum": [ true ] }, "phone": { "type": "boolean", "enum": [ true ] }, "linkedinUrl": { "type": "boolean", "enum": [ true ] }, "githubUrl": { "type": "boolean", "enum": [ true ] }, "portfolioUrl": { "type": "boolean", "enum": [ true ] }, "currentEmployer": { "type": "boolean", "enum": [ true ] }, "highestEducation": { "type": "boolean", "enum": [ true ] }, "yearsOfExperience": { "type": "boolean", "enum": [ true ] } } } }, "additionalProperties": false }, "state": { "type": [ "string", "null" ] }, "workHistoryLocations": { "type": "array", "items": { "type": "string" } }, "yearsOfExperience": { "type": [ "integer", "null" ] }, "zipCode": { "type": [ "string", "null" ] } }, "required": [ "addressLine1", "city", "country", "currentEmployer", "githubUrl", "highestEducation", "homeLocation", "linkedinUrl", "ownTitles", "phone", "portfolioUrl", "state", "workHistoryLocations", "yearsOfExperience", "zipCode" ], "additionalProperties": false }, "professionalSummary": { "type": [ "string", "null" ], "description": "Professional summary or objective", "example": "Experienced full-stack engineer with 8 years building scalable web applications." }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Skills extracted from resume", "example": [ "TypeScript", "React", "Node.js", "PostgreSQL" ] }, "state": { "type": [ "string", "null" ], "description": "State/province from resume", "example": "California" }, "suggestedJobTitles": { "type": "array", "items": { "type": "string" }, "description": "Suggested job titles based on experience", "example": [ "Senior Software Engineer", "Full Stack Developer", "Tech Lead" ] }, "suggestedLocations": { "type": "array", "items": { "type": "string" }, "description": "Suggested job search locations based on resume", "example": [ "San Francisco, CA", "Remote" ] }, "workExperience": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string", "description": "Company name", "example": "Acme Corp" }, "current": { "type": "boolean", "description": "Whether this is the current position", "example": false }, "description": { "type": [ "string", "null" ], "description": "Role description or achievements", "example": "Led a team of 5 engineers building microservices" }, "endDate": { "type": [ "string", "null" ], "description": "End date (free-form from resume)", "example": "Dec 2023" }, "location": { "type": [ "string", "null" ], "description": "City of this role exactly as printed on the resume", "example": "Berlin" }, "startDate": { "type": [ "string", "null" ], "description": "Start date (free-form from resume)", "example": "Jan 2020" }, "title": { "type": "string", "description": "Job title", "example": "Senior Software Engineer" } }, "required": [ "company", "current", "description", "endDate", "startDate", "title" ], "additionalProperties": false }, "description": "Work experience history extracted from resume" }, "yearsOfExperience": { "type": [ "integer", "null" ], "description": "Estimated total years of experience (whole number)", "example": 8 }, "zipCode": { "type": [ "string", "null" ], "description": "ZIP/postal code from resume", "example": "94105" }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "The tokens this call spent from the key owner's account: the work it ran plus the request fee.", "example": 450 } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "city", "companySize", "country", "currentJobTitle", "education", "educationLevel", "email", "experienceLevel", "firstName", "fullName", "industries", "jobTypes", "lastName", "phone", "professionalSummary", "skills", "state", "suggestedJobTitles", "suggestedLocations", "workExperience", "yearsOfExperience", "zipCode", "usage" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance has no tokens for this call. Nothing was spent. ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Read job preferences (/docs/reference/preferences-get) `GET https://api.getmattered.com/api/v1/developer/preferences` The candidate's job preferences: target titles, locations, remote, salary and the rest, in the shape GetMattered saves them. The defaults when none are saved. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Responses ### 200: The preferences. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "benefits": { "type": [ "array", "null" ], "items": { "type": "string" } }, "companySize": { "type": [ "array", "null" ], "items": { "type": "string" } }, "createdAt": { "type": [ "string", "null" ] }, "educationLevel": { "type": [ "string", "null" ] }, "excludeIndustries": { "type": [ "array", "null" ], "items": { "type": "string" } }, "experienceLevel": { "type": [ "string", "null" ] }, "experienceLevels": { "type": [ "array", "null" ], "items": { "type": "string" } }, "id": { "type": "integer" }, "includeRemote": { "type": "boolean" }, "industries": { "type": [ "array", "null" ], "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "jobTypes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "locations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "remoteGlobal": { "type": "boolean" }, "salaryCurrency": { "type": "string", "enum": [ "usd", "eur", "gbp", "cad", "aud", "inr" ], "description": "Currency for salary values", "example": "usd" }, "salaryMax": { "type": [ "number", "null" ] }, "salaryMin": { "type": [ "number", "null" ] }, "skills": { "type": [ "array", "null" ], "items": { "type": "string" } }, "targetRoles": { "type": [ "array", "null" ], "items": { "type": "string" } }, "updatedAt": { "type": [ "string", "null" ] }, "visaSponsorship": { "type": [ "string", "null" ] }, "workStyles": { "type": "array", "items": { "type": "string", "enum": [ "onsite", "hybrid", "remote" ], "description": "User's preferred work style, physical mode only, no geo scoping", "example": "remote" } } }, "required": [ "benefits", "companySize", "createdAt", "educationLevel", "excludeIndustries", "experienceLevel", "experienceLevels", "id", "includeRemote", "industries", "isActive", "jobTypes", "locations", "remoteGlobal", "salaryCurrency", "salaryMax", "salaryMin", "skills", "targetRoles", "updatedAt", "visaSponsorship", "workStyles" ] }, { "type": "object", "properties": { "prefsChanged": { "type": "boolean", "description": "PUT only. True when this save changed at least one job_match_preference column (always true when it created the row). False means nothing moved. Absent on GET.", "example": true } } } ] }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response", "example": { "data": { "benefits": null, "companySize": [ "startup", "medium" ], "createdAt": "2026-09-01T12:00:00.000Z", "educationLevel": "bachelor", "excludeIndustries": null, "experienceLevel": "senior", "experienceLevels": [ "senior" ], "id": 311, "includeRemote": true, "industries": [ "Software & SaaS", "Financial Services" ], "isActive": true, "jobTypes": [ "full_time" ], "locations": [ "San Francisco, United States" ], "remoteGlobal": false, "salaryCurrency": "usd", "salaryMax": 190000, "salaryMin": 150000, "skills": [ "TypeScript", "React", "Node.js", "PostgreSQL" ], "targetRoles": [ "Senior Software Engineer", "Full Stack Developer" ], "updatedAt": "2026-09-20T08:30:00.000Z", "visaSponsorship": null, "workStyles": [ "remote", "hybrid" ] }, "success": true } } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error ### 503: Service Unavailable Error responses use the envelope in /errors.md. # Save job preferences (/docs/reference/preferences) `PUT https://api.getmattered.com/api/v1/developer/preferences` Saves the candidate's job preferences the way GetMattered saves them: titles and places are matched to known ones, then the matches are rebuilt for the new search. Fields you omit stay as saved. At most 6 saves in 5 minutes per account, the app's limit. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "benefits": { "type": "array", "items": { "type": "string" }, "description": "Must-have job benefits", "example": [ "health_insurance", "remote_work" ] }, "companySize": { "type": "array", "items": { "type": "string" }, "description": "Preferred company sizes", "example": [ "startup", "small" ] }, "educationLevel": { "type": "string", "description": "Minimum education level filter", "example": "bachelor" }, "excludeIndustries": { "type": "array", "items": { "type": "string" }, "description": "Industries to exclude from matches", "example": [ "Government & Public Sector" ] }, "experienceLevel": { "type": "string", "enum": [ "intern", "entry", "junior", "mid", "senior", "lead", "executive" ], "description": "Target experience level (DEPRECATED scalar - prefer `experienceLevels`). When `experienceLevels` is present it wins; this scalar is kept so legacy mobile binaries keep working.", "example": "senior" }, "experienceLevels": { "type": "array", "items": { "type": "string", "enum": [ "intern", "entry", "junior", "mid", "senior", "lead", "executive" ], "description": "Professional experience level", "example": "mid" }, "description": "Target experience levels (multi-select, new source of truth). Empty/omitted = no seniority constraint. The first element is mirrored into the deprecated scalar `experienceLevel`.", "example": [ "mid", "senior" ] }, "includeRemote": { "type": "boolean", "description": "Include region-restricted remote jobs (workStyles \"remote\") even when specific locations are set. Does NOT control worldwide remote - see `remoteGlobal`.", "example": true }, "remoteGlobal": { "type": "boolean", "description": "Accept worldwide \"Remote - Anywhere (Global)\" jobs from any region. Independent of `includeRemote`/workStyles \"remote\" (which stay region-restricted). Set via the \"Remote - Anywhere (Global)\" option in the location picker.", "example": false }, "industries": { "type": "array", "items": { "type": "string" }, "description": "Target industries", "example": [ "Technology", "Finance" ] }, "isActive": { "type": "boolean", "description": "Enable or disable daily matches", "example": true }, "jobTypes": { "type": "array", "items": { "type": "string" }, "description": "Preferred job types", "example": [ "full_time", "contract" ] }, "locations": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "Preferred locations as \"City, Country\" or \"Country\" (max 5). Middle admin segments (state/province) are stripped on ingest. Placeholder values (\"anywhere\", \"any\", ...) are rejected for security (they disable location scoping and let clients harvest the full job pool). An empty array is accepted ONLY for a caller opted into `remoteGlobal` - worldwide remote is itself the location answer.", "example": [ "San Francisco, United States", "Berlin, Germany" ] }, "salaryCurrency": { "type": "string", "enum": [ "usd", "eur", "gbp", "cad", "aud", "inr" ], "description": "Currency for the salary band (converted to USD for matching). Defaults to usd.", "example": "eur" }, "salaryMax": { "type": "number", "minimum": 0, "description": "Maximum salary requirement", "example": 200000 }, "salaryMin": { "type": "number", "minimum": 0, "description": "Minimum salary requirement", "example": 100000 }, "skills": { "type": "array", "items": { "type": "string" }, "description": "User skills (from resume or manual entry)", "example": [ "TypeScript", "React", "Node.js", "PostgreSQL" ] }, "targetRoles": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "minItems": 1, "maxItems": 5, "description": "Target role titles (max 5). When present, at least one specific title is required - empty arrays and placeholder values (\"anywhere\", \"any\", ...) are rejected for security (they disable role scoping and let clients harvest the full job pool).", "example": [ "Software Engineer", "Full Stack Developer" ] }, "visaSponsorship": { "type": "string", "description": "Visa sponsorship preference", "example": "required" }, "workStyles": { "type": "array", "items": { "type": "string", "enum": [ "onsite", "hybrid", "remote" ], "description": "User's preferred work style, physical mode only, no geo scoping", "example": "remote" }, "minItems": 1, "description": "Preferred work styles (onsite/hybrid/remote) - multi-select, at least 1 required. Geo scoping is inferred from `locations`, NOT this field.", "example": [ "remote", "hybrid" ] } }, "additionalProperties": false, "example": { "locations": [ "San Francisco, United States" ], "salaryCurrency": "usd", "salaryMax": 190000, "salaryMin": 150000, "targetRoles": [ "Senior Software Engineer", "Full Stack Developer" ], "workStyles": [ "remote", "hybrid" ] } } ``` ## Responses ### 200: The preferences as saved. ```json { "type": "object", "properties": { "data": { "allOf": [ { "type": "object", "properties": { "benefits": { "type": [ "array", "null" ], "items": { "type": "string" } }, "companySize": { "type": [ "array", "null" ], "items": { "type": "string" } }, "createdAt": { "type": [ "string", "null" ] }, "educationLevel": { "type": [ "string", "null" ] }, "excludeIndustries": { "type": [ "array", "null" ], "items": { "type": "string" } }, "experienceLevel": { "type": [ "string", "null" ] }, "experienceLevels": { "type": [ "array", "null" ], "items": { "type": "string" } }, "id": { "type": "integer" }, "includeRemote": { "type": "boolean" }, "industries": { "type": [ "array", "null" ], "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "jobTypes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "locations": { "type": [ "array", "null" ], "items": { "type": "string" } }, "remoteGlobal": { "type": "boolean" }, "salaryCurrency": { "type": "string", "enum": [ "usd", "eur", "gbp", "cad", "aud", "inr" ], "description": "Currency for salary values", "example": "usd" }, "salaryMax": { "type": [ "number", "null" ] }, "salaryMin": { "type": [ "number", "null" ] }, "skills": { "type": [ "array", "null" ], "items": { "type": "string" } }, "targetRoles": { "type": [ "array", "null" ], "items": { "type": "string" } }, "updatedAt": { "type": [ "string", "null" ] }, "visaSponsorship": { "type": [ "string", "null" ] }, "workStyles": { "type": "array", "items": { "type": "string", "enum": [ "onsite", "hybrid", "remote" ], "description": "User's preferred work style, physical mode only, no geo scoping", "example": "remote" } } }, "required": [ "benefits", "companySize", "createdAt", "educationLevel", "excludeIndustries", "experienceLevel", "experienceLevels", "id", "includeRemote", "industries", "isActive", "jobTypes", "locations", "remoteGlobal", "salaryCurrency", "salaryMax", "salaryMin", "skills", "targetRoles", "updatedAt", "visaSponsorship", "workStyles" ] }, { "type": "object", "properties": { "prefsChanged": { "type": "boolean", "description": "PUT only. True when this save changed at least one job_match_preference column (always true when it created the row). False means nothing moved. Absent on GET.", "example": true } } } ] }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response", "example": { "data": { "benefits": null, "companySize": [ "startup", "medium" ], "createdAt": "2026-09-01T12:00:00.000Z", "educationLevel": "bachelor", "excludeIndustries": null, "experienceLevel": "senior", "experienceLevels": [ "senior" ], "id": 311, "includeRemote": true, "industries": [ "Software & SaaS", "Financial Services" ], "isActive": true, "jobTypes": [ "full_time" ], "locations": [ "San Francisco, United States" ], "remoteGlobal": false, "salaryCurrency": "usd", "salaryMax": 190000, "salaryMin": 150000, "skills": [ "TypeScript", "React", "Node.js", "PostgreSQL" ], "targetRoles": [ "Senior Software Engineer", "Full Stack Developer" ], "updatedAt": "2026-09-20T08:30:00.000Z", "visaSponsorship": null, "workStyles": [ "remote", "hybrid" ] }, "success": true } } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error ### 503: Service Unavailable Error responses use the envelope in /errors.md. # Read the candidate profile (/docs/reference/profile-get) `GET https://api.getmattered.com/api/v1/developer/profile` The candidate's name, contact, location, work authorization and links: the facts GetMattered fills application forms with. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Responses ### 200: The profile. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "addressLine1": { "type": [ "string", "null" ], "description": "Address line 1", "example": "123 Main St" }, "addressLine2": { "type": [ "string", "null" ], "description": "Address line 2", "example": "Apt 4B" }, "city": { "type": [ "string", "null" ], "description": "City", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "description": "Country", "example": "US" }, "githubUrl": { "type": [ "string", "null" ], "description": "GitHub profile URL", "example": "https://github.com/johndoe" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "LinkedIn profile URL", "example": "https://linkedin.com/in/johndoe" }, "phone": { "type": [ "string", "null" ], "description": "Phone number", "example": "+1-555-123-4567" }, "portfolioUrl": { "type": [ "string", "null" ], "description": "Portfolio website URL", "example": "https://johndoe.dev" }, "relocationLocations": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Preferred relocation locations as \"City, Country\" or \"Country\". Middle admin segments stripped on read.", "example": [ "New York, United States", "Austin, United States" ] }, "state": { "type": [ "string", "null" ], "description": "State or province", "example": "CA" }, "willingToRelocate": { "type": "boolean", "description": "Willing to relocate for a job", "example": false }, "workAuthorization": { "type": [ "string", "null" ], "enum": [ "us_citizen", "permanent_resident", "visa_holder", "require_sponsorship", "other", null ], "description": "Work authorization status", "example": "us_citizen" }, "zipCode": { "type": [ "string", "null" ], "description": "ZIP or postal code", "example": "94105" }, "email": { "type": "string", "description": "The account email. Read-only here.", "example": "jane@example.com" }, "name": { "type": [ "string", "null" ], "description": "The candidate's full name.", "example": "Jane Doe" } }, "required": [ "addressLine1", "addressLine2", "city", "country", "githubUrl", "linkedinUrl", "phone", "portfolioUrl", "relocationLocations", "state", "willingToRelocate", "workAuthorization", "zipCode", "email", "name" ] }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error ### 503: Service Unavailable Error responses use the envelope in /errors.md. # Update the candidate profile (/docs/reference/profile) `PATCH https://api.getmattered.com/api/v1/developer/profile` Changes the fields you send and leaves the rest. Send `null` to clear a field. The same fields the candidate edits in GetMattered. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "addressLine1": { "type": [ "string", "null" ], "maxLength": 255, "description": "Address line 1", "example": "123 Main St" }, "addressLine2": { "type": [ "string", "null" ], "maxLength": 255, "description": "Address line 2", "example": "Apt 4B" }, "city": { "type": [ "string", "null" ], "maxLength": 100, "description": "City", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "maxLength": 100, "description": "Country", "example": "US" }, "githubUrl": { "type": [ "string", "null" ], "maxLength": 500, "format": "uri", "description": "GitHub profile URL", "example": "https://github.com/johndoe" }, "linkedinUrl": { "type": [ "string", "null" ], "maxLength": 500, "format": "uri", "description": "LinkedIn profile URL", "example": "https://linkedin.com/in/johndoe" }, "phone": { "type": [ "string", "null" ], "maxLength": 20, "description": "Phone number", "example": "+1-555-123-4567" }, "portfolioUrl": { "type": [ "string", "null" ], "maxLength": 500, "format": "uri", "description": "Portfolio website URL", "example": "https://johndoe.dev" }, "relocationLocations": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Preferred relocation locations as \"City, Country\" or \"Country\" (max per-entry stripping of middle admin segments on ingest).", "example": [ "New York, United States", "Austin, United States" ] }, "state": { "type": [ "string", "null" ], "maxLength": 100, "description": "State or province", "example": "CA" }, "willingToRelocate": { "type": "boolean", "description": "Willing to relocate for a job", "example": false }, "workAuthorization": { "type": [ "string", "null" ], "enum": [ "us_citizen", "permanent_resident", "visa_holder", "require_sponsorship", "other", null ], "description": "Work authorization status", "example": "us_citizen" }, "zipCode": { "type": [ "string", "null" ], "maxLength": 20, "description": "ZIP or postal code", "example": "94105" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The candidate's full name, as employers see it.", "example": "Jane Doe" } }, "additionalProperties": false } ``` ## Responses ### 200: The profile after the change. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "addressLine1": { "type": [ "string", "null" ], "description": "Address line 1", "example": "123 Main St" }, "addressLine2": { "type": [ "string", "null" ], "description": "Address line 2", "example": "Apt 4B" }, "city": { "type": [ "string", "null" ], "description": "City", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "description": "Country", "example": "US" }, "githubUrl": { "type": [ "string", "null" ], "description": "GitHub profile URL", "example": "https://github.com/johndoe" }, "linkedinUrl": { "type": [ "string", "null" ], "description": "LinkedIn profile URL", "example": "https://linkedin.com/in/johndoe" }, "phone": { "type": [ "string", "null" ], "description": "Phone number", "example": "+1-555-123-4567" }, "portfolioUrl": { "type": [ "string", "null" ], "description": "Portfolio website URL", "example": "https://johndoe.dev" }, "relocationLocations": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Preferred relocation locations as \"City, Country\" or \"Country\". Middle admin segments stripped on read.", "example": [ "New York, United States", "Austin, United States" ] }, "state": { "type": [ "string", "null" ], "description": "State or province", "example": "CA" }, "willingToRelocate": { "type": "boolean", "description": "Willing to relocate for a job", "example": false }, "workAuthorization": { "type": [ "string", "null" ], "enum": [ "us_citizen", "permanent_resident", "visa_holder", "require_sponsorship", "other", null ], "description": "Work authorization status", "example": "us_citizen" }, "zipCode": { "type": [ "string", "null" ], "description": "ZIP or postal code", "example": "94105" }, "email": { "type": "string", "description": "The account email. Read-only here.", "example": "jane@example.com" }, "name": { "type": [ "string", "null" ], "description": "The candidate's full name.", "example": "Jane Doe" } }, "required": [ "addressLine1", "addressLine2", "city", "country", "githubUrl", "linkedinUrl", "phone", "portfolioUrl", "relocationLocations", "state", "willingToRelocate", "workAuthorization", "zipCode", "email", "name" ] }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error ### 503: Service Unavailable Error responses use the envelope in /errors.md. # Read the resume (/docs/reference/resume-get) `GET https://api.getmattered.com/api/v1/developer/resume` The resume GetMattered applies with: the candidate's base resume, as text. 404 when the candidate has none yet. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Responses ### 200: The resume. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The resume document.", "example": 512 }, "mimeType": { "type": [ "string", "null" ], "description": "The stored file type.", "example": "application/pdf" }, "text": { "type": [ "string", "null" ], "description": "The resume as text, when GetMattered read it. Null while a new upload is still being read.", "example": "Jane Doe\nSenior Software Engineer..." }, "title": { "type": "string", "example": "Jane Doe resume" } }, "required": [ "id", "mimeType", "text", "title" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error ### 503: Service Unavailable Error responses use the envelope in /errors.md. # Upload a resume (/docs/reference/resume) `POST https://api.getmattered.com/api/v1/developer/resume` Uploads a new resume for the candidate, the way the GetMattered upload does: the same file types and 10 MB limit, and it becomes the resume GetMattered applies with. GetMattered reads the file before it answers, so the answer carries the text it read. Spends the tokens it uses plus the request fee, recorded as `parse`. At most 10 uploads a minute per account. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Responses ### 200: The stored resume and the text GetMattered read from it. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The resume document.", "example": 512 }, "mimeType": { "type": [ "string", "null" ], "description": "The stored file type.", "example": "application/pdf" }, "text": { "type": [ "string", "null" ], "description": "The resume as text, as GetMattered read it from the file. Null when it found no readable text.", "example": "Jane Doe\nSenior Software Engineer..." }, "title": { "type": "string", "example": "Jane Doe resume" }, "status": { "type": "string", "enum": [ "draft", "generating", "ready", "failed" ], "description": "`ready`: the resume is stored and read; `text` holds what GetMattered read, and is null when the file had no readable text (applications still send the file). `failed`: GetMattered could not read the file. `GET /developer/resume` answers the same resume afterwards.", "example": "ready" }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "The tokens this call spent from the key owner's account: the work it ran plus the request fee.", "example": 450 } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "id", "mimeType", "text", "title", "status", "usage" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance has no tokens for this call. Nothing was spent. ### 403: The account holds as many documents as its plan allows, and none can be removed to make room. Nothing was stored. ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Tailor a resume to a job posting (/docs/reference/tailor) `POST https://api.getmattered.com/api/v1/developer/tailor` Tailors a resume to a job posting and scores it before and after. `light` is a quick rewrite, `pro` a deeper rewrite. Spends the tokens it uses plus the request fee, recorded as `light_cv_pack` or `pro_cv_pack`. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "jobDescription": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The job posting text, 50 to 50,000 characters.", "example": "We are hiring a Senior Frontend Engineer with React, TypeScript and GraphQL experience to own our design system..." }, "jobTitle": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The job title of the posting.", "example": "Senior Frontend Engineer" }, "resumeText": { "type": "string", "minLength": 50, "maxLength": 50000, "description": "The resume as plain text or Markdown, 50 to 50,000 characters.", "example": "Jane Doe\nSenior Software Engineer\n6 years building React and TypeScript apps at Acme. Led the move to Next.js..." }, "tier": { "type": "string", "enum": [ "light", "pro" ], "default": "light", "description": "Tailoring depth. `light` is a quick rewrite, `pro` a deeper rewrite.", "example": "light" } }, "required": [ "jobDescription", "jobTitle", "resumeText" ], "additionalProperties": false } ``` ## Responses ### 200: The tailored resume with its before and after ATS scores. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "after": { "type": "object", "properties": { "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "Overall ATS compatibility score (0-100).", "example": 72 }, "keywordMatches": { "type": "array", "items": { "type": "string" }, "description": "Keywords found in the resume that match the job description.", "example": [ "JavaScript", "React", "Node.js" ] }, "missingKeywords": { "type": "array", "items": { "type": "string" }, "description": "Important keywords from the job description missing from the resume.", "example": [ "TypeScript", "GraphQL" ] }, "sectionScores": { "type": "object", "properties": { "skills": { "type": "number", "minimum": 0, "maximum": 100 }, "experience": { "type": "number", "minimum": 0, "maximum": 100 }, "education": { "type": "number", "minimum": 0, "maximum": 100 }, "formatting": { "type": "number", "minimum": 0, "maximum": 100 }, "keywords": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "skills", "experience", "education", "formatting", "keywords" ], "additionalProperties": false, "description": "Per-section ATS sub-scores derived from the analysis." }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "Actionable improvement suggestions.", "example": [ "Add \"TypeScript\" to your skills section." ] } }, "required": [ "overallScore", "keywordMatches", "missingKeywords", "sectionScores", "suggestions" ], "additionalProperties": false, "description": "The ATS score of the tailored resume." }, "before": { "allOf": [ { "type": "object", "properties": { "overallScore": { "type": "number", "minimum": 0, "maximum": 100, "description": "Overall ATS compatibility score (0-100).", "example": 72 }, "keywordMatches": { "type": "array", "items": { "type": "string" }, "description": "Keywords found in the resume that match the job description.", "example": [ "JavaScript", "React", "Node.js" ] }, "missingKeywords": { "type": "array", "items": { "type": "string" }, "description": "Important keywords from the job description missing from the resume.", "example": [ "TypeScript", "GraphQL" ] }, "sectionScores": { "type": "object", "properties": { "skills": { "type": "number", "minimum": 0, "maximum": 100 }, "experience": { "type": "number", "minimum": 0, "maximum": 100 }, "education": { "type": "number", "minimum": 0, "maximum": 100 }, "formatting": { "type": "number", "minimum": 0, "maximum": 100 }, "keywords": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "skills", "experience", "education", "formatting", "keywords" ], "additionalProperties": false, "description": "Per-section ATS sub-scores derived from the analysis." }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "Actionable improvement suggestions.", "example": [ "Add \"TypeScript\" to your skills section." ] } }, "required": [ "overallScore", "keywordMatches", "missingKeywords", "sectionScores", "suggestions" ], "additionalProperties": false, "description": "The ATS score of the tailored resume." }, { "description": "The ATS score of the resume as sent." } ] }, "keywordsAdded": { "type": "array", "items": { "type": "string" }, "description": "Posting keywords the tailored resume now carries.", "example": [ "GraphQL" ] }, "summary": { "type": [ "string", "null" ], "description": "What the tailoring emphasized and why.", "example": "Moved the design-system work to the top." }, "tailoredResume": { "type": "string", "description": "The tailored resume, Markdown." }, "tier": { "type": "string", "enum": [ "light", "pro" ], "description": "Tailoring depth. `light` is a quick rewrite, `pro` a deeper rewrite.", "example": "light" }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "description": "The tokens this call spent from the key owner's account: the work it ran plus the request fee.", "example": 450 } }, "required": [ "tokens" ], "additionalProperties": false } }, "required": [ "after", "before", "keywordsAdded", "summary", "tailoredResume", "tier", "usage" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 402: The key owner's API balance has no tokens for this call. Nothing was spent. ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Read your monthly usage (/docs/reference/usage) `GET https://api.getmattered.com/api/v1/developer/usage` Calls and the tokens they spent for each of your API keys in one calendar month (UTC). Defaults to the current month. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `month` (query): Calendar month in UTC, `YYYY-MM`. ## Responses ### 200: Calls and tokens per key and operation. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "calls": { "type": "integer", "description": "Calls this month, every outcome.", "example": 120 }, "failedCalls": { "type": "integer", "description": "Calls whose work started and failed on our side.", "example": 1 }, "keyId": { "type": "integer", "example": 3 }, "keyPrefix": { "type": "string", "description": "The first characters of the key.", "example": "gm_live_AbCd" }, "name": { "type": "string", "example": "Production" }, "operations": { "type": "array", "items": { "type": "object", "properties": { "calls": { "type": "integer", "example": 100 }, "operation": { "type": "string", "enum": [ "ats_score", "parse", "analyze_job", "light_cv_pack", "pro_cv_pack", "cover_letter", "apply", "read_profile", "update_profile", "read_resume", "read_preferences", "update_preferences", "search_jobs", "read_matches", "read_job", "list_applications", "approve_application", "cancel_application", "manage_webhooks" ], "description": "What a developer API call does. A call that runs AI work spends the tokens it used plus a flat request fee; a read, an edit, an approval and a webhook change spend nothing.", "example": "ats_score" }, "tokens": { "type": "integer", "example": 45000 } }, "required": [ "calls", "operation", "tokens" ], "additionalProperties": false } }, "refusedCalls": { "type": "integer", "description": "Calls declined before any spend: no tokens, a plan limit, or a posting GetMattered cannot apply to.", "example": 0 }, "tokens": { "type": "integer", "description": "Tokens these calls spent this month.", "example": 61400 } }, "required": [ "calls", "failedCalls", "keyId", "keyPrefix", "name", "operations", "refusedCalls", "tokens" ], "additionalProperties": false } }, "month": { "type": "string", "pattern": "^\\d{4}-(?:0[1-9]|1[0-2])$", "description": "Calendar month in UTC, `YYYY-MM`.", "example": "2026-11" } }, "required": [ "keys", "month" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # List webhook endpoints (/docs/reference/webhooks-get) `GET https://api.getmattered.com/api/v1/developer/webhooks` Your account's webhook endpoints. The secret is never shown again; `secretPrefix` tells them apart. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Responses ### 200: The endpoints, oldest first. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "example": "2026-11-19 17:00:00" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The webhook endpoint.", "example": 7 }, "secretPrefix": { "type": "string", "description": "The first characters of the signing secret.", "example": "whsec_AbCdEf" }, "url": { "type": "string", "example": "https://example.com/hooks/getmattered" } }, "required": [ "createdAt", "id", "secretPrefix", "url" ], "additionalProperties": false } } }, "required": [ "endpoints" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Add a webhook endpoint (/docs/reference/webhooks) `POST https://api.getmattered.com/api/v1/developer/webhooks` Adds a webhook endpoint to your account, at most 5. Answers the signing secret once. GetMattered POSTs a JSON event (`DeveloperWebhookEvent`) when one of your applications becomes `landed`, `not_landed`, `needs_you` or `held_for_review`, usually within two minutes. Each delivery carries `GetMattered-Signature: t=,v1=." under the endpoint secret>`, plus `GetMattered-Event-Id` and `GetMattered-Event-Type`. Answer 2xx within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 5, 10 and 24 hours, then the delivery is marked `failed`. The same event can arrive twice: skip an `id` you have seen. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Request body (application/json) ```json { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Where GetMattered POSTs events. Public `https` only; redirects are not followed.", "example": "https://example.com/hooks/getmattered" } }, "required": [ "url" ], "additionalProperties": false } ``` ## Responses ### 201: The endpoint and its signing secret, shown this once. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "example": "2026-11-19 17:00:00" }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The webhook endpoint.", "example": 7 }, "secretPrefix": { "type": "string", "description": "The first characters of the signing secret.", "example": "whsec_AbCdEf" }, "url": { "type": "string", "example": "https://example.com/hooks/getmattered" }, "secret": { "type": "string", "description": "The signing secret. Shown once: store it now. Verify each delivery with it (see `GetMattered-Signature`).", "example": "whsec_3q2-7wAbCdEfGhIjKlMnOpQrStUvWxYz0123456789" } }, "required": [ "createdAt", "id", "secretPrefix", "url", "secret" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 409: Conflict ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Delete a webhook endpoint (/docs/reference/webhooks-id) `DELETE https://api.getmattered.com/api/v1/developer/webhooks/{id}` Deletes a webhook endpoint. Deliveries not yet sent to it are dropped. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `id` (path, required): The webhook endpoint id. ## Responses ### 200: The endpoint was deleted. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "id": { "type": "integer", "exclusiveMinimum": 0, "description": "The webhook endpoint.", "example": 7 } }, "required": [ "deleted", "id" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Read webhook deliveries (/docs/reference/webhooks-id/deliveries) `GET https://api.getmattered.com/api/v1/developer/webhooks/{id}/deliveries` The newest 20 deliveries to one endpoint: event, status, attempts and the last HTTP status your endpoint answered. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `id` (path, required): The webhook endpoint id. ## Responses ### 200: The deliveries, newest first. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "attempts": { "type": "integer", "description": "Attempts made so far.", "example": 1 }, "createdAt": { "type": "string", "example": "2026-11-19 17:01:00" }, "deliveredAt": { "type": [ "string", "null" ], "example": "2026-11-19T17:01:02.000Z" }, "eventId": { "type": "string", "example": "evt_3f9c2a7d6b8e4f0a9c1d2e3f4a5b6c7d" }, "eventType": { "type": "string", "example": "application.landed" }, "lastStatusCode": { "type": [ "integer", "null" ], "description": "The HTTP status your endpoint answered the last attempt with; null when it did not answer.", "example": 200 }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ], "description": "`pending`: not delivered yet, another attempt is due. `delivered`: the endpoint answered 2xx. `failed`: every attempt failed; no more are made.", "example": "delivered" } }, "required": [ "attempts", "createdAt", "deliveredAt", "eventId", "eventType", "lastStatusCode", "status" ], "additionalProperties": false } } }, "required": [ "deliveries" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md. # Send a test event (/docs/reference/webhooks-id/test) `POST https://api.getmattered.com/api/v1/developer/webhooks/{id}/test` Queues one `webhook.test` event to the endpoint, signed like every event. It is sent within a minute; read the result from `GET /developer/webhooks/{id}/deliveries`. Free. Authentication: `Authorization: Bearer gm_live_...` (see /authentication.md). ## Parameters - `id` (path, required): The webhook endpoint id. ## Responses ### 202: The test event is queued. ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string", "example": "evt_3f9c2a7d6b8e4f0a9c1d2e3f4a5b6c7d" }, "queued": { "type": "boolean", "enum": [ true ] } }, "required": [ "eventId", "queued" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "duration": { "type": "number", "minimum": 0, "description": "Request duration in milliseconds", "example": 150 }, "performance": { "type": "object", "properties": { "dbQueries": { "type": "integer", "minimum": 0 }, "totalDbTime": { "type": "number", "minimum": 0 } }, "description": "Performance metrics (preview/local only)" }, "requestId": { "type": "string", "description": "Unique request identifier", "example": "req_abc123" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp", "example": "2026-11-17T12:00:00.000Z" }, "version": { "type": "string", "description": "API version", "example": "v1" } } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "data", "success" ], "additionalProperties": false, "description": "Successful API response" } ``` ### 400: Bad Request ### 401: Unauthorized ### 404: Not Found ### 429: Too Many Requests ### 500: Internal Server Error Error responses use the envelope in /errors.md.