Salesforce is a CRM that helps businesses manage the relationships and interactions with their customers and potential customers. Using their website users can track leads, manage contracts, and do other tasks. Most organizations will have an existing application where all their data will reside. This means that the user needs to spend hours handling things in two different systems and manually keep updating them. Using the salesforce APIs the user can send and receive the data from salesforce programmatically without user input. This will save hours of the user’s time. Salesforce has a big developer ecosystem, including its own Stackoverflow forum. You can read more about what salesforce is through this link.

Recently for one of our clients, we needed to integrate salesforce. The requirement was we need to programmatically send leads that are present in our system to a client’s salesforce account. In Salesforce, leads are people who are interested in your product and service. In this tutorial, we will learn how to programmatically send/create leads in salesforce. 

Prerequisites:

Before proceeding with this tutorial, you should have a basic understanding of Salesforce and OAuth. You can use postman, or curl to hit the salesforce APIs.

1. Create a free developer account

Let’s start by creating a free developer account in salesforce. Once you have your account set up they will create a sandbox environment with a unique sub-domain. With a salesforce developer account, you can freely access all the REST APIs that Salesforce provides.

2. Set up a Connected App

The next step is to create a connected app. Connected apps have a lot of features. To make this tutorial simple as possible let’s just assume that a connected app is an app that is created in salesforce through which we can interact with salesforce. It is also used for authentication.

After you log in to your salesforce developer account you should be able to see a setup icon on the top right corner of the screen. Click to open the setup screen. In the search box to the left, search for App Manager.

Click on the New Connected App button. In the next screen under the Basic Information section enter the following details:

• You can give the Connected App Name as MyApp.
• Once you give the app name it should automatically fill the API name with MyApp.
• Enter your email under Contact Email.

Under the API section

• Make sure Enable OAuth Settings checkbox is checked.
• Enter your desired callback URL. It should be a valid URL like https://localhost:3000/callback. It absolutely needs security so it won’t work over HTTP it needs HTTPS
• Under Selected OAuth Scopes select Access and manage your data (API), and Perform requests on your behalf at any time (refresh_token, offline_access)

Access and manage your data (API): This permission will allow access to Salesforce REST APIs

Perform requests on your behalf at any time (refresh_token, offline_access): This permission will give us access to the refresh token through which we can generate the access token

Click on the save button to create the connected app. It will take around 10 minutes to create the connected app.

Once the app is ready, click on the Manage Consumer Details button.

It should redirect you to a screen where you can get the Consumer Key and Consumer Secret for your connected app.

3. Salesforce OAuth data flow

Salesforce gives access to their APIs via OAuth. The following are the steps involved in 

1. From your client application redirect the user to Salesforce (we will see how to prepare the redirect URL shortly)
2. Salesforce will prompt the user to log in.
3. After the user has logged in, Salesforce will ask for the user’s consent. This screen will show the user the permissions that we selected when we created the Connected app in the previous step.
4. Once the user has given her consent, it will redirect them back to the URL that we configured in the previous step with the authorization code.
5. Using the authorization code we can generate the access token and the refresh token.
6. We can then use the access token to call the Salesforce REST APIs.

We need to append the access token to every API request that we make. The access token expires every 15 minutes.

You can use the refresh token to generate the access token. The expiry settings can be configured so that the refresh token never expires. It will expire after we revoke it.

4. Exploring Salesforce APIs with an example:

Build the Salesforce OAuth URL:

Let’s build the initial URL through which we can request the user to grant access to their Salesforce data for our app. We need to pass the following

1. Consumer Key as client_id (We obtained the Consumer Key after creating the Connected App from the previous step),
2. response_type as code, and 
3. redirect_uri — This should be the same URL that we configured in the Connected APP. In this case, it is https://localhost:3000/callback.

The URL should look something like the below:

https://login.salesforce.com/services/oauth2/authorize?response_type=code
&client_id=YOURCONSUMERID&redirect_uri=https://localhost:3000/callback

You run the above in your browser. If the request is successful Salesforce should redirect you to the following:

After you give the consent it should send you to the redirect URL with the authorization code. It will look something like the below:

Convert authorization code to refresh token and access token:

Once you have the authorization code you can call Salesforce’s token endpoint to retrieve your access and refresh tokens.

We need to pass the client id, client secret, and the other configurations as shown below. The endpoint will look something link below:

You can read more about this endpoint from their documentation. The response from the above API will look something like this:

{
    "access_token": "<access_token>",
    "refresh_token": "<refresh_token>",
    "signature": "<signature>",
    "scope": "refresh_token api",
    "instance_url": "https://testiong.my.salesforce.com",
    "id": "https://login.salesforce.com/id/",
    "token_type": "Bearer",
    "issued_at": "1683462963255"
}

Here along with the access and refresh tokens, we also get the instance_url. We need to use this as the baseUrl to make API calls to get or send the data to the client’s account.

Using the access token we can start making API calls. Since the access token expires quickly we need to use the refresh token to keep generating the access token.

Generate access token using the refresh token:

We can use the same endpoint with grant_type as refresh_token to generate the access token as shown below:

This will return a following response

{
    "access_token": "<access_token>",
    "signature": "<signature>",
    "scope": "refresh_token api",
    "instance_url": "https://testing.my.salesforce.com",
    "id": "https://login.salesforce.com/id/",
    "token_type": "Bearer",
    "issued_at": "1683462963255"
}

5. Salesforce Object

Salesforce objects (sobjects) are like tables in a database that holds an organization’s data. Some examples of Salesforce objects are Leads, Accounts, and Tasks. We can create our own custom objects as well.

Sending a Lead to Salesforce:

In this example, we are going to create a record in the Lead object. The following is a POST API

POST https://INSTANCE.salesforce.com/services/data/v54.0/sobjects/Lead

The header should have the access token:

Authorization: Bearer 00D2w00000NHcu4...

The request body should have the following structure:

{
    "firstName": "testing",
    "lastName": "testing",
    "phone": "0123436791",
    "email": "testing@jpmc.com",
    "company": "Salesforce"
}

A successful API will return the following response:

{
    "id": "<id>",
    "success": true,
    "errors": []
}

Retrieving data from Salesforce

Salesforce has APIs that describe the fields available in a Salesforce Object. In the following example, we are retrieving the structure of the Lead object.

Remember to pass the access token in the header

Authorization: Bearer 00D2w00000NHcu4...

Further steps:

The following are some points that can help you with further integration

• You cannot use the Connected App that is created in one developer account to be used by another developer account.
• REST APIs will only work for clients who have an Enterprise account or a Professional account with the API add on
• When doing the Oauth connection it is recommended to use the Salesforce account of a system administrator
• You can configure the required fields for each sobject used in your Salesforce account.
• Some of the error messages that you get from Salesforce will be inconsistent when you make a mistake while calling the API. Keep an open mind.
• The way to determine the required fields for a sobject is not straightforward. There won’t be a single field that tells us that a field is required. The best way to determine if a field is required is by checking whether the field accepts null or not.