Marketing API Reference

Endpoint Index

Endpoint	Method	Path	Purpose
List Franchises	`GET`	`https://api.breesy.app/marketing/franchises`	Returns franchises granted to the bearer token
List Locations	`GET`	`https://api.breesy.app/marketing/locations`	Returns granted franchise locations
List Filters	`GET`	`https://api.breesy.app/marketing/filters`	Returns valid campaign and market filters
Get Summary	`GET`	`https://api.breesy.app/marketing/summary`	Returns rolled-up reporting totals
List Call Details	`GET`	`https://api.breesy.app/marketing/call-details`	Returns call records grouped by market or location
Get Call Detail	`GET`	`https://api.breesy.app/marketing/call-detail`	Returns one call record by TapClicks call ID

List Franchises

GET https://api.breesy.app/marketing/franchises

Returns the franchise IDs available to the bearer token. Use this endpoint first when an integration needs to discover which franchise_id values it can pass to the reporting endpoints.

Query Parameters

None.

Example Request

GET https://api.breesy.app/marketing/franchises
Authorization: Bearer <api_token>

Example Response

{
  "token": {
    "name": "Agency Reporting",
    "prefix": "marketing_live_...abc123"
  },
  "franchises": [
    {
      "franchise_id": "0d8b6af2-4f5d-4c44-8df5-9b77f5743b10",
      "franchise_name": "Team Example"
    }
  ]
}

List Locations

GET https://api.breesy.app/marketing/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 https://api.breesy.app/marketing/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"
    }
  ]
}

List Filters

GET https://api.breesy.app/marketing/filters

Returns franchise-scoped lookup values. campaign and market values can be used on reporting requests; ad_types are included for display or filter UI parity.

Query Parameters

Name	Required	Description
`franchise_id`	Yes	Must be one of the franchise IDs granted to the bearer token
`location_id`	No	Optional location filter; must belong to the requested granted franchise

Example Request

GET https://api.breesy.app/marketing/filters?franchise_id=0d8b6af2-4f5d-4c44-8df5-9b77f5743b10
Authorization: Bearer <api_token>

Example Response

{
  "markets": [
    "Westfield",
    "North Metro",
    "River District",
    "South County"
  ],
  "ad_types": [
    "Paid Search",
    "Paid Social"
  ],
  "campaigns": [
    "Brand Search - March 2026",
    "Water Damage - Core",
    "Storm Response - Expansion"
  ]
}

Get Summary

GET https://api.breesy.app/marketing/summary

Returns the final aggregated totals for the reporting period.

Projected pipeline fields are additive to the original response. projected_pipeline is total pipeline plus projected value for valid scored leads without an estimate. projected_pipeline_roas is total pipeline ROAS plus projected ROAS. Projected lead value uses similar jobs with the same loss type first; 4+ similar jobs use the interquartile mean, 1-3 similar jobs use the median, and lead score is only used as a fallback when loss-type history is not usable.

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/filters`
`market`	No	Optional market filter; should come from `/marketing/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 https://api.breesy.app/marketing/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_collected": 1200.00,
    "lost_collected": 500.00,
    "total_collected": 77500.00,
    "total_invoiced": 81250.00,
    "open_pipeline_estimate": 57400.00,
    "lost_job_estimate": 34100.00,
    "total_pipeline": 167300.00,
    "projected_pipeline": 188500.00,
    "projected_pipeline_roas": 7.67,
    "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,
      "projected_pipeline": 48600.00,
      "projected_pipeline_roas": 8.97,
      "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 }
  ]
}

List Call Details

GET https://api.breesy.app/marketing/call-details

Returns TapClicks call IDs grouped by market or location. This is a separate endpoint so the original summary response remains backward compatible.

For call records, estimate_value is only populated when a real estimate exists. If a valid scored lead does not have a real estimate yet, estimate_value is null and projected_value contains the projected lead value.

