# Employer API

> Read your company profile and jobs with a personal key, and (when your owner allows it) manage jobs from your own systems. It never reaches applicants.

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

## What an employer key can do

An employer's personal key reads your company's profile and jobs and, if your company owner has switched it on, creates and manages jobs. It acts as you, inside your company, with your role. It cannot read applicants or messages, and it cannot see another company.

Make a key first: [Personal keys](https://greenhired.com/developers/api/v1/personal-keys/). The base address is `https://api.greenhired.com/v1/assistant`.

| Call | Permission | What it does |
| --- | --- | --- |
| `GET /me` | any | Who the key belongs to, your company and your role |
| `GET /company` | `company:read` | Your company's profile and your role |
| `GET /jobs` | `jobs:read` | Your company's jobs |
| `GET /jobs/{slug}` | `jobs:read` | One of your company's jobs, in full |
| `POST /jobs` and the rest | `jobs:write` | Create, change, publish, close and remove jobs. See [Manage jobs](https://greenhired.com/developers/api/v1/employer-jobs/) |

> **Info:** Which people in a company may use a key, and whether a key may change jobs, is decided by the company owner. See [Company rules](https://greenhired.com/developers/api/v1/company-rules/).

## Your company

**`GET https://api.greenhired.com/v1/assistant/company`** (permission `company:read`): Your company's profile and your role.

*curl*

```bash
curl -s https://api.greenhired.com/v1/assistant/company \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY"
```

*JavaScript*

```javascript
const res = await fetch('https://api.greenhired.com/v1/assistant/company', {
  headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_PERSONAL_KEY },
});
const { company, yourRole } = await res.json();
```

*Python*

```python
import os, requests

res = requests.get(
    "https://api.greenhired.com/v1/assistant/company",
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
    timeout=15,
)
data = res.json()
print(data["company"]["name"], data["yourRole"])
```

**The answer (an example)**

```json
{
  "company": {
    "name": "Sunrise Energy", "slug": "sunrise-energy", "tagline": "Rooftop solar for schools",
    "description": "We design and install solar on public buildings.", "website": "https://sunrise.example",
    "industry": "Energy", "size": "11-50", "location": "Leeds", "country": "United Kingdom", "foundedYear": 2019, "verified": true
  },
  "yourRole": "hr_manager"
}
```

## Your jobs

**`GET https://api.greenhired.com/v1/assistant/jobs`** (permission `jobs:read`): Your company's jobs, newest first.

Optional parameters: `status` (a word such as `active`, `draft`, `expired` or `archived`), `limit` (1 to 100, default 25) and `offset`. Removed jobs are never listed.

*curl*

```bash
curl -s "https://api.greenhired.com/v1/assistant/jobs?status=active&limit=50" \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY"
```

*Python*

```python
import os, requests

res = requests.get(
    "https://api.greenhired.com/v1/assistant/jobs",
    params={"status": "active", "limit": 50},
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
    timeout=15,
)
for job in res.json()["jobs"]:
    print(job["jobSlug"], job["status"], job["applications"])
```

**A job in the list**

```json
{ "title": "Solar Project Engineer", "jobSlug": "solar-project-engineer-sunrise-1a2b", "status": "active", "postedAt": "2026-11-10T09:00:00.000Z", "expiresAt": "2027-01-09T09:00:00.000Z", "applications": 7, "workMode": "hybrid", "employmentType": "full-time", "location": "Leeds, United Kingdom" }
```

**`GET https://api.greenhired.com/v1/assistant/jobs/{slug}`** (permission `jobs:read`): One of your company's jobs, in full.

The detail has the posting's own text (description as plain text, requirements, benefits), the fields you can set, the dates, views and the number of applications. `applyEmail` appears only to a personal key, never to an AI assistant. A job of another company, or a removed job, is `404 job_not_found`.

## Job statuses

| Status | Meaning |
| --- | --- |
| `draft` | Not public yet |
| `active` | Live on GreenHired |
| `archived` | Closed by you; still in your list |
| `expired` | Passed its closing date |
| `paused_by_greenhired` | Paused by the GreenHired team. You cannot change it from the API |

## Frequently asked questions

**Can I get my applicants through the API?**

No. Applicants and messages are deliberately not in the account API, for keys and for AI assistants. Use the applicant pipeline in your recruiter account.

**Why does my key answer 403 blocked_by_company?**

Your company owner has limited who may connect apps and keys, and your role is not included. Ask an owner to change it under Company, then Connected app. See [Company rules](https://greenhired.com/developers/api/v1/company-rules/).

**Does the key act as me?**

Yes. It has your company role. A recruiter's key can change only the jobs that recruiter posted; owners and HR managers can change any of the company's jobs.

**Can one key serve a whole team?**

Make one key per integration, under the account of the person who owns it. Keys end if that person leaves the company or changes role.

## Related pages

- https://greenhired.com/developers/api/v1/employer-jobs/
- https://greenhired.com/developers/api/v1/company-rules/
- https://greenhired.com/developers/api/v1/personal-keys/
