API reference · Start here

Make your first request

Call the GreenHired API in five minutes: check your key, list jobs in a category and read your own account with a personal key. Code in curl, JS and Python.

2 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. Before you start
  2. Check that your key works
  3. List jobs
  4. Read your own account
  5. Where to go next
  6. Frequently asked questions

#Before you start

You need a key. For the public jobs API that is a ghk_ key, which the GreenHired team issues on request (see Authentication). For your own account it is a ghpk_ personal key, which you make yourself in about a minute (see Personal keys).

The examples read the key from an environment variable, so it never ends up in your code or your shell history:

curl
export GREENHIRED_API_KEY="ghk_paste_your_key_here"

#Check that your key works

GET /v1/ping accepts any valid key, counts as one request, and tells you whose key it is, which permissions it has, its limits and what you have used.

GET/v1/pingapi.greenhired.comany valid key

Check your key. Needs any valid key.

curl -s https://api.greenhired.com/v1/ping \
  -H "Authorization: Bearer $GREENHIRED_API_KEY"

A good answer looks like this (the numbers are an example):

JSON
{
  "ok": true,
  "key": { "name": "My app", "scopes": ["jobs:read", "categories:read"] },
  "limits": { "requests_per_minute": 60, "requests_per_day": 5000 },
  "usage": {
    "minute": { "used": 1, "remaining": 59, "resets_in_seconds": 42 },
    "today": { "used": 1, "remaining": 4999 }
  }
}

If you get a 401, the key is missing, wrong or revoked. If you get a 503 api_disabled, the API is switched off at the moment.

#List jobs

This asks for the five newest remote jobs in the renewable energy category. Filters are optional and can be combined.

GET/v1/jobsapi.greenhired.comjobs:read

List jobs, newest first.

curl -s "https://api.greenhired.com/v1/jobs?category=renewable-energy&work_mode=remote&limit=5" \
  -H "Authorization: Bearer $GREENHIRED_API_KEY"

Each job has a url on greenhired.com. When you show a job anywhere, link to that url next to it. See Attribution. To get the next page, send page.next_cursor back as cursor with the same filters: see Pagination.

#Read your own account

A personal key works against the account API. This call says who the key belongs to and what it may do:

GET/v1/assistant/meapi.greenhired.comany valid key

Who am I. Needs any valid personal key.

curl -s https://api.greenhired.com/v1/assistant/me \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY"
A job seeker's answer
JSON
{ "type": "job_seeker", "name": "Mia", "key": "my job tracker", "scopes": ["profile:read", "saved:read"] }

#Where to go next

#Frequently asked questions

Why do I get 401 on a request that worked yesterday?
The key was revoked, it expired (personal keys last 90 days unless you chose otherwise), or it is a personal key and the account password changed. A password change ends every personal key. Make a new one.
How many requests do I get?
Public API keys default to 60 a minute and 5,000 a day, and your key may differ: GET /v1/ping shows yours. Personal keys have their own limits. See Rate limits.
Does ping count against my limit?
Yes. It counts as one request. It is still the quickest way to see your key's name, permissions, limits and what you have used.
Which language should I use?
Any. It is plain HTTPS and JSON. The examples use curl, JavaScript (Node 18 or later) and Python with the requests package.