PRO TIPS

Integration with Salesforce Using Flow & HTTP Callout

A headshot for Jay Mehta, Prolocity's PROserve Essential lead

Jay Mehta
PROserve Essentials Lead

So far, we've looked at integrations based on manual uploads, AppExchange packages, and Zapier. While those are all viable integration strategies, it's still possible that you will want to integrate data from a system that doesn't support any of these patterns. But if that system offers its own Application Programming Interface (API), it may be possible to use HTTP Callouts in Flow to build the integration without having to write any custom code.

What's an HTTP Callout?

Basically, an HTTP Callout is a request that either pulls data from or pushes data to an external system. Take, for example, using a web browser. Whenever you load a page, you're really sending a request to the server for data, and the server is returning it–in that example, a collection of HTML, images, style information, and JavaScript code. In HTTP terms, the browser is sending a bunch of GET requests, and server is responding with the relevant files.

Using HTTP Callout does something very similar, except it is designed to send requests that return structured data in a way that Salesforce can decode. Usually, that data is in either XML or JavaScript Object Notation (JSON) format.

Behind the scenes, Zapier does the same thing, but its user interface hides a lot of the complexities. But Zapier's biggest drawback is that its integrations have to be built by developers–not every service has a Zapier integration, and even if they do, not every feature that is available in that service will be exposed via Zapier. In theory, HTTP Callout enables you to connect to those services, and to access functions that aren't exposed via Zapier, assuming you understand how to translate the developer documentation into a working callout.

Ok, that's the theory which, admittedly, is a bit abstract. Let's look at a practical example of something our non-profit clients often need to do that Zapier can't help them with–verifying household incomes against the Federal Poverty Limits calculated by the US Department of Health & Human Services.

An overview of API Requests

HHS publishes documentation for its API. It's a single page, but after reading it we'll have all the information we need to build our callout.

The request we send will look like a plain URL, containing the year we're interested in and the state (since poverty limits can vary state by state). We can optionally include the household size as well, if the household is bigger than a single person. Making a request for a two person household looks something like this:

https://aspe.hhs.gov/topics/poverty-economic-mobility/poverty-guidelines/api/2024/us/2

If you copy that link into a new browser tab and hit the enter key, you'll see what the server's response is; it's a text string:

{"data":{"year":"2024","household_size":"2","income":"20440","state":"us"},"method":"GET","status":200}

This is a format called JSON–JavaScript Object Notation. Let's break down the components:

Method: HTTP uses verbs to define the type of request being made. These are standard across all web apps, and Salesforce now supports all of the standard methods like GET, POST, PATCH, and DELETE. As you examine documentation for APIs, you'll see that they require using one of them for your requests. In this case, GET is used to pull data from an external system, so that's the one we used.

Status: Every HTTP request gets a status code, which tells you how the server handled it. Have you ever seen a 404 error when the server couldn't find a page you asked for? That's an error status code. 200 is the universal HTTP code for a successful operation, and what we got here.

Data: this is the meat of the API response and contains the data we need. The year, household size, and income limits are what we're interested in processing. Note that each API may pass this back differently, so it may not always be labeled as "data," but there will be fields provided somewhere in the response that contain your data.

Another thing to know about accessing a system via API is whether there's any authentication required. This often takes the form of a key or secret. But in this case, we were able to simply make a request via the web browser, we know no authentication is required.

So, to recap, we know the URL to access, the parameters we need to pass over (the year, household size, and location), and that we have no need to authenticate the request. That's all we need to build our callout (or any callout, basically!). So we'll now move to Salesforce and do three basic things:

  1. Set up authentication
  2. Set up a named credential that identifies the external URL
  3. Build the callout and execute it in Flow

Setting up Authentication

Some APIs require authentication in order to access. This helps control access, limit usage to reasonable amounts, and/or lets the provider record usage for billing purposes. But not every API needs authentication; some are provided wholly free of charge with no specific limits. The FPL limit API is one of those.

Even though we don't need to set up an account or a username or password, we do need to tell Salesforce that this API requires no authentication as the first step. To do that, we'll set up an External Credential.

  1. Start by visiting Setup, and selecting Named Credentials
  2. Click the External Credentials tab
  3. Click New
  4. Give the credential a Label (which can have spaces and special characters) and a Name (which can only contain letters and numbers, no spaces or punctuation other than an underscore)
  5. From the drop-down menu, select No Authentication
  6. Click Save

Note that if you're using multiple APIs that have no authentication requirements, you can use this single External Credential for all of them, no need to create multiple ones (although also, no harm in creating multiple ones). Now that we have authentications set up, we can move on to defining the connection to the API, which is set up in a Named Credential.

