API reference · Job seekers and employers

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.

2 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. What a job seeker key can do
  2. Read your profile
  3. Change your profile
  4. Applications and saved jobs
  5. Frequently asked questions

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

CallPermissionWhat it does
GET /meanyWho the key belongs to and what it may do
GET /profileprofile:readRead your profile
PATCH /profileprofile:writeChange parts of your profile
GET /applicationsapplications:readYour applications and their status
GET /savedsaved:readYour saved jobs
PUT /saved/{slug}saved:writeSave an open job
DELETE /saved/{slug}saved:writeRemove a saved job

#Read your profile

GET/v1/assistant/profileapi.greenhired.comprofile:read

Your own profile.

curl -s https://api.greenhired.com/v1/assistant/profile \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY"
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/v1/assistant/profileapi.greenhired.comprofile:write

Change parts of your profile.

FieldRules
headlineText or null, up to 160 characters
summaryText or null, up to 2,000 characters, plain text
skillsList of up to 50 items, each up to 60 characters. Replaces the list
desiredRolesList of up to 20 items, each up to 80 characters. Replaces the list
jobSearchStatusactively_looking, open_to_offers, casually_browsing or not_looking
workModeonsite, 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"}'

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/v1/assistant/applicationsapi.greenhired.comapplications: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/v1/assistant/savedapi.greenhired.comsaved: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/v1/assistant/saved/{slug}api.greenhired.comsaved:write

Save an open job. Saving twice changes nothing.

DELETE/v1/assistant/saved/{slug}api.greenhired.comsaved:write

Remove 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"

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