Technical documentation

Dashboard

Tenant API is the per-tenant CRM runtime. REST is registered with Fastify prefix /api/v1 (server.js → registerRoutes). JWT tenant routes send Authorization: Bearer {{access_token}} unless a route is explicitly public.

Shipment pipeline

flowchart LR
  Lead --> Quote --> Order --> Dispatch
  Dispatch --> Invoice
  Invoice --> Payment

Envelope

• Success: { ok: true, status, invokedEndpoint, invokedMethod, responseTime, timestamp, ...result }
• Error: { ok: false, status, invokedMethod, responseTime, timestamp, error }
• Do not leak SQL or stacks in production (src/core/index.js error handler).
• Lists paginate. Role-scoped totals must match visible rows (src/common/list-scope.js).

Guards

Platform rules

• One DB + one runtime per tenant. Owner remains source of truth for platform billing. Tenant stores a mirrored copy of those commercial transactions only.
• Static uploads: GET /uploads/* with path traversal protection. Multipart writes use getTenantApiPublicDir().
• Set TENANT_API_PUBLIC_ORIGIN to the browser-facing API origin (no trailing slash) so stored signed-PDF URLs are not derived from internal Host.
• Quote → order is POST /api/v1/tenant/orders with quoteId. There is no POST /tenant/quotes/:id/convert-to-order.
• Accounts send-invoice sets paymentStatus to invoice_sent. Order/dispatch send-invoice is email only.
• Invoices module (/invoices) ≠ Accounts workbench. Payments module (/payments) ≠ order nested /tenant/orders/:orderId/payments ≠ Accounts paymentStatus on the order row.

Health

Body includes ok, version (0.1.0), environment, timestamp, uptime, message.

curl --request GET "{{base_url}}/api/v1/health"

Uploads

• GET /uploads/* is registered on the app without the /api/v1 prefix (server.js).
• GET /uploads/customer-signatures/:filename/download is a dedicated download route.
• Quote/order/dispatch attachment URLs typically live under this tree after multipart write.

Implementation map

Auth

Login issues JWT access and refresh tokens. Access tokens carry userId, tenantId, roles[], department, and permissions[]. Passwords arrive encoded from the CRM UI; the API decodes, then bcrypts. Never store plaintext.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Bodies

flowchart LR
  Login --> AccessToken
  AccessToken --> Me
  Refresh --> AccessToken
  RequestReset --> VerifyOtp
  VerifyOtp --> Reset

curl --request POST "{{base_url}}/api/v1/tenant/auth/login" \
  --header "Content-Type: application/json" \
  --data-raw '{ "email": "admin@example.com", "password": "encoded-password" }'

Implementation map

SSE

GET /api/v1/tenant/sse is an authenticated event stream. Heartbeats every 25 seconds (: heartbeat). First event is connected with { ok, tenantId, userId }. Helpers: sendSSEToTenant, sendSSEToUser, sendSSEToUsers. Created lifecycle events (lead.created, quote.created, order.created, dispatch.created) go to a scoped recipient set, not blindly the whole tenant.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Known events

curl --request GET "{{base_url}}/api/v1/tenant/sse" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "Accept: text/event-stream"

Implementation map

Users

Staff CRUD, invites, bulk activate/suspend/delete, activate/suspend, avatar. Lists never include the requester. Higher-role users do not appear in lower-role lists (ROLE_HIERARCHY in users/utils.js). Commission fields apply to sales and dispatch roles.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• search, status (active | suspended), departmentId, roleId
• dateFrom, dateTo
• limit, offset
• orderBy: createdAt | updatedAt | lastLoginAt | firstName | lastName | email
• Invite list: status (pending | accepted | cancelled, default pending), search, limit, offset

Required create fields

• Create user: email, password (min 8), firstName, lastName. Optional: departmentId, roleIds[], commissionType (percentage | fixed) / commissionValue (aliases commisionType / commisionValue)
• Invite: email, firstName, lastName. Optional departmentId, roleIds[]
• Accept invite: token (uuid), password (min 8)
• Bulk: userIds[] (min 1), action (activate | suspend | delete)
• Admin reset-by-email: email, password (min 8)

Enums / lifecycle

SSE

user:created, user:updated, user:activated, user:suspended, user:deleted, user:bulk-operation, user:avatar_updated, user:invite:created, user:invite:resent, user:invite:cancelled, user:invite:accepted.

curl --request GET "{{base_url}}/api/v1/tenant/users?limit=50&offset=0" \
  --header "Authorization: Bearer {{access_token}}"

Implementation map

Departments

Org units used by users, teams, email templates, and some list filters. Create/delete require Admin or Sub Admin plus permission keys. Patch uses departments.update without the extra roleGuard.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• limit (default 50)
• offset (default 0)
• orderBy / orderDir (ASC | DESC, default DESC)
• search
• dateFrom / dateTo (ISO datetime)
• month + year together (month 1–12). Date range wins when either dateFrom or dateTo is sent
• List windows default to the current calendar month when no explicit range is sent (resolveListCreatedAtRange)

Required create fields

• name (1–80 chars). Optional description.

Implementation map

Teams

Teams own members, heads (roleInTeam: head | member), and sourceOrigins. Team origins win over tenant Settings origins when both match a public capture request (capture-origin.js + lead capture controller).

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• limit (default 50)
• offset (default 0)
• orderBy / orderDir (ASC | DESC, default DESC)
• search
• dateFrom / dateTo (ISO datetime)
• month + year together (month 1–12). Date range wins when either dateFrom or dateTo is sent
• List windows default to the current calendar month when no explicit range is sent (resolveListCreatedAtRange)

Required create fields

• name (1–120). Optional: description, departmentId, sourceOrigins[] (strings), isActive (default true)
• Replace members: { members: [{ userId, roleInTeam? }] } with roleInTeam head | member (default member)

Org-team list-scope

Lifecycle lists merge org-team visibility (mergeOrgTeamLifecycleWhere): Admin/Sub Admin unchanged; team members see team-origin records plus assigned plus created-by-self; non-team privileged heads hide team-owned records unless assigned/created.

SSE

team.created, team.updated, team.deleted, team.members_updated.

Implementation map

Roles

Seeded roles include admin, sub-admin, sales, sales-head, dispatch, dispatch-head, marketing, marketing-head, accounts, accounts-head (plus admin-depart in hierarchy utils). Create attaches permissionIds.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• limit (default 50)
• offset (default 0)
• orderBy / orderDir (ASC | DESC, default DESC)
• search
• dateFrom / dateTo (ISO datetime)
• month + year together (month 1–12). Date range wins when either dateFrom or dateTo is sent
• List windows default to the current calendar month when no explicit range is sent (resolveListCreatedAtRange)

Required create fields

• name (1–80). Optional description, permissionIds[] (uuids, default []).

Implementation map

Permissions

Keys look like leads.read or orders.update. Routes call permissionGuard('resource.action'). Create stores key, name, optional description.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• limit (default 50)
• offset (default 0)
• orderBy / orderDir (ASC | DESC, default DESC)
• search
• dateFrom / dateTo (ISO datetime)
• month + year together (month 1–12). Date range wins when either dateFrom or dateTo is sent
• List windows default to the current calendar month when no explicit range is sent (resolveListCreatedAtRange)

Required create fields

• key (1–120), name (1–150). Optional description.

Permission keys used by routes (non-exhaustive)

• users.read|create|update|delete
• departments.*, teams.*, roles.*, permissions.*
• leads.read|create|update|delete, quotes.*, orders.*, dispatch.*
• sales.assign, dispatch.assign, carriers.assign
• orders.send-invoice, dispatch.send-invoice
• accounts.read, accounts.send_invoice, accounts.update_payment
• invoices.*, payments.*, carriers.*, customers.read|create|update
• analytics.view, templates.view, search.view, email-templates.read

Implementation map

Admin

Tenant-admin views of subscription, features, and owner-pushed templates. Owner syncs into this tenant on login and on an interval, plus a webhook. Tenant is not the authority for platform billing.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Bodies

• Apply template: optional key (min 3), overwrite (default true)
• Webhook body: optional tenantId, reason, triggeredBy, triggeredAt, timestamp

Implementation map

Leads

Authenticated lead CRUD, packages (vehicles or other), notes, history, convert-to-quote. Public capture is unauthenticated and origin-gated. Convert loads the linked Customer and writes city, state, postal, address, and country onto the new quote. Creating a quote with leadId does the same hydration.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• search, stage, isActive, priority (low|normal|high), assignedTo, customer, transportType
• originCity / originState / originZip, destinationCity / destinationState / destinationZip
• expectedShipDateFrom / expectedShipDateTo, source, trackingNumber
• dateFrom / dateTo, month+year
• limit, offset
• orderBy: createdAt | updatedAt | expectedShipDate | expectedDeliveryDate | amount | priority | leadNumber
• Change history: limit, offset, orderBy (timeStamp|actionType)

Required create fields

• Either vehicle (make, model, year) or other (type, name) — not both
• Optional staff fields include contactName, contactEmail, contactPhone, origin/destination, transportType, assignedTo (triggers sales.assign), priority (default normal)
• Public capture additionally requires Origin match; assignment fields in the body are ignored

Nested resources

• Vehicles: modelYear (1900–2100), make, model. Optional: type, inop, carrierPay, brokerFee, vin, plateNumber, color, weight, mods, notes, addOn, lotNumber, status (active|inactive)
• Others: type, name. Optional weight, dimensions, description, status
• Internal notes: note (min 1)

Enums / lifecycle

List-scope

• Admin / Sub Admin / sales-head: all sales pipeline (canViewAllSalesPipeline)
• sales: rows where assignedTo is self
• Others: empty list (mode: none)
• Plus org-team visibility merge

SSE

lead.created (scoped), lead.updated, lead.deleted, lead.assigned (to assignee), lead.converted + quote.created on convert, lead.vehicle.*, lead.other.*, lead.note.*.

flowchart LR
  Capture --> Lead
  StaffCreate --> Lead
  Lead --> ConvertToQuote
  ConvertToQuote --> Quote

curl --request POST "{{base_url}}/api/v1/public/leads/capture" \
  --header "Content-Type: application/json" \
  --header "Origin: https://quotes.example.com" \
  --header "x-tenant-id: {{tenant_id}}" \
  --data-raw '{ "make": "Honda", "model": "Civic", "year": 2018, "contactEmail": "jane@example.com" }'

curl --request GET "{{base_url}}/api/v1/tenant/leads?limit=50&offset=0" \
  --header "Authorization: Bearer {{access_token}}"

Implementation map

Quotes

Quote CRUD, duplicate, customer email, vehicles/others, notes, history, Aqua pricing helper. POST /tenant/quotes with leadId hydrates customer fields from the lead’s customer. Multipart create/PATCH merges uploaded files with attachment URLs.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• Common list window: search, dateFrom/dateTo, month+year, limit, offset
• status / quoteStatus, state, leadId, assignedUser, assignedUserId, assignedTo, salesAssignedUserId, assignedTeam
• customer, transportType, trackingNumber, quoteNumber, leadSource, approvalStatus
• originCity/originState/originPostalCode/originZip, destination equivalents, source
• shippingDateFrom/shippingDateTo, isActive
• orderBy: createdAt | updatedAt | quoteCreated | shippingDate | amount | quoteNumber

Required create fields

• With leadId: package/customer can hydrate from the lead
• Without leadId: vehicle (make,model,year) or other (type,name), plus transportType, customerPhone, origin city/state/country, destination city/state/country, shippingDate
• Customer email: POST /tenant/quotes/customer-email body quoteId, subject (1–998), optional message

Enums / lifecycle

Package manage

canManageQuotePackages: admin/sub-admin/sales-head, or sales whose assignedUser matches. Dispatch roles blocked from package mutations.

List-scope

Same sales pipeline as leads: all for admin/sub-admin/sales-head; sales sees assignedUser self or quotes whose lead is assigned to self.

SSE

quote.created (scoped), quote.updated, quote.deleted, quote.assigned, quote.converted (on order create from quote), quote.rejected, quote.rework_required.

curl --request POST "{{base_url}}/api/v1/tenant/orders" \
  --header "Authorization: Bearer {{access_token}}" \
  --header "Content-Type: application/json" \
  --data-raw '{ "quoteId": "{{quote_id}}", "customerEmail": "jane@example.com" }'

Implementation map

Orders

Lifecycle after quote approval: list, create (including quote convert), patch, payment status, delivered, cancel, activate, approve/reject, assign carrier, nested packages, BOL (view-only), calendar events, signatures, nested payments, emails. orders.update is seeded for sales / sales-head so operational edits (including attachments) do not require Admin.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• Common window + status (ORDER_STATUSES), orderStatus, secondaryStatus, state
• leadId, quoteId, assignedTo, assignedUser, assignedUserId, salesAssignedUserId, assignedDepartmentId, assignedRoles (comma), assignedTeam
• customer, transportType, trackingNumber, orderNumber, customerReference, leadSource, approvalStatus, paymentStatus
• origin/destination city/state/postal/zip, source, pickup/delivery date ranges, isActive
• orderBy: createdAt | updatedAt | orderCreated | pickupDate | deliveryDate | amount | status | orderNumber

Required create / convert fields

• Direct create: optional quoteId/leadId; most fields optional with defaults (orderStatus default draft, money defaults 0)
• Convert: quoteId required + customerEmail required (convertQuoteToOrderSchema)
• Nested payment: paymentType, amount (positive)
• Nested calendar: title, startAt
• Assign carrier: carrierId
• Reject: reason (min 1)
• Send invoice / customer email: optional emailTemplateId; customer email needs subject

Enums / lifecycle

flowchart LR
  Quote --> PostOrder
  PostOrder --> PendingApproval
  PostOrder --> AwaitingDispatch
  PendingApproval --> Approve
  Approve --> AssignCarrier
  AssignCarrier --> Dispatch

List-scope

• Admin / Sub Admin / dispatch-head: all orders
• dispatch: assignedTo self
• sales-head: orders owned by sales/sales-head via quote.assignedUser / lead.assignedTo (not dispatcher)
• sales: same ownership for self only

SSE

order.created (scoped), order.updated, order.deleted, order.assigned, order.approved, order.rejected, order.reactivated, order.requires_approval, order.carrier_assigned / order.carrier_updated / order.carrier_removed, nested vehicle/other/note/signature/payment/calendar_event, plus quote.converted / quote.rejected / dispatch.deleted on related actions.

curl --request GET "{{base_url}}/api/v1/tenant/orders?limit=50&offset=0" \
  --header "Authorization: Bearer {{access_token}}"

Implementation map

Dispatch

On-road records: state, secondary status, delivered, cancel, vehicles/others, notes, history, BOL (create lives here; orders BOL is view-only), invoice email and customer email. Create requires orderId.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• search, status, secondaryStatus, state, orderId, carrierId, carrierName, assignedTo, assignedDepartmentId, assignedRoles
• customer, transportType, trackingNumber, dispatchNumber, origin, destination, city/state/postal/zip, source, leadSource, primaryRep, referralSource, paymentStatus
• pickup/delivery/ship date ranges, isActive, dateFrom/dateTo, month+year
• orderBy: createdAt | updatedAt | status | pickupDate | deliveryDate | dispatchedAt | pickedUpAt | deliveredAt | dispatchNumber

Required create fields

• orderId (uuid). Optional carrierId, status default confirmed, assignment, dates, money, attachments.

Enums / lifecycle

List-scope

Admin / Sub Admin / dispatch-head: all. dispatch: assignedTo self. Others: none.

SSE

dispatch.created (scoped), dispatch.updated, dispatch.deleted, dispatch.assigned, dispatch.delivered, dispatch.cancelled, nested vehicle/other/note/bol; may also emit order.approved, order.carrier_removed, order.note.*.

curl --request GET "{{base_url}}/api/v1/tenant/dispatch?limit=50&offset=0" \
  --header "Authorization: Bearer {{access_token}}"

Implementation map

Carriers

Carrier CRUD plus nested drivers, insurance, trailers, other contacts, and attachments. Trailer delete allows Admin/Sub Admin or carriers.delete.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• Carriers: search, status (new|active|inactive|suspended|archived), limit, offset, orderBy (name|status|mcNumber|createdAt|updatedAt)
• Drivers: search, status (active|inactive), pagination, orderBy driverName|status|createdAt|updatedAt
• Insurance: search, status (active|expired|inactive), dateFrom/dateTo, orderBy default expirationDate
• Trailers / other-contacts: search, status, pagination; contacts also contactType

Required create fields

• Carrier: name (1–150). Optional MC, phones, emails, capabilities booleans, attachments[]
• Driver: driverName
• Insurance: policyNumber, insuranceCompany, expirationDate
• Trailer: trailerType
• Other contact: contactName

SSE

carrier.created / updated / deleted; carrier.driver.*; carrier.insurance.*; carrier.trailer.*; carrier.otherContact.*.

Implementation map

Customers

Customer book and sales assignment. Assign is sales.assign. Create allows admin/sub-admin/sales-head/sales or customers.create. Update allows admin/sub-admin/sales-head or customers.update.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• Common list window + isActive, state, city, postalCode / postalZip, companyName
• orderBy: email | name | companyName | createdAt | updatedAt | leadsCount | quotesCount | ordersCount

Required create fields

• name (1–180). Either email or phone required. Optional address fields: companyName, address, address2, city, state, postalCode, country
• Assign sales: assignedSalesUserId (optional uuid / none token → null)

Enums

status: active | inactive.

SSE

Assigning sales can emit lead.assigned / quote.assigned to the new assignee when linked records move.

Implementation map

Invoices

Brokerage invoice records billed against an order (orderId + amount). This is not the Accounts workbench and not Owner platform invoices.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• search, status, orderId, dateFrom, dateTo, limit, offset, orderBy (createdAt|updatedAt|dueDate|amount|status)

Required create fields

• orderId (uuid), amount (number). Optional status (default pending), dueDate.

Implementation map

Payments

Brokerage payment records against an invoice row (invoiceId). This is not nested order payments (/tenant/orders/:orderId/payments) and not Accounts paymentStatus on the order.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• search, status, invoiceId, method, dateFrom, dateTo, limit, offset, orderBy (createdAt|updatedAt|amount|status)

Required create fields

• invoiceId (uuid), amount. Optional method, status (default pending).

Implementation map

Accounts

Accounts workbench over orders in awaiting_client_signature (ACCOUNT_ORDER_STATUS). Permissions: accounts.read, accounts.send_invoice, accounts.update_payment. :id is an order id.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• Common list window + paymentStatus, paymentMethod, orderId, dispatchId, assignedTo, invoiceSentBy, transportType
• minAmount / maxAmount, isActive
• orderBy: createdAt | updatedAt | totalTariff | paymentStatus | invoiceSentAt | orderNumber | dispatchNumber

Bodies

• Send invoice: optional emailTemplateId
• Payment status: at least one of paymentStatus, commissionPaidOn, paymentDate
• partial / paid require paidAmount > 0
• commissionPaidOn non-null requires paymentDate in the same request
• paymentDate must be on/after order createdAt and no later than ~2 months from today

Enums

SSE

accounts.invoice_sent, accounts.payment_updated.

Implementation map

Bulk operations

Multi-select actions from CRM tables. Ids arrays are 1–100 uuids. Each route uses the same permission the single-record action would need, plus assign permissions when an assignee is in the body.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Bodies

SSE

Bulk convert emits quote.created / order.created via emitBulkOperationEvent. Individual reassign still uses module assignment events.

Implementation map

Marketing

Campaigns and list imports. Authenticated only (authGuard); no permissionGuard on these routes. Import completion can create leads and emit lead.created.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Required create fields

• Campaign: name, channel. Optional status (default draft), budget, startAt, endAt
• Start import: source
• Update import: optional status, row counts, leads[{ title, source?, amount?, notes? }]

SSE

Import-created leads emit lead.created to the tenant from the marketing controller.

Implementation map

Calendar

Standalone events at /calendar/events. Order-nested calendar lives under /tenant/orders/:orderId/calendar-events (see Orders). Standalone routes are authGuard only.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• userId, from, to (ISO datetime). No pagination schema on this list.

Required create fields

• title, startAt. Optional description, endAt, location, userId.

SSE

calendar.created ({ id, ... }), calendar.updated, calendar.deleted. Order nested events use order.calendar_event.*.

Implementation map

Notifications

In-app notifications plus Web Push subscribe/unsubscribe and preferences. VAPID public key is on Settings (GET /tenant/settings/vapid-public-key). Default list limit is 10, not 50.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• status (all|read|unread, default all)
• userId
• limit (default 10), offset
• search

Required create / push fields

• Create: title. Optional userId (null = tenant-wide), category (default general), body, path, data
• Mark read: { read: boolean } default true
• Push subscribe: endpoint (url), keys.p256dh, keys.auth

SSE

notify.info, notify.read, notify.all_read, notify.deleted. Notification-service also pushes notify.info per recipient.

Implementation map

Email templates

List is open to any authenticated user. Get-by-id requires email-templates.read. Create/update/delete require Admin, Sub Admin, or a department head role (sales-head, dispatch-head, marketing-head, accounts-head). Inactive templates are filtered in the list service unless status=all.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• status (all|active|inactive, default active)
• search
• limit (1–100, default 50), offset
• orderBy title|updatedAt|createdAt (default updatedAt)

Required create fields

• title (1–255). Optional payload object (default {}), status (active|inactive, default active).

SSE

email-template.created, email-template.updated, email-template.deleted.

Implementation map

Files

Structured file metadata at /api/v1/files. This is not the static /uploads/* tree used by quote/order/dispatch attachments.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• tag optional.

Required create fields

• originalName, mimeType, size. Provide storageKey or bufferBase64. Optional tags[]. PATCH only updates tags.

Implementation map

Search

Global search, recent searches, and lifecycle-number lookup. All three require search.view. Results are permission- and list-scope-filtered (leads/quotes/orders/dispatch follow the same assignee rules as list endpoints).

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Query fields

• Global: term (default ''), limit (1–25, default 10)
• Recent: limit (1–20, default 10), daysAgo (1–30, default 30)
• Lifecycle number: at least one of number, lead_number, quote_number, order_number, dispatch_number, tracking_number; limit per entity table (1–500, default 100)

Entity buckets include leads, quotes, orders, dispatches, carriers, customers, invoices, knowledge base, campaigns, calendar events, users, plus nav modules filtered by permission.

curl --request GET "{{base_url}}/api/v1/tenant/search?term=civic&limit=10" \
  --header "Authorization: Bearer {{access_token}}"

Implementation map

Knowledge base

Internal articles. authGuard only. Prefix is /api/v1/knowledge-base/entries, not under /tenant/.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• category, tag

Required create fields

• title, content. Optional tags[], category.

Implementation map

AI pricing

Quote helper. Route preHandler is authGuard; the controller also calls authGuard and requires tenant context. Configure the AI key in Settings integrations (ai_api_key, stored encoded). Related helper: GET /tenant/quotes/:id/aqua-pricing (quotes.read).

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Required body fields

• origin, destination. Optional make, model, year (1900–2100), type, brokerFee (min 50), quoteId.

Implementation map

Analytics

Role-aware dashboards. All routes require analytics.view. Team dashboard SSE (analytics.team_dashboard.updated) is emitted from sales/dispatch mutations, not from these GET routes.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Dashboard query fields

• shipmentStatisticsYear, shippingLocationYear, shippingLocationMonth
• revenueYear, commissionStatisticsYear, commissionStatisticsMonth
• statsYear, statsMonth

SSE

analytics.team_dashboard.updated with { team: sales|dispatch, date } (tenant timezone default America/Chicago).

Implementation map

Nav counts

Pipeline totals for CRM sidebar badges (leads, quotes, orders, dispatch). authGuard only. Each bucket is filled only if the JWT has the matching *.read permission; otherwise that key stays 0. Totals use the same stats/list-scope as the module lists (active pipeline defaults).

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Response data shape: { leads, quotes, orders, dispatch } numbers.

curl --request GET "{{base_url}}/api/v1/tenant/nav-counts" \
  --header "Authorization: Bearer {{access_token}}"

Implementation map

Templates

Owner-published document templates cached on the tenant. View, diff, history. Apply is on Admin (POST /admin/apply-template), not here.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Query fields

• List: type optional
• History: since, limit (numeric)

Implementation map

Settings

Tenant settings, notification channels, integrations (stored encoded; returned encoded), VAPID key, and sourceOrigins / source_origins for public lead capture. Origin values are scheme + host, no path. Team sourceOrigins override tenant origins when both match.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

PATCH fields

• Settings: commissionValue, commissionType (flat|percentage), organizationName, ownerName, timezone, ipRestrictionEnabled, allowedIps[] (max 100), companyInformation{...}, sourceOrigins[] / source_origins[] (urls), notifications{ email, inApp, push }, integrations
• Notifications: email, inApp, push booleans
• Integrations: ai_api_key, zoom{ apiKey, apiSecret, accountId }, googleMaps{ apiKey }, emailService{ provider, apiKey, fromEmail, fromName, smtpHost, smtpPort, user, password }

SSE

settings.updated, settings.integrations_updated.

Implementation map

Public profiles

Unauthenticated profile by public unique id (the personal URL slug). No authGuard. Invalid slug format → 400; missing → 404.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Response includes data.user (presented profile + uniqueId, successDispatches, roles) and organizationName.

Implementation map

eDocs

Send a sign link from the CRM (quotes.update). Public verify/submit/me/refresh are origin-gated for the eDocs site. Session JWT must have tokenType === 'edoc_access' and edocId for /public/me.

flowchart LR
  SendLink --> OpenDoc
  OpenDoc --> VerifyCustomer
  VerifyCustomer --> Sign
  Sign --> SignedPdf

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

SSE

On signed submit: edoc.signed plus quote.updated / order.updated / lead.updated / dispatch.updated when those ids exist on the eDoc.

Implementation map

Desktop app

Authenticated download of the Windows installer. File is public/uploads/dispatchly-v1.0.0.exe. 404 if missing. Content-Disposition: attachment.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

curl --request GET "{{base_url}}/api/v1/desktop-app/download" \
  --header "Authorization: Bearer {{access_token}}" \
  --output dispatchly-v1.0.0.exe

Implementation map

Activity logs

Privileged audit of user actions. List is Admin / Sub Admin only. Creates also SSE activity-log.created to privileged viewers.

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

Implementation map

Request logs

HTTP request audit for Admin / Sub Admin. Filter by method, status, risk flags. status list-query key is omitted so it does not collide with HTTP status filtering (statusCode).

Routes

All paths below are relative to /api/v1 unless noted. Send Authorization: Bearer {{access_token}} on every authGuard route.

List / query fields

• Common window (search, dateFrom/dateTo, month+year, limit, offset) minus status
• method (max 12 chars), statusCode, flaggedOnly (true/false), riskMin (0–100)
• orderBy: createdAt | riskScore

Implementation map