Calling the Salesforce REST API from an external system has three layers: authenticate via OAuth, construct the request URL with the right API version and resource, and handle the response with proper error handling. Build with a tested client library (Salesforce ships SDKs for Node, Python, Java, .NET) rather than rolling raw HTTP; the SDKs handle authentication, retries, and pagination consistently.
- Create a Connected App for OAuth
Setup > App Manager > New Connected App. Configure OAuth with the right flow (JWT Bearer for server integrations, Web Server for user-facing). Note the Consumer Key and Consumer Secret. Pre-authorize the right profiles or permission sets.
- Obtain an access token
Make a POST to /services/oauth2/token with the OAuth grant parameters. The response includes access_token (used in subsequent API calls), instance_url (the base URL for API calls), and refresh_token (used to renew without re-authenticating).
- Construct the API call URL
Use the instance_url and the API version: https://yourdomain.my.salesforce.com/services/data/v60.0/sobjects/Account. Append /RecordId for specific records, /describe for metadata, or use /query?q=SOQL for SOQL queries.
- Add the Authorization header
Every request needs Authorization: Bearer ACCESS_TOKEN. Without it, the API returns 401. Tokens expire (typically 2 hours); handle 401 by refreshing the token and retrying.
- Send the request and parse the response
Use the appropriate HTTP verb (GET, POST, PATCH, DELETE) with JSON body for write operations. The response is JSON. Check the HTTP status code and the response body for errors. 2xx responses are success; 4xx are client errors; 5xx are server errors.
- Handle pagination for query results
Large query results return a nextRecordsUrl field. Make a GET to that URL to retrieve the next page. Repeat until the response indicates done=true. Most SDKs handle pagination automatically.
- Implement retry with exponential backoff
Transient errors (503, 504, rate limit responses) should be retried with exponential backoff. Permanent errors (400, 404) should not retry. Build retry logic into the integration layer so callers do not have to handle it.
- Monitor API consumption
Call the Limits endpoint periodically to track daily API consumption. Setup > API Usage shows historical patterns. Alert when consumption approaches the daily cap so you can investigate spike causes before hitting the limit.
Web Server, JWT Bearer, Client Credentials, or Refresh Token. Drives how the integration obtains access tokens.
Pinned in the URL path. Pin to a specific version for stability; upgrade deliberately during planned maintenance.
Patterns for bundling multiple operations into one HTTP request to reduce round trips and API consumption.
- REST API call counts against the daily API cap. High-volume integrations can blow the cap during peak periods. Monitor consumption and rate-limit upstream callers if needed.
- Tokens expire after the configured lifetime. Implement refresh token handling; 401 responses without retry logic produce intermittent integration failures.
- API version pinning is required for stable integrations. Letting the URL drift to whatever version Salesforce currently serves produces subtle behavior changes as versions release.
- REST API is per-record. For bulk operations over 50,000 records, switch to Bulk API 2.0. REST batch operations cap at 25 sub-requests per call.
- Connected App secrets must be stored in a secrets manager, never embedded in client code or version control. Leaked Consumer Secrets are the most common Salesforce credential incident.