What it does
Sales reps and marketing ops look at the same new contacts for different reasons. Marketing wants to know which channel sent them; sales wants to know who is calling them, and today. Both usually find out from a HubSpot list view that nobody remembered to sort.
Every weekday at 8:00 the agent counts the contacts created since the previous run, splits the leads by original source, and names the ones nobody owns yet. Unowned leads are the ones that go cold, so they get their own table.
How it works
1Pull contacts created since the last run
Call
POST /crm/v3/objects/contacts/searchwithcreatedate GTE24 hours ago (on Mondays, since Friday 8:00), sorted bycreatedatedescending, with propertiesfirstname,lastname,email,company,lifecyclestage,hs_lead_status,hs_analytics_source,hs_analytics_source_data_1andhubspot_owner_id.- 2
2Separate leads from the rest
A lead is a contact whose
lifecyclestageislead,marketingqualifiedleadorsalesqualifiedlead. Leave out subscribers, test sign-ups and addresses on your own company's domain. - 3
3Group by original source
Group leads on
hs_analytics_source(ORGANIC_SEARCH,PAID_SEARCH,PAID_SOCIAL,REFERRALS,DIRECT_TRAFFIC,EMAIL_MARKETING,OFFLINEand so on), and usehs_analytics_source_data_1to name the search engine, campaign or import behind the biggest groups. 4Compare with a week ago
Run the same search for the same 24 hours one week earlier, so Tuesday is compared with last Tuesday and not with a Monday that covered a weekend.
- 5
5List the unowned leads
Leads with an empty
hubspot_owner_id, oldest first, with company, source and hours waited. Post the count as the tile, the source split and this list underneath. Post it to the board
With
BRIEFKIN_TOKENset, the agent sends the result as one card that updates in place every run. Without it, you get the report in the chat.
Install and run it
Pick your agent, where the data comes from and how to schedule it; the commands below follow.
Install the skill
One command. It puts the SKILL.md in ~/.claude/skills and in ~/.agents/skills, which Codex, Cursor, Gemini CLI, Copilot CLI and OpenCode read too.
shell
curl -fsSL https://briefkin.dev/skills/hubspot-new-leads-digest/install | shRun it
Ask Claude Code:
prompt
Run the hubspot-new-leads-digest skillOr paste the prompt instead of installing:
prompt
From HubSpot, find contacts created in the last 24 hours (on Mondays, since Friday morning). Count the ones whose lifecycle stage is lead, marketing qualified lead or sales qualified lead, leaving out test and internal addresses. Break them down by original source (`hs_analytics_source`), with the detail from `hs_analytics_source_data_1` for the largest sources, and compare the total with the same 24 hours a week earlier. Then list every lead with no `hubspot_owner_id`, oldest first, with company, source and hours waiting. End with the lead that should be assigned first and why.Put it on a schedule
Weekdays at 8:00, from cron on any machine where Claude Code is signed in:
crontab
0 8 * * 1-5 claude -p "Run the hubspot-new-leads-digest skill"Add it with
crontab -e. A laptop asleep at that time runs it when it wakes if you use launchd or Task Scheduler instead; GitHub Actions works for the API route.Send it to your board
Connect Briefkin once with
curl -fsSL https://briefkin.dev/install | shand every run lands on your board as a stat tile. How setup works
View the SKILL.mdRaw file
SKILL.md---
name: hubspot-new-leads-digest
description: "Each weekday morning: how many contacts and leads came into HubSpot since yesterday, from which sources, and which have no owner yet. Use when the user asks for this, or when it runs on a schedule."
---
# HubSpot new leads digest
Each weekday morning: how many contacts and leads came into HubSpot since yesterday, from which sources, and which have no owner yet.
Sales reps and marketing ops look at the same new contacts for different reasons. Marketing wants to know which channel sent them; sales wants to know who is calling them, and today. Both usually find out from a HubSpot list view that nobody remembered to sort.
Every weekday at 8:00 the agent counts the contacts created since the previous run, splits the leads by original source, and names the ones nobody owns yet. Unowned leads are the ones that go cold, so they get their own table.
## Two ways to get the data
Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.
## Route A: API or MCP server
### What you need
- A private app token with the `crm.objects.contacts.read` and `crm.objects.owners.read` scopes, set as `HUBSPOT_ACCESS_TOKEN`, or a HubSpot connector that can read contacts.
If something is missing, say what and stop; do not invent numbers.
### Steps
1. **Pull contacts created since the last run** (HubSpot): Call `POST /crm/v3/objects/contacts/search` with `createdate GTE` 24 hours ago (on Mondays, since Friday 8:00), sorted by `createdate` descending, with properties `firstname`, `lastname`, `email`, `company`, `lifecyclestage`, `hs_lead_status`, `hs_analytics_source`, `hs_analytics_source_data_1` and `hubspot_owner_id`.
2. **Separate leads from the rest**: A lead is a contact whose `lifecyclestage` is `lead`, `marketingqualifiedlead` or `salesqualifiedlead`. Leave out subscribers, test sign-ups and addresses on your own company's domain.
3. **Group by original source**: Group leads on `hs_analytics_source` (`ORGANIC_SEARCH`, `PAID_SEARCH`, `PAID_SOCIAL`, `REFERRALS`, `DIRECT_TRAFFIC`, `EMAIL_MARKETING`, `OFFLINE` and so on), and use `hs_analytics_source_data_1` to name the search engine, campaign or import behind the biggest groups.
4. **Compare with a week ago** (HubSpot): Run the same search for the same 24 hours one week earlier, so Tuesday is compared with last Tuesday and not with a Monday that covered a weekend.
5. **List the unowned leads**: Leads with an empty `hubspot_owner_id`, oldest first, with company, source and hours waited. Post the count as the tile, the source split and this list underneath.
## Route B: the browser
### What you need
- Signed in to HubSpot with permission to view all contacts, not only owned ones.
If something is missing, say what and stop; do not invent numbers.
### Steps
Start at https://app.hubspot.com/contacts/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.
1. **Open the contacts list**: Pick the account if needed; HubSpot lands on **CRM > Contacts**. Filter **Create date** is after yesterday 8:00 (on Mondays, after Friday 8:00), sort by Create date newest first, and with **Edit columns** show Email, Company name, **Lifecycle stage**, Lead status, **Original source**, **Original source drill-down 1** and **Contact owner**.
2. **Keep only the leads**: Add **Lifecycle stage** is any of **Lead**, **Marketing qualified lead** and **Sales qualified lead**. The record count above the table is the lead total; ignore rows with your own company domain or obvious test addresses.
3. **Group by original source**: Sort by Original source and count the rows per value (Organic search, Paid search, Paid social, Referrals, Direct traffic, Offline sources). The drill-down column names the search engine, campaign or import behind the largest groups.
4. **Compare with a week ago**: Change the Create date filter to a custom range covering the same 24 hours one week earlier and note the lead count, so Tuesday is compared with last Tuesday.
5. **List the unowned leads**: Add **Contact owner** is unknown, sort by Create date oldest first, and read company, source and how many hours each has waited.
Note: Contacts created by imports, integrations or forms without the tracking code show Offline sources, as in the API route. The table shows up to 100 rows per page; on a busy day export the filtered view instead of paging.
## The report
- **New leads** since the last run, against the same weekday last week, and all new contacts for context.
- **By source**: leads per original source, with the campaign, form or import behind the largest.
- **No owner yet**: unowned leads, oldest first, with how long each has waited.
- One line on the lead to assign first.
## Post it to Briefkin
When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.
```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
-H "authorization: Bearer $BRIEFKIN_TOKEN" \
-H "content-type: application/json" \
-d @- <<'JSON'
{
"v": 1,
"event_id": "hubspot-new-leads-digest/<date of this run, e.g. 2026-10-16>",
"item_key": "hubspot-new-leads-digest",
"project": "Acme",
"source": "HubSpot new leads digest skill",
"kind": "metric",
"title": "38 new leads since yesterday, 5 without an owner",
"metric": {
"label": "New leads",
"value": 38,
"better": "higher",
"period_start": "<start of the period, ISO 8601>",
"period_end": "<end of the period, ISO 8601>"
},
"glance": [
{
"type": "Grid",
"props": {
"columns": 2
},
"children": [
{
"type": "Stat",
"props": {
"label": "All new contacts",
"value": 61
}
},
{
"type": "Stat",
"props": {
"label": "Leads with no owner",
"value": 5,
"tone": "warn"
}
}
]
},
{
"type": "Badges",
"props": {
"items": [
{
"label": "Organic search 14",
"tone": "info"
},
{
"label": "Paid search 9",
"tone": "info"
},
{
"label": "Referrals 6",
"tone": "info"
}
]
}
}
],
"widget": [
{
"type": "Bars",
"props": {
"items": [
{
"label": "Organic search",
"value": 14
},
{
"label": "Paid search",
"value": 9
},
{
"label": "Referrals",
"value": 6
},
{
"label": "Paid social",
"value": 4
},
{
"label": "Direct traffic",
"value": 3
},
{
"label": "Offline sources",
"value": 2
}
],
"unit": "leads"
}
},
{
"type": "Table",
"props": {
"columns": [
"Lead with no owner",
"Company",
"Source",
"Waiting"
],
"align": [
"left",
"left",
"left",
"right"
],
"rows": [
[
"Jordan Rivera",
"Contoso",
"Paid search, pricing page form",
"22 h"
],
[
"Mei Tanaka",
"Fabrikam",
"Organic search",
"19 h"
],
[
"Luis Ortega",
"Tailspin Toys",
"Referrals",
"15 h"
],
[
"Hannah Weber",
"Litware",
"Organic search",
"9 h"
],
[
"Kofi Mensah",
"Proseware",
"Paid social",
"3 h"
]
]
}
},
{
"type": "Callout",
"props": {
"text": "Assign Jordan Rivera first: a demo request from the pricing page, waiting 22 hours.",
"tone": "warn"
}
}
],
"size": "md"
}
JSON
```
Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.
Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters).
## Run it on a schedule
Suggested: Weekdays at 8:00 (`0 8 * * 1-5`). From cron, with the agent signed in on that machine:
```bash
0 8 * * 1-5 claude -p "Run the hubspot-new-leads-digest skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```
Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/hubspot-new-leads-digest#schedule
Source: https://briefkin.dev/skills/hubspot-new-leads-digest
What your agent needs
A private app token with the
crm.objects.contacts.readandcrm.objects.owners.readscopes, set asHUBSPOT_ACCESS_TOKEN, or a HubSpot connector that can read contacts.
Connecting HubSpot
- HubSpot MCP server, HubSpot's remote server at
https://mcp.hubspot.com. HubSpot also offers a Claude connector built on the same server; you sign in with your HubSpot user and it sees what that user can see (docs). - API with a private app token. Create a private app in your HubSpot account settings, give it only the scopes the report reads (
crm.objects.deals.read,crm.objects.contacts.read,crm.objects.companies.read,crm.objects.owners.read), and store its token inHUBSPOT_ACCESS_TOKEN.
The MCP server and connector can create and update records, so for unattended reports a private app with only .read scopes is the safer credential.
Questions
Why does a contact show as Offline sources or Direct traffic when it came from an ad?
Original source comes from the contact's first tracked visit. Contacts created by an import, an integration or a form without the HubSpot tracking code land in OFFLINE, and visits that lost their UTM parameters land in DIRECT_TRAFFIC. hs_analytics_source_data_1 usually names the integration or import that created them.
Does it use the HubSpot Leads object?
Not by default: it reads contacts and their lifecycle stage, which every HubSpot account has. If your team works leads in the Sales Hub Leads object, point the first step at the leads object API (/crm/v3/objects/leads) and keep the owner check the same.
Do I need Briefkin to use the HubSpot new leads digest skill?
No. The skill runs with your own agent and gives you the report in the chat. With a Briefkin token set, each run also posts it to your board as a stat tile, so you can glance at it instead of asking again.
Which agents can run it?
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, Windsurf and Amp all read SKILL.md files. The install command puts it in ~/.claude/skills and ~/.agents/skills, where they look. ChatGPT, the Claude app and Grok take the prompt instead. Pick your agent under "Install and run it" and the commands change to match.
Can it work without an API or MCP server, from my browser?
Yes. Switch the data source to "Your browser" and the steps change to the HubSpot pages themselves: the agent opens app.hubspot.com/contacts in a browser you are signed in to and reads the numbers off the page. Claude Code, Codex, Cursor, Claude app and ChatGPT can drive a browser out of the box; Gemini CLI, Copilot CLI and OpenCode need a Playwright or Chrome DevTools MCP server first. It is slower than the API and needs you signed in, so it suits a report you run by hand or from a scheduler on your own computer.