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.
On this page
#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 with its own key.
Make a key first: 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
/v1/assistant/profileapi.greenhired.comprofile:readYour own profile.
curl -s https://api.greenhired.com/v1/assistant/profile \
-H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" 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); 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"]) {
"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.
/v1/assistant/profileapi.greenhired.comprofile:writeChange 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 -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"}' 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()); 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.
/v1/assistant/applicationsapi.greenhired.comapplications:readThe jobs you applied to.
{ "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.
/v1/assistant/savedapi.greenhired.comsaved:readYour saved jobs.
{ "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" } /v1/assistant/saved/{slug}api.greenhired.comsaved:writeSave an open job. Saving twice changes nothing.
/v1/assistant/saved/{slug}api.greenhired.comsaved:writeRemove a saved job.
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" 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 with its own key, then save a job by its
slugwithPUT /saved/{slug}. - Why do I get 403 insufficient_scope?
- Your key does not carry the permission that call needs, for example
saved:writeforPUT /saved/{slug}. Make a new key with it ticked.
Was this page helpful?