Manage bidirectional HubSpot-Salesforce sync using a Claude Code skill

mkdir -p .claude/skills/crm-sync/{templates,references}

.claude/skills/crm-sync/
├── SKILL.md                            # workflow guidelines + config
├── templates/
│   └── field-mapping.md                # HubSpot ↔ Salesforce field mapping
└── references/
    ├── hubspot-crm-api.md              # HubSpot API patterns
    └── salesforce-rest-api.md          # Salesforce API patterns

---
name: crm-sync
description: Audit and remediate sync mismatches between HubSpot and Salesforce. Compares contacts, companies, and deals across both CRMs, reports discrepancies, and optionally pushes fixes.
disable-model-invocation: true
allowed-tools: Bash, Read, Grep
---
 
## Goal
 
Audit and remediate sync mismatches between HubSpot and Salesforce. The user may ask for a full audit, a targeted comparison of specific records, or a fix for known mismatches. Adapt the workflow based on what they request.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token (required)
- `SALESFORCE_ACCESS_TOKEN` — Salesforce OAuth access token (required)
- `SALESFORCE_INSTANCE_URL` — Salesforce instance URL, e.g. https://yourorg.my.salesforce.com (required)
- `SLACK_BOT_TOKEN` — Slack bot token starting with xoxb- (optional — for posting sync reports)
- `SLACK_CHANNEL_ID` — Slack channel ID starting with C (optional — required if SLACK_BOT_TOKEN is set)
 
Default scope: contacts. The user may request companies or deals instead. Default lookback: 7 days for audit, all records for targeted comparisons.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Determine user intent:
   - **Audit** — scan for mismatches across a set of records
   - **Sync** — push recent changes from one system to the other
   - **Fix** — remediate specific mismatched records
3. Fetch records from HubSpot using the CRM Search API. See `references/hubspot-crm-api.md` for endpoint details and pagination.
4. Fetch corresponding records from Salesforce using SOQL queries. See `references/salesforce-rest-api.md` for query syntax and response shapes.
5. Match records across systems using email address (contacts), domain (companies), or deal name + amount (deals).
6. Compare field values using the mapping in `templates/field-mapping.md`. For each matched pair, check every mapped field for differences.
7. Based on user intent:
   - **Audit**: Print a summary table of mismatched records and fields. Group by object type.
   - **Sync**: Push the newer value (based on timestamps) to the outdated system. Confirm before writing.
   - **Fix**: Update the specified records in the target system. Confirm before writing.
8. If `SLACK_BOT_TOKEN` and `SLACK_CHANNEL_ID` are set, post a summary report to Slack with mismatch counts and actions taken.
9. Print a final summary with record counts, mismatch counts, and any errors encountered.
 
## Important notes
 
- HubSpot timestamps (`hs_lastmodifieddate`) are in **milliseconds** since epoch. Salesforce timestamps (`SystemModstamp`) are in ISO 8601 format. Convert both to UTC datetime objects before comparing.
- HubSpot rate limits: 100 requests per 10 seconds for private apps. Batch requests where possible. Add 100ms delays between pages.
- Salesforce rate limits vary by edition — typically 15,000-100,000 requests per 24 hours. Use SOQL bulk queries to minimize API calls.
- HubSpot contacts match to Salesforce Contacts or Leads (check both). HubSpot companies match to Salesforce Accounts. HubSpot deals match to Salesforce Opportunities.
- Email matching is case-insensitive. Normalize both sides to lowercase before comparing.
- When fixing records, NEVER overwrite a field in one system without logging what the previous value was. Print a before/after table for every change.
- Use the `requests` library for HTTP calls. Install with pip if needed.
- `SLACK_CHANNEL_ID` must be the channel ID (starts with `C`), not the channel name. The Slack bot must be invited to the target channel.

# HubSpot CRM API Reference
 
## Authentication
 
All requests use Bearer token authentication:
```
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
## Search contacts
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
```
 
**Body:**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hs_lastmodifieddate",
          "operator": "GTE",
          "value": "<cutoff_timestamp_ms>"
        }
      ]
    }
  ],
  "properties": ["email", "firstname", "lastname", "phone", "jobtitle", "company", "lifecyclestage", "hs_lastmodifieddate"],
  "limit": 100
}
```
 
- `value` for date filters is a Unix timestamp in **milliseconds**.
- `limit` max is 100. Paginate using `paging.next.after` if more results exist.
 
**Response shape:**
 
```json
{
  "total": 45,
  "results": [
    {
      "id": "101",
      "properties": {
        "email": "laura.chen@meridian.com",
        "firstname": "Laura",
        "lastname": "Chen",
        "phone": "(555) 987-6543",
        "jobtitle": "VP Operations",
        "company": "Meridian Logistics",
        "lifecyclestage": "customer",
        "hs_lastmodifieddate": "1741248840000"
      }
    }
  ],
  "paging": {
    "next": { "after": "100" }
  }
}
```
 
## Get a single contact
 
**Request:**
 
```
GET https://api.hubapi.com/crm/v3/objects/contacts/{contactId}?properties=email,firstname,lastname,phone,jobtitle,company,lifecyclestage,hs_lastmodifieddate
```
 
## Search companies
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/companies/search
```
 
