Skip to main content

​
Scope

This page documents the live route handlers currently implemented in the tibs-survey repo under app/api. These routes are not public rider APIs. Most of them require either a project session, fieldwork access, or admin access.

​
Project-authenticated routes

RouteMethodAccessCurrent behavior
/api/catalog/corridorsGETproject-authenticatedreturns corridor options for internal forms
/api/catalog/routesGETproject-authenticatedreturns route options for restricted workflows
/api/catalog/saccosGETproject-authenticatedreturns sacco options for restricted workflows
/api/vehicles/lookupGETproject-authenticatedlooks up approved vehicles by plate
/api/documents/[documentKey]/acceptPOSTproject-authenticatedrecords required legal-document acceptance
/api/projects/[projectSlug]/joinPOSTproject-authenticatedjoins or switches project context
/api/expensesPOSTproject-authenticatedsubmits surveyor expense claims through submit_surveyor_expense_claim
/api/expenses/[expenseId]/disputePOSTproject-authenticatedopens a dispute on an expense review decision
/api/submissions/[submissionId]/disputePOSTproject-authenticatedopens a dispute on a submission review decision
/api/withdrawal-requestsPOSTproject-authenticatedcreates a withdrawal request after payout-balance checks
/api/surveyor/payout-detailsPATCHproject-authenticatedupdates the surveyor’s payout details
/api/surveyor/photoPOST, DELETEproject-authenticatedmanages the surveyor profile photo

​
Fieldwork-authenticated routes

RouteMethodAccessCurrent behavior
/api/session/startPOSTfieldwork-authenticatedstarts a surveyor session after working-window, daily-cap, assignment, and geofence checks
/api/session/touchPOSTfieldwork-authenticatedkeeps an active session alive and ends it if the current work state is invalid
/api/session/endPOSTfieldwork-authenticatedends an active session and validates the end location for non-admin users
/api/assignments/claimPOSTfieldwork-authenticatedclaims an open assignment slot after time, status, and corridor checks
/api/assignments/releasePOSTfieldwork-authenticatedreleases an assignment and may reopen the slot
/api/submissionsPOSTfieldwork-authenticatedsubmits vehicle collection entries through submit_vehicle_collection_entry and triggers auto-review

​
Admin and internal routes

The admin surface is already broad and should be treated as internal-only. Current route families include:
Route familyMethods in usePurpose
/api/admin/surveyors*GET, POST, PATCH, DELETEmanage surveyor records, status, recovery, payout details, and photos
/api/admin/assignments*POST, PATCHmanage route assignments
/api/admin/assignment-slots*POST, PATCHmanage assignment slot creation and updates
/api/admin/submissions/[submissionId]/reviewPATCHreview survey submissions
/api/admin/expenses/[expenseId]/reviewPATCHreview expense claims
/api/admin/expense-disputes/[disputeId]PATCHresolve expense disputes
/api/admin/submission-disputes/[disputeId]PATCHresolve submission disputes
/api/admin/withdrawal-requests/[requestId]PATCHapprove or fulfill withdrawal requests
/api/admin/payout-entriesPOSTwrite payout and finance entries
/api/admin/vehicles*PATCHbulk or per-vehicle internal updates
/api/admin/settings/*POST, PATCHinternal settings for Brevo, payout rate, inactivity reminders, and expense automation

​
Webhook route

RouteMethodAccessCurrent behavior
/api/webhooks/brevoPOSTwebhook secret requiredvalidates the configured Brevo secret header and records delivery events

​
Important implementation notes

  • requireProjectApiSession is the common baseline for many restricted routes
  • requireFieldworkApiSession is used where active surveyor field access is required
  • admin routes should not be documented as public integrations
  • the operations app includes many more internal routes than the future public API draft and they should stay separated conceptually