Setting up a Named Credential

A Named Credential defines the URL of the external service, tied to an authentication mechanism, and then allows it to be used in a Callout. Setting up a Named Credential happens in the same place as the External Credential, because they're inextricably linked. So, you can continue right where you left off from the prior steps:

  1. Click the Named Credential tab
  2. Give the credential a Label (which can have spaces and special characters) and a Name (which can only contain letters and numbers, no spaces or punctuation other than an underscore).
  3. Enter the URL for the API you're calling. For most APIs, this is the base website URL; so in this example, we'll make it: https://aspe.hhs.gov
  4. Make sure Enabled for Callouts is checked.
  5. Select the External Credential you just created under External Credential.
  6. Click Save

Now that we've set up a named credential, we can start building our Flow and set up the callout.

Setting up the HTTP Callout inside a Flow

Here's where we'll go cooking show style–I won't show all the user interface elements logic that we're going to use (although we'll cover it quickly in a bonus video). Instead we'll focus on how to set up the callout. That's what's going to let you actually request data from HHS. To do that, you should start building a Flow–in this case a Screen Flow will work best:

  1. Insert an Action element into your Flow.
  2. At the bottom left of the Action window, click Create HTTP Callout
  3. Give the callout a name.
  4. Select the Named Credential you just created. You should see the URL you set appear to help you confirm you got the correct one.
  5. Click Next
  6. Give the request a name
  7. Select a Method for your request. This is defined by the documentation for the API you're using, as described above. For the FPL API, we'll use GET.
  8. Set the URL path; this is everything in the URL beyond the base website address. It must begin with a forward slash. Patterning it on the URL example at the top, we'll enter /topics/poverty-economic-mobility/poverty-guidelines/api/2024/US/2

But wait, you might be thinking. What if I want to request data for a year other than 2024, a household larger than two members, or for the non-Continental US (Alaska or Hawaii)? Hard-coding those values into this Callout wouldn't allow that. So, we'll fix that by replacing those with path variables that let us insert an arbitrary year or state when we perform the Callout.

Salesforce shows you how to define a path variable; it's a specially formatted section of the URL path that's wrapped in curly braces. So, in the URL path, we'll replace "2024" with {year}, the "US" with {location}, and the 2 with {hhsize}. After you've done that and clicked out of the URL Path field, you'll see three new entries appear for the path variables you just created. You can put in an optional description to help yourself remember what these variables represent–these will show in the Flow editor when the action is added.

You also have to define the type of data each variable is. The location is pretty easy; that's a text value, which Salesforce refers to as a string. A year can actually be either a number (integer) or a string, because the API doesn't care either way. It might make sense to make it an integer so that you can validate user data entry (i.e. make sure they put in a valid year that isn't way in the future). And HH Size is also an integer, because the API won't accept decimals.

Before you can hit Save, there's one last thing to do; you have to either provide a sample response so that Salesforce understands how to parse the data that the service will hand back, or test the connection live to grab sample data. If you choose the former, all you need is the sample response further up the page. Simply click the New button, and paste that string of JSON into the left hand side of the pane. Click Review, and you'll see Salesforce break the response into individual variables, which it will again ask you to define the data types for.

If you chose the Connect for Schema option, you will likely encounter an error that tells you the callout may not exist. This is a common permissions error–check the setup video below at the nine minute mark for details on how to solve it.

You can accept the mappings Salesforce enters for you. When you're done, click save. You'll go back to the Action element definition (remember when we started there a few minutes ago?). Now, you'll have the option to insert a year, location, and household size before clicking Done.

Congrats, you've defined a Callout! If you debug your Flow, you should see the callout be performed, and data returned. Once you've got that data, you can use business logic in your Flow to use it (for instance, to determine if a Contact's income is over the limit the API returns).

Next Steps

We've been able to build an HTTP Callout that grabs data that we couldn't have brought into Salesforce in another way–all without writing any code.

HTTP Callouts are great for experienced admins, but even they have their limits. You may have gotten an idea from the setup of some of them. First off, the configuration provides the options that you have, but some APIs require more sophisticated options (such as encoding requests). If those are required, callouts likely aren't an option, and custom code may be your only choice.

Another consideration with HTTP Callout is Salesforce platform limits; while the limits that affect HTTP Callout and custom code are broadly similar, custom code gives you the option to adjust the default limits in ways you can't in Flow. So again, in some circumstances, Flow may not be an option while custom code can be.