Funnel API Reference

API endpoints for managing vendor funnel links and accessing funnel analytics.

Authentication

All endpoints require authentication via API key or session token.

Authorization: Bearer YOUR_TOKEN

Or for internal requests:

Authorization: YOUR_API_KEY

Vendor Funnel Links

List Funnel Links

Get all configured funnel links for your organization.

GET /api/vendor-funnel-links

Response:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "inquiryVendorId": "660e8400-e29b-41d4-a716-446655440001",
      "inquiryVendorName": "Facebook Lead Ads",
      "applicationVendorId": "770e8400-e29b-41d4-a716-446655440002",
      "applicationVendorName": "Full Application Form",
      "timeWindowHours": 24,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Create Funnel Link

Create a new link between an inquiry vendor and an application vendor.

POST /api/vendor-funnel-links

Request Body:

Field	Type	Required	Description
inquiryVendorId	string (UUID)	Yes	ID of the inquiry vendor
applicationVendorId	string (UUID)	Yes	ID of the application vendor
timeWindowHours	integer	No	Match window in hours (default: 24)

Example Request:

{
  "inquiryVendorId": "660e8400-e29b-41d4-a716-446655440001",
  "applicationVendorId": "770e8400-e29b-41d4-a716-446655440002",
  "timeWindowHours": 24
}

Response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "inquiryVendorId": "660e8400-e29b-41d4-a716-446655440001",
    "applicationVendorId": "770e8400-e29b-41d4-a716-446655440002",
    "timeWindowHours": 24,
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

Errors:

Code	Message	Cause
400	Inquiry vendor must have type ‘inquiry’	Vendor is not set to inquiry type
400	Application vendor must have type ‘application’	Vendor is not set to application type
400	Funnel link already exists	This vendor pair is already linked
404	Vendor not found	Invalid vendor ID

Delete Funnel Link

Remove a funnel link.

DELETE /api/vendor-funnel-links/:id

Parameters:

Parameter	Type	Description
id	string (UUID)	The funnel link ID

Response:

{
  "success": true,
  "message": "Funnel link deleted"
}

Check for Funnel Links

Check if any funnel links are configured. Used to conditionally show the funnel analytics dashboard.

GET /api/vendor-funnel-links/has-links

Response:

{
  "success": true,
  "hasLinks": true
}

Funnel Analytics

Funnel Overview

Get summary metrics for the lead funnel.

GET /api/analytics/funnel/overview

Query Parameters:

Parameter	Type	Required	Description
startDate	string (ISO 8601)	No	Start of period (default: 30 days ago)
endDate	string (ISO 8601)	No	End of period (default: today)

Example Request:

GET /api/analytics/funnel/overview?startDate=2025-01-01&endDate=2025-01-31

Response:

{
  "success": true,
  "data": {
    "period": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    },
    "totalInquiries": 1500,
    "totalApplications": 850,
    "matchedApplications": 450,
    "conversionRate": 0.30,
    "averageTimeToConvertSeconds": 14400,
    "averageTimeToConvertFormatted": "4 hours"
  }
}

Time-to-Convert Breakdown

Get distribution of conversion times.

GET /api/analytics/funnel/time-to-convert

Query Parameters:

Parameter	Type	Required	Description
startDate	string (ISO 8601)	No	Start of period
endDate	string (ISO 8601)	No	End of period

Response:

{
  "success": true,
  "data": {
    "period": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    },
    "distribution": [
      {
        "bucket": "0-1hr",
        "count": 120,
        "percentage": 0.267
      },
      {
        "bucket": "1-6hr",
        "count": 150,
        "percentage": 0.333
      },
      {
        "bucket": "6-12hr",
        "count": 80,
        "percentage": 0.178
      },
      {
        "bucket": "12-24hr",
        "count": 60,
        "percentage": 0.133
      },
      {
        "bucket": "24hr+",
        "count": 40,
        "percentage": 0.089
      }
    ],
    "totalConversions": 450,
    "medianTimeToConvertSeconds": 10800,
    "medianTimeToConvertFormatted": "3 hours"
  }
}

Drop-off Analysis

Get information about unconverted inquiries.

GET /api/analytics/funnel/drop-offs

Query Parameters:

Parameter	Type	Required	Description
startDate	string (ISO 8601)	No	Start of period
endDate	string (ISO 8601)	No	End of period
minAgeHours	integer	No	Minimum age of inquiry to consider dropped (default: 24)

