Route HubSpot leads by territory and company size using a Claude Code skill

mkdir -p .claude/skills/territory-routing/{templates,references}

.claude/skills/territory-routing/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── slack-routing-summary.md      # Slack notification template
└── references/
    └── hubspot-contacts-api.md       # HubSpot Contacts API patterns

---
name: territory-routing
description: Route or re-route HubSpot contacts by territory and company size
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Apply territory and company size routing rules to HubSpot contacts in bulk. Support three modes: route only unassigned contacts (default), re-route all contacts after territory changes, and dry-run to preview routing decisions without writing.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (optional, for posting routing summaries)
- `SLACK_CHANNEL_ID` — Slack channel ID starting with C (optional)
 
Default territory configuration (the user may override any of these):
 
- **Enterprise threshold**: 1,000 employees — contacts at companies this size or larger route to the enterprise AE
- **Territory map**: state abbreviations mapped to reps (e.g., NY/MA → Alice, CA/WA → Bob, FL/TX → Carol)
- **Default rep**: catch-all for contacts whose state doesn't match any territory
 
## Workflow
 
1. Validate that `HUBSPOT_ACCESS_TOKEN` is set. If missing, print the error and exit.
2. Determine the routing mode from the user's request:
   - **Default**: fetch only contacts where `hubspot_owner_id` has no value (unassigned)
   - **Re-route all**: fetch all contacts regardless of current owner
   - **Dry-run**: run either mode above but skip the PATCH step; print what would change
3. Fetch contacts from HubSpot using the CRM Search API. See `references/hubspot-contacts-api.md` for the endpoint and response format. Request these properties: `firstname`, `lastname`, `email`, `company`, `state`, `country`, `numberofemployees`, `hubspot_owner_id`. Paginate using the `after` cursor if there are more than 100 results.
4. For each contact, apply the three-tier routing hierarchy:
   - **Enterprise override**: if `numberofemployees` >= enterprise threshold, assign to enterprise rep
   - **Territory match**: if the contact's `state` (uppercased) matches a territory, assign to that territory's rep
   - **Fallback**: assign to the default rep
5. Unless in dry-run mode, update each contact's `hubspot_owner_id` via PATCH. See `references/hubspot-contacts-api.md` for the request format.
6. Print a summary of routing decisions: how many enterprise, territory-matched, and fallback assignments.
7. If `SLACK_BOT_TOKEN` and `SLACK_CHANNEL_ID` are set, post a summary to Slack using the template in `templates/slack-routing-summary.md`.
 
## Important notes
 
- The `state` property in HubSpot may contain full state names ("California"), abbreviations ("CA"), or lowercase ("ca"). Normalize to uppercase abbreviations before matching. If full names are common, add a mapping (e.g., "CALIFORNIA" → "CA").
- `numberofemployees` may be stored as a string, sometimes with commas ("1,500") or ranges ("1001-5000"). Parse defensively — strip commas, take the first number from ranges, default to 0 on failure.
- HubSpot's CRM Search API returns max 100 results per page. Use the `after` cursor from `paging.next.after` to get all contacts.
- When filtering for unassigned contacts, use the `NOT_HAS_PROPERTY` operator on `hubspot_owner_id`.
- HubSpot rate limit is 100 requests per 10 seconds for private apps. Add a small delay between PATCH calls if routing more than 80 contacts.
- `SLACK_CHANNEL_ID` must be the channel ID (starts with `C`), not the channel name.
- Use `urllib.request` for HTTP calls (no external dependencies required).

# Slack Routing Summary Template
 
Use this Block Kit structure for the routing summary message posted after a bulk routing run.
 
## Block Kit JSON
 
```json
{
  "channel": "<SLACK_CHANNEL_ID>",
  "text": "Territory routing complete: <total> contacts routed",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Territory Routing Summary"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*<total> contacts routed*\n\n• Enterprise (1,000+ employees): <count> → <rep name>\n• Territory matches: <count>\n  - NY/MA: <count> → Alice\n  - CA/WA: <count> → Bob\n  - FL/TX: <count> → Carol\n• Fallback: <count> → <default rep name>"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Mode: <default | re-route all | dry-run> • Run at <timestamp>"
        }
      ]
    }
  ]
}
```
 
## Notes
 
- The top-level `text` field is required by the Slack API as a fallback for notifications.
- Group counts by routing reason (enterprise, each territory, fallback).
- Include the mode (default, re-route all, dry-run) and timestamp in the context block.
- For dry-run mode, prefix the header with "[DRY RUN]" so it's obvious no changes were made.

# HubSpot Contacts API Reference
 
## Search for contacts
 
Use the CRM Search API to find contacts matching specific criteria.
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
**Body (unassigned contacts only):**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hubspot_owner_id",
          "operator": "NOT_HAS_PROPERTY"
        }
      ]
    }
  ],
  "properties": ["firstname", "lastname", "email", "company", "state", "country", "numberofemployees", "hubspot_owner_id"],
  "limit": 100
}
```
 
**Body (all contacts — no filter):**
 
```json
{
  "properties": ["firstname", "lastname", "email", "company", "state", "country", "numberofemployees", "hubspot_owner_id"],
  "limit": 100
}
```
 
- `limit` max is 100. If there are more results, use the `after` cursor from `paging.next.after` to paginate.
- Pass the `after` value as a top-level field in the request body: `"after": "100"`.
 
**Response shape:**
 
```json
{
  "total": 47,
  "results": [
    {
      "id": "12345",
      "properties": {
        "firstname": "Rachel",
        "lastname": "Kim",
        "email": "rachel@contoso.com",
        "company": "Contoso Ltd",
        "state": "CA",
        "country": "US",
        "numberofemployees": "2400",
        "hubspot_owner_id": null
      }
    }
  ],
  "paging": {
    "next": {
      "after": "100"
    }
  }
}
```
 
## Update a contact's owner
 
**Request:**
 
```
PATCH https://api.hubapi.com/crm/v3/objects/contacts/<contact_id>
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
**Body:**
 
```json
{
  "properties": {
    "hubspot_owner_id": "<owner_id>"
  }
}
```
 
- `owner_id` is a numeric string (e.g., "111111"). Find owner IDs via HubSpot Settings > Users & Teams, or `GET /crm/v3/owners`.
- Returns the updated contact object on success (HTTP 200).
 
## Rate limits
 
- Private apps: 100 requests per 10 seconds.
- If routing more than ~80 contacts, add a 100ms delay between PATCH calls to stay within limits.
- Search API counts as 1 request per page regardless of how many results are returned.

/territory-routing

Routing unassigned contacts by territory...
  Fetched 47 unassigned contacts (1 page)
  Enterprise (1000+ emp): 8 → Dave
  Territory match: 31
    NY/MA: 12 → Alice
    CA/WA: 11 → Bob
    FL/TX: 8 → Carol
  Fallback: 8 → Eve
  Updated 47 contacts in HubSpot
  Posted summary to #sales-ops
Done. Routed 47 contacts.

# Route unassigned contacts every weekday at 9am
0 9 * * 1-5 cd /path/to/your/project && claude -p "Run /territory-routing" --allowedTools 'Bash(*)' 'Read(*)'

name: Territory Routing
on:
  schedule:
    - cron: '0 14 * * 1-5'  # Weekdays at 9am ET
  workflow_dispatch: {}       # Manual trigger for testing
jobs:
  route:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /territory-routing"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}