API Documentation

Integrate Mouthfully tracking into your application with our RESTful API

Overview

The Mouthfully Tracking API allows you to send tracking events from your website or application. All requests should be made to:

POST https://mouthfully.com/api/track

Authentication

The API uses your unique tracking_code to identify your company. You can find your tracking code in your dashboard after signing up.

No API keys or tokens required—just include your tracking_code in the request body.

Track Event

Send tracking events to record page views, referral clicks, email captures, and conversions. The widget automatically handles visitor identification, session management, and referral code storage. When embedded on your website, it automatically tracks page views and referral clicks without any manual configuration.

POST/api/track

Request Body

{
  "tracking_code": "REF-XXXXXXXXXXXX",  // Required
  "event_type": "page_view",            // Required
  "visitor_id": "unique-visitor-id",    // Required
  "session_id": "unique-session-id",    // Required
  
  // Optional fields
  "referral_code": "REF123",
  "page_url": "https://example.com",
  "customer_email": "user@example.com",
  "conversion_value": 99.99,
  "metadata": { "custom": "data" }
}

Event Types

page_view

Automatically tracked on every page load. Includes page URL, path, referrer, and user agent. No manual action required when using the widget.

referral_click

Automatically tracked when clicking links with referral codes in URL parameters (e.g., ?mthf=REF123). No manual action required when using the widget.

email_capture

Track when a user provides their email. Use MouthfullyTracking.trackEmailCapture(email).

conversion

Track purchases or conversions. Requires customer_email. Use MouthfullyTracking.trackConversion(data) on your checkout success page.

custom

Custom events for your specific use cases. Use MouthfullyTracking.trackEvent('custom', data).

How Automatic Tracking Works

Visitor ID: Generated once per visitor and stored in localStorage (persists 30+ days)
Session ID: Generated new for each page load to track individual sessions
Referral Codes: Extracted from URL parameters (e.g., ?mthf=REF123) and stored in cookies/localStorage for 30 days
Page Context: Automatically includes page URL, path, referrer, and user agent in all events

Example Requests

Track Page View

fetch('https://mouthfully.com/api/track', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tracking_code: 'REF-XXXXXXXXXXXX',
    event_type: 'page_view',
    visitor_id: 'visitor-123',
    session_id: 'session-456',
    page_url: window.location.href
  })
});

Track Conversion

fetch('https://mouthfully.com/api/track', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tracking_code: 'REF-XXXXXXXXXXXX',
    event_type: 'conversion',
    visitor_id: 'visitor-123',
    session_id: 'session-456',
    customer_email: 'customer@example.com',
    conversion_type: 'purchase',
    conversion_value: 99.99,
    order_id: 'ORDER-12345'
  })
});

Error Codes

400Bad Request

Missing required fields or invalid event_type

403Forbidden

Account not active or monthly limit reached

404Not Found

Invalid tracking_code

500Server Error

Internal server error occurred

Ready to Get Started?

Get Started Free