Post jobs with the employer API
The employer API lets your HR system or applicant tracking system (ATS) post jobs to GreenHired without retyping them. With a personal key it can read your company and jobs and, when your company owner allows it, create, edit, publish, close and remove jobs. New jobs arrive as drafts, and each one passes the same checks as the recruiter portal before it goes live. It cannot read who applied.
- Drafts by default
- Same checks as the portal
- The owner decides who may use it
From your HR system to the job board
Every call acts as the person who made the key, inside their company and with their role.
Read your company
Your company's public profile and your role in it.
GET /companyList and read jobs
Your company's jobs, in pages of up to 100, or one job in full, with the number of applications. No applicant details.
GET /jobsCreate and edit jobs
Send a job as JSON. It is saved as a draft unless you ask for it to go live. Change fields later, or clear an optional one with null.
POST and PATCH /jobsPublish and reopen
Publish a draft, or reopen a closed job, with an optional closing date.
POST /jobs/{slug}/publishClose or remove
Take a live job off the board and keep it in your list with the status archived, or remove it. A removed job is hidden everywhere and kept for the audit log.
POST /jobs/{slug}/close, DELETE /jobs/{slug}Same rules as the portal
The recruiter portal's rules apply to every write: title and description checks, salary rules, apply link rules, cleaned up HTML, and a check that stops the same job being posted twice. You get the same refusals, in JSON.
Every writeYour company owner decides who can post
A key can change jobs only when the owner has allowed it, and only inside the limits of the role of the person who made it.
- A key needs the jobs:write permission, and the owner must switch on job changes for the company. If an owner switches it off later, writes with that key answer 403 job_writes_off.
- Owners decide which roles may make a key. By default that is owners and HR managers. Owners can see and remove members' connections.
- Owners and HR managers can change any of the company's jobs. A recruiter's key can change only the jobs that recruiter posted.
Create, review, publish, close
Four steps cover the life of a job. The review step can happen in the API or in the portal.
- 01
Create the job
POST /jobs with a title, description, work mode, location and green category. By default you get a draft back.
- 02
Review it
Read it with GET /jobs/{slug}, or open the draft in the recruiter portal.
- 03
Publish it
POST /jobs/{slug}/publish. The portal's checks run, and the job goes live.
- 04
Close it
POST /jobs/{slug}/close when the role is filled. It stays in your list with the status archived.
Post an approved role from your HR system
Northwind Solar keeps its vacancies in an HR system. When a recruiter approves a role there, a small script sends it to GreenHired as a draft, and a second approval publishes it. The company, the people and the role are invented, and the calls and limits are the real ones.
Northwind Solar, employer- Ayesha, an HR manager, makes a key with company:read, jobs:read and jobs:write.
The company owner had switched on job changes, which is what lets the page offer jobs:write. If an owner switches it off later, writes with that key answer 403 job_writes_off.
- The script calls POST /jobs for the approved role.
GreenHired saves a draft and returns its slug. A company can create 20 new jobs a day across all its keys.
- A second approval in the HR system makes the script publish the draft.
The job goes live after the portal's checks. If a check fails, the answer is the same refusal the portal would show, in JSON.
- When the role is filled, the script calls close.
The job leaves the board and stays in the list with the status archived.
Three permissions for employers
You choose them when you make the key.
| Permission | What it allows |
|---|---|
company:read | Your company's public profile and your role in it |
jobs:read | Your company's jobs, one job in full, and how many applications each has. Not applicants |
jobs:write | Create, change, publish, close and remove your company's jobs. Needs jobs:read, and the company owner must switch it on. Only personal keys can do this: an AI assistant connected through MCP cannot |
Each key may make 60 requests a minute, 30 of them changes, and 5,000 requests a day. New jobs have their own cap of 20 a day for the whole company, however many keys it has. Past a limit the API answers 429 with a Retry-After header.
What the API can and cannot do
It can
- Read your company and its jobs
- Create, edit, publish, close and remove jobs when the owner's switch is on
- Run from your own server or an automation tool
- Be removed by you or by the company owner at any time
It cannot
- Read applicants, their CVs or their messages
- See another company
- Skip a check the recruiter portal runs
- Change billing, passwords or team members
Guides and related pages
Post and manage jobs
Every call, every job field and sample requests in curl, JavaScript and Python.
Read your company and jobs
The reference for company and job reads with a personal key.
Company rules
Who may connect an app or make a key, and whether keys may change jobs.
Job posting in the portal
The same jobs, posted by hand in the recruiter portal.
Use an AI assistant instead
Let an assistant read your company's jobs without any code.
Get started as a recruiter
Create a company account and post your first job.
Questions people ask
Who can make an employer key?
People whose company role the owner allows. By default that is owners and HR managers. The owner can also see and remove the keys and connections of members.
Can the API read applicants?
No. There is no permission for applicants, messages or other companies. You can see how many applications a job has, not who applied.
Does the API skip the checks of the portal?
No. Writing a job calls the same code as the recruiter portal, so the title, description, salary and apply-link rules all apply, and you get the same refusals in JSON.
Is a job posted through the API live at once?
Not unless you ask. A new job is a draft unless you send the status active, and publishing runs the same checks as the portal.
Does it work with my applicant tracking system?
The API is a plain web API. Any system or automation tool that can send web requests with a JSON body and an Authorization header can use it. If yours cannot, a developer or an automation tool can sit between the two.
Do I need a developer to use it?
You need someone, or an automation tool, that can send web requests. If you post only a few jobs, the recruiter portal is faster.
Connect your hiring system
Ask your company owner to switch on job changes, make a key and send your first draft. Start with GET /me to check that the key works.