6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

Twitter Github Coding Music Newsletter RSS Contact

Ballard Software
Salesforce and Microsoft Software Development

January 5, 2019 by Kyle Ballard | Salesforce

Introduction to the
Salesforce REST API (us-
ing Postman)
This post is going to be a rather lengthy introductory course
on the Salesforce REST API. If you’re just looking for the
Postman collection, or would like to just follow along, click
here. We’ll discuss authentication, basic read operations,
SOQL queries, batch & composite queries, and querying with
an external key. We’ll also touch on the Salesforce
workbench.

In future posts, I’ll discuss creating, updating, and deleting

data with the REST API. I’m also planning posts on the Bulk
API and Streaming API. If you aren’t already familiar with the
Salesforce ecosystem, I’d encourage you to read this post first.
Additionally, you’ll need Postman on your machine to get the
most benefit from this post.

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 1/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

Salesforce Setup

Let’s get started. If you haven’t done so already, you’ll need to

setup a developer account on
https://developer.salesforce.com.

Once you’re logged in, from the gear icon in the top-right,
navigate to Setup. From the ‘Quick Find’ box on the left, type
in “App Manager” and select the menu item with the same
name. On this screen, you’ll see a number of pre-built connec-
tion points. Let’s add our own by selecting “New Connected
App” in the top-right.

Enter the following information and click “Save”:

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 2/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

Connected App Name: Postman Client

API Name: Postman_Client
Contact Email: <enter_your_email_address_here>
Enable OAuth Settings: checked
Callback URL: http://localhost/callback
Selected Oauth Scopes: Access and manage your
data (api)

Once this is setup, you’ll be notified that it takes a few min-

utes for Salesforce to finalize your setup. Make a note of the
“Consumer Key” and “Consumer Secret” that are listed on the
app screen. The final piece of information you need is a secu-
rity token. Navigate to the profile settings (see below) and se-
lect the Reset My Security Token item and follow along with
the instructions to obtain one we’ll use for logging in.

A quick word about security tokens. These are not

needed (and may be preferable to not use for better
security) if you are on a network with a static IP and
https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 3/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

can white-list that address inside the ‘Settings >

Security > Network access’ menu item. If you have
this set you can skip setting the security token for the
rest of the article. You could also just use the token
now, and then change your approach in production. I
am just using this approach to allow everyone to fol-
low along.

Postman Setup

If you haven’t done so already, please import the Postman col-

lection by downloading it here. You can either download and
extract the zip, or copy/paste the raw text. Pressing ctrl+O or
navigating to File > Import in Postman will let you perform ei-
ther to import the collection. When you’re done, it should
look similar to this:

You’ll also need to setup an ‘Environment’ for Salesforce,

which you can see int the top-right of the screenshot above.
You’ll need to set the values for your client-id, client-secret,
and also your username/password. I strongly encourage stor-
https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 4/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

ing these values in the Environment instead of in the Postman

request so they can be shared securely with others. Below is
an example of what your Postman environment for
Salesforce should look like when it’s done.

Be sure you’re also creating the fields for instance-url and ac-
cess-token above even though they are empty. More on this
below.

Authentication

Ok, so with the setup ceremony out of the way, let’s start hav-
ing fun. Below is an example authentication request to
Salesforce. Note this is a POST request, sent x-www-form-ur-
lencoded with a set of key/value pairs which are coming from
https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 5/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

our environment (in the top-right as Salesforce). Also, please

observe how the {{password}} and {{security-token}} fields ap-
pear right next to each other concatenated.

Something we’re also going to review here is the “Tests” tab of

this request. Tests are a fantastic feature in Postman, and they
are worth learning more about. For the sake of this post, we
are just going to use the Test feature to set our environment
variables for {{access-token}} and {{instance-url}}. This is
slick, because now we taken our json response, parsed it, and
stored pieces of the response into our environment and can
reuse that data automatically in our future requests.

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 6/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

API Limits

I think it’s important to make our first ‘real’ request to the

Salesforce API as a request to obtain the ‘limits’ for your ac-
count. API limits are an important concept in Salesforce as
this is a SaaS/multi-tenant environment and you are sharing
resources with other users. Note below, we are using our {{ac-
cess-token}} as stored from our authentication test.

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 7/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

The limits you see here are for a 24-hour period. Our devel-
oper account is limited to 15,000 API requests per day, and we
have 14,999 remaining, having used our first one to inquire
about the limits for our account. A keen eye will also note our
“Postman Client” app we defined earlier, has a limit range but
nothing is set. Apps can have their own API limit quotas po-
tentially as well, and may be something a Salesforce admin
sets for your app.

Limits encourage good software design and should be em-

braced. You’ll want to consider limits and supporting applica-
tion design principals to ensure your application can work
within those limits. One quick note is if you are looking to
modify a large amount of data, take a look at the Bulk API
which I will discuss in a future post.

Basic Queries

The format for single-object queries in Salesforce is typically:

/services/data/<version>/sobjects/<objectType>/<salesforceId>.
An example of this is below. The last part of this query is a
Salesforce Id, which is a 15-character case-sensitive key, and
will never change, even if the record is deleted, then later
undeleted.

For the example below, the record identifier is likely different

for your system, so be sure to head to the Sales app inside
your Salesforce portal and filter the Accounts screen to view
all, and select one from the list. Salesforce always puts the
identifier for the current record in the URL, so you can grab
https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 8/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

