June 23, 2017 markhartnady

Salesforce CRM REST API – The most basic recipe

Salesforce CRM REST API – The most basic recipe


Salesforce provides various methods to read, add, delete or update data. The user interface is only one! If you need to connect to Salesforce from external systems to retrieve or modify records in small volumes, the Salesforce REST API web service is by far the easiest to use.

There are many guides on the internet explaining concepts such as the REST protocol, OAuth2, hand-shaking, callbacks, session management, etc, however if your requirements are simple, wading through the text can be somewhat dull. Salesforce’s own documentation is certainly the most comprehensive. Personally, I find it good reading material when I need a sleep aid. If you’re looking for something a bit more straight-forward and to the point, however, read on…

Really, for basic API use, you need to do two things:

  1. Get a new access token
  2. Use this access token in each subsequent API call-out until it expires, in which case see point 1


1x user account on the Salesforce org (sandbox, prod or developer will suffice) including:
* Username
* Password
* Security Token [what’s this?]

1x Security Profile applied to this user that allows create/read/update/delete permissions on the objects you wish to modify
NB: Every API resource request we make will be with this user, so all the operations on the data you modify through your API calls will be logged against this user in audit logs.

Instructions – Setup

    1. Create a Connected App in your target org
    2. To create a connected app, click “Setup” near your name in the top right corner then
    3. In the left-hand navigation bar type “apps” and select the item as shown below:

  1. Scroll to the bottom of the page to the “Connected Apps” section and click “New”
  2. Provide a new name for the Connected App, and a bogus callback URL (any URL will do as we won’t be using it) and save.
  3. Once this is done, a “Client Secret” and “Client Id” will be generated. The client secret is a series of numbers, whereas the client id is a long series of seemingly random UTF-8 characters. You will need to save these details somewhere for now
  4. Once you have created your Connected App, you can start to test connecting to SF via API. To do this, you will need to develop an application using any internet technology/platform capable of connecting to the internet and posting/retrieving data using the HTTPS protocol (e.g. Java, PHP, Apex, etc). However to simplify testing, you may want to use either the “curl” command-line in Unix/Linux (or via Cygwin on Windows) or even simpler, use a REST-based API testing client such as the Google Chrome plugin “Advanced REST client” available for free on the Google Chrome Web Store here. The rest of this recipe will use the Advanced REST Client chrome app for instructions.

Instructions – Getting an Access Token

  1. Let’s start by getting what is called an OAuth2 access token from your Salesforce sandbox. To do this, in the Google Chrome Advanced REST Client “URL” input box, type:

    (for prod, just replace “test” in the URL with “login”)

  2. Select POST as the method and in the “Raw Headers” section type:
    Content-Type: application/x-www-form-urlencoded
  3. In the “Data Form” section, enter your client_id, client_secret, username, password* and a final additional parameter called “grant_type” = “password”
    *PS: The password should be your normal salesforce password + your users security token. E.g. if your password is “myPassword!” and your security token is “61WhVHCHUkBIBGUm4ayC3588” then enter “myPassword!61WhVHCHUkBIBGUm4ayC3588”
  4. Your screen should now look something like this:
  5. Once this detail is provided, hit SEND
  6. In the HTTP response body, you will now have an “access_token” as well as an “instance_url”. You will be using the “instance_url” in all subsequent requests to create/read/update/delete data, and in every request, you will need to provide the access_token in the header. Generally, the access_token will be valid for 2 hours, but this depends on your salesforce settings. The timeout duration can be modified.

Instructions – Using the Access Token to Securely Modify Your Data

  1. Now that you have your instance_url and access_token, we can create some data! Let’s try create a Lead via API. In the “URL” input box within your Google Chrome Advanced REST Client, enter:

    where instance_url = the instance_url you got back from the Access Token request in the previous step. This should be something like “https://cs86.salesforce.com” or “http://yourcustomdomain.cs82.salesforce.com” etc.

  2. In the Raw Headers section, enter the following:
    Content-Type: application/json
    Accept-Type: application/json
    Authorization: Bearer ACCESS_TOKEN

    ACCESS_TOKEN = the access token you got back in the previous step, so it should look something like this:

    Content-Type: application/json
    Accept-Type: application/json
    Authorization: Bearer 3j9ApkCiRpiZNuEfUy7MT7jG1E2wjpjgCeIqDrssp6735vIlOGZn91yRLoZEer
  3. In the “Raw Payload” section enter a JSON payload structure of Lead information such as this:
      "FirstName": "Test",
      "LastName": "Lead",
      "Email": "test@lead.com",
      "Phone": "0123456789",
      "Company" : "Test Company",
      "LeadSource": "Web",
      "Country" : "United Kingdom"

    JSON is a data format standard used by many REST API services. You can read up more on JSON data formats here.

  4. Your screen should now look something like this:
  5. When you are ready, hit SEND. You will now see the result of your request in the Response Body. To test that your lead has successfully been created, log into your target Salesforce org, navigate to the Leads object, and select “Today’s Leads” from the List Views. If everything has worked, your Lead should be at the top of the list!

Hopefully by following the example, you’ve started to piece together the fundamentals of OAuth2 authentication and how Salesforce implements it’s standard out-of-the-box Web Services. Each object has it’s own specific set of URI resources. To get the full list, just do a GET request on https://your_salesforce_instance/services/data/v39.0/ where v39.0 is the version of the API you want to interrogate. Otherwise, continue to explore the incredibly rich but dull catalogue of documentation on the Salesforce support and help websites.

Happy API-ing!

Tagged: , , ,

About the Author

markhartnady Salesforce ninja