**Body:**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hs_lastmodifieddate",
          "operator": "GTE",
          "value": "<cutoff_timestamp_ms>"
        }
      ]
    }
  ],
  "properties": ["name", "domain", "industry", "phone", "city", "state", "annualrevenue", "numberofemployees", "hs_lastmodifieddate"],
  "limit": 100
}
```
 
## Search deals
 
**Request:**
 
```
POST https://api.hubapi.com/crm/v3/objects/deals/search
```
 
**Body:**
 
```json
{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "hs_lastmodifieddate",
          "operator": "GTE",
          "value": "<cutoff_timestamp_ms>"
        }
      ]
    }
  ],
  "properties": ["dealname", "amount", "closedate", "dealstage", "pipeline", "hubspot_owner_id", "hs_lastmodifieddate"],
  "limit": 100
}
```
 
## Update a contact
 
**Request:**
 
```
PATCH https://api.hubapi.com/crm/v3/objects/contacts/{contactId}
```
 
**Body:**
 
```json
{
  "properties": {
    "phone": "(555) 987-6543",
    "jobtitle": "VP Operations"
  }
}
```
 
## Update a company
 
**Request:**
 
```
PATCH https://api.hubapi.com/crm/v3/objects/companies/{companyId}
```
 
## Update a deal
 
**Request:**
 
```
PATCH https://api.hubapi.com/crm/v3/objects/deals/{dealId}
```
 
## Notes
 
- Pagination: continue fetching with `after` value from `paging.next.after` until `paging` is absent.
- Rate limit: 100 requests per 10 seconds. Add 100ms delays between paginated requests.
- All timestamps in properties are milliseconds since epoch (string format in responses).
- Empty properties are returned as `null`, not omitted.

# Salesforce REST API Reference
 
## Authentication
 
All requests use Bearer token authentication:
```
Authorization: Bearer <SALESFORCE_ACCESS_TOKEN>
```
 
Base URL: `<SALESFORCE_INSTANCE_URL>/services/data/v59.0`
 
## Query contacts
 
**Request:**
 
```
GET <SALESFORCE_INSTANCE_URL>/services/data/v59.0/query?q=<SOQL>
```
 
**SOQL:**
 
```sql
SELECT Id, Email, FirstName, LastName, Phone, Title, Account.Name,
       LeadSource, SystemModstamp
FROM Contact
WHERE SystemModstamp > 2026-02-27T00:00:00Z
ORDER BY SystemModstamp DESC
```
 
**Response shape:**
 
```json
{
  "totalSize": 32,
  "done": true,
  "records": [
    {
      "Id": "003XXXXXXXXXXXXXXX",
      "Email": "laura.chen@meridian.com",
      "FirstName": "Laura",
      "LastName": "Chen",
      "Phone": "(555) 987-6543",
      "Title": "VP Operations",
      "Account": { "Name": "Meridian Logistics" },
      "LeadSource": "Inbound",
      "SystemModstamp": "2026-03-05T14:30:00.000+0000"
    }
  ]
}
```
 
## Query leads
 
Some HubSpot contacts may map to Salesforce Leads instead of Contacts:
 
```sql
SELECT Id, Email, FirstName, LastName, Phone, Title, Company,
       LeadSource, SystemModstamp
FROM Lead
WHERE SystemModstamp > 2026-02-27T00:00:00Z AND IsConverted = false
ORDER BY SystemModstamp DESC
```
 
## Query accounts
 
```sql
SELECT Id, Name, Website, Industry, Phone, BillingCity, BillingState,
       AnnualRevenue, NumberOfEmployees, SystemModstamp
FROM Account
WHERE SystemModstamp > 2026-02-27T00:00:00Z
ORDER BY SystemModstamp DESC
```
 
- Match HubSpot companies to Salesforce Accounts by domain. Extract domain from `Website` field (strip protocol and path).
 
## Query opportunities
 
```sql
SELECT Id, Name, Amount, CloseDate, StageName, Account.Name,
       Owner.Name, SystemModstamp
FROM Opportunity
WHERE SystemModstamp > 2026-02-27T00:00:00Z
ORDER BY SystemModstamp DESC
```
 
## Update a record
 
**Request:**
 
```
PATCH <SALESFORCE_INSTANCE_URL>/services/data/v59.0/sobjects/{ObjectType}/{RecordId}
Content-Type: application/json
Authorization: Bearer <SALESFORCE_ACCESS_TOKEN>
```
 
**Body:**
 
```json
{
  "Phone": "(555) 987-6543",
  "Title": "VP Operations"
}
```
 
Returns `204 No Content` on success.
 
## Token refresh
 
If the access token expires (401 INVALID_SESSION_ID), use the refresh token:
 
```
POST https://login.salesforce.com/services/oauth2/token
Content-Type: application/x-www-form-urlencoded
 
