Skip to main content

API Endpoints

Complete reference of all API endpoints in the backend.

Base URL​

Development: http://localhost:3000
Production: https://api.thepluggnamibia.com

Authentication​

Send OTP​

Send a verification code to a phone number.

POST /api/auth/send-otp

Request Body:

{
  "phone": "+264812345678",
  "role": "PROVIDER" | "SERVICE_SEEKER"
}

Response:

{
  "success": true,
  "message": "OTP sent successfully",
  "nextAllowedAt": "2024-01-01T00:01:00.000Z",
  "remainingSmsCount": 29
}

Verify OTP​

Verify the OTP code and authenticate user.

POST /api/auth/verify-otp

Request Body:

{
  "phone": "+264812345678",
  "code": "12345",
  "role": "PROVIDER" | "SERVICE_SEEKER",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "profilePhoto": "https://..."
}

Response:

{
  "success": true,
  "message": "OTP verified successfully",
  "user": {
    "id": "user-id",
    "phone": "+264812345678",
    "role": "PROVIDER",
    "profile": {...}
  }
}

Provider Endpoints​

Get Provider Profile​

GET /api/provider/profile/:providerId

Get Providers by Service​

GET /api/provider/by-service/:serviceId

Query params: latitude, longitude, maxDistance

Update Online Status​

PUT /api/provider/:providerId/online-status

Request Body:

{
  "isOnline": true
}

Accept Job​

POST /api/provider/accept-job

Request Body:

{
  "jobId": "job-id",
  "providerId": "provider-id"
}

Service Seeker Endpoints​

Create Job​

POST /api/service-seeker/jobs

Request Body:

{
  "userId": "user-id",
  "categoryId": "category-id",
  "serviceId": "service-id",
  "description": "Job description",
  "location": "Windhoek, Namibia",
  "dateTime": "2024-01-01T10:00:00Z",
  "estimatedCost": 500,
  "isCallOut": true
}

Get User Jobs​

GET /api/service-seeker/jobs/:userId

Cancel Job​

PUT /api/service-seeker/jobs/:jobId/cancel

Admin Endpoints​

All admin endpoints require x-api-key header.

Get Dashboard Stats​

GET /api/admin/dashboard/stats

Get Users​

GET /api/admin/users

Query params: role, status

Update User Status​

PUT /api/admin/users/:userId/status

Request Body:

{
  "status": "ACTIVE" | "SUSPENDED" | "BANNED"
}

Verify Provider​

PUT /api/admin/providers/:providerId/verify

Request Body:

{
  "isVerified": true
}

Error Responses​

All endpoints may return:

400 Bad Request

{
  "error": "Error message"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "nextAllowedAt": "2024-01-01T00:01:00.000Z"
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "Detailed error message"
}