Marketing API Reference

`GET /functions/v1/marketing-report-locations`

Returns the list of location IDs available for a granted franchise.

Query Parameters

Name	Required	Description
`franchise_id`	Yes	Must be one of the franchise IDs granted to the bearer token

Example Request

GET /functions/v1/marketing-report-locations?franchise_id=0d8b6af2-4f5d-4c44-8df5-9b77f5743b10
Authorization: Bearer <api_token>

Example Response

{
  "franchise_id": "0d8b6af2-4f5d-4c44-8df5-9b77f5743b10",
  "locations": [
    {
      "location_id": "5b0af77c-c488-4e8b-a834-fbe8d9b0a3f3",
      "location_name": "Westfield"
    },
    {
      "location_id": "7f0a95c2-b84a-45ae-92e9-f57a4d27d5f1",
      "location_name": "North Metro"
    }
  ]
}

`GET /functions/v1/marketing-report-filters`

Returns franchise-scoped campaign and market values that can be used on the summary request.

Query Parameters

Name	Required	Description
`franchise_id`	Yes	Must be one of the franchise IDs granted to the bearer token

Example Request

GET /functions/v1/marketing-report-filters?franchise_id=0d8b6af2-4f5d-4c44-8df5-9b77f5743b10
Authorization: Bearer <api_token>

Example Response

{
  "franchise_id": "0d8b6af2-4f5d-4c44-8df5-9b77f5743b10",
  "markets": [
    "Westfield",
    "North Metro",
    "River District",
    "South County"
  ],
  "campaigns": [
    "Brand Search - March 2026",
    "Water Damage - Core",
    "Storm Response - Expansion"
  ]
}

`GET /functions/v1/marketing-report-summary`

Returns the final aggregated totals for the reporting period.

Query Parameters

Name	Required	Description
`franchise_id`	Yes	Must be one of the franchise IDs granted to the bearer token
`start_date`	Yes	Inclusive report start date
`end_date`	Yes	Inclusive report end date
`location_id`	No	Optional location filter; must belong to the requested granted franchise
`campaign`	No	Optional campaign filter; should come from `marketing-report-filters`
`market`	No	Optional market filter; should come from `marketing-report-filters`

Validation Rules

start_date and end_date are required
start_date must be less than or equal to end_date
campaign and market should come from the franchise filter lookup endpoint

Example Request

GET /functions/v1/marketing-report-summary?franchise_id=0d8b6af2-4f5d-4c44-8df5-9b77f5743b10&location_id=5b0af77c-c488-4e8b-a834-fbe8d9b0a3f3&campaign=Water%20Damage%20-%20Core&market=Westfield&start_date=2026-03-01&end_date=2026-03-31
Authorization: Bearer <api_token>

Example Response

{
  "report_period": {
    "start_date": "2026-03-01",
    "end_date": "2026-03-31"
  },
  "scope": {
    "franchise_id": "0d8b6af2-4f5d-4c44-8df5-9b77f5743b10",
    "location_id": "5b0af77c-c488-4e8b-a834-fbe8d9b0a3f3"
  },
  "summary_metrics": {
    "ad_spend": 24555.00,
    "paid_media_calls": 72,
    "matched_calls": 41,
    "unique_jobs_matched": 54,
    "phone_match_rate": 0.569,
    "unmatched_calls": 31,
    "won_collected": 75800.00,
    "open_pipeline_estimate": 57400.00,
    "lost_job_estimate": 34100.00,
    "total_pipeline": 167300.00,
    "won_roas": 5.42,
    "total_pipeline_roas": 6.81,
    "won_roi": 4.42
  },
  "market_breakdown": [
    {
      "market_name": "Westfield",
      "ad_spend": 5420.00,
      "paid_media_calls": 15,
      "matched_calls": 9,
      "unmatched_calls": 6,
      "phone_match_rate": 0.60,
      "unique_jobs_matched": 12,
      "won_jobs": 4,
      "open_jobs": 3,
      "lost_jobs": 5,
      "won_collected": 18400.00,
      "open_pipeline_estimate": 13800.00,
      "lost_job_estimate": 11000.00,
      "total_pipeline": 43200.00,
      "won_roas": 5.94,
      "total_pipeline_roas": 7.97,
      "won_roi": 4.94
    }
  ],
  "jobs_lost_reason_buckets": [
    { "bucket": "Could not reach customer", "count": 8 },
    { "bucket": "Customer chose competitor", "count": 6 }
  ],
  "unmatched_call_buckets": [
    { "bucket": "New Service Leads", "count": 9 },
    { "bucket": "Follow-ups on Existing Work", "count": 7 },
    { "bucket": "Not Service Leads", "count": 8 },
    { "bucket": "Other - Requested Live Agent", "count": 4 },
    { "bucket": "No Record Found", "count": 3 }
  ]
}