When a call is attributed to one or more Dash jobs, each call record also includes actual_estimate_value, total_collected, total_invoiced, and attributed_job_count. total_invoiced is the attributed job invoice subtotal. Call records can also include campaign, UTM, and marketing extension fields when those values are available from the source data.

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/filters`
`market`	No	Optional market filter; should come from `/marketing/filters`
`group_by`	No	`market` or `location`; defaults to `market`

Example Request

GET https://api.breesy.app/marketing/call-details?franchise_id=0d8b6af2-4f5d-4c44-8df5-9b77f5743b10&start_date=2026-03-01&end_date=2026-03-31&group_by=market
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": null
  },
  "group_by": "market",
  "groups": [
    {
      "market_name": "Westfield",
      "label": "Westfield",
      "call_count": 2,
      "projected_pipeline": 3200.00,
      "calls": [
        {
          "tapclicks_call_id": "abc123",
          "paid_call_id": "2bfbbf6f-3c0a-4636-b826-7a409fef6e88",
          "call_start_time": "2026-03-12T15:22:00+00:00",
          "caller_number": "704-555-1234",
          "estimate_value": 4256.39,
          "projected_value": null,
          "actual_estimate_value": 4256.39,
          "total_collected": 2100.00,
          "total_invoiced": 4256.39,
          "attributed_job_count": 1,
          "lead_status": "estimate_created",
          "job_outcome": "open"
        },
        {
          "tapclicks_call_id": "def456",
          "paid_call_id": "7e543c02-b1df-42df-a4ee-697188a9656b",
          "call_start_time": "2026-03-18T19:14:00+00:00",
          "caller_number": "704-555-5678",
          "estimate_value": null,
          "projected_value": 3200.00,
          "actual_estimate_value": 0,
          "total_collected": 0,
          "total_invoiced": 0,
          "attributed_job_count": 0,
          "lead_status": "valid_no_estimate",
          "job_outcome": "none"
        }
      ]
    }
  ]
}

Lead Status Values

Value	Meaning
`estimate_created`	Matched to a job with a real estimate
`valid_no_estimate`	Valid marketing lead with a lead score and projected value, but no estimate yet
`open_job_no_estimate`	Matched to an open job that does not have an estimate yet
`lost_no_estimate`	Matched to a lost job that does not have an estimate
`collected`	Matched to a completed/paid job
`admin_error`	Matched job was closed as an administrative or internal error
`no_record_found`	No matching job or Breesy service record was found

Get Call Detail

GET https://api.breesy.app/marketing/call-detail

Returns details for one TapClicks call ID.

The same value rule applies here: estimate_value is for a real estimate, and projected_value is returned when the call only has a projected lead value. Matched calls also include the same actual_estimate_value, total_collected, total_invoiced, and attributed_job_count fields returned by the grouped call detail endpoint. Campaign, UTM, and marketing extension fields may also be present when available.

Query Parameters

Name	Required	Description
`franchise_id`	Yes	Must be one of the franchise IDs granted to the bearer token
`tapclicks_call_id`	Yes	Call ID from the TapClicks call detail data
`location_id`	No	Optional location filter; must belong to the requested granted franchise
`start_date`	No	Optional inclusive start date to narrow lookup
`end_date`	No	Optional inclusive end date to narrow lookup

Example Request

GET https://api.breesy.app/marketing/call-detail?franchise_id=0d8b6af2-4f5d-4c44-8df5-9b77f5743b10&tapclicks_call_id=abc123
Authorization: Bearer <api_token>

Example Response

{
  "tapclicks_call_id": "abc123",
  "paid_call_id": "2bfbbf6f-3c0a-4636-b826-7a409fef6e88",
  "call_start_time": "2026-03-12T15:22:00+00:00",
  "caller_number": "704-555-1234",
  "estimate_value": 4256.39,
  "projected_value": null,
  "actual_estimate_value": 4256.39,
  "total_collected": 2100.00,
  "total_invoiced": 4256.39,
  "attributed_job_count": 1,
  "lead_status": "estimate_created",
  "job_outcome": "open"
}