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.
On this page
#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.
| Call | What it does |
|---|---|
POST /jobs | Create 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}/publish | Publish a draft, or reopen a closed job. Optional { "expiresAt": "2026-12-31" } |
POST /jobs/{slug}/close | Take 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
/v1/assistant/jobsapi.greenhired.comjobs:writeCreate 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"
}' const res = await fetch('https://api.greenhired.com/v1/assistant/jobs', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.GREENHIRED_PERSONAL_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Solar Project Engineer',
description: 'Design and manage rooftop solar projects for schools.',
employmentType: 'full-time',
workMode: 'hybrid',
country: 'United Kingdom',
city: 'Leeds',
greenCategory: 'renewable-energy',
}),
});
const { job, duplicate } = await res.json();
console.log(res.status, job.jobSlug, job.status, duplicate); import os, requests
res = requests.post(
"https://api.greenhired.com/v1/assistant/jobs",
json={
"title": "Solar Project Engineer",
"description": "Design and manage rooftop solar projects for schools.",
"employmentType": "full-time",
"workMode": "hybrid",
"country": "United Kingdom",
"city": "Leeds",
"greenCategory": "renewable-energy",
},
headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
timeout=30,
)
body = res.json()
print(res.status_code, body["job"]["jobSlug"], body["job"]["status"], body["duplicate"]) 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.
| Field | Rules |
|---|---|
title | Required. Up to 200 characters |
description | Plain text or simple HTML, up to 60,000 characters. Required to publish |
requirements, benefits | Text or null, up to 5,000 characters each |
department | Text or null, up to 80 characters |
employmentType | full-time, part-time, contract, internship or freelance |
seniority | entry, mid, senior, lead, director or executive, or null |
experienceYears | Whole number 0 to 60, or null |
openings | Whole number 1 to 999 |
workMode | onsite, hybrid or remote |
locationRaw, city, state, country | Text or null, up to 160 (locationRaw) or 80 characters |
salaryMin, salaryMax | Whole numbers 0 to 1,000,000,000, or null. The range must be the right way round |
salaryCurrency, salaryPeriod | A 3-letter currency code; year, month or hour |
applyType | internal (apply on GreenHired) or external (send to your own page) |
applyUrl | A web address. Required to publish an external job |
applyEmail | An email address of a teammate with a GreenHired account, who is notified of new applications |
applyInstructions | Text or null, up to 2,000 characters |
expiresAt | A date (2026-12-31) or Unix seconds, in the future, or null |
skillsTags | List of up to 30 skills, each up to 60 characters |
greenCategory | A category slug from Categories. It decides where the job appears and how candidates are matched |
status | On 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 import os, requests
base = "https://api.greenhired.com/v1/assistant"
headers = {"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"], "Content-Type": "application/json"}
slug = "solar-project-engineer-sunrise-1a2b"
requests.patch(f"{base}/jobs/{slug}", json={"department": "Delivery", "openings": 2}, headers=headers, timeout=30)
requests.post(f"{base}/jobs/{slug}/publish", headers=headers, timeout=30)
requests.post(f"{base}/jobs/{slug}/close", headers=headers, timeout=30)
requests.delete(f"{base}/jobs/{slug}", headers=headers, timeout=30) 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_capwithRetry-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. Withoutstatusthe job is a draft, andPOST /jobs/{slug}/publishmakes it live. - What happens if my script retries a create?
- If the same post was made a moment ago you get
200with"duplicate": trueand 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
publishandclose. SendingstatustoPATCHis a400that 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.
Was this page helpful?