API Reference

The Everyday Vacancies API provides read-only access to Zimbabwe's leading job aggregation platform. All responses are JSON. Every request must include a valid developer API key.

Base URLhttps://api.everydayvacancies.co.zw

Versionv1.0

Specopenapi.json

Authentication

All endpoints require an X-API-Key HTTP header containing a Developer API key issued through your developer dashboard. Keys are prefixed with ev_.

Employer account required. Developer access is only available to Employer (company) accounts on Everyday Vacancies. If you signed up as a job seeker you must convert your account before you can activate developer access.

Developer accounts also require Multi-Factor Authentication (MFA) to be active. If you remove MFA from your account, your developer account is automatically deactivated and all keys stop working immediately.

How to authenticate

curl https://api.everydayvacancies.co.zw/jobs/ \
  -H "X-API-Key: ev_your_key_here"

const res = await fetch(
  'https://api.everydayvacancies.co.zw/jobs/',
  { headers: { 'X-API-Key': 'ev_your_key_here' } }
);
const data = await res.json();

import httpx

headers = {"X-API-Key": "ev_your_key_here"}
resp = httpx.get(
    "https://api.everydayvacancies.co.zw/jobs/",
    headers=headers,
)
data = resp.json()

401 response (missing / invalid key)

{
  "detail": "Unauthorized"
}

Rate limits

Limits are enforced per API key (not per IP).

Window	Limit
Per hour	100 requests
Per day	1 000 requests

When either limit is exceeded the API returns HTTP 429:

HTTP/1.1 429 Too Many Requests

{ "detail": "Ratelimited" }

Limits reset on a rolling window. To stay within limits, cache responses locally and use page_size efficiently.

Error codes

Status	When it occurs	Body
401	Missing, invalid, or revoked API key; developer account inactive; MFA removed; or account is not an Employer account	`{"detail": "Unauthorized"}`
404	Requested resource does not exist (wrong slug, unpublished job, etc.)	`{"detail": "Job not found."}`
422	Invalid query parameter value (e.g. non-integer page number)	`{"detail": [{"loc": ["query", "page"], "msg": "..."}]}`
429	Rate limit exceeded (100/hour or 1 000/day per key)	`{"detail": "Ratelimited"}`
500	Unexpected server error	`{"detail": "Internal server error"}`

Pagination

All list endpoints return a paginated envelope:

{
  "count": 412,          // total matching records
  "page": 1,             // current page (1-based)
  "page_size": 20,       // records returned this page
  "total_pages": 21,     // total number of pages
  "results": [ … ]       // array of objects
}

Parameter	Type	Default	Max	Description
`page`	int	1	—	Page number (≥ 1)
`page_size`	int	20	100	Records per page

GET /jobs/ List published jobs

Returns a paginated list of all published, active DetailedJobPosting records, ordered by premium status then recency.

Query parameters

Name	Type	Description
`page`	int	Page number (default: 1)
`page_size`	int	Results per page (default: 20, max: 100)
`category`	string	Filter by category slug (e.g. `engineering`)
`job_type`	string	`full_time` · `part_time` · `contract` · `freelance` · `internship`
`experience_level`	string	`entry` · `mid` · `senior` · `executive`
`location`	string	Partial match against location (e.g. `Harare`)
`is_remote`	bool	`true` or `false`
`search`	string	Partial match against job title

Example request

GET /jobs/?job_type=full_time&location=Harare&page_size=5
X-API-Key: ev_your_key_here

Example response 200

{
  "count": 48,
  "page": 1,
  "page_size": 5,
  "total_pages": 10,
  "results": [
    {
      "slug": "software-engineer-harare-2026",
      "title": "Software Engineer",
      "company": {
        "slug": "techco-zw",
        "company_name": "TechCo Zimbabwe",
        "industry": "Information Technology",
        "city": "Harare",
        "country": "Zimbabwe",
        "logo_url": "https://r2.everydayvacancies.co.zw/logos/techco.png"
      },
      "location": "Harare, Zimbabwe",
      "job_type": "full_time",
      "category": "engineering",
      "experience_level": "mid",
      "salary_min": "1200.00",
      "salary_max": "1800.00",
      "is_remote": false,
      "is_premium": true,
      "is_rated": false,
      "is_job_of_the_day": false,
      "application_deadline": "2026-04-30",
      "created_at": "2026-03-01T10:30:00Z",
      "apply_url": "https://everydayvacancies.co.zw/jobs/software-engineer-harare-2026/apply/"
    }
  ]
}

GET /jobs/featured/ Featured jobs

Returns premium, rated, and job-of-the-day listings. Not paginated — a flat array.

Parameter	Type	Description
`limit`	int	Max results (default: 10, max: 50)

Example request

GET /jobs/featured/?limit=3
X-API-Key: ev_your_key_here

Example response 200

[
  {
    "slug": "head-of-finance-2026",
    "title": "Head of Finance",
    "company": { "company_name": "BancABC Zimbabwe", … },
    "is_premium": true,
    "is_rated": false,
    "is_job_of_the_day": true,
    "apply_url": "https://everydayvacancies.co.zw/jobs/head-of-finance-2026/apply/"
  }
]

GET /jobs/{slug}/ Job detail

