What the Salesforce REST API Is

The Salesforce REST API lets external systems interact with your Salesforce org over HTTPS using JSON. You can create, read, update, and delete records; run SOQL queries; invoke Apex; publish events; and more.

It’s the primary integration surface for most modern use cases — MuleSoft, Python scripts, Postman tests, mobile apps, serverless functions. If you’re integrating with Salesforce, you’re probably using REST.

Authentication: OAuth 2.0

You cannot call the API without authentication. Salesforce uses OAuth 2.0. The flow you pick depends on the client.

Client Credentials Flow (Server-to-Server)

For backend services calling Salesforce without a user present.

  1. Create a Connected App in Salesforce Setup.
  2. Enable “Client Credentials Flow.”
  3. Assign a default Run As user with the permissions your integration needs.
  4. Record the Client ID and Client Secret.

Request a token:

curl -X POST https://login.salesforce.com/services/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "00D...",
  "instance_url": "https://yourorg.my.salesforce.com",
  "token_type": "Bearer"
}

Use the access_token as a Bearer token in subsequent calls. Use the instance_url as your base URL.

JWT Bearer Flow

Server-to-server with cryptographic proof. Better for production — no client secret to leak.

Requires:

  • A certificate uploaded to the Connected App.
  • A signed JWT matching Salesforce’s expectations.

Request:

curl -X POST https://login.salesforce.com/services/oauth2/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=SIGNED_JWT"

Good JWT libraries exist for most languages. Use them.

Web Server Flow (User Auth)

When a user needs to log in and grant access. Standard three-legged OAuth redirect flow. Used for user-facing apps that act on a specific user’s records.

Device Flow

For devices without a browser (CLIs, TVs, IoT). User authorizes on a phone; the device polls for the token.

Making API Calls

Once you have a token, calls are standard HTTPS:

curl -X GET \
  "https://yourorg.my.salesforce.com/services/data/v60.0/sobjects/Account/001xx000003DGb2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Core Operations

Get a Record by ID

GET /services/data/v60.0/sobjects/Account/{id}

Returns all accessible fields. Add ?fields=Name,Industry to limit the response.

Query with SOQL

GET /services/data/v60.0/query?q=SELECT+Id,Name+FROM+Account+LIMIT+10

URL-encode the query. Response includes a records array and an optional nextRecordsUrl for pagination.

Create a Record

POST /services/data/v60.0/sobjects/Account
{
  "Name": "Acme Corporation",
  "Industry": "Technology"
}

Response includes the new id.

Update a Record

PATCH /services/data/v60.0/sobjects/Account/{id}
{
  "Industry": "Healthcare"
}

Only the fields you include are updated.

Upsert by External ID

PATCH /services/data/v60.0/sobjects/Account/External_Id__c/ext-12345
{
  "Name": "Acme",
  "Industry": "Tech"
}

Create or update based on the external ID. Useful for idempotent integrations.

Delete

DELETE /services/data/v60.0/sobjects/Account/{id}

Describe an Object

GET /services/data/v60.0/sobjects/Account/describe

Returns metadata: fields, relationships, picklist values. Useful for discovering the schema programmatically.

Bulk Operations

For moving lots of data, use Bulk API 2.0 — not REST directly. Bulk API handles 10K+ record operations efficiently; single-record REST calls hit API limits fast.

Typical Bulk API 2.0 flow:

  1. Create a job (POST).
  2. Upload CSV data (PUT).
  3. Close the job (PATCH).
  4. Poll status until complete.
  5. Retrieve results.

For 100 records: REST is fine. For 10,000 records: Bulk API.

Handling Errors

Salesforce returns standard HTTP status codes with JSON bodies:

  • 200 OK: success.
  • 201 Created: record created.
  • 400 Bad Request: your payload was invalid.
  • 401 Unauthorized: token expired or bad.
  • 403 Forbidden: the running user can’t perform this operation.
  • 404 Not Found: no such record.
  • 429 Too Many Requests: rate limit hit.

Error response format:

[
  {
    "message": "Required fields are missing: [Name]",
    "errorCode": "REQUIRED_FIELD_MISSING",
    "fields": ["Name"]
  }
]

Parse the array, handle each error per your integration’s policy.

API Versions

URLs include a version: /services/data/v60.0/. Salesforce releases three times a year; each release bumps the version.

Pin your integrations to a specific version. Don’t use the “latest” URL (/services/data/latest/ doesn’t exist anyway, but some implementations float). Pinned versions don’t break when new releases ship.

Upgrade intentionally — test against the new version, then bump your integration’s URLs.

Rate Limits

Salesforce enforces API request limits per 24 hours. Limits scale with license count:

  • Roughly 15,000 baseline plus per-user allocation.
  • Bulk API calls count as one per batch, not per record — dramatic savings for high volume.
  • Check current usage: GET /services/data/v60.0/limits.

Monitor and budget. A runaway integration hitting the limit blocks every other integration in the org.

Common Beginner Mistakes

Hardcoding the login URL. Use https://login.salesforce.com for production, https://test.salesforce.com for sandboxes. After auth, use the instance_url from the response — don’t hardcode yourorg.my.salesforce.com.

Ignoring token expiry. Tokens expire. Your client needs to refresh on 401 responses.

Querying with SELECT *. Not valid in SOQL. Specify fields.

Ignoring API version compatibility. Old versions deprecate eventually. Don’t pin to v40 forever.

Swallowing errors. Always parse the error response. A 400 with “VALIDATION_RULE” tells you exactly what’s wrong.

Frequently Asked Questions

Do I need a Connected App for every integration?

Yes — one per integration (or one shared if the integrations are tightly related). Separate apps make monitoring and rotation easier.

How do I test without a real org?

Sign up for a free Developer Edition org at developer.salesforce.com. Full feature set, low limits, indefinite life.

What about GraphQL?

Salesforce supports GraphQL for reads (queries). For writes, stay with REST or Apex REST. GraphQL is a newer addition; REST remains the primary API.

What’s the “Composite” API?

REST, but multiple operations in one request. Reduces round trips. See the composite API article for patterns.

Share