Skip to main content

Examples

Examples 1 to 9 use the events endpoint and the base request structure below; the last three cover access, benchmarks and insights.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>'

Outputs below use illustrative data.

Example 1: Group-wide spend, leads, and ROAS​

With no dimensions, a single aggregated row is returned for the whole group.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=spend,leads,roasPotential'
Output example
[
  { "spend": 18450.12, "leads": 412, "roasPotential": 4.31 }
]

Example 2: Spend and cost per lead by account​

Add account to break the metrics out per account.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=account,spend,leads,avgCostPerLead'
Output example
[
  { "account": "Example Home Services", "spend": 12310.45, "leads": 287, "avgCostPerLead": 42.89 },
  { "account": "Example Home Services 2", "spend": 6139.67, "leads": 125, "avgCostPerLead": 49.12 }
]

Example 3: ROAS by campaign​

When campaign is a dimension, spend-based metrics use spend attributed to the specific campaign.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=account,campaign,spend,revenuePotential,roasPotential'
Output example
[
  { "account": "Example Home Services", "campaign": "Search - Branded", "spend": 2104.33, "revenuePotential": 11892.50, "roasPotential": 5.65 },
  { "account": "Example Home Services", "campaign": "Search - HVAC", "spend": 4880.10, "revenuePotential": 15210.00, "roasPotential": 3.12 }
]

Example 4: Customer counts by funnel step​

Group by adjustedType to see how customers are distributed across funnel stages.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=adjustedType,customers'
Output example
[
  { "adjustedType": "lead-originated", "customers": 540 },
  { "adjustedType": "booked", "customers": 65 },
  { "adjustedType": "estimated", "customers": 210 },
  { "adjustedType": "sold", "customers": 18 },
  { "adjustedType": "closed", "customers": 120 },
  { "adjustedType": "canceled", "customers": 22 }
]

Example 5: Closed revenue by attribution category, filtered​

Closed revenue per category, restricted to organic or advertising with the or operator. See filtering.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=account,attributionCategory,closedRevenue' \
  --data-urlencode 'attributionCategory=["or", "Organic", "Advertising"]'
Output example
[
  { "account": "Example Home Services", "attributionCategory": "Organic", "closedRevenue": 138172.68 },
  { "account": "Example Home Services", "attributionCategory": "Advertising", "closedRevenue": 4844.05 }
]

Example 6: Revenue potential by campaign using regex​

Filters campaigns containing "gmb" or "gbp" with a case-insensitive regex.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=account,campaign,revenuePotential' \
  --data-urlencode 'campaign=["regex", "gmb|gbp", "ui"]'
Output example
[
  { "account": "Example Home Services", "campaign": "GBP Listing", "revenuePotential": 77637.32 },
  { "account": "Example Home Services", "campaign": "GMB Listing - North", "revenuePotential": 1289.00 }
]

Example 7: Conversion quality​

Conversion grading metrics. They require the lead-grading feature; accounts without it return 0.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=account,conversions,gradedConversions,percentConversionsGraded,conversionQuality'
Output example
[
  { "account": "Example Home Services", "conversions": 341, "gradedConversions": 322, "percentConversionsGraded": 0.94, "conversionQuality": 0.81 }
]

Example 8: Funnel step and cancellation rates​

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=account,stepBookRate,stepEstimateRate,stepSoldRate,stepCloseRate,cancelRate'
Output example
[
  { "account": "Example Home Services", "stepBookRate": 0.44, "stepEstimateRate": 0.63, "stepSoldRate": 0.58, "stepCloseRate": 0.91, "cancelRate": 0.25 }
]

Example 9: Weekly spend and leads by account​

interval computes the metrics separately for each interval and tags every row with its start/end. It combines with dimensions, so this returns one row per week × account. Edge weeks may be partial.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/events' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'start=2026-05-01' \
  --data-urlencode 'end=2026-05-31' \
  --data-urlencode 'fields=account,spend,leads' \
  --data-urlencode 'interval=week'
Output example
[
  { "start": "2026-05-01", "end": "2026-05-03", "account": "Example Home Services", "spend": 1450.00, "leads": 38 },
  { "start": "2026-05-04", "end": "2026-05-10", "account": "Example Home Services", "spend": 3680.50, "leads": 92 },
  { "start": "2026-05-11", "end": "2026-05-17", "account": "Example Home Services", "spend": 3102.88, "leads": 71 }
]

Example 10: Find which organization to request​

Start here if you don't know your organization id. This endpoint takes no organization in its path.

curl --get --compressed \
  --url 'https://searchlight.digital/api' \
  --header 'Authorization: <your-api-key>'
Output example
{
  "user": "you@example.com",
  "organizations": [
    { "organization": "example-group", "accounts": ["example-home-services", "example-plumbing"] },
    { "organization": "example-group-northeast", "accounts": ["example-plumbing"] }
  ],
  "endpoints": [ { "endpoint": "events", "path": "/api/{organization}/events" } ],
  "dictionary": { "bookRate": { "displayName": "Book Rate", "type": "metric" } }
}

Example 11: Compare your booking rate to the industry​

Benchmarks return the industry figure and the distribution for one calendar month; request your own numbers from events and compare against them.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/benchmarks' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'month=2026-05' \
  --data-urlencode 'fields=bookRate,matchRate,roasClosed' \
  --data-urlencode 'normalizedBusinessUnit=HVAC'
Output example
[
  { "series": "benchmark", "cohortAccounts": 619, "bookRate": 0.4103, "matchRate": 0.3794, "roasClosed": 13.45 },
  { "series": "p10", "cohortAccounts": 619, "bookRate": 0.2083, "matchRate": 0.2031, "roasClosed": 4.21 },
  { "series": "p25", "cohortAccounts": 619, "bookRate": 0.2969, "matchRate": 0.2804, "roasClosed": 8.30 },
  { "series": "p50", "cohortAccounts": 619, "bookRate": 0.3909, "matchRate": 0.3631, "roasClosed": 14.02 },
  { "series": "p75", "cohortAccounts": 619, "bookRate": 0.4689, "matchRate": 0.4415, "roasClosed": 24.39 },
  { "series": "p90", "cohortAccounts": 619, "bookRate": 0.5409, "matchRate": 0.5138, "roasClosed": 37.94 }
]

Example 12: Latest insight action items for one account​

Omitting start/end returns the most recent insight per account; fields trims the document to the sections you want.

curl --get --compressed \
  --url 'https://searchlight.digital/api/<organization>/insights' \
  --header 'Authorization: <your-api-key>' \
  --data-urlencode 'account=example-home-services' \
  --data-urlencode 'fields=period,action_items'
Output example
[
  {
    "account": "example-home-services",
    "date": "2026-07-21",
    "insight": {
      "period": "June 2026",
      "action_items": [
        {
          "title": "6 calls from 'water heater rental' searches, a service you don't offer",
          "action": "Worth discussing with your marketing agency: adding these as negative keywords",
          "priority": "low",
          "impact": { "value": 6, "unit": "calls", "display": "6 calls" }
        }
      ]
    }
  }
]