# 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).