Response:

{
  "success": true,
  "data": {
    "period": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    },
    "totalDroppedInquiries": 1050,
    "dropOffRate": 0.70,
    "byVendor": [
      {
        "vendorId": "660e8400-e29b-41d4-a716-446655440001",
        "vendorName": "Facebook Lead Ads",
        "droppedCount": 450,
        "totalInquiries": 600,
        "dropOffRate": 0.75
      },
      {
        "vendorId": "770e8400-e29b-41d4-a716-446655440002",
        "vendorName": "Google Lead Forms",
        "droppedCount": 350,
        "totalInquiries": 500,
        "dropOffRate": 0.70
      }
    ],
    "byAge": [
      {
        "bucket": "24-48hr",
        "count": 200
      },
      {
        "bucket": "2-7days",
        "count": 500
      },
      {
        "bucket": "7days+",
        "count": 350
      }
    ]
  }
}

By-Vendor Metrics

Get funnel metrics broken down by vendor pair.

GET /api/analytics/funnel/by-vendor

Query Parameters:

Parameter	Type	Required	Description
startDate	string (ISO 8601)	No	Start of period
endDate	string (ISO 8601)	No	End of period

Response:

{
  "success": true,
  "data": {
    "period": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    },
    "vendorPairs": [
      {
        "inquiryVendorId": "660e8400-e29b-41d4-a716-446655440001",
        "inquiryVendorName": "Facebook Lead Ads",
        "applicationVendorId": "880e8400-e29b-41d4-a716-446655440003",
        "applicationVendorName": "Full Application Form",
        "inquiries": 600,
        "conversions": 150,
        "conversionRate": 0.25,
        "averageTimeToConvertSeconds": 12600,
        "averageTimeToConvertFormatted": "3.5 hours"
      },
      {
        "inquiryVendorId": "770e8400-e29b-41d4-a716-446655440002",
        "inquiryVendorName": "Google Lead Forms",
        "applicationVendorId": "880e8400-e29b-41d4-a716-446655440003",
        "applicationVendorName": "Full Application Form",
        "inquiries": 500,
        "conversions": 175,
        "conversionRate": 0.35,
        "averageTimeToConvertSeconds": 9000,
        "averageTimeToConvertFormatted": "2.5 hours"
      }
    ]
  }
}

Daily Trends

Get daily funnel metrics for trend analysis.

GET /api/analytics/funnel/daily

Query Parameters:

Parameter	Type	Required	Description
startDate	string (ISO 8601)	No	Start of period
endDate	string (ISO 8601)	No	End of period

Response:

{
  "success": true,
  "data": {
    "period": {
      "start": "2025-01-01",
      "end": "2025-01-07"
    },
    "daily": [
      {
        "date": "2025-01-01",
        "inquiries": 50,
        "applications": 30,
        "conversions": 15,
        "conversionRate": 0.30
      },
      {
        "date": "2025-01-02",
        "inquiries": 55,
        "applications": 32,
        "conversions": 18,
        "conversionRate": 0.33
      },
      {
        "date": "2025-01-03",
        "inquiries": 48,
        "applications": 28,
        "conversions": 14,
        "conversionRate": 0.29
      }
    ]
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Invalid date range",
  "details": {
    "startDate": "Must be before endDate"
  }
}

401 Unauthorized

{
  "success": false,
  "error": "Authentication required"
}

403 Forbidden

{
  "success": false,
  "error": "Insufficient permissions"
}

404 Not Found

{
  "success": false,
  "error": "Resource not found"
}

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "requestId": "req_abc123"
}

Rate Limits

Funnel API endpoints share the standard rate limits:

Plan	Requests/Minute
Education ($899/mo)	500
Enterprise ($1,999/mo)	1000

Lead Funnel Guide - Feature overview and configuration
Lead Ingestion API - Lead submission endpoints
Authentication - API authentication

Lead Ingestion Enrichment

Funnel API Reference

Authentication

Vendor Funnel Links

List Funnel Links

Create Funnel Link

Delete Funnel Link

Check for Funnel Links

Funnel Analytics

Funnel Overview

Time-to-Convert Breakdown

Drop-off Analysis

By-Vendor Metrics

Daily Trends

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Rate Limits

Related Documentation