> ## Documentation Index
> Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ATS Integrations

> Connect Greenhouse and Ashby to import jobs and exchange assessment results

# ATS Integrations

Connect your Applicant Tracking System (Greenhouse or Ashby) to Gradient. Two
independent capabilities:

* **Job import** — Gradient holds your ATS API key and reads your jobs and
  candidates, so you can seed roles from real job descriptions and pull
  candidates in.
* **Assessment partner** — you paste a Gradient-minted partner key into your ATS,
  and the ATS starts Gradient assessments and receives the scores back.

These endpoints are admin-only and used by the Settings → Integrations UI. The
feature is gated per organization; contact Gradient to enable it.

## Connection status

```
GET /api/settings/integrations
```

Returns the connection + partner-key status for every supported provider. Never
returns any secret — only the last four characters of a connected key and the
non-secret partner-key prefix.

## Connect a provider

```
POST /api/settings/integrations/:provider
```

`:provider` is `greenhouse`, `ashby`, or `workday`. The credential is validated
with a live call before it is stored (encrypted at rest).

<ParamField body="apiKey" type="string" required>
  The provider credential. Greenhouse: a Harvest API key. Ashby: an API key with
  job and application read access. Workday: a JSON string
  `{ tenant, host, clientId, clientSecret, refreshToken }` for an OAuth API client
  with Recruiting read scope.
</ParamField>

## Disconnect a provider

```
DELETE /api/settings/integrations/:provider
```

Removes the stored key for that provider.

## Health check

```
POST /api/settings/integrations/:provider/check
```

Probes the provider live with the stored key and returns `{ ok: boolean }`,
updating the connection status.

## Partner key — info

```
GET /api/settings/integrations/:provider/partner-key
```

Returns the non-secret prefix of the minted partner key, or `null` if none has
been minted for this provider. `:provider` must be `greenhouse` or `ashby` —
Workday has no assessment-partner framework.

## Partner key — mint or rotate

```
POST /api/settings/integrations/:provider/partner-key
```

Mints (or rotates) the assessment-partner key you paste into your ATS
(`greenhouse` or `ashby` only). Returns the full key **once** in the response;
any previously minted key stops working immediately.

## Search ATS jobs

```
GET /api/ats/jobs
```

Search open jobs on the connected provider, for the role-import picker.

<ParamField query="provider" type="string" required>
  `greenhouse` or `ashby`.
</ParamField>

<ParamField query="q" type="string">
  Case-insensitive title filter. Omit to list all open jobs.
</ParamField>

<ParamField query="id" type="string">
  When present, returns that single job's full detail (including the job
  description body) instead of a search list.
</ParamField>

## Link a role to an ATS job

```
POST /api/roles/:id/ats-link
```

<ParamField body="provider" type="string" required>
  `greenhouse` or `ashby`.
</ParamField>

<ParamField body="jobId" type="string" required>
  The ATS job id to link this role to.
</ParamField>

<ParamField body="jobName" type="string">
  A display name for the linked job. Defaults to the job id.
</ParamField>

## Unlink a role

```
DELETE /api/roles/:id/ats-link
```

Clears the role's ATS job link.

## List candidates on a role's linked job

```
GET /api/roles/:id/ats-candidates
```

Returns the candidates (applications) on the ATS job this role is linked to, each
flagged with whether it is already imported into Gradient.

## Pull candidates into Gradient

```
POST /api/roles/:id/ats-candidates
```

Imports the selected applications as Gradient candidates, deduped on their ATS
application id.

<ParamField body="applicationIds" type="string[]" required>
  The ATS application ids to import.
</ParamField>