Batch-enrich Salesforce contacts with Apollo using a Claude Code skill

mkdir -p .claude/skills/sf-apollo-enrich/{templates,references}

---
name: sf-apollo-enrich
description: Batch-enrich un-enriched Salesforce leads with Apollo contact data. Queries leads missing key fields, enriches via Apollo People Enrich API, and writes results back to Salesforce.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Workflow
 
1. Read `references/salesforce-api.md` for SOQL query and sObject update patterns
2. Read `references/apollo-people-enrich.md` for the enrichment API
3. Read `templates/field-mapping.md` for Apollo → Salesforce field mapping
4. Query Salesforce for Leads where Title is null and Email is not null (SOQL)
5. For each lead, call Apollo People Enrich with the email
6. Build an update payload using only fields that Apollo returned
7. PATCH each Lead in Salesforce with the enriched data
8. Print a summary: total found, enriched, skipped
 
## Rules
 
- Only update fields that Apollo returns non-null values for
- Rate limit: 0.7 seconds between Apollo calls (100/min limit)
- Handle Apollo 429 responses by waiting 60 seconds and retrying
- Filter out personal email domains before calling Apollo
- Use environment variables: SALESFORCE_INSTANCE_URL, SALESFORCE_ACCESS_TOKEN, APOLLO_API_KEY

# Salesforce REST API Reference
 
## Query records with SOQL
 
```
GET {SALESFORCE_INSTANCE_URL}/services/data/v59.0/query?q={SOQL}
Authorization: Bearer {SALESFORCE_ACCESS_TOKEN}
```
 
Example SOQL — find Leads missing job title:
```sql
SELECT Id, Email, FirstName, LastName, Company, Title, Phone
FROM Lead
WHERE Title = null AND Email != null
ORDER BY CreatedDate DESC
LIMIT 50
```
 
Response:
```json
{
  "totalSize": 42,
  "records": [
    {
      "Id": "00Q5e000001abc",
      "Email": "jane@acme.com",
      "FirstName": "Jane",
      "LastName": "Smith",
      "Company": "Acme Inc",
      "Title": null,
      "Phone": null
    }
  ]
}
```
 
## Update a Lead
 
```
PATCH {SALESFORCE_INSTANCE_URL}/services/data/v59.0/sobjects/Lead/{LeadId}
Authorization: Bearer {SALESFORCE_ACCESS_TOKEN}
Content-Type: application/json
```
 
Request body:
```json
{
  "Title": "VP of Engineering",
  "Phone": "+14155550142",
  "Department": "Engineering",
  "LinkedIn_URL__c": "https://linkedin.com/in/janesmith"
}
```
 
Successful response: HTTP 204 No Content.
 
Notes:
- LinkedIn_URL__c is a custom field — must be created in Salesforce first
- Access token expires per session timeout settings. Use refresh tokens for long-running automations
- SOQL strings must be URL-encoded when passed as query params

# Apollo People Enrich API Reference
 
```
POST https://api.apollo.io/v1/people/enrich
x-api-key: {APOLLO_API_KEY}
Content-Type: application/json
```
 
Request body:
```json
{
  "email": "jane@acme.com",
  "reveal_personal_emails": false
}
```
 
Response:
```json
{
  "person": {
    "title": "VP of Engineering",
    "seniority": "vp",
    "departments": ["engineering"],
    "linkedin_url": "https://linkedin.com/in/janesmith",
    "phone_numbers": [
      { "sanitized_number": "+14155550142", "type": "work_direct" }
    ],
    "organization": {
      "name": "Acme Inc",
      "estimated_num_employees": 500,
      "industry": "Computer Software",
      "annual_revenue": 50000000
    }
  }
}
```
 
If no match: `{"person": null}`. Costs 1 credit per call.
 
Rate limit: ~100 requests per minute. On 429 response, wait 60 seconds and retry.
 
Bulk alternative: POST /v1/people/bulk_enrich (up to 10 records per call).

# Field Mapping: Apollo → Salesforce
 
## Lead fields
 
| Apollo field | Salesforce field | Type | Notes |
|---|---|---|---|
| person.title | Title | Standard | Job title |
| person.phone_numbers[0].sanitized_number | Phone | Standard | First work phone |
| person.departments[0] | Department | Standard | Primary department |
| person.linkedin_url | LinkedIn_URL__c | Custom (URL) | Must create in Salesforce first |
| person.organization.name | Company | Standard | Lead company name |
| person.seniority | Seniority__c | Custom (Text) | Optional custom field |
 
## Account fields (optional, if updating parent Account)
 
| Apollo field | Salesforce field | Notes |
|---|---|---|
| person.organization.industry | Industry | Standard picklist |
| person.organization.estimated_num_employees | NumberOfEmployees | Standard number field |
 
## Rules
 
1. Only include fields in the update payload if Apollo returned a non-null value
2. Do not overwrite existing Salesforce values unless explicitly asked
3. Custom fields (LinkedIn_URL__c, Seniority__c) must be created in Salesforce before use

# In Claude Code
/sf-apollo-enrich

# Run daily at 9 AM
0 9 * * * cd /path/to/project && claude -p "Run /sf-apollo-enrich for the 50 most recent leads missing a title." --allowedTools 'Bash,Read' 2>&1 >> /var/log/sf-enrich.log

name: Salesforce Apollo Enrichment
on:
  schedule:
    - cron: '0 14 * * *'  # 9 AM ET = 2 PM UTC
  workflow_dispatch: {}
jobs:
  enrich:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /sf-apollo-enrich for the 50 most recent leads missing a title."
          allowed_tools: "Bash,Read"
        env:
          SALESFORCE_INSTANCE_URL: ${{ secrets.SALESFORCE_INSTANCE_URL }}
          SALESFORCE_ACCESS_TOKEN: ${{ secrets.SALESFORCE_ACCESS_TOKEN }}
          APOLLO_API_KEY: ${{ secrets.APOLLO_API_KEY }}