grant_type=refresh_token&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&refresh_token=<REFRESH_TOKEN>
```
 
**Response:**
 
```json
{
  "access_token": "00DXXXXXXXXXXXXXXX!...",
  "instance_url": "https://yourorg.my.salesforce.com"
}
```
 
## Notes
 
- URL-encode SOQL queries when passing as the `q` parameter.
- Pagination: if `done` is `false`, follow `nextRecordsUrl` to fetch remaining records.
- `SystemModstamp` is the most reliable "last modified" timestamp. It updates on any field change including system-triggered updates.
- Salesforce timestamps are ISO 8601 format with timezone offset.
- SOQL date literals: `LAST_N_DAYS:7`, `LAST_N_HOURS:24`, `TODAY`, `THIS_WEEK`.
- Rate limits vary by edition. Enterprise = 100,000 requests/24 hours. Professional = 15,000/24 hours.
- A `204 No Content` response on PATCH means success. No body is returned.

# HubSpot ↔ Salesforce Field Mapping
 
## Contacts
 
| HubSpot Property | Salesforce Field (Contact) | Salesforce Field (Lead) | Match Key |
|---|---|---|---|
| email | Email | Email | Yes — primary match key (case-insensitive) |
| firstname | FirstName | FirstName | |
| lastname | LastName | LastName | |
| phone | Phone | Phone | |
| jobtitle | Title | Title | |
| company | Account.Name | Company | |
| lifecyclestage | LeadSource (mapped) | LeadSource (mapped) | |
 
## Companies / Accounts
 
| HubSpot Property | Salesforce Field (Account) | Match Key |
|---|---|---|
| domain | Website (extract domain) | Yes — primary match key |
| name | Name | |
| industry | Industry | |
| phone | Phone | |
| city | BillingCity | |
| state | BillingState | |
| annualrevenue | AnnualRevenue | |
| numberofemployees | NumberOfEmployees | |
 
## Deals / Opportunities
 
| HubSpot Property | Salesforce Field (Opportunity) | Match Key |
|---|---|---|
| dealname | Name | Yes — match on name + amount |
| amount | Amount | Yes — secondary match key |
| closedate | CloseDate | |
| dealstage | StageName (mapped) | |
| pipeline | (no direct equivalent) | |
 
## Comparison rules
 
1. Match records using the designated match key (email for contacts, domain for companies, name+amount for deals)
2. For each matched pair, compare every mapped field
3. Normalize before comparing: lowercase emails, strip phone formatting, trim whitespace
4. Treat null/empty as equivalent — don't flag a mismatch if one side is null and the other is an empty string
5. For timestamp comparison, use `hs_lastmodifieddate` (HubSpot, milliseconds) vs `SystemModstamp` (Salesforce, ISO 8601). The more recent timestamp indicates the authoritative value.
 
## Stage mapping (deals ↔ opportunities)
 
HubSpot and Salesforce use different stage names. Common mappings:
 
| HubSpot Stage | Salesforce Stage |
|---|---|
| appointmentscheduled | Qualification |
| qualifiedtobuy | Needs Analysis |
| presentationscheduled | Proposal/Price Quote |
| decisionmakerboughtin | Perception Analysis |
| contractsent | Negotiation/Review |
| closedwon | Closed Won |
| closedlost | Closed Lost |
 
These are defaults. Update this table to match your pipeline configuration.

/crm-sync

Validating environment variables... all set.
Fetching HubSpot contacts modified in the last 7 days...
  Found 47 contacts
Fetching Salesforce contacts and leads...
  Found 52 contacts, 11 leads
Matching records by email...
  Matched: 41 pairs
  HubSpot-only: 6 (no Salesforce match)
  Salesforce-only: 17 (no HubSpot match)
 
Mismatches found: 12 of 41 matched records
 
| Email                        | Field     | HubSpot Value     | Salesforce Value   |
|------------------------------|-----------|-------------------|--------------------|
| laura.chen@meridian.com      | phone     | (555) 987-6543    | (555) 012-3456     |
| laura.chen@meridian.com      | jobtitle  | VP Operations     | Director of Ops    |
| james.okoro@pinnacle.io      | company   | Pinnacle Health   | Pinnacle Health Inc|
| ...                          | ...       | ...               | ...                |
 
Summary: 12 mismatched records, 23 mismatched fields total.

# Run a sync audit every morning at 8 AM
0 8 * * * cd /path/to/your/project && claude -p "Run /crm-sync — audit all contacts modified in the last 24 hours and post the report to Slack" --allowedTools 'Bash(*)' 'Read(*)'

name: CRM Sync Audit
on:
  schedule:
    - cron: '0 13 * * 1-5'  # 8 AM ET, weekdays
  workflow_dispatch: {}
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /crm-sync — audit contacts, companies, and deals modified in the last 24 hours. Post the mismatch report to Slack."
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          SALESFORCE_ACCESS_TOKEN: ${{ secrets.SALESFORCE_ACCESS_TOKEN }}
          SALESFORCE_INSTANCE_URL: ${{ secrets.SALESFORCE_INSTANCE_URL }}
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
          SLACK_CHANNEL_ID: ${{ secrets.SLACK_CHANNEL_ID }}