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.
On this page
#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:
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.
/v1/pingapi.greenhired.comany valid keyCheck your key. Needs any valid key.
curl -s https://api.greenhired.com/v1/ping \
-H "Authorization: Bearer $GREENHIRED_API_KEY" const res = await fetch('https://api.greenhired.com/v1/ping', {
headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY },
});
console.log(await res.json()); import os, requests
res = requests.get(
"https://api.greenhired.com/v1/ping",
headers={"Authorization": "Bearer " + os.environ["GREENHIRED_API_KEY"]},
timeout=15,
)
print(res.json()) A good answer looks like this (the numbers are an example):
{
"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.
/v1/jobsapi.greenhired.comjobs:readList 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" const url = 'https://api.greenhired.com/v1/jobs?category=renewable-energy&work_mode=remote&limit=5';
const res = await fetch(url, { headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY } });
const { data, page } = await res.json();
for (const job of data) console.log(job.title, '-', job.url);
console.log('more pages:', page.has_more); import os, requests
res = requests.get(
"https://api.greenhired.com/v1/jobs",
params={"category": "renewable-energy", "work_mode": "remote", "limit": 5},
headers={"Authorization": "Bearer " + os.environ["GREENHIRED_API_KEY"]},
timeout=15,
)
res.raise_for_status()
body = res.json()
for job in body["data"]:
print(job["title"], "-", job["url"])
print("more pages:", body["page"]["has_more"]) 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:
/v1/assistant/meapi.greenhired.comany valid keyWho am I. Needs any valid personal key.
curl -s https://api.greenhired.com/v1/assistant/me \
-H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" const res = await fetch('https://api.greenhired.com/v1/assistant/me', {
headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_PERSONAL_KEY },
});
console.log(await res.json()); import os, requests
res = requests.get(
"https://api.greenhired.com/v1/assistant/me",
headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
timeout=15,
)
print(res.json()) { "type": "job_seeker", "name": "Mia", "key": "my job tracker", "scopes": ["profile:read", "saved:read"] } #Where to go next
- Job seekers: Job seeker API
- Employers: Employer API and Manage jobs
- Apps and partners: List jobs, Categories and Salary statistics
- AI assistants: MCP server
#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/pingshows 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
requestspackage.
Was this page helpful?