Employer API
Read your company profile and jobs with a personal key, and (when your owner allows it) manage jobs from your own systems. It never reaches applicants.
#What an employer key can do
An employer's personal key reads your company's profile and jobs and, if your company owner has switched it on, creates and manages jobs. It acts as you, inside your company, with your role. It cannot read applicants or messages, and it cannot see another company.
Make a key first: Personal keys. The base address is https://api.greenhired.com/v1/assistant.
| Call | Permission | What it does |
|---|---|---|
GET /me | any | Who the key belongs to, your company and your role |
GET /company | company:read | Your company's profile and your role |
GET /jobs | jobs:read | Your company's jobs |
GET /jobs/{slug} | jobs:read | One of your company's jobs, in full |
POST /jobs and the rest | jobs:write | Create, change, publish, close and remove jobs. See Manage jobs |
#Your company
/v1/assistant/companyapi.greenhired.comcompany:readYour company's profile and your role.
curl -s https://api.greenhired.com/v1/assistant/company \
-H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" const res = await fetch('https://api.greenhired.com/v1/assistant/company', {
headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_PERSONAL_KEY },
});
const { company, yourRole } = await res.json(); import os, requests
res = requests.get(
"https://api.greenhired.com/v1/assistant/company",
headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
timeout=15,
)
data = res.json()
print(data["company"]["name"], data["yourRole"]) {
"company": {
"name": "Sunrise Energy", "slug": "sunrise-energy", "tagline": "Rooftop solar for schools",
"description": "We design and install solar on public buildings.", "website": "https://sunrise.example",
"industry": "Energy", "size": "11-50", "location": "Leeds", "country": "United Kingdom", "foundedYear": 2019, "verified": true
},
"yourRole": "hr_manager"
} #Your jobs
/v1/assistant/jobsapi.greenhired.comjobs:readYour company's jobs, newest first.
Optional parameters: status (a word such as active, draft, expired or archived), limit (1 to 100, default 25) and offset. Removed jobs are never listed.
curl -s "https://api.greenhired.com/v1/assistant/jobs?status=active&limit=50" \
-H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" import os, requests
res = requests.get(
"https://api.greenhired.com/v1/assistant/jobs",
params={"status": "active", "limit": 50},
headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
timeout=15,
)
for job in res.json()["jobs"]:
print(job["jobSlug"], job["status"], job["applications"]) { "title": "Solar Project Engineer", "jobSlug": "solar-project-engineer-sunrise-1a2b", "status": "active", "postedAt": "2026-11-10T09:00:00.000Z", "expiresAt": "2027-01-09T09:00:00.000Z", "applications": 7, "workMode": "hybrid", "employmentType": "full-time", "location": "Leeds, United Kingdom" } /v1/assistant/jobs/{slug}api.greenhired.comjobs:readOne of your company's jobs, in full.
The detail has the posting's own text (description as plain text, requirements, benefits), the fields you can set, the dates, views and the number of applications. applyEmail appears only to a personal key, never to an AI assistant. A job of another company, or a removed job, is 404 job_not_found.
#Job statuses
| Status | Meaning |
|---|---|
draft | Not public yet |
active | Live on GreenHired |
archived | Closed by you; still in your list |
expired | Passed its closing date |
paused_by_greenhired | Paused by the GreenHired team. You cannot change it from the API |
#Frequently asked questions
- Can I get my applicants through the API?
- No. Applicants and messages are deliberately not in the account API, for keys and for AI assistants. Use the applicant pipeline in your recruiter account.
- Why does my key answer 403 blocked_by_company?
- Your company owner has limited who may connect apps and keys, and your role is not included. Ask an owner to change it under Company, then Connected app. See Company rules.
- Does the key act as me?
- Yes. It has your company role. A recruiter's key can change only the jobs that recruiter posted; owners and HR managers can change any of the company's jobs.
- Can one key serve a whole team?
- Make one key per integration, under the account of the person who owns it. Keys end if that person leaves the company or changes role.
Was this page helpful?