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