# API Documentation

## Base URL

```
http://localhost:8000/api
```

## Authentication

- **Method**: Laravel Sanctum (Bearer token)
- **Header**: `Authorization: Bearer <token>`
- **Token obtained from**: `POST /api/login`
- **Unauthenticated response**: `{"success": false, "message": "Unauthenticated."}` (HTTP 401)

## Response Format

All endpoints return JSON with the same envelope:

```json
{
    "success": true|false,
    "message": "Human-readable message",
    "data": { ... } | null,
    "errors": { ... } | null  // Only on validation errors
}
```

## Naming Convention

All authenticated routes use `POST` method with a verb-path pattern:
`POST /api/{module}/{action}`

Exceptions: File downloads use `GET`.

## Public Endpoints

| Method | Path | Controller | Purpose |
|--------|------|-----------|---------|
| POST | `/api/register` | RegistrationController@register | Send registration OTP |
| POST | `/api/register/verify` | RegistrationController@verifyAndRegister | Verify OTP and create user |
| POST | `/api/login` | AuthController@login | Login, returns Sanctum token |
| GET | `/api/google/callback` | GoogleAuthController@handleCallback | Google OAuth callback |
| GET | `/ivr/call/incoming/upload` | PhoneCallLogController@upload_ivr_incoming_call | IVR incoming call upload |
| GET | `/ivr/call/outgoing/upload` | PhoneCallLogController@upload_ivr_outgoing_call | IVR outgoing call upload |
| GET | `/google/auth` | GoogleAuthController@redirectToGoogle | Google OAuth redirect |
| POST | `/webhook/lead-capture` | LeadController@webhook_facebook_lead_capture | Facebook lead webhook |

## Authenticated Endpoints

### Account Validation (All auth routes pass through `account_validation` middleware first)

| Method | Path | Controller | Purpose |
|--------|------|-----------|---------|
| POST | `/api/verify` | AuthController@verify | Verify account |
| POST | `/api/logout` | AuthController@logout | Logout (revoke token) |

### User Management

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/user/create` | Create user |
| POST | `/api/user/all/fetch` | List all users |
| POST | `/api/user/details/fetch` | Get user details |
| POST | `/api/user/own/data` | Get own user data |
| POST | `/api/user/own/image/update` | Update own profile image |
| POST | `/api/user/own/image/delete` | Delete own profile image |
| POST | `/api/user/personal/update` | Update personal info |
| POST | `/api/user/address/update` | Update address |
| POST | `/api/user/bank/update` | Update bank details |
| POST | `/api/user/professional/update` | Update professional details |
| POST | `/api/user/schedule/update` | Update work schedule |
| POST | `/api/user/integration/update` | Update integrations |
| POST | `/api/user/device_token/update` | Update FCM device token |
| POST | `/api/user/impersonate` | Impersonate another user |
| POST | `/api/user/impersonate/leave` | Leave impersonation |
| POST | `/api/user/status/update` | Update user status |
| POST | `/api/user/search` | Search users |
| POST | `/api/user/kyc` | KYC verification |
| POST | `/api/user/document/create` | Create user document |
| POST | `/api/user/document/delete` | Delete user document |
| POST | `/api/user/asset/create` | Create asset assignment |
| POST | `/api/user/asset/return` | Return asset |
| POST | `/api/user/kpi/update` | Update KPI targets |
| POST | `/api/user/kpi/current/fetch` | Fetch current KPI |
| POST | `/api/user/analytics/fetch` | Fetch user analytics |

### Company

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/company/create` | Create company |
| POST | `/api/company/update` | Update company |
| POST | `/api/company/active/fetch` | List active companies |
| POST | `/api/company/inactive/fetch` | List inactive companies |
| POST | `/api/company/delete` | Delete company |
| POST | `/api/company/status/update` | Update status |
| POST | `/api/company/search` | Search companies |

