Salesforce is one of the most integration-friendly CRMs on the market. Whether you’re building lightweight services, syncing external systems, or orchestrating complex enterprise workflows, Salesforce’s APIs give you everything you need to connect data across systems.
Two of the most commonly used integration options are the REST API and the SOAP API. Each API has its strengths, best-fit scenarios, and different implementation considerations.
This guide breaks down everything you need to know — from conceptual differences to authentication, performance, limits, and real-world use cases.
1. Introduction to Salesforce APIs
Salesforce exposes multiple APIs:
- REST API
- SOAP API
- Bulk API (v1/v2)
- Streaming APIs
- GraphQL API (Pilot/GA depending on your org)
- Metadata API
- Tooling API
But when someone says “I’m integrating with Salesforce”, 90% of the time they're talking about REST or SOAP.
These two are the pillars of synchronous integrations.
2. REST API vs SOAP API at a Glance
3. When to Use REST API
REST is the modern, flexible choice — ideal when performance and simplicity are key.
Best for:
- Mobile applications
- Single-page web apps
- Microservices
- JavaScript-based clients (Node.js, React, Angular)
- Integrations requiring speed and small payloads
- Scenarios with frequent small operations (CRUD)
Why choose REST?
- JSON is compact and easy to parse
- No WSDL needed
- Great for stateless, scalable integrations
- Wide language support
4. When to Use SOAP API
SOAP is the heavyweight choice — strict, structured, and enterprise-grade.
Best for:
- Legacy systems and ERPs
- Complex enterprise environments
- Systems requiring strict contract definitions (WSDL)
- Integrations that need strong typing and formal validation
- Partner integrations where security and compliance are essential
Why choose SOAP?
- Rigid standards (WSDL ensures type safety)
- Mature WS-Security support
- Better for big, structured enterprise systems
5. Authentication in REST vs SOAP
REST Authentication Options
- OAuth 2.0 (recommended)
- Web Server flow
- User-Agent flow
- JWT Bearer flow (best for server-to-server)
- Username-Password flow
- Session ID (via SOAP login)
- API Token + Username (rare, deprecated style)
SOAP Authentication
SOAP uses:
- login() call with username + password + security token
- Returns a sessionId (used in the header for subsequent requests)
6. Practical REST API Examples
6.1. Querying Records (SOQL)
Endpoint:
GET /services/data/v60.0/query/?q=SELECT+Id,Name+FROM+Account
Response (JSON):
{
"totalSize": 1,
"records": [
{
"Id": "001...XYZ",
"Name": "Acme Corp"
}
]
}6.2. Creating a Record
Endpoint:
POST /services/data/v60.0/sobjects/Account
Body:
{
"Name": "New REST Account",
"Industry": "Technology"
}
Success Response:
{
"id": "001...",
"success": true,
"errors": []
}
7. Practical SOAP API Examples
7.1. SOAP Login Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:partner.soap.sforce.com">
<soapenv:Body>
<urn:login>
<urn:username>yourUsername</urn:username>
<urn:password>yourPassword+SecurityToken</urn:password>
</urn:login>
</soapenv:Body>
</soapenv:Envelope>Response contains:
- sessionId
- serverUrl
You then include sessionId in subsequent SOAP headers.
7.2. Creating an Account (SOAP)
<soapenv:Envelope ...>
<soapenv:Header>
<urn:SessionHeader>
<urn:sessionId>SESSION_ID</urn:sessionId>
</urn:SessionHeader>
</soapenv:Header>
<soapenv:Body>
<urn:create>
<urn:sObjects xsi:type="urn:Account">
<Name>New SOAP Account</Name>
<Industry>Finance</Industry>
</urn:sObjects>
</urn:create>
</soapenv:Body>
</soapenv:Envelope>8. Performance Comparison
REST is generally 2–5× faster due to lightweight JSON payloads.
9. Error Handling
REST Example Error:
[
{
"message": "Required field missing: Name",
"errorCode": "REQUIRED_FIELD_MISSING"
}
]SOAP Example Error:
SOAP provides richer structure:
<faultcode>sf:INVALID_FIELD</faultcode>
<faultstring>Invalid field Name for Account</faultstring>SOAP errors are more enterprise-friendly, with strict typing.
10. Salesforce Limits for REST and SOAP
Both APIs consume the same limits:
- API calls per 24 hours
- Concurrent requests
- Payload limits
- SOQL query limits
Bulk operations? → Use Bulk API instead for large datasets.
11. Best Practices for Choosing Between REST and SOAP
Choose REST if:
- You want speed
- You need lightweight mobile or web integrations
- You're building microservices
- You don’t need XML schemas
Choose SOAP if:
- You’re integrating with a legacy/enterprise system
- You need WSDL-based contract validation
- You want strict type definitions
12. Integration Architecture Recommendations
❶ Server-to-Server Integrations → Use OAuth JWT Flow (REST)
- Fast
- No user interaction
- Secure
❷ ERP / Legacy Systems → Use SOAP
- These systems often require WSDL contracts
- Easy mapping to strongly typed objects
❸ Custom Apps / Webhooks → Use REST
- Clean JSON
- Easy debugging
- Fast to implement
❹ Large Data Sync → Mix REST for metadata + Bulk API for data
13. Final Recommendation
If you’re building a modern integration today, REST API is your go-to — simple, fast, scalable.
But if your integration involves legacy systems, enterprise-level requirements, or heavy contract validation, SOAP API still shines.
The smart approach many architects use:
➡️ REST for real-time and lightweight operations
➡️ SOAP for structured enterprise workflows
➡️ Bulk API for large datasets
Conclusion
Salesforce provides powerful APIs, but choosing the right one depends on your system, payload size, complexity, and performance needs. REST and SOAP each play a unique role in the integration landscape.
By understanding their strengths, authentication models, error handling, and optimal use cases, you can design more reliable and scalable Salesforce integrations.