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

- Source: https://greenhired.com/developers/api/v1/employer-jobs/
- Section: GreenHired developers · API · Job seekers and employers
- Last updated: 2026-11-21

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

> **Info:** Send a JSON body with `Content-Type: application/json`. `publish`, `close` and `DELETE` have no body and need no header.

## Create a job

**`POST https://api.greenhired.com/v1/assistant/jobs`** (permission `jobs:write`): Create a job (a draft by default).

*curl*

```bash
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"
  }'
```

*JavaScript*

```javascript
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);
```

*Python*

```python
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](https://greenhired.com/developers/api/v1/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

*curl*

```bash
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
```

*Python*

```python
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_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.

## Related pages

- https://greenhired.com/developers/api/v1/employers/
- https://greenhired.com/developers/api/v1/company-rules/
- https://greenhired.com/developers/api/v1/errors/
