Salesforce API skill for Codex

Done well means: the integration authenticates without a stored password, writes are idempotent upserts on an external ID, the right API is used for the volume, daily API usage is measured, and anything touching production data was tried in a sandbox and confirmed by the user first.

Pick the API by volume and shape

Records per run	Use	Why
1 to ~200, interactive	REST sObject endpoints	Simple, immediate errors
Up to 200 per call, several objects or dependent steps	Composite / sObject Collections	One API call, optional all-or-none
Thousands to millions	Bulk API 2.0 ingest or query jobs	Async, CSV, cheap on API limits
React to changes in Salesforce	Change Data Capture or Platform Events via Pub/Sub API	No polling
Metadata (fields, flows, permission sets)	Salesforce CLI / Metadata API	Deployable source, not data

Authentication

Flow	When
OAuth 2.0 JWT bearer (certificate)	Server-to-server, runs as a named integration user. Default choice
OAuth 2.0 client credentials	Server-to-server with a configured run-as user; no certificate handling
Web server (auth code + PKCE)	Your app acts as each signed-in Salesforce user
Username-password	Do not use; blocked by default in new orgs and bypasses MFA

Create the app as an External Client App (Salesforce’s current model; creating classic connected apps may be disabled in newer orgs). Use a dedicated API-only integration user with a permission set granting exactly the objects and fields the job touches. Sandboxes log in via https://test.salesforce.com; production via https://login.salesforce.com or the My Domain URL.

import time, jwt, requests          # PyJWT with cryptography installed

def jwt_login(client_id, username, key_pem, login_url="https://login.salesforce.com"):
    assertion = jwt.encode(
        {"iss": client_id, "sub": username, "aud": login_url, "exp": int(time.time()) + 180},
        key_pem, algorithm="RS256")
    r = requests.post(f"{login_url}/services/oauth2/token", timeout=30, data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": assertion})
    r.raise_for_status()
    tok = r.json()
    return tok["instance_url"], tok["access_token"]

Secrets and keys come from env or a secret manager (read AGENTS.md). Every call needs network; in an offline Codex sandbox, write the code and ask before running it.

API version

List what the org supports with GET /services/data/ and pin the newest listed version in config (for example v64.0). Never mix versions within one integration; field availability and behaviour change between releases.

sf org login web --alias dev-sandbox --instance-url https://test.salesforce.com
sf data query --query "SELECT Id, Name FROM Account LIMIT 5" --target-org dev-sandbox
sf org list limits --target-org dev-sandbox | grep -i DailyApiRequests

REST essentials

from simple_salesforce import Salesforce

sf = Salesforce(instance_url=instance_url, session_id=access_token, version="64.0")

# Idempotent upsert by external ID (create if absent, update if present)
sf.Account.upsert("ERP_Id__c/ACME-001", {"Name": "Acme Ltd", "Industry": "Manufacturing"})

# Describe once; cache the field list and picklist values
meta = sf.Contact.describe()
writable = {f["name"] for f in meta["fields"] if f["updateable"]}

Task	Endpoint
Upsert by external ID	PATCH /services/data/vXX.X/sobjects/Account/ERP_Id__c/ACME-001
Up to 200 records in one call	POST/PATCH /composite/sobjects with allOrNone
Dependent steps (create Account, then Contact referencing it)	POST /composite with referenceId and @{ref.id}, up to 25 subrequests
Field metadata	GET /sobjects/Contact/describe
Records changed in a window	GET /sobjects/Account/updated/?start=...&end=...
Usage	GET /limits

External ID fields must be marked External ID (and ideally Unique) on the object. Upserting on a non-unique external ID with duplicates returns MULTIPLE_CHOICES (300).

SOQL

def query_all(sf, soql):
    res = sf.query(soql)
    while True:
        yield from res["records"]
        if res["done"]:
            return
        res = sf.query_more(res["nextRecordsUrl"], identifier_is_url=True)

soql = ("SELECT Id, Name, Owner.Email, (SELECT Id, Email FROM Contacts) "
        "FROM Account WHERE LastModifiedDate >= LAST_N_DAYS:7 AND Type = 'Customer' "
        "ORDER BY LastModifiedDate")
for acc in query_all(sf, soql):
    ...

• Values from users go through escaping: single quote and backslash must be escaped (value.replace("\\", "\\\\").replace("'", "\\'")) or SOQL injection follows.
• Date literals are unquoted (CreatedDate > 2026-10-01T00:00:00Z, LAST_N_DAYS:30).
• queryAll (/queryAll) includes deleted and archived records; query does not.
• OFFSET caps at 2,000; page with nextRecordsUrl or keyset (WHERE Id > :last ORDER BY Id).
• Large objects need selective filters on indexed fields (Id, Name, external IDs, lookups, CreatedDate, SystemModstamp). Check with GET /query?explain=<soql>: a TableScan with high relative cost will time out at scale.
• Use SystemModstamp rather than LastModifiedDate for incremental syncs; it also moves on system updates.

Bulk API 2.0

Use for anything beyond a few thousand rows. Flow: create job -> upload CSV -> mark UploadComplete -> poll -> download successful, failed and unprocessed results. Full request sequence, CSV rules and query-job paging with Sforce-Locator are in references/bulk-api-2.md; read it before writing a Bulk job.

delete moves records to the Recycle Bin; hardDelete is permanent and needs a special permission. Both need explicit user confirmation of the exact record set (show the count and a sample of IDs from the query that built the CSV).

Limits and errors

• Every response carries Sforce-Limit-Info: api-usage=1234/100000. Log it; alert above 80%.
• Long-running requests (over 20 seconds) are capped at 25 concurrent in production.
• Back off on REQUEST_LIMIT_EXCEEDED, UNABLE_TO_LOCK_ROW (retry with jitter; sort child records by parent ID in Bulk to reduce lock contention) and 503.

Error	Meaning
INVALID_SESSION_ID (401)	Token expired or revoked; re-run the auth flow
INVALID_FIELD / No such column	Field absent, wrong API name, or hidden by field-level security for the integration user
FIELD_CUSTOM_VALIDATION_EXCEPTION	A validation rule rejected the record; read its message
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY	A trigger or flow failed; the message contains the Apex/flow error
DUPLICATES_DETECTED	Duplicate rules; decide with the user whether to bypass via header or fix data
INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST	Use picklist API values, not labels

Change events instead of polling

Enable Change Data Capture for the objects (Setup -> Change Data Capture), then subscribe to /data/AccountChangeEvent through the Pub/Sub API (gRPC). Store the replay ID after processing; events are retained for 72 hours, so a consumer down longer than that must resync with SOQL.

Gotchas

• IDs are 15-char case-sensitive or 18-char case-insensitive; store and compare the 18-char form.
• API writes fire triggers, flows and assignment rules; a “simple” import can send emails to customers. Check automation on the object in the sandbox first.
• Datetimes are UTC; dates have no time zone. Do not convert dates through local time.
• Record types and required fields differ per profile; describe as the integration user.
• Multi-currency orgs need CurrencyIsoCode on money fields.

Verification

• Run the job against a sandbox seeded with representative data; compare counts by SOQL (SELECT COUNT() FROM Account WHERE ERP_Id__c != null) before and after.
• For Bulk jobs, numberRecordsFailed must be 0 or every failure explained from failedResults.
• Log Sforce-Limit-Info before and after to report API calls consumed.