Search API Connector Documentation

Print

Import Intercom Data to Google Sheets

In this guide, we’ll walk through how to pull data from the Intercom API directly into Google Sheets, using the API Connector add-on for Google Sheets. We’ll first get an API key from Intercom, and then set up a request to pull in contact and conversation data to your spreadsheet.

CONTENTS

BEFORE YOU BEGIN

Click here to install the API Connector add-on from the Google Marketplace.

PART 1: GET YOUR INTERCOM API KEY

  1. While logged into your Intercom account, navigate to the Developer Hub and click New App.
    intercom-img1
  2. A modal will appear, prompting you for details about your app. You can name it anything, but for this example we’ll name it ‘Google Sheets’. Leave the ‘internal integration’ radio button selected, and click Create App.
    intercom-img2
  3. You’ll now see a page containing your Access Token. Copy this to your clipboard as you’ll need it in a moment. That’s it, you now have access to the Intercom API!
    intercom-img3

PART 2: CREATE YOUR API REQUEST URL

We’ll follow the Intercom documentation to access a list of users.

  • API root: https://api.intercom.io
  • Endpoint: /contacts

Putting it together, we get the full API Request URL:

https://api.intercom.io/contacts

PART 3: PULL INTERCOM API DATA INTO SHEETS

We can now enter our values into API Connector and import Intercom API data into Google Sheets.

  1. Open up Google Sheets and click Add-ons > API Connector > Open.
  2. In the Create screen, enter the Request URL we just created
    intercom-img4
  3. Under Headers, enter two sets of key-value pairs, like this:
    AuthorizationBearer YOUR_API_KEY
    Acceptapplication/json
    Replace YOUR_API_KEY with the key provided above in part 1.

    intercom-img5
  4. Create a new tab and click ‘Set current’ to use that tab as your data destination.
  5. Name your request and click Run. A moment later you’ll see a list of contacts in your Google Sheet:
    intercom-img6

PART 4: MORE EXAMPLE API URLS

Experiment with endpoints and query strings as described in the documentation to see other types of Intercom data. For example, you can try the following URLs:

  • Admins (view other users in your workspace):
https://api.intercom.io/admins
  • Companies (list companies):
https://api.intercom.io/companies
  • Conversations (List conversations you have with users on your system):
https://api.intercom.io/conversations
  • Counts (counts of users and companies by segment):
https://api.intercom.io/counts
  • Data Attributes (attributes used to describe your customer and company models):
https://api.intercom.io/data_attributes
  • Events (events belonging to a specific user. Substitute in the data » id retrieved from the /contacts endpoint):
https://api.intercom.io/events?type=user&intercom_user_id=INTERCOM_USER_ID
  • Notes (view notes about users):
https://api.intercom.io/notes
  • Segments (view your workspace segments):
https://api.intercom.io/segments
  • Teams (view teams in your workspace):
https://api.intercom.io/teams

Handle Filtering

If you are filtering conversations, you can use Intercom’s search endpoint as described here. In that case you’d set a POST request to https://api.intercom.io/conversations/search and a POST body like this:

{
 "query":  {
    "field": "updated_at",
    "operator": ">",
    "value": 1560436784
  }
}

Another method of filtering is through JMESPath (paid feature). JMESPath is useful for limiting the number of fields that get returned, and for fixing fields in place. For example here’s a JMESPath expression that could be used to limit and set fields from the /conversations endpoint:

conversations[].{type:type, id:id, created_at:created_at, updated_at:updated_at,first_contact_reply_type:first_contact_reply.type,first_contact_reply_url:first_contact_reply.url,team_assignee_id:team_assignee_id, state:state,sla_applied_type:sla_applied.type,sla_applied_name:sla_applied.name,sla_applied_sla_status:sla_applied.sla_status,statistics:statistics,conversation_rating:conversation_rating.rating,conversation_remark:conversation_rating.remark,conversation_created_at:conversation_rating.created_at,teammates:teammates,custom_attributes:custom_attributes}
intercom-img10

Handle Pagination

Some Intercom endpoints will return a limited set of data, generally just 10 or 20 records at one time. To retrieve additional data, you can first try appending ?per_page=50 to the end of your URL to bump that up to 50 records (different endpoints have different limits).

To get more than that, you’ll need to follow the instructions listed in the documentation. Most of their endpoints currently use pagination links located in the pages » next field, as described here. With API Connector, you can run these as separate requests, or loop through pages automatically using pagination handling (paid feature), like this:

  • API URL: enter your request URL as usual, making sure to include per_page=50
  • Pagination type: next page URL
  • Field name: pages.next
  • Number of pages: enter the number of pages you’d like to fetchintercom-img8

Contacts use cursor-based pagination, so if you’re fetching from the contacts endpoint, you’d instead paginate through records like this:

  • API URL: https://api.intercom.io/contacts?per_page=150
  • Pagination type: cursor
  • Next token parameter: starting_after
  • Next token field: pages.next.starting_after
  • Number of pages: enter the number of pages you’d like to fetch
    intercom-img11

According to their documentation, more endpoints will use cursor-based pagination in the future, so please check their documentation for their latest requirements.

3 thoughts on “Import Intercom Data to Google Sheets”

    • Hi Dimitris, thanks for the message. API Connector prints out data in the order it comes back from the API, so data can switch location if an API sends back different fields between pulls. Typically this happens when a field is empty, such that the API doesn’t send it at all, which shifts around all the surrounding data.

      To address, you can add filtering to pull back data that always contains results or you can include a JMESPath expression (paid feature). JMESPath allows you to select your fields and fix them in place regardless of what the API sends back. There’s an example JMESPath expression in the ‘Handle Filtering’ section of this article.

      As for IMPORTAPI vs. the sidebar, they process data the same way so I’m not sure yet why you’re getting different results. It should be exactly the same. Can you please share your request URLs or your sheet with me so I can take a look?

      Reply

Leave a Comment