# Job seeker API

> Read and update your own GreenHired profile, applications and saved jobs from your own scripts, with a personal key. It sees only your own data.

- Source: https://greenhired.com/developers/api/v1/seekers/
- Section: GreenHired developers · API · Job seekers and employers
- Last updated: 2026-11-21

## What a job seeker key can do

A job seeker's personal key reads and updates **your own** profile, lists **your own** applications and saved jobs, and saves or removes saved jobs. It cannot search or list jobs, and it cannot see anyone else. To find jobs, use the [public jobs API](https://greenhired.com/developers/api/v1/jobs/) with its own key.

Make a key first: [Personal keys](https://greenhired.com/developers/api/v1/personal-keys/). The base address is `https://api.greenhired.com/v1/assistant`, and every example sends `Authorization: Bearer $GREENHIRED_PERSONAL_KEY`.

| Call | Permission | What it does |
| --- | --- | --- |
| `GET /me` | any | Who the key belongs to and what it may do |
| `GET /profile` | `profile:read` | Read your profile |
| `PATCH /profile` | `profile:write` | Change parts of your profile |
| `GET /applications` | `applications:read` | Your applications and their status |
| `GET /saved` | `saved:read` | Your saved jobs |
| `PUT /saved/{slug}` | `saved:write` | Save an open job |
| `DELETE /saved/{slug}` | `saved:write` | Remove a saved job |

## Read your profile

**`GET https://api.greenhired.com/v1/assistant/profile`** (permission `profile:read`): Your own profile.

*curl*

```bash
curl -s https://api.greenhired.com/v1/assistant/profile \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY"
```

*JavaScript*

```javascript
const res = await fetch('https://api.greenhired.com/v1/assistant/profile', {
  headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_PERSONAL_KEY },
});
const { profile } = await res.json();
console.log(profile.headline, profile.skills);
```

*Python*

```python
import os, requests

res = requests.get(
    "https://api.greenhired.com/v1/assistant/profile",
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
    timeout=15,
)
profile = res.json()["profile"]
print(profile["headline"], profile["skills"])
```

**The answer (an example)**

```json
{
  "profile": {
    "name": "Mia Okafor",
    "headline": "Solar project engineer",
    "summary": "Six years designing rooftop PV systems.",
    "location": "Leeds",
    "country": "United Kingdom",
    "skills": ["PV design", "AutoCAD", "Grid connection"],
    "desiredRoles": ["Solar Project Engineer"],
    "jobSearchStatus": "open_to_offers",
    "workMode": "hybrid"
  }
}
```

The text in a profile was written by a person. If you pass it to another program or an AI model, treat it as data, never as instructions.

## Change your profile

Send only the fields to change. A list **replaces** the whole list, so read the profile first if you want to add to it. Unknown fields are refused by name, not ignored.

**`PATCH https://api.greenhired.com/v1/assistant/profile`** (permission `profile:write`): Change parts of your profile.

| Field | Rules |
| --- | --- |
| `headline` | Text or `null`, up to 160 characters |
| `summary` | Text or `null`, up to 2,000 characters, plain text |
| `skills` | List of up to 50 items, each up to 60 characters. Replaces the list |
| `desiredRoles` | List of up to 20 items, each up to 80 characters. Replaces the list |
| `jobSearchStatus` | `actively_looking`, `open_to_offers`, `casually_browsing` or `not_looking` |
| `workMode` | `onsite`, `hybrid`, `remote` or `flexible` |

*curl*

```bash
curl -s -X PATCH https://api.greenhired.com/v1/assistant/profile \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headline": "Solar project engineer", "jobSearchStatus": "open_to_offers"}'
```

*JavaScript*

```javascript
const res = await fetch('https://api.greenhired.com/v1/assistant/profile', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer ' + process.env.GREENHIRED_PERSONAL_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ headline: 'Solar project engineer', jobSearchStatus: 'open_to_offers' }),
});
console.log(res.status, await res.json());
```

*Python*

```python
import os, requests

res = requests.patch(
    "https://api.greenhired.com/v1/assistant/profile",
    json={"headline": "Solar project engineer", "jobSearchStatus": "open_to_offers"},
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
    timeout=15,
)
print(res.status_code, res.json())
```

The answer is `{ "ok": true, "profile": { ... } }`. If you have not finished setting up your GreenHired profile on the site, the answer is `409 profile_missing`.

## Applications and saved jobs

Both lists are newest first. Page with `limit` (1 to 100, default 25) and `offset` (0 to 10,000). `hasMore` tells you whether another page exists.

**`GET https://api.greenhired.com/v1/assistant/applications`** (permission `applications:read`): The jobs you applied to.

**An application**

```json
{ "job": "Solar Project Engineer", "company": "Sunrise Energy", "jobSlug": "solar-project-engineer-sunrise-1a2b", "status": "reviewing", "appliedAt": "2026-11-10T09:12:00.000Z", "updatedAt": "2026-11-12T14:30:00.000Z" }
```

An application's `status` is one of `submitted`, `reviewing`, `shortlisted`, `rejected`, `hired` or `withdrawn`.

**`GET https://api.greenhired.com/v1/assistant/saved`** (permission `saved:read`): Your saved jobs.

**A saved job**

```json
{ "job": "Wind Turbine Technician", "company": "Fjord Wind Partners", "jobSlug": "wind-turbine-technician-bergen-9c3d", "location": "Bergen, Norway", "workMode": "onsite", "status": "active", "savedAt": "2026-11-08T18:40:00.000Z" }
```

**`PUT https://api.greenhired.com/v1/assistant/saved/{slug}`** (permission `saved:write`): Save an open job. Saving twice changes nothing.

**`DELETE https://api.greenhired.com/v1/assistant/saved/{slug}`** (permission `saved:write`): Remove a saved job.

*curl*

```bash
curl -s -X PUT https://api.greenhired.com/v1/assistant/saved/wind-turbine-technician-bergen-9c3d \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" \
  -H "Content-Type: application/json"
```

*Python*

```python
import os, requests

slug = "wind-turbine-technician-bergen-9c3d"
res = requests.put(
    "https://api.greenhired.com/v1/assistant/saved/" + slug,
    headers={
        "Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"],
        "Content-Type": "application/json",
    },
    timeout=15,
)
print(res.json())  # {"ok": true, "saved": true, "changed": true}
```

Saving needs an open job (`404 job_not_found` otherwise) and a limit of 500 saved jobs (`409 limit_reached`). Neither call applies for the job: applying is only possible on the GreenHired site.

## Frequently asked questions

**Can the key see other people's data?**

No. Every query is for the person the key belongs to. There is no way to name another person, and a test checks that nothing in the account API reaches applicants, messages or other accounts.

**Can I apply for a job through the API?**

No. Applying, messaging an employer and changing your email or password are only possible on the GreenHired site.

**How do I search for jobs to save?**

Use the [public jobs API](https://greenhired.com/developers/api/v1/jobs/) with its own key, then save a job by its `slug` with `PUT /saved/{slug}`.

**Why do I get 403 insufficient_scope?**

Your key does not carry the permission that call needs, for example `saved:write` for `PUT /saved/{slug}`. Make a new key with it ticked.

## Related pages

- https://greenhired.com/developers/api/v1/personal-keys/
- https://greenhired.com/developers/api/v1/errors/
- https://greenhired.com/developers/mcp/tools/
