API Reference

API Reference

This document provides a comprehensive API reference for the Merq platform. The full OpenAPI specification is available in the backend at /api/docs (when running locally).

Base URL

Environment	URL
Development	http://localhost:8080/api
Production	https://api.merq.io/api

Authentication

All API requests require authentication via JWT token.

Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}

Using the Token

Include the token in the Authorization header:

Authorization: Bearer <your-token>

API Endpoints

Authentication

Method	Endpoint	Description
POST	/auth/login	User login
POST	/auth/register	User registration
POST	/auth/refresh	Refresh token
POST	/auth/forgot-password	Request password reset
POST	/auth/reset-password	Reset password

Office (Admin) Endpoints

All office endpoints require office/v1/ prefix.

Visits

Method	Endpoint	Description
GET	/office/v1/outlet-visits	List visits
POST	/office/v1/outlet-visits	Create visit
POST	/office/v1/outlet-visits/bulk	Bulk create visits
POST	/office/v1/outlet-visits/import	Import from CSV
GET	/office/v1/outlet-visits/export	Export to CSV
POST	/office/v1/outlet-visits/send-to-field	Send to field staff
GET	/office/v1/outlet-visits/:id	Get visit detail
PUT	/office/v1/outlet-visits/:id/force-close	Force close visit
PUT	/office/v1/outlet-visits/:id/cancel	Cancel visit
POST	/office/v1/outlet-visits/:visit_id/assign-users	Assign users

Visit Submissions

Method	Endpoint	Description
GET	/office/v1/outlet-visits/submissions	List submissions
GET	/office/v1/outlet-visits/submissions/:id	Get submission
POST	/office/v1/outlet-visits/submissions/:id/approval	Approve/reject

Outlets

Method	Endpoint	Description
GET	/office/v1/outlets	List outlets
POST	/office/v1/outlets	Create outlet
GET	/office/v1/outlets/:id	Get outlet
PUT	/office/v1/outlets/:id	Update outlet
DELETE	/office/v1/outlets/:id	Delete outlet

Users

Method	Endpoint	Description
GET	/office/v1/users	List users
POST	/office/v1/users	Create user
GET	/office/v1/users/:id	Get user
PUT	/office/v1/users/:id	Update user
DELETE	/office/v1/users/:id	Delete user

Teams

Method	Endpoint	Description
GET	/office/v1/teams	List teams
POST	/office/v1/teams	Create team
GET	/office/v1/teams/:id	Get team
PUT	/office/v1/teams/:id	Update team
DELETE	/office/v1/teams/:id	Delete team

Projects

Method	Endpoint	Description
GET	/office/v1/projects	List projects
POST	/office/v1/projects	Create project
GET	/office/v1/projects/:id	Get project
PUT	/office/v1/projects/:id	Update project
DELETE	/office/v1/projects/:id	Delete project

Products

Method	Endpoint	Description
GET	/office/v1/products	List products
POST	/office/v1/products	Create product
GET	/office/v1/products/:id	Get product
PUT	/office/v1/products/:id	Update product
DELETE	/office/v1/products/:id	Delete product

Principals

Method	Endpoint	Description
GET	/office/v1/principals	List principals
POST	/office/v1/principals	Create principal
GET	/office/v1/principals/:id	Get principal
PUT	/office/v1/principals/:id	Update principal
DELETE	/office/v1/principals/:id	Delete principal

Forms

Method	Endpoint	Description
GET	/office/v1/forms	List forms
POST	/office/v1/forms	Create form
GET	/office/v1/forms/:id	Get form
PUT	/office/v1/forms/:id	Update form
DELETE	/office/v1/forms/:id	Delete form

Attendance

Method	Endpoint	Description
GET	/office/v1/attendances	List attendances
POST	/office/v1/attendances	Record attendance
GET	/office/v1/attendances/:id	Get attendance

Dashboard

Method	Endpoint	Description
GET	/office/v1/dashboard/metrics	Dashboard metrics
GET	/office/v1/dashboard/summary	Summary data

Notifications

Method	Endpoint	Description
GET	/office/v1/notifications	List notifications
GET	/office/v1/notifications/unread-count	Unread count
PUT	/office/v1/notifications/:id/read	Mark as read
PUT	/office/v1/notifications/read-all	Mark all read

Export

Method	Endpoint	Description
GET	/office/v1/export/submissions/csv	Export submissions CSV
GET	/office/v1/export/submissions/pdf	Export submissions PDF
GET	/office/v1/export/jobs	List export jobs
GET	/office/v1/export/jobs/:id	Get export job status
GET	/office/v1/export/jobs/:id/download	Download export file

Mobile (App) Endpoints

All mobile endpoints require app/v1/ prefix.

Visits

Method	Endpoint	Description
GET	/app/v1/outlet-visits	List user’s visits
POST	/app/v1/outlet-visits	Create self-assigned visit
GET	/app/v1/outlet-visits/:id	Get visit detail
POST	/app/v1/outlet-visits/:id/check-in	Check in to visit
POST	/app/v1/outlet-visits/:id/check-out	Check out from visit
POST	/app/v1/outlet-visits/:id/submit-form	Submit form
GET	/app/v1/outlet-visits/active-visit	Get active visit

Submissions

Method	Endpoint	Description
GET	/app/v1/outlet-visits/submissions	List submissions
GET	/app/v1/outlet-visits/submissions/:id	Get submission

Profile

Method	Endpoint	Description
GET	/app/v1/profile	Get profile
PUT	/app/v1/profile	Update profile
PUT	/app/v1/profile/password	Change password

Notifications

Method	Endpoint	Description
GET	/app/v1/notifications	List notifications
PUT	/app/v1/notifications/:id/read	Mark as read
POST	/app/v1/notifications/tokens	Register FCM token

Query Parameters

Common query parameters for list endpoints:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	10	Items per page
keyword	string	-	Search keyword
sort_by	string	created_at	Sort field
sort_order	string	desc	Sort direction (asc/desc)

Common Response Formats

Success Response

{
  "success": true,
  "message": "Success",
  "code": "SUCCESS",
  "data": { ... }
}

Paginated Response

{
  "success": true,
  "message": "Success",
  "code": "LIST_OK",
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}

Error Response

{
  "success": false,
  "message": "Error message",
  "code": "ERROR_CODE",
  "errors": { ... }
}

Rate Limiting

See Rate Limiting for details.

WebSocket

WebSocket is available for real-time features:

wss://api.merq.io/ws

Requires authentication token in query string:

wss://api.merq.io/ws?token=<jwt-token>

Postman Collection

A Postman collection is available for testing. Import from:

merq-backend/docs/merq-api-collection.json

Related Documentation

• Authentication - Auth flow details
• Rate Limiting - Rate limit rules
• Architecture Overview - System architecture