Skip to main content

API Endpoints Reference

Overview & Base URLs​

All API endpoints are hosted on the unified platform domain:

  • Production Base URL: https://hitechinsurance.ai
  • Staging Base URL: https://staging.hitechinsurance.ai
  • Local Development: http://localhost:3000

Authentication Schemes​

SchemeTypeLocationDescription
HMAC-SHA256 (HtiHmacAuth)API KeyHeaders: x-hti-signature, x-hti-timestampRequired for CRM lead forwarding (/api/leads/*). Timestamp must be within 5-min UTC window.
Admin Session Cookie (AdminSessionAuth)CookieCookie: authjs.session-tokenNextAuth session cookie for internal administrative endpoints (/api/meta/leads/*, /api/career/resume/*).
User Session CookieCookieCookie: authjs.session-tokenNextAuth session cookie for user dashboard endpoints (/api/user/*, /api/referral/*).
Swagger Password Session (SwaggerSessionAuth)CookieCookie: hti_swagger_tokenSecure cryptographic token cookie protecting Swagger UI & OpenAPI JSON endpoints.
Google reCAPTCHA v3TokenRequest Body: recaptchaTokenAutomated bot protection for all public website forms (/api/forms/*).
Platform Webhook VerificationQuery / SecretHeader/Query: hub.challenge, X-Goog-Signature, secret tokensThird-party marketing webhook verification handshakes (Meta, Google, TikTok).

Table of Contents​

  1. Health & System (1 endpoint)
  2. HTI Lead Ingestion (2 endpoints)
  3. Career Applications (1 endpoint)
  4. Authentication & Verification (4 endpoints)
  5. Marketing Webhooks (7 endpoints)
  6. Meta Leads Management (5 endpoints)
  7. Public Website Forms (11 endpoints)
  8. User Profile (5 endpoints)
  9. Referral Program (3 endpoints)
  10. Email Signatures & Media (1 endpoint)
  11. Telemetry & Analytics (4 endpoints)
  12. API Documentation (4 endpoints)
  13. Text-to-Speech & Voice Services (2 endpoints)
    • POST /api/tts — Synthesize text into high-fidelity neural MP3 speech
    • GET /api/tts — Synthesize text into neural MP3 speech via query parameters

Health & System​

Service health checks and uptime monitoring

GET /api/health​

Summary: Check system health
Operation ID: getHealth
Authentication: None (Public)

Returns the current health status and UTC ISO timestamp of the API service.

Response Samples​

HTTP 200 — Service is operational

{
  "status": "ok",
  "timestamp": "2026-09-15T10:30:00.000Z"
}

HTI Lead Ingestion​

HMAC-SHA256 authenticated inbound lead streams from Falcon CRM

POST /api/leads/personal​

Summary: Ingest personal lines insurance lead
Operation ID: ingestPersonalLead
Authentication: HtiHmacAuth

Receives personal lines lead data transferred from Falcon / HTI CRM. Requires HMAC-SHA256 signature verification using the shared secret and a 5-minute replay window timestamp. Features idempotent upsert based on external lead.id.

Parameters​

NameInRequiredTypeDescription
x-hti-signatureheaderYesstringHMAC-SHA256 hex signature of {timestamp}.{rawRequestBody}
x-hti-timestampheaderYesstringUnix epoch timestamp in milliseconds. Requests older than 5 minutes are rejected.

Request Body​

Personal lines lead payload with nested lead and user objects

{
  "lead": {
    "id": "lead_pl_987654",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phone": "555-234-5678",
    "addressState": "CA",
    "addressCity": "Los Angeles",
    "addressZipCode": "90001",
    "insuranceLineType": "Personal Auto",
    "status": "New"
  },
  "user": {
    "id": "agent_123",
    "email": "agent@falcon.com",
    "firstName": "Agent",
    "lastName": "Smith",
    "phone": "555-987-6543"
  }
}

Response Samples​

HTTP 201 — Personal lead received and stored successfully

{
  "success": true,
  "message": "Personal lines lead received successfully",
  "data": {
    "leadId": "64f9b8c2f1a23c0012345678",
    "externalLeadId": "lead_pl_987654",
    "leadType": "personal",
    "status": "new",
    "createdAt": "2026-10-23T10:30:00.000Z"
  }
}

HTTP 400 — Invalid payload format or malformed JSON

{
  "success": false,
  "error": "Invalid payload format. Expected root object with a 'lead' property."
}

HTTP 401 — Unauthorized - HMAC signature mismatch or expired timestamp

{
  "success": false,
  "error": "Invalid HMAC signature."
}

HTTP 429 — Rate limit exceeded

{
  "success": false,
  "error": "Rate limit exceeded. Too many requests. Please try again later."
}

HTTP 500 — Internal server error

{
  "success": false,
  "error": "Internal server error processing personal lines lead."
}

POST /api/leads/commercial-trucking​

Summary: Ingest commercial trucking insurance lead
Operation ID: ingestCommercialTruckingLead
Authentication: HtiHmacAuth

Receives commercial trucking and logistics lead data transferred from Falcon / HTI CRM. Authenticates via HMAC-SHA256 signature with a 5-minute replay window. Supports DOT number, MC number, EIN number, company legal/DBA names, garaging location, and years in business.

Parameters​

NameInRequiredTypeDescription
x-hti-signatureheaderYesstringHMAC-SHA256 hex signature of {timestamp}.{rawRequestBody}
x-hti-timestampheaderYesstringUnix epoch timestamp in milliseconds

Request Body​

Commercial trucking lead payload

{
  "lead": {
    "id": "lead_truck_5551",
    "companyName": "Apex Express Freight LLC",
    "companyDBA": "Apex Haulers",
    "firstName": "Robert",
    "lastName": "Miller",
    "email": "robert@apexhaulers.com",
    "phone": "555-345-6789",
    "usDot": "3928172",
    "mcNumber": "1482910",
    "einNumber": "84-2918273",
    "garagingState": "TX",
    "garagingCity": "Dallas",
    "garagingZip": "75201",
    "yearsInBusiness": 4,
    "insuranceLineType": "Commercial Auto / Trucking",
    "stage": "Qualified"
  },
  "user": {
    "id": "agent_456",
    "email": "agent@falcon.com"
  }
}

Response Samples​

HTTP 201 — Commercial trucking lead stored successfully

{
  "success": true,
  "message": "Commercial trucking lead received successfully",
  "data": {
    "leadId": "64f9b8c2f1a23c0012345679",
    "externalLeadId": "lead_truck_5551",
    "leadType": "commercial_trucking",
    "status": "new",
    "createdAt": "2026-10-23T10:30:00.000Z"
  }
}

HTTP 400 — Invalid payload format

HTTP 401 — Unauthorized - HMAC mismatch or expired replay window

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

Career Applications​

Applicant resume retrieval (Admin only)

GET /api/career/resume/{id}​

Summary: Download career applicant resume
Operation ID: downloadResume
Authentication: AdminSessionAuth

Securely downloads the uploaded applicant resume binary file for a given CareerForm document ID. Restricted to authenticated administrators.

Parameters​

NameInRequiredTypeDescription
idpathYesstringMongoDB ObjectID of the CareerForm application

Response Samples​

HTTP 200 — Resume binary file stream

HTTP 401 — Unauthorized - Not authenticated as admin

HTTP 403 — Forbidden - Insufficient permissions

HTTP 404 — Career form or resume file not found

{
  "error": "Career form not found"
}

HTTP 429 — Rate limit exceeded

HTTP 500 — Server error downloading resume

Authentication & Verification​

User authentication, password reset, and email verification

GET /api/auth/validate-reset-token​

Summary: Validate password reset token
Operation ID: validateResetToken
Authentication: None (Public)

Lightweight endpoint to pre-validate whether a password reset token exists and has not expired prior to displaying the reset password form.

Parameters​

NameInRequiredTypeDescription
tokenqueryYesstringThe secret password reset verification token

Response Samples​

HTTP 200 — Token validation result

{
  "valid": true,
  "error": "invalid_token"
}

HTTP 400 — Missing required token parameter

{
  "valid": false,
  "error": "Missing token"
}

HTTP 429 — Rate limit exceeded (Strict auth tier)

HTTP 500 — Server error

GET /api/auth/verify-email​

Summary: Verify user email address
Operation ID: verifyEmail
Authentication: None (Public)

Public link clicked by users from their email verification message. Validates the token, marks emailVerified = true on the User record, dispatches the welcome email, and redirects to /sign-in.

Parameters​

NameInRequiredTypeDescription
tokenqueryYesstringEmail verification token

Response Samples​

HTTP 307 — Redirect to sign-in page with status query parameter (verified=true or error=...)

HTTP 429 — Rate limit exceeded

GET /api/auth/{nextauth}​

Summary: NextAuth.js authentication router
Operation ID: nextAuthHandlerGet
Authentication: None (Public)

Built-in NextAuth router handling CSRF tokens, session state retrieval, OAuth providers, and credentials authentication.

Parameters​

NameInRequiredTypeDescription
nextauthpathYesstringNextAuth action path (e.g. session, csrf, providers, signin)

Response Samples​

HTTP 200 — NextAuth JSON response

POST /api/auth/{nextauth}​

Summary: NextAuth.js credentials & signin handler
Operation ID: nextAuthHandlerPost
Authentication: None (Public)

Handles signin submissions, signout, and callback validation.

Parameters​

NameInRequiredTypeDescription
nextauthpathYesstringNextAuth action path (e.g. callback/credentials, signout)

Response Samples​

HTTP 200 — NextAuth JSON response

Marketing Webhooks​

Inbound webhooks from Google Ads, TikTok Ads, and Meta Lead Ads

POST /api/webhook/google​

Summary: Google Ads lead form webhook
Operation ID: googleLeadWebhook
Authentication: None (Public)

Receives lead events from Google Ads Lead Form assets (Search, YouTube, Demand Gen, Display). Optionally verifies HMAC-SHA256 signature using X-Goog-Signature and GOOGLE_WEBHOOK_SECRET. Logs event to GoogleWebhookLog and initiates asynchronous CRM processing.

Parameters​

NameInRequiredTypeDescription
X-Goog-SignatureheaderNostringHMAC signature generated by Google Ads

Request Body​

{
  "lead_id": "1234567890abcdef",
  "campaign_id": 1982739182,
  "campaign_name": "CA Auto Insurance Campaign",
  "ad_network_type": "SEARCH",
  "user_column_data": [
    {
      "column_id": "FIRST_NAME",
      "string_value": "Alice"
    },
    {
      "column_id": "LAST_NAME",
      "string_value": "Smith"
    },
    {
      "column_id": "EMAIL",
      "string_value": "alice@example.com"
    },
    {
      "column_id": "PHONE_NUMBER",
      "string_value": "+15552345678"
    }
  ]
}

Response Samples​

HTTP 200 — Google webhook acknowledged successfully

{
  "success": true,
  "message": "Google webhook received",
  "leadId": "1234567890abcdef"
}

HTTP 400 — Missing lead_id or invalid JSON payload

HTTP 403 — Invalid HMAC signature

HTTP 500 — Server processing error

GET /api/webhook/tiktok​

Summary: TikTok webhook verification handshake
Operation ID: tiktokWebhookVerify
Authentication: None (Public)

Validates TikTok Ads Manager webhook subscription using verify_token and returns challenge in plain text.

Parameters​

NameInRequiredTypeDescription
verify_tokenqueryYesstring
challengequeryYesstring

Response Samples​

HTTP 200 — Plaintext challenge echo

HTTP 403 — Verification failed (token mismatch)

HTTP 500 — Server configuration error

POST /api/webhook/tiktok​

Summary: TikTok lead event webhook
Operation ID: tiktokLeadEvent
Authentication: None (Public)

Receives lead generation event payloads from TikTok Ads Manager and schedules background ingestion.

Request Body​

{
  "lead_id": "tiktok_lead_001",
  "advertiser_id": "adv_9988",
  "campaign_id": "cmp_4433",
  "form_id": "form_123",
  "fields": [
    {
      "name": "name",
      "values": [
        "Alex Driver"
      ]
    }
  ]
}

Response Samples​

HTTP 200 — TikTok webhook received and acknowledged

{
  "success": true,
  "message": "TikTok webhook received",
  "leadId": "tiktok_lead_001"
}

HTTP 400 — Missing lead_id or invalid JSON

HTTP 500 — Internal server error

GET /api/webhooks/meta​

Summary: Meta Lead Ads verification handshake
Operation ID: metaWebhookVerify
Authentication: None (Public)

Validates Meta webhook subscription handshake (hub.mode=subscribe, hub.verify_token, hub.challenge).

Parameters​

NameInRequiredTypeDescription
hub.modequeryYesstring
hub.verify_tokenqueryYesstring
hub.challengequeryYesstring

Response Samples​

HTTP 200 — Challenge string echoed back to Meta

HTTP 400 — Invalid hub.mode

HTTP 403 — Verify token mismatch

HTTP 500 — META_VERIFY_TOKEN not configured

POST /api/webhooks/meta​

Summary: Meta Lead Ads event receiver
Operation ID: metaLeadEvent
Authentication: None (Public)

Receives real-time lead notification from Facebook/Instagram Lead Ads, logs entry, and triggers asynchronous lead retrieval via Graph API.

Request Body​

{
  "object": "page",
  "entry": [
    {
      "id": "109283748291",
      "time": 1726396200,
      "changes": [
        {
          "field": "leadgen",
          "value": {
            "leadgen_id": "987213812739",
            "page_id": "109283748291",
            "form_id": "5544332211",
            "ad_id": "6655443322",
            "campaign_id": "7766554433"
          }
        }
      ]
    }
  ]
}

Response Samples​

HTTP 200 — Webhook received successfully

{
  "success": true,
  "message": "Webhook received",
  "eventsReceived": 1
}

HTTP 400 — Invalid object type or malformed JSON

HTTP 500 — Server error

GET /api/webhooks/meta/debug​

Summary: Meta webhook diagnostics
Operation ID: getMetaWebhookDebug
Authentication: None (Public)

Inspects Meta Graph API configuration, database connectivity, and recent webhook transaction logs.

Response Samples​

HTTP 200 — Diagnostic report

{
  "timestamp": "2026-10-23T10:30:00.000Z",
  "checks": {}
}

POST /api/webhooks/meta/debug​

Summary: Simulate Meta webhook event
Operation ID: simulateMetaWebhook
Authentication: None (Public)

Fetches and processes a specific leadgenId directly from Meta Graph API for end-to-end integration testing.

Request Body​

{
  "leadgenId": "123456789012345"
}

Response Samples​

HTTP 200 — Lead simulated and fetched successfully from Graph API

HTTP 400 — Missing leadgenId or Graph API permission error

HTTP 500 — Internal server error

Meta Leads Management​

Administrative CRUD, search, and retry operations for Meta Lead Ads

GET /api/meta/leads​

Summary: List Meta leads
Operation ID: listMetaLeads
Authentication: AdminSessionAuth

Returns a paginated, filterable, and searchable list of Meta leads. Requires Admin permissions.

Parameters​

NameInRequiredTypeDescription
pagequeryNointeger
limitqueryNointeger
platformqueryNostring
statusqueryNostring
crmStatusqueryNostring
campaignIdqueryNostring
adIdqueryNostring
searchqueryNostring
dateFromqueryNostring
dateToqueryNostring
sortFieldqueryNostring
sortOrderqueryNostring

Response Samples​

HTTP 200 — Paginated list of leads

{
  "data": [
    {}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

HTTP 401 — Unauthorized

HTTP 403 — Forbidden

HTTP 429 — Rate limit exceeded

HTTP 500 — Server error

GET /api/meta/leads/{id}​

Summary: Get single Meta lead details
Operation ID: getMetaLeadById
Authentication: AdminSessionAuth

Returns complete lead details by database ID. Requires Admin permissions.

Parameters​

NameInRequiredTypeDescription
idpathYesstring

Response Samples​

HTTP 200 — Lead record details

{}

HTTP 401 — Unauthorized

HTTP 404 — Lead not found

HTTP 500 — Server error

PATCH /api/meta/leads/{id}​

Summary: Update Meta lead status or notes
Operation ID: updateMetaLead
Authentication: AdminSessionAuth

Updates status, crmStatus, or notes for a Meta lead. Requires Admin permissions.

Parameters​

NameInRequiredTypeDescription
idpathYesstring

Request Body​

{
  "status": "new",
  "crmStatus": "pending",
  "notes": "Customer requested callback tomorrow at 2 PM."
}

Response Samples​

HTTP 200 — Lead updated successfully

{}

HTTP 400 — No valid fields provided to update

HTTP 401 — Unauthorized

HTTP 404 — Lead not found

HTTP 500 — Server error

DELETE /api/meta/leads/{id}​

Summary: Delete Meta lead
Operation ID: deleteMetaLead
Authentication: AdminSessionAuth

Permanently deletes a Meta lead record. Requires Admin permissions.

Parameters​

NameInRequiredTypeDescription
idpathYesstring

Response Samples​

HTTP 200 — Lead deleted successfully

{
  "success": true
}

HTTP 401 — Unauthorized

HTTP 404 — Lead not found

HTTP 500 — Server error

POST /api/meta/leads/{id}/retry​

Summary: Retry failed Meta lead processing
Operation ID: retryMetaLead
Authentication: AdminSessionAuth

Re-triggers asynchronous Graph API lead retrieval and forwarding for a previously failed lead.

Parameters​

NameInRequiredTypeDescription
idpathYesstring

Response Samples​

HTTP 200 — Retry initiated

{
  "success": true,
  "message": "Retry initiated. Lead will be processed asynchronously."
}

HTTP 400 — Unable to retry lead (e.g. max retries exceeded)

HTTP 401 — Unauthorized

HTTP 429 — Rate limit exceeded

HTTP 500 — Server error

Public Website Forms​

Public user-facing form submissions (quotes, contact, events, claims, careers, privacy, newsletter, waitlist). Protected by resilient Google reCAPTCHA v3 verification with ad-blocker fail-open handling and quarantine audit logging.

POST /api/forms/quote/draft​

Summary: Step 1: Submit draft insurance quote lead
Operation ID: createQuoteDraft
Authentication: None (Public)

Creates an initial draft lead capturing personal contact details and desired insurance line. Returns a leadId to be completed in Step 2.

Request Body​

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "5551234567",
  "insuranceType": "auto",
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Draft lead created successfully

{
  "success": true,
  "data": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "firstName": "string",
    "email": "string",
    "insuranceType": "string",
    "status": "draft"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/quote/complete​

Summary: Step 2: Submit detailed insurance quote information
Operation ID: completeQuoteLead
Authentication: None (Public)

Completes an existing draft lead with detailed coverage attributes (auto, home, truck, commercial). Also supports direct completion without a prior draft.

Request Body​

{
  "leadId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "5551234567",
  "insuranceType": "auto",
  "state": "TX",
  "zipCode": "75001",
  "autoDetails": {
    "vehicles": [
      {
        "year": "string",
        "make": "string",
        "model": "string"
      }
    ]
  },
  "homeDetails": {
    "propertyType": "string",
    "squareFootage": "string"
  },
  "truckDetails": {
    "companyName": "string",
    "dot": "string",
    "fleetSize": "string"
  },
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 200 — Lead completed successfully

{
  "success": true,
  "data": {
    "_id": "string",
    "status": "completed"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/events/{slug}/leads​

Summary: Submit attendee event lead via QR campaign
Operation ID: submitEventLead
Authentication: None (Public)

Captures dynamic attendee responses for a promotional event campaign identified by slug.

Parameters​

NameInRequiredTypeDescription
slugpathYesstringEvent campaign URL slug

Request Body​

{
  "responses": {
    "name": "Alex Smith",
    "phone": "5559876543",
    "email": "alex@example.com",
    "truckCount": "5"
  }
}

Response Samples​

HTTP 201 — Event lead submitted successfully

{
  "success": true,
  "message": "Lead captured successfully"
}

HTTP 400 — Missing required fields or validation failure

HTTP 404 — Event not found or inactive

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/careers/apply​

Summary: Submit career application with resume
Operation ID: applyCareer
Authentication: None (Public)

Submits an employment application including applicant details, experience statement, and base64-encoded resume file.

Request Body​

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "phone": "5551234567",
  "state": "TX",
  "experience": "5+ years in commercial insurance underwriting and customer service.",
  "resume": {
    "name": "resume.pdf",
    "mimeType": "application/pdf",
    "data": "data:application/pdf;base64,JVBERi0xLj..."
  },
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Application submitted successfully

{
  "success": true,
  "data": {
    "_id": "string",
    "firstName": "string",
    "email": "string"
  }
}

HTTP 400 — Validation failed or file error

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/contact​

Summary: Submit general Contact Us inquiry
Operation ID: submitContactMessage
Authentication: None (Public)

Submits a customer inquiry or support message to the Hitech customer care team.

Request Body​

{
  "name": "Carlos Gomez",
  "email": "carlos@example.com",
  "subject": "Policy Question",
  "message": "I would like to inquire about combining my commercial and personal coverage.",
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Contact message sent successfully

{
  "success": true,
  "data": {
    "_id": "string",
    "name": "string"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/claims​

Summary: Submit insurance claim report
Operation ID: submitClaimReport
Authentication: None (Public)

Initiates a formal insurance policy claim report for accident, property loss, or commercial incidents.

Request Body​

{
  "firstName": "Robert",
  "lastName": "Johnson",
  "email": "robert@example.com",
  "phone": "5553334444",
  "isCustomer": "yes",
  "consent": true,
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Claim filed successfully

{
  "success": true,
  "data": {
    "_id": "string",
    "firstName": "string"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/schedule-call​

Summary: Schedule agent phone callback
Operation ID: scheduleCall
Authentication: None (Public)

Books a preferred date and time slot for a phone consultation with a licensed agent.

Request Body​

{
  "firstName": "Sarah",
  "lastName": "Miller",
  "email": "sarah@example.com",
  "phone": "5557778888",
  "preferredDate": "2026-10-15",
  "preferredTime": "2:00 PM",
  "insuranceType": "commercial",
  "source": "website",
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Call appointment scheduled successfully

{
  "success": true,
  "data": {
    "_id": "string",
    "preferredDate": "string",
    "preferredTime": "string"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/newsletter​

Summary: Subscribe to newsletter
Operation ID: subscribeNewsletter
Authentication: None (Public)

Registers an email address for newsletter updates, special offers, and safety tips.

Request Body​

{
  "email": "subscriber@example.com",
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Newsletter subscription successful

{
  "success": true,
  "data": {
    "_id": "string",
    "email": "string"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 409 — Email already subscribed

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/privacy/intake​

Summary: Submit consumer privacy rights request (CCPA/GDPR)
Operation ID: submitPrivacyIntake
Authentication: None (Public)

Submits a formal consumer privacy intake request (know, delete, opt-out, correct) under applicable state privacy legislation.

Request Body​

{
  "state": "california",
  "requestType": "delete",
  "whoAreYou": "consumer",
  "firstName": "Maria",
  "lastName": "Garcia",
  "email": "maria@example.com",
  "phone": "5554445555",
  "address": "123 Main St",
  "city": "Austin",
  "zipCode": "78701",
  "authorizedAgent": "no",
  "attachment": {
    "name": "string",
    "contentType": "string",
    "contentInBase64": "string"
  },
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Privacy request submitted successfully

{
  "success": true,
  "data": {
    "_id": "string",
    "requestId": "PRI-000042"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/privacy/appeal​

Summary: Submit privacy decision appeal
Operation ID: submitPrivacyAppeal
Authentication: None (Public)

Submits a formal appeal regarding a previously processed or denied privacy request.

Request Body​

{
  "state": "texas",
  "prevRequestId": "PRI-000042",
  "firstName": "Maria",
  "lastName": "Garcia",
  "email": "maria@example.com",
  "phone": "5554445555",
  "explanation": "I am appealing the denial of deletion request PRI-000042.",
  "recaptchaToken": "03AFcWeA..."
}

Response Samples​

HTTP 201 — Appeal submitted successfully

{
  "success": true,
  "data": {
    "_id": "string",
    "requestId": "PAP-000015"
  }
}

HTTP 400 — Validation failed

HTTP 403 — Bot suspected / submission rejected by reCAPTCHA guard (score < 0.10)

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

POST /api/forms/waitlist​

Summary: Join mobile application waitlist
Operation ID: joinAppWaitlist
Authentication: None (Public)

Registers an email address for early access notification when the Hitech mobile app launches.

Request Body​

{
  "email": "user@example.com"
}

Response Samples​

HTTP 201 — Added to waitlist successfully

{
  "success": true,
  "data": {
    "email": "user@example.com"
  }
}

HTTP 400 — Invalid email

HTTP 429 — Rate limit exceeded

HTTP 500 — Internal server error

User Profile​

User panel profile retrieval and contact info management (locked full name, editable email and phone)

GET /api/user/profile​

Summary: Get current user profile
Operation ID: getUserProfile
Authentication: AdminSessionAuth

Retrieves the authenticated user's profile details including locked full name, email, phone, and role.

Response Samples​

HTTP 200 — Profile successfully retrieved

{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "fullName": "string",
    "email": "string",
    "phone": "string",
    "role": "user",
    "referralCode": "string"
  }
}

HTTP 401 — Unauthorized

HTTP 404 — User not found

HTTP 500 — Internal server error

PATCH /api/user/profile​

Summary: Profile modification endpoint (Locked)
Operation ID: updateUserProfile
Authentication: AdminSessionAuth

User profile information (full name, email, phone) is locked for verified insurance policy compliance. Modifications are disabled and return 403 Forbidden.

Response Samples​

HTTP 403 — Forbidden - user profile fields are locked

POST /api/user/profile/avatar​

Summary: Upload and update user profile avatar
Operation ID: uploadUserAvatar
Authentication: AdminSessionAuth

Uploads a cropped base64 image (PNG, JPG, or WebP up to 2MB) and stores it as the authenticated user's profile avatar.

Request Body​

{
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

Response Samples​

HTTP 200 — Profile avatar updated successfully

{
  "success": true,
  "data": {
    "profilePictureUrl": "string"
  }
}

HTTP 400 — Invalid image format or payload exceeds 2MB limit

HTTP 401 — Unauthorized

HTTP 404 — User account not found

HTTP 500 — Internal server error

DELETE /api/user/profile/avatar​

Summary: Delete user profile avatar
Operation ID: deleteUserAvatar
Authentication: AdminSessionAuth

Removes profile picture for authenticated user.

Response Samples​

HTTP 200 — Avatar removed successfully

{
  "success": true,
  "data": {
    "profilePictureUrl": null
  }
}

HTTP 401 — Unauthorized

HTTP 404 — User account not found

HTTP 500 — Internal server error

GET /api/user/submissions​

Summary: Get authenticated user submissions and saved drafts
Operation ID: getUserSubmissions
Authentication: AdminSessionAuth

Retrieves complete submission history including quotes, contact messages, scheduled calls, claims, and resumable incomplete draft applications for authenticated user.

Response Samples​

HTTP 200 — User submissions and drafts retrieved successfully

{
  "success": true,
  "data": {
    "quotes": [
      {}
    ],
    "drafts": [
      {}
    ],
    "calls": [
      {}
    ],
    "claims": [
      {}
    ],
    "contacts": [
      {}
    ]
  }
}

HTTP 401 — Unauthorized

HTTP 500 — Internal server error

Referral Program​

Customer referral rewards, unique link generation, email invitations, and paginated referral activities

GET /api/referral​

Summary: Get referral overview data
Operation ID: getReferralOverview
Authentication: AdminSessionAuth

Retrieves referral metrics, referral link, and user referral info. Disabled for administrative accounts.

Response Samples​

HTTP 200 — Referral data retrieved

{
  "success": true,
  "data": {
    "referralCode": "string",
    "referralLink": "string",
    "totalReferrals": 0,
    "pendingRewards": 0,
    "claimedRewards": 0
  }
}

HTTP 401 — Unauthorized

HTTP 403 — Feature disabled for admins

HTTP 500 — Internal server error

GET /api/referral/activities​

Summary: Get paginated referral activities
Operation ID: getReferralActivities
Authentication: AdminSessionAuth

Retrieves referral activity log with search, reward status filtering, and sorting. Disabled for admins.

Parameters​

NameInRequiredTypeDescription
pagequeryNointeger
limitqueryNointeger
searchqueryNostring
rewardStatusqueryNostring
sortByqueryNostring

Response Samples​

HTTP 200 — Paginated activities list

HTTP 401 — Unauthorized

HTTP 403 — Feature disabled for admins

HTTP 500 — Internal server error

POST /api/referral/invite​

Summary: Send referral email invitation
Operation ID: sendReferralInvite
Authentication: AdminSessionAuth

Sends an email invite with the authenticated user's referral code. Disabled for admins.

Request Body​

{
  "email": "referee@example.com"
}

Response Samples​

HTTP 200 — Invitation sent successfully

HTTP 400 — Invalid email or self-invite

HTTP 401 — Unauthorized

HTTP 403 — Feature disabled for admins

HTTP 422 — Validation error

HTTP 429 — Daily invite limit reached

HTTP 500 — Internal server error

Email Signatures & Media​

Public streaming endpoints for persistent email signatures and inline rich-text images in outgoing emails and templates

GET /api/signatures/{id}​

Summary: Stream public email signature or inline image
Operation ID: getSignatureImage
Authentication: None (Public)

Public high-performance image streaming endpoint for database-backed custom email signatures and inline rich-text images embedded in bulk email campaigns and reusable templates. Returns raw image binary with immutable client caching headers (Cache-Control: public, max-age=31536000, immutable), guaranteeing 100% rendering fidelity across strict enterprise desktop and mobile email clients (Gmail, Outlook, Apple Mail) without requiring user authentication.

Parameters​

NameInRequiredTypeDescription
idpathYesstringMongoDB ObjectId of the signature or inline media image document

Response Samples​

HTTP 200 — Image binary stream with content type and immutable cache headers

HTTP 400 — Invalid signature ID format (not a valid 24-character hex ObjectId)

HTTP 404 — Signature or inline image asset not found in database

HTTP 500 — Internal server error streaming media

Telemetry & Analytics​

Real-time client telemetry, active presence heartbeat beacons, visitor navigation journeys, and blog view analytics

POST /api/telemetry/visit​

Summary: Record visitor page visit
Operation ID: recordTelemetryVisit
Authentication: None (Public)

Logs client geolocation (country code, US state code) and daily visit aggregates derived from CDN headers, in-memory GeoIP lookup, client timezone, or locale.

Request Body​

{
  "timeZone": "America/Los_Angeles",
  "locale": "en-US"
}

Response Samples​

HTTP 200 — Visit recorded successfully

{
  "ok": true,
  "country": "US",
  "region": "CA"
}

HTTP 500 — Failed to record visit

{
  "ok": false
}

POST /api/telemetry/blog-visit​

Summary: Record editorial blog article view
Operation ID: recordBlogVisit
Authentication: None (Public)

Increments aggregate view counter for an editorial blog article slug and synchronizes article title in the database.

Request Body​

{
  "slug": "commercial-auto-insurance-guide",
  "title": "Comprehensive Guide to Commercial Auto Insurance"
}

Response Samples​

HTTP 200 — Blog visit recorded successfully

{
  "ok": true,
  "slug": "commercial-auto-insurance-guide"
}

HTTP 400 — Missing or invalid article slug

{
  "ok": false,
  "error": "Missing slug"
}

HTTP 500 — Server error

{
  "ok": false
}

POST /api/telemetry/journey​

Summary: Track visitor navigation journey event
Operation ID: trackVisitorJourney
Authentication: None (Public)

Logs granular visitor session events (PAGE_VIEW, FORM_START, FORM_SUBMIT, CTA_CLICK, AUTH), UTM attribution, and device telemetry for analytics and funnel drop-off tracking.

Request Body​

{
  "sessionId": "sess_98fbc12093",
  "visitorId": "vis_10928374",
  "event": {
    "type": "PAGE_VIEW",
    "path": "/insurance/commercial-trucking",
    "title": "Commercial Trucking Insurance"
  },
  "timeZone": "America/Phoenix",
  "landingPage": "/insurance/commercial-trucking",
  "utmSource": "google",
  "utmMedium": "cpc"
}

Response Samples​

HTTP 200 — Journey event recorded successfully

{
  "success": true
}

HTTP 400 — Invalid payload: missing sessionId or event path

{
  "error": "Invalid payload: missing sessionId or event path"
}

HTTP 500 — Server error

{
  "success": false
}

POST /api/telemetry/heartbeat​

Summary: Active presence heartbeat beacon
Operation ID: recordTelemetryHeartbeat
Authentication: None (Public)

Receives periodic 20-second active presence pings from active browser sessions to populate real-time online visitor monitors. Also removes visitors when action is 'leave'.

Request Body​

{
  "sessionId": "sess_a89bc3",
  "page": "/quote",
  "countryCode": "US",
  "timeZone": "America/Chicago",
  "action": "heartbeat"
}

Response Samples​

HTTP 200 — Heartbeat processed successfully

{
  "ok": true,
  "countryCode": "US"
}

HTTP 400 — Missing sessionId

{
  "ok": false,
  "error": "Missing sessionId"
}

HTTP 500 — Server error

{
  "ok": false
}

API Documentation​

Interactive Swagger OpenAPI documentation UI, authentication challenge, and raw JSON specification

GET /api/docs​

Summary: Interactive Swagger OpenAPI documentation UI
Operation ID: getSwaggerDocsUi
Authentication: None (Public)

Renders the interactive Swagger API Explorer interface when authenticated. If unauthenticated, serves an access key password challenge page.

Response Samples​

HTTP 200 — HTML page rendering Swagger UI or Access Key challenge dialog

<!-- HTML Content / Document Stream -->

POST /api/docs/auth​

Summary: Authenticate Swagger documentation access
Operation ID: loginSwaggerDocs
Authentication: None (Public)

Validates access key against SWAGGER_DOCS_PASSWORD_HASH using bcrypt and sets an HTTP-only secure cookie ('hti_swagger_token'). Protected by strict brute-force rate limiting.

Request Body​

{
  "password": "your_swagger_access_password"
}

Response Samples​

HTTP 200 — Swagger documentation unlocked successfully

{
  "success": true,
  "message": "Swagger documentation unlocked successfully."
}

HTTP 400 — Missing or malformed password

{
  "success": false,
  "error": "Password is required"
}

HTTP 401 — Incorrect access key

{
  "success": false,
  "error": "Incorrect access key. Please try again."
}

HTTP 429 — Brute-force rate limit exceeded

{
  "success": false,
  "error": "Too many failed attempts. Please wait before trying again.",
  "message": "string"
}

HTTP 500 — Internal server error during verification

{
  "success": false,
  "error": "Internal server error during verification."
}

DELETE /api/docs/auth​

Summary: Lock Swagger documentation session
Operation ID: logoutSwaggerDocs
Authentication: None (Public)

Clears the active Swagger documentation cookie session.

Response Samples​

HTTP 200 — Swagger documentation session locked

{
  "success": true,
  "message": "Swagger documentation session locked."
}

GET /api/docs/openapi.json​

Summary: Get raw OpenAPI 3.0 specification JSON
Operation ID: getOpenApiSpecJson
Authentication: SwaggerSessionAuth

Returns the complete OpenAPI 3.0 specification in JSON format. Requires Basic HTTP Authentication or an active Swagger session cookie.

Response Samples​

HTTP 200 — OpenAPI 3.0 JSON specification object

{}

HTTP 401 — Unauthorized - Authentication required

{
  "error": "Unauthorized",
  "message": "Authentication required to access OpenAPI documentation specification."
}

Text-to-Speech & Voice Services​

Edge neural speech synthesis powered by msedge-tts v2.1.1 and Microsoft Azure Neural Voice services

POST /api/tts​

Summary: Synthesize text into high-fidelity neural MP3 speech
Operation ID: synthesizeSpeechPost
Authentication: None (Public)

Synthesizes arbitrary localized legal or platform text into natural human-grade neural audio. Supports 20+ specialized neural voices across 11 regional dialects (US, UK, Canadian, Australian, Irish, New Zealand English, Mexican/European Spanish, Hindi, Punjabi) with speed rate adjustments. Implements an in-memory 500-chunk LRU buffer cache and returns binary audio stream with immutable HTTP caching headers (Cache-Control: public, max-age=31536000, immutable).

Request Body​

FieldTypeRequiredDefaultDescription
textstringYes—Plain text string to synthesize into speech
voicestringNo"en-US-JennyNeural"Neural voice identifier from the allowed voices catalog
ratenumberNo1.0Playback speed rate multiplier (e.g. 0.75, 1.0, 1.25, 1.5)
{
  "text": "HiTech Insurance is committed to protecting your privacy and commercial transportation data.",
  "voice": "en-US-JennyNeural",
  "rate": 1.0
}

Response Samples​

HTTP 200 — Binary MPEG audio stream (audio/mpeg)

  • Content-Type: audio/mpeg
  • Cache-Control: public, max-age=31536000, immutable
  • Content-Length: Size in bytes of audio binary

HTTP 400 — Missing or invalid text parameter

{
  "error": "Missing or invalid text parameter"
}

HTTP 500 — Failed to synthesize speech

{
  "error": "Failed to synthesize speech"
}

GET /api/tts​

Summary: Synthesize text into neural MP3 speech via query parameters
Operation ID: synthesizeSpeechGet
Authentication: None (Public)

Provides direct streaming URL support for standard HTML5 <audio> tags and native browser media player requests.

Parameters​

NameInRequiredTypeDefaultDescription
textqueryYesstring—URL-encoded text string to synthesize
voicequeryNostring"en-US-JennyNeural"Neural voice identifier
ratequeryNonumber1.0Playback speed rate multiplier

Response Samples​

HTTP 200 — Binary MPEG audio stream (audio/mpeg)