Backend service online

Zim JobHunters API

REST API for the Zim JobHunters platform, covering account onboarding, candidate registration, employer workflows, jobs, opportunities, events, notifications, payments, and administrator tools.

Open Swagger UI Open ReDoc View OpenAPI JSON

Service Overview

Built as a documented REST backend with OpenAPI 3.0.3 schema output, interactive API docs, and machine-readable health and discovery endpoints.

  • Version v1
  • Health Endpoint /api/health/
  • API Index /api/

Public Registration Endpoints

The backend exposes public onboarding endpoints plus a browsable active jobs catalogue for web and mobile clients.

  • Candidate Registration POST /api/candidates/register/
  • Employer Registration POST /api/employers/register/
  • Public Active Jobs GET /api/jobs/
  • Behavior Candidate registration creates the candidate profile and role assignment. Employer registration creates the employer organisation and the initial owner membership. Public jobs listing returns only active jobs with pagination, search, and sector, location, employment, experience, and salary filters.

Administrator Endpoints

Authenticated organisation management operations live under the dedicated administrator app.

  • Employer Management Collection GET, POST /api/administrator/employers/
  • Job Management Collection GET, POST /api/administrator/jobs/
  • Job Sector Management GET, POST /api/administrator/sectors/
  • Location Management GET, POST /api/administrator/locations/
  • Notification Delivery POST /api/admin/notifications/send/
  • Employer Management Detail GET, PUT, PATCH, DELETE /api/administrator/employers/<id>/
  • Job Management Detail GET, PUT, PATCH, DELETE /api/administrator/jobs/<job_id>/
  • Job Approval POST /api/administrator/jobs/<job_id>/approve/
  • Behavior Administrator employer CRUD supports authenticated reads and restricts employer profile mutations to owner or admin employer memberships and platform admins. Administrator job management supports paginated listing, filtering, search, creation, approval, update, and deletion for platform admins only, while sector and location endpoints maintain the shared job taxonomy. Administrators can also send targeted notifications to all users, candidate users, employer users, or a specific employer company.

Employer App Endpoints

Employer-owned job management now lives inside the employers app, scoped by employer membership.

  • Employer Job Management Detail GET, PUT, PATCH, DELETE /api/employers/{employer_id}/jobs/<job_id>/
  • Employer Job Management Collection GET, POST /api/employers/{employer_id}/jobs/
  • Behavior Employer job management is scoped to the authenticated employer, records the user who created each job, and supports draft or submit-for-approval workflow states.

Notification Inbox

Authenticated users have a private notification inbox with read and archive controls, while delivery stays scoped to the intended audience.

  • Inbox List GET /api/notifications/
  • Actions GET /api/notifications/unread-count/, POST /api/notifications/<id>/read/, POST /api/notifications/read-all/, POST /api/notifications/<id>/archive/
  • Behavior Users only see notifications delivered to their own account. Inbox listing supports pagination, filtering, unread counts, ordering, archive-aware visibility, and admin delivery management through dedicated sender endpoints.

Recommended workflow: start at the API index for machine-readable discovery, use the OpenAPI schema for generated clients, and use Swagger UI or ReDoc for human-friendly exploration.