{"id":1676,"date":"2018-06-06T11:52:50","date_gmt":"2018-06-06T11:52:50","guid":{"rendered":"https:\/\/gosqeng.test\/?p=1676"},"modified":"2022-07-20T18:48:48","modified_gmt":"2022-07-20T18:48:48","slug":"salesforce-rest-api-integration","status":"publish","type":"post","link":"https:\/\/www.gosquared.com\/blog\/salesforce-rest-api-integration","title":{"rendered":"How to build a basic Salesforce REST API Integration"},"content":{"rendered":"

\"Building<\/p>\n

Want to know How to build a basic Salesforce REST API Integration? In today’s post, GoSquared’s<\/a> Sales Engineer Russell Vaughan will show you how.<\/p>\n

Being in the Software as a Service space, you have to admire what Salesforce has managed to accomplish. It would be hard to argue their success, particularly at the enterprise customer level.<\/p>\n

While they have one of the most tuned and well-known sales approaches in software, there is almost a feeling that when a company gets to a certain size, they just decide it\u2019s time to use Salesforce. It\u2019s due to this that if you have a product that operates in the Sales and Marketing space, there is huge opportunity in tapping into the Salesforce community and ecosystem.<\/p>\n

For example, we\u2019ve built the GoSquared Salesforce integration<\/a> to capture the on-site behaviour of leads when they\u2019re browsing your website (E.g. when a lead views your pricing page or watches a webinar), and send this directly into Salesforce ready for your sales team to act on within their existing workflow.<\/p>\n

Digging into the Salesforce developer ecosystem<\/h2>\n

With a company that has the breadth and depth of product that Salesforce offers, there will always be pros and cons to getting your head around their documentation and terminology.<\/p>\n

They have an incredible developer community, including their own Stackoverflow-esque forums. If you hit a road block, it\u2019s likely someone\u2019s hit it before you and you can find a documented solution.<\/p>\n

Similarly they have an extremely robust e-learning platform with tracks that you can complete across a plethora of different subjects to get up to speed on a lot of their terminology and principals.<\/p>\n

There can, however, be an abundance of content to sift through and it can be an incredibly time consuming process \u2013 particularly if building and developing on the Salesforce Platform is not going to be the core responsibility of your job!<\/p>\n

This blog post is really focused around communicating, at a very basic level, the key concepts needed to build a basic Salesforce REST API integration.<\/p>\n

Salesforce REST API Integration vs Salesforce App<\/h2>\n

It\u2019s important to highlight the difference between a Salesforce REST API integration and a Salesforce app that you\u2019d find on their AppExchange (essentially the Salesforce App Store.)<\/p>\n

Listing an app within the Salesforce AppExchange will give you the ability to build your product directly into the Salesforce platform. For example, visualising your product\u2019s data directly within a component in Salesforce. While there are clear benefits in having a presence within this ecosystem it\u2019s important to note that there are some costs associated with doing so.<\/p>\n

A REST API integration is a lot simpler and is primarily focused around sending data from your application and fetching data from Salesforce. Currently there is no cost associated with this type of integration however it’s worth noting that REST integrations are only accessible to Salesforce users on their enterprise plans (there is scope to get REST API access on Professional and Group editions but involves getting your app whitelisted.)<\/p>\n

For the purposes of this post, our example REST API integration is going to be super basic. Our app is going to have customer data that we want to send to Salesforce and there will be customer data in Salesforce that we want to retrieve.<\/p>\n

Essentially then, our REST API integration is going to need to do 3 critical things:<\/p>\n

    \n
  1. Allow a user of our application to authorise us to access and transfer their Salesforce data on their behalf.<\/li>\n
  2. Allow a user to push data from our application to Salesforce.<\/li>\n
  3. Allow a user to retrieve Salesforce data to be used within our app.<\/li>\n<\/ol>\n

    Getting set up with Salesforce<\/h2>\n

    Create a free developer account<\/h3>\n

    Start by getting yourself a free Salesforce Developer account<\/a>.<\/p>\n

    The Salesforce developer accounts are awesome and pretty much give you a working Salesforce organisation (an organisation is Salesforce\u2019s terminology for an account) so you can get a feel for the interface and even add and manage users.<\/p>\n

    Set up a Connected App<\/h3>\n

    Once you have your developer account set up you\u2019ll want to set up a Connected App<\/strong>. Connected Apps have the ability to offer a lot of functionality and sometimes that can make it a bit difficult to get your head around them.<\/p>\n

    For the purposes of this and how we\u2019re going to use it, it\u2019s easiest to think of a connected app as a small app that sits on Salesforce\u2019s infrastructure that you point your integration to. It is responsible for managing the authentication and also the routing of requests to the relevant client instances.<\/p>\n

    Once you\u2019ve set up your Salesforce developer account, you can set up a connected app by clicking the Setup<\/strong> icon in the top-right navigation menu and select Setup<\/strong>.<\/p>\n

    Enter App Manager<\/strong> in the Quick Find<\/strong> box and then select App Manager<\/strong>.<\/p>\n

    \"Screenshot<\/p>\n

    1. Click New Connected App<\/strong>.<\/p>\n

    2. In the New Connected App form, fill in:<\/p>\n

    In the Basic Information<\/strong> section:<\/p>\n

      \n
    1. Connect App Name: YourAppName.<\/li>\n
    2. API Name: this will automatically become \u2018YourAppName\u2019.<\/li>\n
    3. Contact Email: enter your email address.<\/li>\n<\/ol>\n

      In the API (Enable OAuth Settings)<\/strong> section:<\/p>\n

        \n
      1. Check Enable OAuth Settings.<\/li>\n
      2. Callback URL: enter your callback url, example: https:\/\/www.yourappname.com\/api\/callback<\/li>\n<\/ol>\n

        This will be the URL which Salesforce POSTs to when the user has authorised your app to access their data. This will include the access and request token<\/strong> (we\u2019ll explain a bit more on this below but they are essential to be able to send and receive data.) So if you don\u2019t have one already, you\u2019ll need to set up an endpoint who\u2019s role it is to receive and handle this request.<\/p>\n

        Under Selected OAuth Scopes<\/strong>:<\/p>\n

          \n
        1. Select Access and manage your data (API)<\/strong>.<\/li>\n
        2. Click Add<\/strong>.<\/li>\n<\/ol>\n

          Once you\u2019ve set up your app, you\u2019ll be given a Consumer Key<\/strong> and a Consumer Secret<\/strong> for you app.<\/p>\n

          The basic Salesforce Oauth data flow<\/h2>\n

          \"Salesforce<\/p>\n

          With the connected app set up, its handy to get an idea of how the data flow works.<\/p>\n

          To start, your user is directed to a Saleforce.com authorisation endpoint, there they log in and approve access for your app to access their data.<\/p>\n

          After a successful authorisation Salesforce sends a response with an Access token<\/strong> and Refresh token<\/strong>.<\/p>\n

          The Access token<\/strong> is to be passed in the header of all API requests for data. This token has an expiry date and will always expire. By default the Connected Apps have an access token with an expiry of 15 minutes (inline with the sessions settings within your Salesforce settings).<\/p>\n

          The Refresh token<\/strong> is to be used to retrieve a valid access token (e.g. when the current access token expires). You can change the expiry settings on this but you can also set this never to expire, only when it revoked.<\/p>\n

          Example API calls:<\/h3>\n

          To make the initial authorisation request for a user to grant your app access to their data (this is where your user is initially directed to a Saleforce.com authorisation endpoint and logs in) you\u2019d make the following request. The client_id<\/strong> in the below call will be your consumer ID<\/strong> from the connected app. The redirect_uri<\/strong> will be the Callback URL<\/strong>.<\/p>\n

          \ncurl https:\/\/login.salesforce.com\/services\/oauth2\/authorize?response_type=code\n&client_id=YOURCONSUMERID&redirect_uri=https:\/\/www.yourappname.com\/api\/callback\n<\/code><\/pre>\n
          A successful response from this will redirect the page to a Salesforce login page where the user is able to login and authenticate. After Salesforce confirms that the client has authorised your app to access their data, the end-user\u2019s browser is redirected to the callback URL you\u2019ve specified by the redirect_uri parameter. Salesforce then appends an authorisation code<\/strong> to the redirect URL, their request will look similar to the below.<\/p>\n
          \nhttps:\/\/www.yourappname.com\/api\/callback?code=aWekysIEeqM9PiThEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D\n<\/code><\/pre>\n
          You\u2019ll use this as the value for your code<\/strong> parameter when you make a request to Salesforce\u2019s token endpoint to receive your Access and Refresh Token<\/strong>.<\/p>\n
          Example request:<\/h3>\n
          \ncurl login.salesforce.com\/services\/oauth2\/token?grant_type=authorization_code&redirect_uri=https:\/\/www.yourappname.com\/api\/callback&client_id=YOUR_CONSUMER_ID&client_secret=YOUR_CONSUMER_SECRET&code=aWekysIEeqM9PiThEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D\n<\/code><\/pre>\n
          Example Response:<\/h3>\n
          \n{\n  \"access_token\": \"YOUR_ACCESS_TOKEN\",\n  \"refresh_token\": \"YOUR_REFRESH_TOKEN\",\n  \"signature\": \"signature\",\n  \"scope\": \"refresh_token api id\",\n  \"instance_url\": \"https:\/\/instance.salesforce.com\",\n  \"id\": \"https:\/\/login.salesforce.com\/id\/id,\n  \"token_type\": \"Bearer\",\n  \"issued_at\": \"timestamp\"\n}\n<\/code><\/pre>\n
          Outside of the access and response token, the instance_url is import also. It\u2019s what you\u2019ll need to build the base of your future API calls.<\/p>\n
          Now we have the access token, we\u2019re able to start making requests to send and receive data on our users behalf. Something to keep in mind though, as mentioned earlier, is that these access tokens will always expire at some point.<\/p>\n
          Due to that, you\u2019ll want to keep your access token up to date by making a call to the token endpoint and changing the grant_type to \u2018refresh_token<\/strong>\u2019 along with including the refresh token you had received in the previous call.<\/p>\n
          Example call:<\/h3>\n
          \ncurl https:\/\/login.salesforce.com\/services\/oauth2\/token?grant_type=refresh_token&client_id=YOUR_CONSUMER__ID&client_secret=YOUR_CONSUMER__SECRET&refresh_token=YOUR_REFRESH_TOKEN\n<\/code><\/pre>\n
          Example response:<\/h3>\n
          \n{\n  \"access_token\": \"REFRESHED_ACCESS_TOKEN\",\n  \"signature\": \"signature\",\n  \"scope\": \"refresh_token id api\",\n  \"instance_url\": \"https:\/\/INSTANCE.salesforce.com\",\n  \"id\": \"https:\/\/login.salesforce.com\/id\/idE\",\n  \"token_type\": \"Bearer\",\n  \"issued_at\": \"timestamp\"\n}\n<\/code><\/pre>\n
          Now we have a way to keep our access tokens valid and up to date, we\u2019re set up and ready to start working with Salesforce objects.<\/p>\n
          Understanding Salesforce objects<\/h2>\n
          Salesforce objects<\/strong> (sobjects) are effectively database tables that contain an organisation’s data. Examples of standard Salesforce objects will be \u201cAccounts\u201d, \u201cContacts\u201d, \u201cLeads\u201d, and \u201cTasks.\u201d You also have scope to create your own custom objects.<\/p>\n
          A Salesforce record<\/strong> describes a specific occurrence of an object (such as a specific contact like \u201cJonny Appleseed\u201d that is represented by a Contact object). A basic comparison would be like a row in a database table.<\/p>\n
          For the following examples, we\u2019re just going to focus on Contacts.<\/p>\n
          Send data from your app to Salesforce<\/h2>\n
          Creating a contact in salesforce is really straightforward. You just need to build the API url using the instance from your access token response and use the access token value as your bearer token in the header.<\/p>\n
          One thing to keep an eye out for through is for characters that need to be escaped in your access token.<\/p>\n
          For example this access token should have the exclamation mark escaped<\/p>\n
          So this:<\/p>\n
          \n00D1r000000dumU!AQEAQFd.O1Q5DVQrUYvr.........\n<\/code><\/pre>\n
          Becomes this:<\/p>\n
          \n00D1r000000dumU\\!AQEAQFd.O1Q5DVQrUYvr........\n<\/code><\/pre>\n
          you can then make the below call to create a contact.<\/p>\n
          Example request<\/h3>\n
          \ncurl https:\/\/INSTANCE.salesforce.com\/services\/data\/v42.0\/sobjects\/Contact -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" -H \"Content-Type: application\/json\" -d '{\"FirstName\" : \"Johnny\", \"LastName\" : \"Appleseed\"}'\n<\/code><\/pre>\n
          (Your contact will need a last name as the minimum for an entry to be created.)<\/p>\n
          The response you get back will be the id of your contact<\/p>\n
          \n{\"id\":\"0031r000029NDckAAG\",\"success\":true,\"errors\":[]}\n<\/code><\/pre>\n
          Which will also let you build a link directly to the contact.<\/p>\n
          \nhttps:\/\/INSTANCE.salesforce.com\/0031r000029NDckAAG\n<\/code><\/pre>\n
          Retrieving data from Salesforce to your app<\/h2>\n
          If you want to retrieve a list of contacts there are a few ways you can do it. You can make a request to the contact endpoint and it will return a bunch of information about your contacts that I found a bit cumbersome to navigate.<\/p>\n
          I actually prefer to use a combination a contacts \u2018describe\u2019 endpoint, which will return all of the fields we can populate about our user.<\/p>\n
          Example request:<\/p>\n
          \ncurl https:\/\/INSTANCE.salesforce.com\/services\/data\/v20.0\/sobjects\/Contact\/describe -H  \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n<\/code><\/pre>\n
          That will give a detailed response of all of the fields available. (I\u2019ve just given an example of the \u2018first name\u2019 element for brevity)<\/p>\n
          \n{\n      \"autoNumber\": false,\n      \"byteLength\": 120,\n      \"calculated\": false,\n      \"calculatedFormula\": null,\n      \"caseSensitive\": false,\n      \"controllerName\": null,\n      \"createable\": true,\n      \"custom\": false,\n      \"defaultValue\": null,\n      \"defaultValueFormula\": null,\n      \"defaultedOnCreate\": false,\n      \"dependentPicklist\": false,\n      \"deprecatedAndHidden\": false,\n      \"digits\": 0,\n      \"externalId\": false,\n      \"filterable\": true,\n      \"groupable\": true,\n      \"htmlFormatted\": false,\n      \"idLookup\": false,\n      \"inlineHelpText\": null,\n      \"label\": \"First Name\",\n      \"length\": 40,\n      \"name\": \"FirstName\",\n      \"nameField\": false,\n      \"namePointing\": false,\n      \"nillable\": true,\n      \"picklistValues\": [],\n      \"precision\": 0,\n      \"referenceTo\": [],\n      \"relationshipName\": null,\n      \"relationshipOrder\": null,\n      \"restrictedPicklist\": false,\n      \"scale\": 0,\n      \"soapType\": \"xsd:string\",\n      \"sortable\": true,\n      \"type\": \"string\",\n      \"unique\": false,\n      \"updateable\": true,\n      \"writeRequiresMasterRead\": false\n    }\n<\/code><\/pre>\n
          Once you\u2019ve got the fields you can then use them (or a selection) to build a custom query:<\/p>\n
          \ncurl https:\/\/INstance.salesforce.com\/services\/data\/v42.0\/query\/?q=SELECT+id,name,email,phone+from+Contact -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n<\/code><\/pre>\n
          That will return all contacts with their associated properties.<\/p>\n
          \n{\"totalSize\":1,\"done\":true,\"records\":[{\"attributes\":{\"type\":\"Contact\",\"url\":\"\/services\/data\/v42.0\/sobjects\/Contact\/id\"},\"Id\":\"id\",\"Name\":\"Jonny Appleseed\",\"Email\":\"jonny.appleseed@myfriend.com\",\"Phone\":\"555-555-555\"} ]}\n<\/code><\/pre>\n
          That should now give you a way to retrieve contact data from Salesforce to use within your app.<\/p>\n
          Further resources<\/h2>\n
          Hopefully that gives a good enough foundation to start exploring more of the Salesforce objects you can interact with through a REST API integration. Here are some additional resources to more in-depth information about the Salesforce REST endpoints.<\/p>\n