API for job seekers

Read your own data with the job seeker API

The job seeker API lets a script you write read and update your own GreenHired profile, and list your applications and saved jobs. Use it to keep a spreadsheet or dashboard current without copying by hand. You make a personal key, a secret code that acts as you, in your account, and choose what it may do. It does not search jobs: for that, use the public jobs API or the MCP server.

  • You make the key yourself
  • It cannot search jobs
What your key can do

What the job seeker API can do

Every call acts on your own account, with the permissions you ticked when you made the key.

Read your profile

Your headline, summary, skills, job search status and the other fields in the table below. Not your email, phone, CV or password.

GET /profile

Update parts of it

Change the fields that profile:write covers, if you allowed it.

PATCH /profile

List your applications

The jobs you applied to and where each one stands, in pages of up to 100. Not your CV, cover letter, answers or messages.

GET /applications

Read your saved jobs

The jobs you saved, in pages of up to 100, ready to copy into a tracker or a spreadsheet.

GET /saved

Save and remove jobs

Save an open job by its slug, the last part of the job's web address, or take one off your list. You can keep up to 500.

PUT and DELETE /saved/{slug}
Your key

Make a key on the Connected apps page

You name the key, tick permissions, choose how long it lasts and copy it. It is shown once. GreenHired does not store the key itself, so it cannot show it again.

  • Name it for its job, such as my job tracker.
  • Write permissions are never ticked for you.
  • It stops working after 30, 90, 180 or 365 days, and 90 is the default.
  • GreenHired also emails you a notice that a key was made. The email never contains the key.
An example

Sam keeps a job tracker up to date

Sam keeps a spreadsheet of green jobs. A small script runs each morning with a key that can only read applications and saved jobs, so a leaked key could not change anything. Sam and the script are invented, and the calls and limits are the real ones.

Sam, job seeker
  1. Sam makes a key with applications:read and saved:read.

    The key can read two lists and nothing else. It cannot change the profile or save a job.

  2. The script calls GET /applications and GET /saved.

    Each call returns JSON, the plain text format scripts read, with up to 100 jobs and a hasMore flag. Sam's script makes a few calls a day, far under the limits of 60 a minute and 1,000 a day.

  3. The script writes the rows into the spreadsheet.

    It keeps asking for the next page while hasMore is true, so Sam sees every application and saved job in one place. If the laptop is lost, pressing Remove on Connected apps stops the key at once.

Permissions

The five permissions you can tick

You choose them when you make the key.

PermissionWhat it allows
profile:readYour name, headline, summary, location, skills, desired roles, job search status and work mode
profile:writeChange your headline, summary, skills, desired roles, job search status and work mode
applications:readThe jobs you applied to and where each one stands
saved:readYour saved jobs
saved:writeSave an open job or remove a saved job

A write permission brings its read permission with it. You can keep up to 5 live keys, each with its own permissions. There is no permission for messages, passwords or anyone else's data.

Limits and safety

What a key can and cannot do

It can

  • Act on your own account only
  • Read and change only what you ticked
  • Make 60 requests a minute, 30 of them changes, and 1,000 requests a day

It cannot

  • Search or list jobs. Use the public jobs API for that
  • Apply to a job or send a message
  • Read your email address, phone number, CV or password
  • See anyone else's data
Questions

Questions people ask

Is it safe to make a key?

It is as safe as you keep it. Treat the key like a password and keep it out of web pages and shared files. The key sees only your own data and only what you ticked, and it stops when it expires or when you remove it.

Can the API search for jobs?

No. A personal key reads and updates your own data. To search jobs, use the public jobs API, which has its own key that the GreenHired team issues on request, or ask an AI assistant through the MCP server.

Do I need to know how to code?

A little. The API answers in JSON, so you call it from a script, a command line or a no-code tool that can send web requests. If you only want an assistant to do the work, use the MCP server instead.

What if I lose a key?

Remove it on the Connected apps page and make a new one. A removed key stops working at once.

Where do I put the key when I call the API?

Send it in an Authorization header as a bearer token. Call the API from your own server or computer, never from a web page, because a key in browser code can be read by every visitor.

Do I need a GreenHired account?

Yes, a job seeker account, because the key acts as you. You make the key on the Connected apps page after you sign in.

Make your first key

Open Connected apps, make a key and call GET /me to check that it works. You can remove it whenever you like.