Returns the full detail of a single published DetailedJobPosting.

Path parameters

Name	Description
`slug`	Unique job slug (from list endpoint)

Example request

GET /jobs/software-engineer-harare-2026/
X-API-Key: ev_your_key_here

Example response 200

{
  "slug": "software-engineer-harare-2026",
  "title": "Software Engineer",
  "company": { "company_name": "TechCo Zimbabwe", … },
  "location": "Harare, Zimbabwe",
  "job_type": "full_time",
  "department": "Engineering",
  "description": "We are looking for a mid-level software engineer…",
  "requirements": "3+ years Python experience…",
  "responsibilities": "Build and maintain REST APIs…",
  "skills_required": "Python, Django, PostgreSQL",
  "application_method": "online",
  "verification_status": "verified",
  "require_cv": true,
  "max_applications": null,
  "is_job_of_the_day": false,
  "detail_view_count": 134,
  "updated_at": "2026-03-01T12:00:00Z",
  "apply_url": "https://everydayvacancies.co.zw/jobs/software-engineer-harare-2026/apply/"
}

Error response 404

{ "detail": "Job not found." }

GET /jobs/quick/ List quick jobs

Returns a paginated list of active QuickJobPosting records.

Parameter	Type	Description
`page`	int	Page number (default: 1)
`page_size`	int	Default: 20, max: 100
`search`	string	Partial match against title

Example response 200

{
  "count": 210,
  "page": 1,
  "page_size": 20,
  "total_pages": 11,
  "results": [
    {
      "slug": "accountant-vacancy-bulawayo",
      "title": "Accountant Vacancy",
      "created_at": "2026-03-02T08:00:00Z",
      "apply_url": "https://everydayvacancies.co.zw/jobs/quick/accountant-vacancy-bulawayo/"
    }
  ]
}

GET /jobs/quick/{slug}/ Quick job detail

Returns the full description and detail-view count for a single QuickJobPosting.

Example response 200

{
  "slug": "accountant-vacancy-bulawayo",
  "title": "Accountant Vacancy",
  "description": "Our client in Bulawayo is seeking a qualified accountant…",
  "detail_view_count": 89,
  "created_at": "2026-03-02T08:00:00Z",
  "apply_url": "https://everydayvacancies.co.zw/jobs/quick/accountant-vacancy-bulawayo/"
}

GET /companies/ List companies with active jobs

Returns companies that have at least one published, active job posting. Ordered alphabetically.

Parameter	Type	Description
`page`	int	Page number
`page_size`	int	Default: 20, max: 100
`industry`	string	Filter by industry
`search`	string	Partial match on company name

Example response 200

{
  "count": 82,
  "page": 1,
  "page_size": 20,
  "total_pages": 5,
  "results": [
    {
      "slug": "techco-zw",
      "company_name": "TechCo Zimbabwe",
      "industry": "Information Technology",
      "company_type": "private",
      "company_size": "51-200",
      "city": "Harare",
      "country": "Zimbabwe",
      "logo_url": "https://r2.everydayvacancies.co.zw/logos/techco.png",
      "active_job_count": 4
    }
  ]
}

GET /companies/{slug}/ Company detail

Returns the full public profile of a company. Contact details (email, phone) are intentionally omitted — direct users to the EV website to apply.

Example response 200

{
  "slug": "techco-zw",
  "company_name": "TechCo Zimbabwe",
  "industry": "Information Technology",
  "company_type": "private",
  "company_size": "51-200",
  "city": "Harare",
  "country": "Zimbabwe",
  "logo_url": "https://r2.everydayvacancies.co.zw/logos/techco.png",
  "active_job_count": 4,
  "company_description": "We build software for African enterprises…",
  "products_services": "ERP, CRM, custom software development",
  "mission": "Empowering African businesses through technology",
  "website_url": "https://techco.co.zw",
  "founded_year": 2015
}

GET /meta/categories/ All job categories

Returns all valid category value/label pairs to use when filtering jobs.

Example response

[
  { "value": "accounting_finance", "label": "Accounting & Finance" },
  { "value": "engineering", "label": "Engineering" },
  { "value": "information_technology", "label": "Information Technology" }
]

GET /meta/departments/ All departments

[
  { "value": "Human Resources", "label": "Human Resources" },
  { "value": "Finance", "label": "Finance" }
]

GET /meta/job-types/ All job types

[
  { "value": "full_time",  "label": "Full Time" },
  { "value": "part_time",  "label": "Part Time" },
  { "value": "contract",   "label": "Contract" },
  { "value": "freelance",  "label": "Freelance" },
  { "value": "internship", "label": "Internship" }
]

GET /meta/experience-levels/ All experience levels

[
  { "value": "entry",     "label": "Entry Level" },
  { "value": "mid",       "label": "Mid Level" },
  { "value": "senior",    "label": "Senior Level" },
  { "value": "executive", "label": "Executive" }
]

API Reference

Authentication

How to authenticate

401 response (missing / invalid key)

Rate limits

Error codes

Jobs

Query parameters

Example request

Example response 200

Example request

Example response 200

Path parameters

Example request

Example response 200

Error response 404

Example response 200

Example response 200

Companies

Example response 200

Example response 200

Meta / Lookup

Example response