API reference · Job seekers and employers

Manage jobs with the API

Create, edit, publish, close and remove your company's jobs from your own systems with a personal key. Drafts by default, the same checks as the portal.

4 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. Before you start
  2. Create a job
  3. Fields
  4. Change, publish, close and remove
  5. Limits and rules
  6. Frequently asked questions

#Before you start

Managing jobs needs three things: a personal key with the jobs:write permission, a company owner who has switched on job changes for the company, and a company role that may work on jobs (owner, HR manager or recruiter). Without the owner's switch the answer is 403 job_writes_off.

Writing a job calls the same code as the recruiter portal, so every portal rule applies: the title and description checks before a job goes live, the salary rules, the apply-link and notification-email rules, HTML sanitising, a double-post guard, and the public copy staying in step. You get the same refusals, in JSON.

CallWhat it does
POST /jobsCreate a job. A draft unless you send "status": "active"
PATCH /jobs/{slug}Change fields. null clears an optional field. The status cannot be set here
POST /jobs/{slug}/publishPublish a draft, or reopen a closed job. Optional { "expiresAt": "2026-12-31" }
POST /jobs/{slug}/closeTake a live job off the board. It stays in your list as closed
DELETE /jobs/{slug}Remove the job: hidden everywhere, kept for the audit log

#Create a job

POST/v1/assistant/jobsapi.greenhired.comjobs:write

Create a job (a draft by default).

curl -s -X POST https://api.greenhired.com/v1/assistant/jobs \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Solar Project Engineer",
    "description": "Design and manage rooftop solar projects for schools.\n\nYou will work with our install teams.",
    "employmentType": "full-time",
    "workMode": "hybrid",
    "country": "United Kingdom",
    "city": "Leeds",
    "greenCategory": "renewable-energy",
    "skillsTags": ["PV design", "Project management"],
    "salaryMin": 45000, "salaryMax": 55000, "salaryCurrency": "GBP", "salaryPeriod": "year"
  }'

The answer is 201 with { "ok": true, "duplicate": false, "job": { ... } }. If the same job was posted a moment ago (a retry or a double click), you get 200 with "duplicate": true and the job that already exists, and nothing new is created.

A plain-text description becomes paragraphs (a blank line starts a new one). A description that contains HTML tags is cleaned by the same sanitiser the portal uses: scripts and event handlers are removed.

#Fields

Only these fields are accepted. Anything else is a 400 invalid_job that names the field, so a typo or an attempt to set something you may not never goes through silently.

FieldRules
titleRequired. Up to 200 characters
descriptionPlain text or simple HTML, up to 60,000 characters. Required to publish
requirements, benefitsText or null, up to 5,000 characters each
departmentText or null, up to 80 characters
employmentTypefull-time, part-time, contract, internship or freelance
seniorityentry, mid, senior, lead, director or executive, or null
experienceYearsWhole number 0 to 60, or null
openingsWhole number 1 to 999
workModeonsite, hybrid or remote
locationRaw, city, state, countryText or null, up to 160 (locationRaw) or 80 characters
salaryMin, salaryMaxWhole numbers 0 to 1,000,000,000, or null. The range must be the right way round
salaryCurrency, salaryPeriodA 3-letter currency code; year, month or hour
applyTypeinternal (apply on GreenHired) or external (send to your own page)
applyUrlA web address. Required to publish an external job
applyEmailAn email address of a teammate with a GreenHired account, who is notified of new applications
applyInstructionsText or null, up to 2,000 characters
expiresAtA date (2026-12-31) or Unix seconds, in the future, or null
skillsTagsList of up to 30 skills, each up to 60 characters
greenCategoryA category slug from Categories. It decides where the job appears and how candidates are matched
statusOn create only: draft (default) or active

#Change, publish, close and remove

SLUG=solar-project-engineer-sunrise-1a2b
H=(-H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY" -H "Content-Type: application/json")
BASE=https://api.greenhired.com/v1/assistant

# change a field
curl -s -X PATCH "${H[@]}" -d '{"department": "Delivery", "openings": 2}' $BASE/jobs/$SLUG
# publish the draft
curl -s -X POST "${H[@]}" $BASE/jobs/$SLUG/publish
# close it (it stays in your list)
curl -s -X POST "${H[@]}" $BASE/jobs/$SLUG/close
# remove it
curl -s -X DELETE "${H[@]}" $BASE/jobs/$SLUG

Each of these answers with the updated job ({ "ok": true, "job": { ... } }), except DELETE, which answers { "ok": true, "removed": true }. Publishing a draft that is not fit to go live is a 400 invalid_job that says why, for example a missing description. A removed job cannot be changed or brought back.

#Limits and rules

  • A company can create 20 new jobs a day through the API, for all its keys together (resets at 00:00 UTC). Past that the answer is 429 company_job_cap with Retry-After. A repeat of the same job and a refused job do not use the allowance. Changing, publishing, closing and removing are not counted.
  • A recruiter can change only the jobs that recruiter posted. Owners and HR managers can change any of the company's jobs.
  • A job that GreenHired has paused (paused_by_greenhired) cannot be changed, published or removed from the API: 403 admin_hold.
  • A suspended company, and a company that requires two-factor sign-in when you have not turned it on, cannot change anything.
  • Every change is written to your company's audit log with the key's name and the names of the fields changed, never the job text.
  • AI assistants can never change jobs. Only a personal key can.

#Frequently asked questions

Why do I get 403 job_writes_off?
A company owner has not switched on job changes for the company. Owners do it under Company, then Connected app, with the setting "Let API keys create and change our jobs". It is off by default.
Does a new job go live straight away?
Only if you send "status": "active" and it passes the same checks as the portal. Without status the job is a draft, and POST /jobs/{slug}/publish makes it live.
What happens if my script retries a create?
If the same post was made a moment ago you get 200 with "duplicate": true and the existing job. You do not get a second copy, and it does not use your daily allowance.
Can I set a job's status with PATCH?
No. Use publish and close. Sending status to PATCH is a 400 that tells you to use those endpoints.
Does it work for jobs I post in the portal?
Yes. Jobs created in the recruiter portal and through the API are the same jobs. You can create in one place and change in the other, within the role rules above.