one from your instance there. (ex:

https://na85.lightning.force.com/lightning/r/Account/0011U0000
06ee9iQAA/view)

Something you may see in the future, is querying with a cus-

tom object or a custom property. Salesforce differentiates
standard and custom objects with a “__c” postfix on object
types and properties which are not standard. If I had created
a custom object called “MyCustomObject” I would query this
with “/MyCustomObject__c/” in the URL. We’ll see this again
when we talk about querying with external keys later in the
post.

Additionally, when querying an object, you can filter the

fields which are returned. Do you see how appending the
fields querystring parameter allows us to narrow down the
resulting record to just the pieces of information we’d like to
retrieve? The smaller payload here will result in improved

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 9/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

performance over the wire and also faster deserialization

time in our applications.

SOQL Queries

Once you’re comfortable with basic querying in Salesforce, a

good next step is the SOQL query syntax. SOQL is often used
inside the Salesforce ecosystem inside their Apex language
programming paradigm, but we can also leverage it here for
REST calls as well. As you can see (1) the language is very SQL-
like in nature with the one big difference (to me) being joins.

The result set we get back from the query has our results (3)
and also a few interesting fields to note (2). The first is the to-
talSize and done parameters. If the value for done is false, you
will also see a top-level property called nextRecordsUrl that
will look like: /services/data/v44.0/query/01g2100000PeqVoAAJ-
https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 10/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

2000/ (yours will be slightly different). You would then take

this URL and use it to retrieve records 2001 – 4000 by re-run-
ning this request with the new URL and applying your same
SOQL query to the end of this nextRecordsUrl parameter.

Querying with an External Key

Most often when you are using the Salesforce REST API, you
are doing so to connect it to an external business system
which has it’s own record identifiers/keys. Salesforce under-
stands this notion, and allows you to create properties on
your objects which are of type “External Id”.

To setup one of these fields, navigation to Setup (1) > Object

Manager (2) > Select your relevant record type, Lead in this

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 11/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

case (3) > Fields & Relationships (4) and then add a new
record of type text (5) as the type of parameter for your key.

On the following screen specify a name for your field, and an

API/Field name will be auto-generated for you (1). Note that
anything which is a custom field or custom object type in
Salesforce will always be referenced with “__c” at the end of
it. So in a bit, we’ll see how this field “External_Id” actually
maps to “External_Id__c” in the API. Finally, the checkbox at
the end (2) indicates that this field is a unique identifier for a
record in an external system.

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 12/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

Now that we have our External Id field setup, we can perform

queries against it. You can also use this to update records as
well which I’ll talk about in the future, including how to refer-
ence parent/child records using the external id on each (i.e.
Accounts + Contacts). See how instead of using the Salesforce
Id in the request, we’ve included the External_Id__c property
in the URL and then referenced the record which has a value
in this field of 21456.

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 13/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

Batch & Composite Queries

Salesforce offers two ways to execute multiple ‘requests’,

which they refer to as subrequests, via a single API request in
the form of batch queries & composite queries.

Let’s start with batch queries as shown in the screenshot be-

low. In our payload (1), you’ll see we can provide multiple
subrequests in an array. The batch query format supports up
to 25 subrequests per API request, and each subrequest exe-
cutes independently. Each subrequest also counts against our
API limit noted earlier. The advantage here is we reduce our
round-trip processing time and improve the speed of our
applications.

In our response we can see any errors were returned (2) and
the status code for each independent subrequest/response (3)
https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 14/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

along with the payload that would be returned. The batch API
can also be used to perform PATCH, POST, and DELETE to
modify your Salesforce data, which I’ll discuss in the future.

Composite queries are similar to batch queries, but different

in a few key ways. First, the individual component subre-
quests do not count against your API limits. Second, the sub-
requests are executed in order.

Also, note how the response object from a prior query (1) can
later be referenced in a subsequent query (2) in the chain.
Each response from a composite query is wrapped in a body
object (3). Similar to the batch API, you can also use this to
create, update, and delete records instead of just querying it.

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 15/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

Salesforce Workbench

There is a great utility application available at:

https://workbench.developerforce.com/. This portal allows to
you do the same operations we described above when proto-
typing your applications with Postman. Not only do you gain
access the REST API in a nice visual interface, but you can
also test SOQL queries, subscribe to Push Topics (to be noti-
fied when data changes in Salesforce), view standard and cus-
tom object metadata, and more.

Below is an example of the “REST Explorer” in the work-

bench, available by going to Utilities > Rest Explorer after log-
ging in. You can click through each of these endpoints and see
everything Salesforce exposes via the API.

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 16/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

Final Thoughts

Salesforce provides developers with a well designed, properly

versioned, full-featured API to use to connect your applica-
tions to their ecosystem. There are multiple ways to read as
well as modify data inside the Salesforce system that allow
you to work in a performant and responsible way that allows
all users of the platform to maintain similar performance in
their requests as well. If you enjoyed this post, I’d love to hear
how it helped you. You can find me on Twitter and Github.
Also, I’d love if you subscribe to my semi-regular newsletter
of fun things I’ve found online.

Kyle Ballard

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 17/18
6/12/23, 7:47 PM Introduction to the Salesforce REST API (using Postman) - Ballard Software

← Understanding OAuth 2.0 Web Server Flow •In Salesforce

Statically Typed Newsletter: Volume 1 →

Casper WP by Lacy Morrow

https://ballardsoftware.com/introduction-to-the-salesforce-rest-api-using-postman/ 18/18