### Lead Management

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/lead/create` | Create lead |
| POST | `/api/lead/update` | Update lead |
| POST | `/api/lead/delete` | Delete lead |
| POST | `/api/lead/all/fetch` | List all leads |
| POST | `/api/lead/raw/all/fetch` | List raw leads |
| POST | `/api/lead/verified/all/fetch` | List verified leads |
| POST | `/api/lead/client/all/fetch` | List clients |
| POST | `/api/lead/all/search` | Search leads |
| POST | `/api/lead/note/create` | Create note |
| POST | `/api/lead/notes/fetch` | Fetch notes |
| POST | `/api/lead/follow-up/create` | Create follow-up |
| POST | `/api/lead/follow-ups/fetch` | Fetch follow-ups |
| POST | `/api/lead/follow-ups/all/fetch` | Fetch all follow-ups |
| POST | `/api/lead/verified/convert` | Convert to verified |
| POST | `/api/lead/not_interest/convert` | Mark not interested |
| POST | `/api/lead/call_back/convert` | Mark call back |
| POST | `/api/lead/single/transfer` | Transfer single lead |
| POST | `/api/lead/bulk/transfer` | Bulk transfer leads |
| POST | `/api/lead/bulk/delete` | Bulk delete leads |
| POST | `/api/lead/single/share` | Share lead |
| POST | `/api/lead/priority/update` | Update priority |
| POST | `/api/lead/phone/primary/set` | Set primary phone |
| POST | `/api/lead/email/primary/set` | Set primary email |
| POST | `/api/lead/claim` | Claim lead |
| POST | `/api/lead/analytics` | Lead analytics |
| GET | `/api/lead/export` | Export leads (Excel) |
| POST | `/api/lead/import` | Import leads (Excel/CSV) |
| GET | `/api/lead/import/template` | Download import template |

#### Lead Sales Sub-routes (`/api/lead/sale/*`)

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/lead/sale/create` | Create lead sale |
| POST | `/api/lead/sale/incentive/update` | Update incentive |
| POST | `/api/lead/sale/update` | Update sale |
| POST | `/api/lead/sale/delete` | Delete sale |
| POST | `/api/lead/sale/payment/create` | Create payment |
| POST | `/api/lead/sale/payment/update` | Update payment |
| POST | `/api/lead/sale/payment/delete` | Delete payment |
| POST | `/api/lead/sale/aggregated/fetch` | Aggregated sales report |
| POST | `/api/lead/sale/individual/fetch` | Individual sales list |

#### Lead Overview Sub-routes (`/api/lead/overview/*`)

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/lead/overview/sale/fetch` | Sale data |
| POST | `/api/lead/overview/quotation/fetch` | Quotation data |
| POST | `/api/lead/overview/meeting/fetch` | Meeting data |
| POST | `/api/lead/overview/visit/fetch` | Visit data |
| POST | `/api/lead/overview/demo/fetch` | Demo data |
| POST | `/api/lead/overview/project/fetch` | Project data |
| POST | `/api/lead/overview/task/fetch` | Task data |

### Meeting

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/meeting/create` | Create meeting |
| POST | `/api/meeting/update` | Update meeting |
| POST | `/api/meeting/transfer` | Transfer active user |
| POST | `/api/meeting/reschedule` | Reschedule meeting |
| POST | `/api/meeting/cancel` | Cancel meeting |
| POST | `/api/meeting/delete` | Soft delete meeting |
| POST | `/api/meeting/arrived` | Mark arrived (within 30min window) |
| POST | `/api/meeting/started` | Mark started (with GPS) |
| POST | `/api/meeting/otp/send` | Send OTP to lead's phone |
| POST | `/api/meeting/otp/verify` | Verify OTP |
| POST | `/api/meeting/completed` | Mark completed |
| POST | `/api/meeting/active/fetch` | List active meetings |
| POST | `/api/meeting/completed/fetch` | List completed meetings |
| POST | `/api/meeting/cancelled/fetch` | List cancelled meetings |
| POST | `/api/meeting/overdue/fetch` | List overdue meetings |
| POST | `/api/meeting/search` | Search meetings |

### Demo

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/demo/create` | Create demo |
| POST | `/api/demo/update` | Update demo |
| POST | `/api/demo/delete` | Delete demo |
| POST | `/api/demo/all/fetch` | List demos |
| POST | `/api/demo/start` | Start demo |
| POST | `/api/demo/complete` | Complete demo |
| POST | `/api/demo/cancel` | Cancel demo |
| POST | `/api/demo/share` | Share demo |
| POST | `/api/demo/creator/update` | Update creator |
| POST | `/api/demo/reschedule` | Reschedule demo |
| POST | `/api/demo/responses/sync` | Sync attendee responses |

### Product

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/product/all/fetch` | List products |
| POST | `/api/product/create` | Create product |
| POST | `/api/product/update` | Update product |
| POST | `/api/product/delete` | Delete product |
| POST | `/api/product/search` | Search products |
| GET | `/api/product/export` | Export products (Excel) |

### Visit

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/visit/create` | Create visit |
| POST | `/api/visit/all/fetch` | List visits |
| POST | `/api/visit/search` | Search visits |
| POST | `/api/visit/delete` | Delete visit |

### Task

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/task/create` | Create task |
| POST | `/api/task/update` | Update task |
| POST | `/api/task/delete` | Delete task |
| POST | `/api/task/complete` | Complete task |
| POST | `/api/task/search` | Search tasks |
| POST | `/api/task/all/fetch` | List all tasks |
| POST | `/api/task/log/create` | Create task log |
| POST | `/api/task/log/delete` | Delete task log |
| POST | `/api/task/user/log/fetch` | Fetch user logs |
| POST | `/api/task/user/log/create` | Create user log |
| POST | `/api/task/user/log/delete` | Delete user log |
| POST | `/api/task/query/create` | Create query |
| POST | `/api/task/query/complete` | Complete query |
| POST | `/api/task/query/delete` | Delete query |
| POST | `/api/task/query/all/fetch` | List queries |
| POST | `/api/task/recurrence/stop` | Stop recurrence |

### Project

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/project/create` | Create project |
| POST | `/api/project/update` | Update project |
| POST | `/api/project/complete` | Complete project |
| POST | `/api/project/delete` | Delete project |
| POST | `/api/project/all/fetch` | List all projects |
| POST | `/api/project/active/fetch` | List active projects |
| POST | `/api/project/complete/fetch` | List completed projects |
| POST | `/api/project/task/fetch` | Project tasks |
| POST | `/api/project/media/upload` | Upload media |
| POST | `/api/project/media/delete` | Delete media |
| POST | `/api/project/media/fetch` | List media |
| POST | `/api/project/ticket/create` | Create ticket |
| POST | `/api/project/ticket/update` | Update ticket |
| POST | `/api/project/ticket/delete` | Delete ticket |
| POST | `/api/project/ticket/fetch` | List tickets |

### Attendance

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/attendance/check_in` | Check in (with image, GPS) |
| POST | `/api/attendance/check_out` | Check out (with image, GPS) |
| POST | `/api/attendance/report/fetch` | Aggregated attendance report |
| POST | `/api/attendance/detailed/report/fetch` | Detailed report |
| POST | `/api/attendance/mark` | Manual mark attendance |
| POST | `/api/attendance/today/own/fetch` | Today's own attendance |
| POST | `/api/attendance/location/track` | Track GPS location |
| POST | `/api/attendance/location/history` | Location history |
| POST | `/api/attendance/backfill` | Backfill attendance |

### Shift

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/shift/create` | Create shift |
| POST | `/api/shift/update` | Update shift |
| POST | `/api/shift/all/fetch` | List shifts |
| POST | `/api/shift/search` | Search shifts |
| POST | `/api/shift/delete` | Delete shift |

### Tag

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/tag/create` | Create tag |
| POST | `/api/tag/update` | Update tag |
| POST | `/api/tag/delete` | Delete tag |
| POST | `/api/tag/all/fetch` | List tags |
| POST | `/api/tag/search` | Search tags |

### Quotation

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/quotation/create` | Create quotation |
| POST | `/api/quotation/update` | Update quotation |
| POST | `/api/quotation/delete` | Delete quotation |
| POST | `/api/quotation/all/fetch` | List quotations |
| POST | `/api/quotation/detail/fetch` | Quotation details |
| POST | `/api/quotation/draft/create` | Create draft |
| POST | `/api/quotation/draft/update` | Update draft |
| POST | `/api/quotation/draft/delete` | Delete draft |
| POST | `/api/quotation/draft/all/fetch` | List drafts |
| POST | `/api/quotation/draft/detail/fetch` | Draft details |
| POST | `/api/quotation/draft/finalize` | Finalize draft |
| POST | `/api/quotation/send-email` | Send via email |
| POST | `/api/quotation/email-history` | Email history |
| POST | `/api/quotation/resend-email` | Resend email |
| GET | `/api/quotation/pdf` | Download PDF |
| POST | `/api/quotation/term/create` | Create term |
| POST | `/api/quotation/term/update` | Update term |
| POST | `/api/quotation/term/delete` | Delete term |
| POST | `/api/quotation/term/fetch` | List terms |
| POST | `/api/quotation/email/body/update` | Update email body |
| POST | `/api/quotation/email/body/fetch` | Fetch email body |

### Leave

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/leave/type/create` | Create leave type |
| POST | `/api/leave/type/all/fetch` | List leave types |
| POST | `/api/leave/type/search` | Search leave types |
| POST | `/api/leave/type/update` | Update leave type |
| POST | `/api/leave/type/delete` | Delete leave type |
| POST | `/api/leave/entitlement/create` | Create entitlement |
| POST | `/api/leave/entitlement/update` | Update entitlement |
| POST | `/api/leave/application/create` | Apply leave |
| POST | `/api/leave/application/update` | Update application |
| POST | `/api/leave/application/approve` | Approve leave |
| POST | `/api/leave/application/reject` | Reject leave |
| POST | `/api/leave/application/pending/fetch` | Pending approvals |
| POST | `/api/leave/application/approved/fetch` | Approved applications |
| POST | `/api/leave/application/rejected/fetch` | Rejected applications |
| POST | `/api/leave/application/own/fetch` | Own approvals |

### Holiday

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/holiday/create` | Create holiday |
| POST | `/api/holiday/update` | Update holiday |
| POST | `/api/holiday/delete` | Delete holiday |
| POST | `/api/holiday/all/fetch` | List holidays |
| POST | `/api/holiday/by-year` | Holidays by year |
| POST | `/api/holiday/current-year` | Current year holidays |
| POST | `/api/holiday/year-options` | Year type options |

### Payroll

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/payroll/create` | Create payroll |
| POST | `/api/payroll/update` | Update payroll |
| POST | `/api/payroll/delete` | Delete payroll |
| POST | `/api/payroll/all/fetch` | List payrolls |
| POST | `/api/payroll/export` | Export payroll |
| POST | `/api/payroll/all/export` | Export all payrolls |

### Finance

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/finance/sale/fetch` | Finance sales report |
| POST | `/api/finance/sale/approve` | Approve sale |
| POST | `/api/finance/sale/bill/mark` | Mark bill raised |

### Dashboard

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/dashboard/attendance/today` | Today's attendance |
| POST | `/api/dashboard/attendance/subordinates/today` | Subordinates attendance |
| POST | `/api/dashboard/lead/latest` | Latest leads |
| POST | `/api/dashboard/meeting/latest` | Latest meetings |
| POST | `/api/dashboard/task/latest` | Latest tasks |
| POST | `/api/dashboard/project/latest` | Latest projects |
| POST | `/api/dashboard/demo/latest` | Latest demos |
| POST | `/api/dashboard/visit/latest` | Latest visits |
| POST | `/api/dashboard/sale/latest` | Latest sales |
| POST | `/api/dashboard/query/own/fetch` | Own queries |
| POST | `/api/dashboard/holidays` | Upcoming holidays |
| POST | `/api/dashboard/birthdays` | Upcoming birthdays |
| POST | `/api/dashboard/call-logs/chart` | Call logs chart data |
| POST | `/api/dashboard/sales/chart` | Sales chart data |
| POST | `/api/dashboard/counts` | Dashboard counts |

### Communication

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/phone/call/logs/uploads` | Upload call data |
| POST | `/api/phone/call/logs/fetch` | Fetch call logs |
| POST | `/api/phone/call/logs/aggregated` | Aggregated call data |
| POST | `/api/phone/call/logs/user/records` | User call records |
| POST | `/api/phone/call/logs/number/history` | Number history |
| POST | `/api/ivr/call` | Make IVR call |
| POST | `/api/ivr/call/logs/aggregated` | Aggregated IVR data |
| POST | `/api/ivr/call/logs/fetch` | IVR call logs |
| POST | `/api/ivr/call/logs/number/history` | IVR number history |
| POST | `/api/notification/user/fetch` | User notifications |
| POST | `/api/activity/user/log/fetch` | Activity logs |
| POST | `/api/timesheet/user/fetch` | User timesheet |

### Settings

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/account/update` | Update account |
| POST | `/api/account/logo/update` | Update logo |
| POST | `/api/account/document/create` | Create document |
| POST | `/api/account/document/update` | Update document |
| POST | `/api/account/document/delete` | Delete document |
| POST | `/api/account/document/fetch` | List documents |
| POST | `/api/setting/role/create` | Create role |
| POST | `/api/setting/role/update` | Update role |
| POST | `/api/setting/ivr/credential/update` | Update IVR API key |
| POST | `/api/setting/ivr/credential/fetch` | Fetch IVR API key |
| POST | `/api/role/all/fetch` | List roles |
| POST | `/api/role/permission/all/fetch` | List permissions |
| POST | `/api/smtp_credential/fetch` | Fetch SMTP config |
| POST | `/api/smtp_credential/update` | Update SMTP config |
| POST | `/api/sms_credential/fetch` | Fetch SMS config |
| POST | `/api/sms_credential/update` | Update SMS config |
| POST | `/api/waba_credential/fetch` | Fetch WABA config |
| POST | `/api/waba_credential/update` | Update WABA config |
| POST | `/api/rcs_credential/fetch` | Fetch RCS config |
| POST | `/api/rcs_credential/update` | Update RCS config |
| POST | `/api/payment/type/fetch` | Payment types |
| POST | `/api/payment/type/create` | Create payment type |
| POST | `/api/payment/type/update` | Update payment type |
| POST | `/api/payment/type/delete` | Delete payment type |
| POST | `/api/app-version/fetch` | App version info |
| POST | `/api/app-version/create` | Create version |
| POST | `/api/app-version/update` | Update version |
| POST | `/api/app-version/status/update` | Update version status |
| POST | `/api/app-version/delete` | Delete version |
| POST | `/api/app-version/all/fetch` | List versions |

## Common Error Responses

| Status | Meaning |
|--------|---------|
| 401 | Unauthenticated (no token or invalid token) |
| 403 | Forbidden (lacks permission) |
| 422 | Validation error (invalid input) |
| 500 | Server error |

## Pagination

List endpoints accept optional pagination parameters:
- Request body or query params: `page`, `perPage` (or `per_page`)
- Response includes Laravel pagination metadata
- Default perPage varies by endpoint (typically 10-25)

## File Uploads

- Profile images, check-in/out images: multipart POST with `image` field
- Documents, assets: `file` field
- Quotation attachments: `files[]` array (max 5, 5MB each, 20MB total)
- Allowed types: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, JPG, PNG, GIF
- Files stored in `storage/app/private/` or `storage/app/public/`
- Served via web routes at `/storage/{filename}` or `/storage/{category}/{filename}`

## Google Auth Flow

1. Frontend redirects to `GET /api/google/auth`
2. User authorizes on Google
3. Google redirects to `GET /api/google/callback`
4. Tokens stored in database
5. Used for Google Calendar event creation (demos, meetings)