Skip to Content

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 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

Send the posting URL. It can be the employer's own posting or a job-board link to it.

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:

modeWhat happens
autoGetMattered sends the application once it is ready.
reviewGetMattered prepares it and holds it. The account owner approves it in GetMattered.
left outThe 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:

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

GET /developer/applications/{id} answers with one of six states. Application states says what each one means and which webhook event it sends.

statusWhat it means
in_progressGetMattered is preparing or sending it, or it was sent and the employer has not confirmed it yet.
held_for_reviewIt is ready and waits for the account owner to approve it in GetMattered.
needs_youIt waits on the account owner for something else, such as a detail only they can give.
landedThe employer confirmed it. landedEvidence says how.
heldIt stopped, and a mail may be the employer's answer, so GetMattered will not send it again. Do not retry.
not_landedIt 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.

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

A posting GetMattered cannot apply to answers 422 with "outcome": "not_applied". Nothing was sent and nothing was spent.

POST /developer/apply 422 response
{
  "success": false,
  "outcome": "not_applied",
  "reason": "unsupported_host"
}
reasonWhat it means
unsupported_hostGetMattered does not apply on that hiring system.
posting_not_foundThe employer has no open posting at that link.
import_failedThe posting could not be read.
already_appliedThis job already has an application.
no_employer_postingThe job-board posting was read, and no employer posting GetMattered applies on was found.
account_only_boardThe 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:

StatusBodyWhat to do
400error.code BAD_REQUESTRead error.message. The account has no resume, or the posting was flagged as suspicious.
402"error": "limit_reached", limit.action ai_tokensThe account is out of API tokens. Buy a pack, then call again. See Pricing.
403error.code FORBIDDENThe key was made without "Can send applications". Create a key with it ticked. See Key scopes.
429error.code APPLIES_IN_FLIGHT_LIMIT5 applications started by API are already in progress. Call again once one is sent or held for review.
429error.code RATE_LIMIT_EXCEEDEDThe key made more than 60 calls this minute. See Rate limits.
503error.code SERVICE_UNAVAILABLEThe 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

On this page