API for recruiters

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
What the employer API does

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 /company

List 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 /jobs

Create 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 /jobs

Publish and reopen

Publish a draft, or reopen a closed job, with an optional closing date.

POST /jobs/{slug}/publish

Close 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 write
Company rules

Your 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.
How a job goes live

Create, review, publish, close

Four steps cover the life of a job. The review step can happen in the API or in the portal.

  1. 01

    Create the job

    POST /jobs with a title, description, work mode, location and green category. By default you get a draft back.

  2. 02

    Review it

    Read it with GET /jobs/{slug}, or open the draft in the recruiter portal.

  3. 03

    Publish it

    POST /jobs/{slug}/publish. The portal's checks run, and the job goes live.

  4. 04

    Close it

    POST /jobs/{slug}/close when the role is filled. It stays in your list with the status archived.

An example

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

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

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

  4. When the role is filled, the script calls close.

    The job leaves the board and stays in the list with the status archived.

Permissions

Three permissions for employers

You choose them when you make the key.

PermissionWhat it allows
company:readYour company's public profile and your role in it
jobs:readYour company's jobs, one job in full, and how many applications each has. Not applicants
jobs:writeCreate, 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.

Limits and safety

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
Questions

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.