Agent Skills: salesforce

Troubleshooting

If requests fail, run zero doctor check-connector --env-name SALESFORCE_TOKEN or zero doctor check-connector --url https://your-instance.my.salesforce.com/services/data/v60.0/query --method GET

Core APIs

Query Contacts (SOQL)

curl -s "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/query?q=SELECT+Id,FirstName,LastName,Email,Phone+FROM+Contact+LIMIT+20" --header "Authorization: Bearer $SALESFORCE_TOKEN" | jq '[.records[] | {Id, FirstName, LastName, Email, Phone}]'

Docs: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm

Search Contacts by Email

Replace <email> with the email address to search for:

curl -s "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/query?q=SELECT+Id,FirstName,LastName,Email+FROM+Contact+WHERE+Email=%27<email>%27+LIMIT+5" --header "Authorization: Bearer $SALESFORCE_TOKEN" | jq '[.records[] | {Id, FirstName, LastName, Email}]'

Get Contact

Replace <contact-id> with the Salesforce Contact ID (18-char string starting with 003):

curl -s "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/sobjects/Contact/<contact-id>" --header "Authorization: Bearer $SALESFORCE_TOKEN" | jq '{Id, FirstName, LastName, Email, Phone, AccountId}'

Create Contact

Write to /tmp/sf_request.json:

{
  "FirstName": "Jane",
  "LastName": "Doe",
  "Email": "jane.doe@example.com",
  "Phone": "+1-555-0100",
  "Title": "Software Engineer",
  "LeadSource": "Web"
}

curl -s -X POST "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/sobjects/Contact/" --header "Authorization: Bearer $SALESFORCE_TOKEN" --header "Content-Type: application/json" -d @/tmp/sf_request.json | jq '{id, success}'

Update Contact

Replace <contact-id> with the Contact ID.

Write to /tmp/sf_request.json:

{
  "Phone": "+1-555-0200",
  "Title": "Senior Engineer"
}

curl -s -X PATCH "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/sobjects/Contact/<contact-id>" --header "Authorization: Bearer $SALESFORCE_TOKEN" --header "Content-Type: application/json" -d @/tmp/sf_request.json -w "\nHTTP Status: %{http_code}\n"

Create Lead

Write to /tmp/sf_request.json:

{
  "FirstName": "Jane",
  "LastName": "Doe",
  "Email": "jane.doe@example.com",
  "Company": "Acme Corp",
  "LeadSource": "Web",
  "Status": "Open - Not Contacted"
}

curl -s -X POST "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/sobjects/Lead/" --header "Authorization: Bearer $SALESFORCE_TOKEN" --header "Content-Type: application/json" -d @/tmp/sf_request.json | jq '{id, success}'

Query Accounts

curl -s "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/query?q=SELECT+Id,Name,Industry,AnnualRevenue+FROM+Account+LIMIT+20" --header "Authorization: Bearer $SALESFORCE_TOKEN" | jq '[.records[] | {Id, Name, Industry, AnnualRevenue}]'

SOSL Full-Text Search

Search across multiple objects. Replace <search-term>:

curl -s "https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/v60.0/search?q=FIND+%7B<search-term>%7D+IN+ALL+FIELDS+RETURNING+Contact(Id,Name,Email),Lead(Id,Name,Email)" --header "Authorization: Bearer $SALESFORCE_TOKEN" | jq '[.searchRecords[] | {Id, Name, type: .attributes.type}]'

Guidelines

1. Token expiry: If you receive 401 INVALID_SESSION_ID, the token has expired.
2. API version: Uses /v60.0/ (Spring '26). Check supported versions at https://$SALESFORCE_INSTANCE.my.salesforce.com/services/data/.
3. Object IDs: Contact IDs start with 003, Account IDs with 001, Lead IDs with 00Q, Opportunity IDs with 006.
4. SOQL strings: Single-quote string values in WHERE clauses, URL-encoded as %27 (e.g., WHERE+Email=%27user@example.com%27).
5. Upsert: Use PATCH /sobjects/Contact/<external-field>/<value> to upsert by an external ID field.
6. Rate limits: Per-org API limits vary by Salesforce edition. Monitor the Sforce-Limit-Info response header for remaining API calls.