API reference · Job seekers and employers

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.

2 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. What an employer key can do
  2. Your company
  3. Your jobs
  4. Job statuses
  5. Frequently asked questions

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

CallPermissionWhat it does
GET /meanyWho the key belongs to, your company and your role
GET /companycompany:readYour company's profile and your role
GET /jobsjobs:readYour company's jobs
GET /jobs/{slug}jobs:readOne of your company's jobs, in full
POST /jobs and the restjobs:writeCreate, change, publish, close and remove jobs. See Manage jobs

#Your company

GET/v1/assistant/companyapi.greenhired.comcompany:read

Your company's profile and your role.

curl -s https://api.greenhired.com/v1/assistant/company \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY"
The answer (an example)
JSON
{
  "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

GET/v1/assistant/jobsapi.greenhired.comjobs:read

Your 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"
A job in the list
JSON
{ "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" }
GET/v1/assistant/jobs/{slug}api.greenhired.comjobs:read

One 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

StatusMeaning
draftNot public yet
activeLive on GreenHired
archivedClosed by you; still in your list
expiredPassed its closing date
paused_by_greenhiredPaused 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.