Outreach is a leading Sales Engagement Platform, helping sales teams to drive more revenue by improving productivity, effectiveness, and efficiency. Building a customer-facing Outreach integration can unlock interesting use cases like automatically enrolling your customer’s leads into sequences, customizing your customer’s email sequences, and building analytics on email data.

Building an Outreach integration can be a challenging process due to its complex API and authentication process. Fortunately, we’ve already gone through the headache of building and maintaining a complex native Outreach integration and have distilled all of the wisdom and gotchas we’ve picked up over the years into this guide.

If you’re unfamiliar with what native integrations are in the first place, you can reference our previous blog post aptly titled what are native integrations?

As a side note, I’ll be using the Vessel SDK to build this integration so I don’t have to worry about setting up Auth or handling any Outreach API quirks.

If you don’t want to use Vessel, no worries, I’ve kept this guide as generic as possible and it will be useful regardless of how you decide to build your native Outreach integration.

Getting Setup For your Outreach Integration

Before you dive into writing code for your Outreach integration, there are a few logistical things you’ll want to get out of the way before we can begin making API calls.

Get API Access

If you’re using the Vessel API, you can skip this step.

To start building your Outreach integration, you need to first request access to the API. This can be a time-consuming process so make sure to request access as soon as you know you want to build an integration.

🔗 Request Access Here

Create A Outreach OAuth App

If you’re using Vessel, you can go ahead and skip this step since we’ve got a pre-approved Outreach application you can use.

If you’re not using Vessel, you’ll need to keep reading to learn how to setup an OAuth app.

• Head to the “Apps” tab in your organization settings

• Create a new app on the “Your apps” tab, choose an appropriate name.

• Add the “OAuth” feature in the Feature selection tab. Make sure to add any scopes for objects you want to access as well as set the OAuth callback URL.

The Outreach API at a Glance

Before we dive into the details of building an Outreach integration, let's take a quick look at some important things to know about the Outreach API:

Authentication

The first step to making an API call is to ask your user for permission to access their data. We do this by “installing” the OAuth app we created inside of their Outreach instance.

During this process, your user will be shown a popup window that asks them to grant you permission to read and write their data.

OAuth is a complicated and nuanced topic, for brevity, I’m not going to touch on how to build out an OAuth flow since it’s not Outreach-specific.

If you’re new to OAuth and just need to get something going fast or don’t want to deal with the notorious headache of OAuth, you can use a framework like Vessel to handle it for you.

If you’d prefer to do this yourself, you can read the Outreach OAuth tutorial. Forewarning, the tutorial is very Outreach specific so if you know you’ll need to build other integrations in the future, I’d invest in doing more research so you understand how to build a more generic Auth flow since OAuth is an infamously difficult problem.

Regardless of how you choose to build authentication, the important part is that you’re able to get your user's credentials so you can push and pull data through the API.

Making an API Call

Now that you’re able to authenticate your user, you can begin making API calls to their CRM 🥳. In this section, we’ll explore how to read and write to the Outreach API in real-time.

Reading From the API

Reading data from the Outreach API is a common use case for integrations. You may need to retrieve information about prospects, sequences, or other objects in the Outreach platform.

When making API calls to read data from the Outreach API, here are a few things to keep in mind:

• Limited Lists support: There’s quite a few resources that don’t have a great way to list all objects. The most glaring are tags. Tags are a common way to organize prospects in Outreach, unfortunately, there’s no way to list all tags so keep that in mind when building out your use case.
• Filtering notation: Outreach APIs express filters using bracket-query notation. If you’re not familiar with this notation you’ll want to read up on how to filter the data. Outreach supports powerful filtering mechanisms so it’s worth a read.
• Request Specific Fields: To improve query performance, you can specify specific fields and associated-object fields to fetch when listing resources.

Through Outreach API

Here's an example of how to make a GET request to fetch prospects using the Outreach API:

const url = 'https://api.outreach.io/api/v2/prospects';

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'application/vnd.api+json'  
  }
});

const data = await response.json();

‍

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to the Outreach API. Here's an example of how to use the Vessel SDK to fetch prospects:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({ 
  apiKey: process.env.API_KEY,
  accessToken: "YOUR_CUSTOMERS_ACCESS_TOKEN"
})

const data = await vessel.unifications.engagement.contacts.list();

Note that we can use the unified API for this call so that we don’t have to rebuild this flow if we want to support other sales engagement platforms.

Writing to the API

In addition to reading data, you may also need to write data to the Outreach API. This can involve creating or updating prospects, sequences, or other objects in the Outreach platform.

When making API calls to write data to the Outreach API, there are a few gotchas to keep in mind:

• Shape: The body of your request must be a JSON object that includes the 'data' key, with an object that contains the 'type' and 'attributes' keys. You’ll need to reference the documentation for what the type attribute should be.
• Related Objects: The above rule also applies when creating a relationship to a related object. Don’t forget to include the type and data attribute in the relationship fields as well (see below).

Through Outreach API

Here's an example of how to make a POST request to create a prospect using the Outreach API:

const url = 'https://api.outreach.io/api/v2/prospects';

const response = await fetch(url, { 
  method: 'POST', 
  headers: {
    'Authorization': `Bearer ${accessToken}`,    
    'Content-Type': 'application/vnd.api+json'
  },  
  body: JSON.stringify({
    data: {
      type: 'prospect',      
      attributes: {
        firstName: 'John',
        lastName: 'Doe',
        email: 'john.doe@example.com'
      }
    }
  })
});

const data = await response.json();

With Vessel

If you're using the Vessel SDK, you can simplify the process of making API calls to the Outreach API. Here's an example of how to use the Vessel SDK to create a prospect:

import Vessel from '@vesselapi/sdk';

const vessel = Vessel({
  apiKey: process.env.API_KEY,
  accessToken: "YOUR_CUSTOMERS_ACCESS_TOKEN"
})

await vessel.unifications.engagements.contact.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john.doe@example.com'
});

Again, we can use the unified API to avoid having to build this out for multiple Sales Engagement integrations.

Closing Thoughts

Publishing your Application

Once you have built your Outreach integration, you can submit it for review to get it listed on the Outreach App Marketplace. This will allow other Outreach users to discover and use your application.

To publish your application you can head to the “Review and Publish” tab on the app configuration page and select “Public and listed in Outreach Marketplace”:

About Us

Hopefully, you found this article helpful for building out your native Outreach integration. I know I certainly wish something like this existed when we built out our Outreach integration.

If you decided to give Vessel a spin while following this tutorial, thank you. If you have any feedback while using the SDK, don’t hesitate to reach out at support@vessel.dev. We’re a team of engineers at heart and take every piece of feedback extremely seriously.

if you’re curious to learn more about why we started Vessel and how we view the future of customer-facing integrations, you can read more in our “what are native integration platforms” posts.

On that note, if you ever have any questions about building an Outreach integration while you’re going through this tutorial, regardless of if you decide to use Vessel, don’t hesitate to reach out at zach@vessel.dev and I’ll be more than happy to personally help.