Apply to a job by API
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
- Create a key with Can send applications ticked, in the dashboard at getmattered.com/dashboard/developers. See Key scopes.
- Upload a resume to the account in GetMattered. Without one, the call answers
400and sends nothing. - Use a posting on a hiring system GetMattered supports. Any other posting answers
422with 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
Send the posting URL. It can be the employer's own posting or a job-board link to it.
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:
{
"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
GET /developer/applications/{id} answers with one of six states.
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.
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
A posting GetMattered cannot apply to answers 422 with "outcome": "not_applied".
Nothing was sent and nothing was spent.
{
"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. |
403 | error.code FORBIDDEN | The key was made without "Can send applications". Create a key with it ticked. See 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. |
503 | error.code SERVICE_UNAVAILABLE | The posting is still being read. Call again after the Retry-After header. |
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.
Next
- Score a resume against a job post before you apply.
- Application states lists every state and its webhook event.
- Every field of both calls is in the reference: Apply to a job posting and Read an application.