If you are new to Salesforce APIs and want to understand which APIs are available to access objects in your Salesforce org, then this blog post is for you. The Salesforce Platform provides APIs that enable you to create, read, update, and delete records (commonly referred to as CRUD operations) in your org. We’ll highlight and compare these APIs to help you understand the API landscape available, and provide links to supporting documentation and other blog posts with more detail.
Salesforce provides a large and comprehensive collection of APIs that allow external applications to access data and capabilities in the Salesforce Clouds. To see the full list of APIs, most of which are beyond the scope of this post, refer to the API Developer documentation. Additionally, you can also refer to help documentation for guidance on choosing Salesforce APIs, some of which are beyond the focus of this post.
APIs for accessing object data in a Salesforce org
The Salesforce Platform provides multiple APIs to access object data and perform CRUD operations on records in your org. Which API you should use depends upon the type of integration you are implementing, and how much data you need to access.
If you are implementing a UI integration, where a custom UI needs to access data, then use either the UI API or the GraphQL API. Both of these APIs allow you to work with both metadata and data. Note that this blog post is not focused on UI integration and doesn’t discuss this scenario.
If you are implementing a non-UI integration, where an external application needs to access data, then the amount of data that your integration needs to work with will influence the API you should use.
- Need CRUD access to individual records → REST sObject Rows API
- Need CRUD access to 10s through 1000s of records → REST Composite API
- Need to retrieve 1-1000s of records → Query API
- Need CRUD access to large amounts of data, generally more than 2,000 records → Bulk API 2.0 or Bulk API
The table below summarizes and compares the main capabilities of these APIs to help you decide which API is best for your use case.
| User Experience | Behavior | Limits | |
| REST API sObject Resources |
REST API resources for performing a single record CRUD. | Single record CRUD on standard and custom objects. | Each request counts as a single call toward API limits. |
| REST API Query Resource |
REST API resource for executing a SOQL query. | Query standard and custom objects using SOQL.
Response pagination for result sets greater than 2,000 records. |
Each request counts as a single call toward API limits. |
| REST API Composite Resources |
REST API resources for executing multiple operations on multiple objects and other resources in a single request. | Each request can contain multiple operations or sub-requests.
Specific behavior depends on the Composite API resource used. |
Each request counts as a single call toward API limits, with the exception of Composite Batch resource, where each operation counts as a single call toward API limits. |
| SOAP API | Web Services operations supporting both org-specific and org-agnostic WSDLs. | Supports operating on data, retreiving metedata and performing utility operations.
CRUD on standard and custom object with up to 200 records per request. Query standard and custom objects using SOQL, with up to 2,000 records for query pagination. |
Each request counts as a single call toward API limits. |
| Bulk API 2.0 Bulk API |
Asynchronous operations for ingesting, extracting, and deleting large data sets. | Operates on a single object per job.
No SLA for job completion. Not ideal for small scale workloads due to overhead. |
Limits based on mix of records, batches, jobs, data size.
Limits simplified in Bulk API 2.0. Ingest of up to 150MM records per 24 hour period. Extract up to 1TB per 24 hour period. |
| Apex REST & SOAP | For exposing Apex classes as REST API resources and SOAP Web Services. | Custom depending on Apex class. | Each request counts as a single call toward API limits.
Apex governor limits also apply. |
REST API
REST API provides API access, using the RESTful architectural pattern, to a broad range of data and capabilities on the Salesforce Platform as a set of REST resources under the root https://<my-domain>.my.salesforce.com/services/.
The top-level resources available under https://<my-domain>.my.salesforce.com/services/ are:
- REST API:
.../data/vXX.0/resource/version/. When people and Salesforce documentation refer to the Salesforce REST API, they are referring to the versioned resources under this URL. - Bulk API:
.../async/. This is the original Bulk API, sometimes referred to as Bulk v1, while Bulk API 2.0 is part of the REST API. Both of these APIs are discussed below. - OAuth endpoints:
.../oauth2/. These resources enable you to make OAuth authorization requests to Salesforce. These are out of scope for this blog post, so refer to the linked documentation if you want more information.
REST API resources
As introduced above, with the exception of Bulk API and OAuth, all the REST API resources are versioned under https://<my-domain>.my.salesforce.com/services/data/vXX.0/resource. As of the Spring ’24 release, which is API version 60.0, the REST API provides 48 top-level resources.
The REST API Versions resource will retrieve a list of supported API versions with information including the version, label, and link to the version’s root.
The REST API Resources by Version resource will retrieve a list of the available resources for the specified API version, including the resource name and root.
REST API resources to access data
As this blog post is focused on accessing data in your Salesforce org, it will focus on the REST API resources under https://<my-domain>.my.salesforce.com/services/data/vXX.0/ that provide access to objects and records:
- sObject resource:
.../sobjects/. Performs a wide range of operations on individual records of standard and custom objects. - Query resource:
.../query/. Executes a SOQL query to retrieve data. - Composite resources:
.../composite/. Set of resources that can execute multiple operations in a single REST API call. - Bulk API 2.0 resource:
.../jobs/. Provides a streamlined workflow for ingesting, extracting, or deleting large sets of data.
Other REST API resources
While we are discussing REST API, it is worth calling out related REST API resources under https://<my-domain>.my.salesforce.com/services/data that provide access to metadata, data, and content on the Salesforce Platform, but that are beyond the scope of this blog post:
- Connect API: For access to B2B Commerce, CMS-managed content, Experience Cloud sites, files, notifications, topics, Chatter feeds, users, groups, and more
- Search API: For executing SOSL statements
- Limits API: Returns information about the limits in your org, including the maximum allocation and remaining allocation based on usage
- UI API: For building Salesforce UIs for native mobile apps and custom web apps using the same API that Salesforce uses to build Lightning Experience and Salesforce for Android, iOS and mobile web
REST API sObject resources
The set of REST API sObjects allow you to perform a wide range of operations on standard and custom objects, for example:
- Get CRUD access to individual records
- Traverse object relationships to access records of related objects
- Get metadata describing objects
- Get page layouts and descriptions
- Get an object’s actions
The key characteristic of sObject resources is that they operate on a single object, or on an individual record of a single object. For a full list of the sObject resources, see the REST API Reference.
As this blog post is focused on performing CRUD operations on object data, we are going to highlight the sObject resources that allow you to access individual object records and traverse object relationships.
Accessing individual records
sObject resources allow you to create, retrieve, update, or delete individual records for standard and custom objects.
The sObject Basic Information resource allows you to create a record in a specified object and returns the record ID. For example, the following REST API request will create an Account record with the ID of the newly created record returned in the response
The sObject Rows resource allows you to retrieve, update, or delete individual records in a specified object using the record ID. For example, the following REST API request will retrieve the Name, Description, Industry and Website fields from the Account record with an ID of 0018W00002A4IAPQA3.
Traversing relationships
Using the sObjects Relationship resource, you can traverse an object’s relationships to retrieve, update, or delete a related record. For example, the following REST API request will retrieve, for the Contact record with an ID of 0038W000020wJDXQA2, the parent Account record’s Name field.
REST API Query resource
The Query resource allows you to execute a SOQL query to retrieve data from your Salesforce org.
To illustrate this, the following request executes a very simple SOQL query to retrieve the Name and Description fields from an Account record, where the Account record’s Name field is ACME Corp.
Note: the above query and other queries in this blog post are not URL encoded for readability. When making these Query resource calls, you should URL encode your queries.
Relationship queries
The Query resource allows you to execute SOQL relationship queries that traverse parent-to-child and child-to-parent relationships between objects to filter and return results. The request below executes a SOQL parent-to-child relationship query to retrieve the Account Name and Description fields, and the FirstName and LastName fields from all related Contact records, which could be multiple, where the Account Name is ACME Corp. The Query resource supports nested SOQL parent-to-child relationship queries up to five levels deep — see the blog post Query More Data with Nested SOQL Queries for more details.
The Query resource can also execute relationship queries that traverse object relationships in the other direction. The following request executes a SOQL parent-to-child relationship query to retrieve the FirstName and LastName fields, and the parent Account record’s Name and Description fields, from Contact records where the parent Account record’s Name field is ACME Corp.
Getting query results
A call to the Query resource can return up to 2,000 records at a time. If the result consists of more than 2,000 records, the response contains the first set of records and a Query Locator to a server-side cursor with the remaining records. Use the Query More Results resource with the Query Locator to retrieve the next batch of records, and repeat this process until all the query results have been retrieved. The only limit is that the cursor and associated query results are available for no longer than two days; there are no limits on the number of open cursors a user may have. The blog post Processing Large Amounts of Data with APIs (Part 1 of 2) discusses how to use the Query Locator to return more than 2,000 records.
If you need your query to also include records that have been deleted because of a merge or delete, use the QueryAll resource, along with the corresponding QueryAll More Results and the Query Locator, to retrieve subsequent batches of results. Be aware that only soft deleted records that are in the recycle bin are returned; deleted records that have been purged from the recycle bin can’t be queried.
REST API Composite resources
The Composite resources are a set of REST API resources that can execute multiple operations in a single REST API call. These are resources that are built by combining existing REST API resources, so that a single request can perform multiple operations.
Orchestration using Composite resources allows for developer-controlled business logic and functionality. Responses from one method can be directed as inputs into another method. Multiple resources can be used in a single call to improve performance.
Composite resources are also key for designing efficient API use in mobile development to reduce client-server round trips.
Which Composite resource should I use?
The Composite resources consist of five different REST API resources that provide different capabilities, all with the commonality that they combine multiple operations called subrequests into a single API call. The table below summarizes and compares the main characteristics of each to help you decide which resource is best for your use case.
| User Experience | Objects and Records | Behavior | Limits | |
| Composite | Orchestrate a series of REST subrequests in single REST call. | Mix of sObject, Query, QueryAll and sObject Collections. | Up to 25 subrequests in one request.
5 subrequests can feature query, queryAll, or sObject Collections resources. Combination of related and independent operations with allOrNone. Pass output of one subrequest as input to another. CRUD on up to 1,020 records. |
Each request counts as a single call toward API limits. |
| Composite Graph | Orchestrate a more complicated and complete series of REST subrequests as multiple independent graphs in a single REST call. | CRUD operations on sObjects only. | Up to 75 graphs in one request.Up to 500 subrequests per request across all graphs.
Operations in each graph are either all completed or all not completed. Failure of one graph does not impact other graphs. |
Each request counts as a single call toward API limits. |
| Composite Batch | Execute a series of independent REST subrequests. | Mix of sObject, Query, QueryAll, Limits, Search, Connect, Chatter, Actions. | Up to 25 subrequests in one request.
Each subrequest commits its data on successful execution. If a subrequest fails, commits by previous subrequests not rolled back. |
Each REST subrequest counts towards API limits.Uses Connect API limits. |
| sObject Tree | Create a tree of nested, parent-child records with single root record. | Multiple sObjects trees, with all root records having the same sObject type. | Create up to 200 related records across five sObject types, five levels deep. | Each request counts as a single call toward API limits. |
| sObject Collections | Execute CRUD actions on multiple sObject records.
Equivalent to SOAP API operations on up to 200 records. |
Depending on operation, records must all be of same sObject type or maybe different sObject types. | For write operations, up to 200 records in one request, with allOrNone.
For read operations, up to 2,000 records in one request. |
Each request counts as a single call toward API limits. |
The blog post Processing Large Amounts of Data with APIs (Part 2 of 2) discusses writing records using the Composite, Composite Batch, and Composite Graph resources in more detail.
Composite resource
The Composite resource allows you to execute a series of REST API sub-requests in a single call from the client, using the output of one sub-request as the input to a subsequent sub-request. The HTTP status codes and response bodies of all the sub-requests are returned in a single response to the client.
In the example below, the first sub-request creates an Account record and references the output as refAccount. The second sub-request creates a Contact record parented under the newly created Account record by referencing refAccount.
Composite Graph resource
The Composite Graph resource provides a more powerful way to orchestrate multiple REST API requests in a single call. This resource allows you to make a single request that consists of multiple independent graphs, with each graph consisting of multiple REST API sub-requests.
In this example, we need to perform the following as a single call:
- Create Account 1 record
- Create Account 2 record, as a child of Account 1 record
- Create Contact 1 record, as a child of Account 2 record
- Create Contact 2 record, who reports to Contact 1 record
- Create Contact 3 record, who reports to Contact 2 record
- Create a Campaign record
- Create an Opportunity record, linked to the Account 1 record and the Campaign record
- Create a Lead record
- Create a CampaignMember record, linked to the Lead record and the Campaign record
We can represent these records as a graph.
The request below shows how the Composite Graph resource can be used to create the above graph of records.
sObject Tree resource
The sObject Tree resource allows you to create a tree of nested, parent-child records with a single root record. The request can contain the following:
- Up to a total of 200 records across all trees
- Records of up to five different sObjects types
- sObject trees up to five levels deep
As an sObject Tree request can contain a single record, you can use this resource to create up to 200 unrelated records of the same type.
The example below creates these records:
- Account record ref1
- Contact record ref2, related to parent Account record ref1
- Contact record ref2, related to parent Account record ref1
- Account record ref4
sObject Collections resource
The sObject Collections resource allows you to execute CRUD actions on multiple, independent records in a single request. The request, response, and behavior depend upon the action being performed as shown in the table below.
| Action | Objects and Records |
| Create | Up to 200 objects of different types |
| Retrieve | Up to 2,000 records of the same type |
| Update | Up to 200 objects of different types |
| Upsert | Up to 200 objects of the same type |
| Delete | Up to 200 objects of different types |
The sObject Collections resource supports the same headers and the same limits as the SOAP API, and allows for a migration from SOAP API to REST API.
The example below shows the Create action.
The example below shows the Retrieve action.
SOAP API
SOAP API is an older API that is well-suited for older system integrations, integrations that need well-defined interfaces using WSDL, and integrations that are performing operations on 200 or fewer records. Some of the key characteristics of SOAP API are:
- Provides two flavors of WSDL: the Enterprise WSDL and the Partner WSDL:
- The Enterprise WSDL describes SOAP operations for a single org and includes object customizations
- The Partner WSDL describes SOAP operations that are agnostic to org-specific customizations and is better suited for partners building applications that work across multiple orgs (see docs for more details)
- Supports XML data only
- Authenticate with the SOAP login call
- Synchronous
- Allows operations on up to 200 records at a time
While fully supported, SOAP API is no longer being enhanced. We recommend that you use the REST API for all new developments.
Bulk APIs
The Bulk APIs are optimized for ingesting, extracting, or deleting large sets of data. They are best suited when you need to process more than 2,000 records.
The Bulk APIs operate asynchronously, allowing Salesforce to process the request in the background. Due to this asynchronous nature, there is no SLA on how quickly the Bulk APIs will process requests.
There are two Bulk APIs available:
- Bulk API 2.0 is the newer API. It provides a streamlined and easier-to-use workflow, and is the focus for enhancements. Bulk API 2.0 is part of REST API, and the URL root is
https://<my-domain>.my.salesforce.com/services/data/vXX.0/jobs. - The original Bulk API. While fully supported, Bulk API is no longer being enhanced. We recommend that you use Bulk API 2.0 where possible.
Comparing Bulk API 2.0 and Bulk API
The table below summarizes the differences between Bulk API 2.0 and Bulk API. You can find more details on the differences in the documentation.
| Bulk API 2.0 | Bulk API | |
| Authentication | All OAuth 2.0 flows supported by REST API. | SOAP login call. |
| Ingest file handling | Customer submits a single file to ingest; batching handled internally by Salesforce. | Customer must break ingest data into batches and submit each batch individually. |
| Ingest data format | CSV. | CSV, XML, JSON and binary attachment. |
| Ingest processing | Supports only parallel processing. | Supports serial and parallel processing. |
| Query job optimization | Automatically performs Primary Key (PK) chunking when supported by object queried. | PK chunking supported for a smaller, fixed set of objects, and is manually invoked and configured. |
| Query results retrieval | All in a single endpoint. | Iterate through retrieval of individual result sets. |
| Limits | Limits based on number of rows ingested and amount of data queried. | Limits based on number of batches ingested and number of result sets created. |
The blog posts Processing Large Amounts of Data with APIs (Part 1 of 2) and Processing Large Amounts of Data with APIs (Part 2 of 2) describe reading and writing large amounts of data using Bulk API 2.0 and Bulk API.
Apex REST & SOAP
Apex is the native programming language for the Salesforce Platform. You can create Apex classes and expose those classes as REST API resources using Apex REST and as SOAP Web Services using Apex SOAP. This provides you with a custom approach to exposing data in your Salesforce org to external applications. For example, your Apex classes could apply your specific business rules when reading and writing data. To learn more, watch this codeLive session showing how to write Apex REST services.
Salesforce Integration user license
A final consideration for using these Salesforce Platform APIs is which user to use to connect to your org. We recommend that each external application that connects to Salesforce to invoke APIs does so using its own dedicated user. This ensures that each application only has access to the data and operations that it needs and nothing more while providing distinct auditability and traceability of requests from each application.
The Salesforce Integration user license provides a cost-effective approach to integrating each of your applications to Salesforce using a dedicated user. Calling REST APIs, including Bulk API 2.0 and Apex REST, using the Salesforce Integration user license with the OAuth Client Credentials flows is discussed in this blog post.
Postman collection
Now that we’ve reviewed the APIs needed to access data in your Salesforce org, it’s time for you to try them out. Salesforce provides a Postman collection with 200+ request templates for tens of Salesforce APIs. This collection allows you to easily authenticate and try requests to the APIs, so you can experience how each API works. See the blog post Explore the Salesforce APIs with the Upgraded Postman Collection for more information. In addition, see our codeLive session on exploring the Salesforce Platform APIs with Postman.
Conclusion
As highlighted above, the Salesforce Platform provides a breadth of APIs with a broad range of capabilities for accessing data in your org. This blog post has provided an introductory overview of those APIs to help you understand what is available to you and to help you decide which APIs are best suited for your use case. There are links to further information within the post and in the resources below. Finally, see our webinar for further insights into API and integrating with the Salesforce Platform.
Resources
- Trailhead: Platform API Basics
- Blog post: Salesforce Platform APIs Collections for Postman
- Trailhead: Quick Start: Connect Postman to Salesforce
- Knowledge article: Salesforce Platform API Versions 21.0 through 30.0 Retirement
- Developer guide: Generating an OpenAPI 3.0 Document for sObjects REST API (Beta)
- Community groups:
About the author
Jeremy Westerman is a Director of Product Management at Salesforce, where he’s responsible for Salesforce APIs to access data on the core Salesforce Platform. Follow him on LinkedIn and the Trailblazer Community.