Missing a custom integration in Grow? Our Custom REST API connector can help you out. Please be aware that we rely on your knowledge in setting up the custom REST connection. You will need to connect your API on your own.

APIs come in a huge variety of types and complexities. Unfortunately, just because a service has an 'REST API' it doesn't mean that Grow will be able to connect to it. And if Grow can connect to it, that does not mean that the reports will all be useful. They could require joining several reports to make it work.

Here are a couple things to look for to know if the API might be able to connect to Grow:

• Grow's custom REST API connector supports "Basic Auth" but not "OAuth 2.0".
• The API must be a REST or "RESTful" API. Grow does not support SOAP APIs.

If you are able to connect a new service Grow via the REST API connector, please let us know in our forum and share the steps you took so others can try it to if they are using the same service.

Connection Setup - Authorization Methods

None

This method does not require any extra configuration.

Authorization Header

This method will include the Authorization parameter in the header of each request with the value specified in the token field.

Basic Auth

This method requires a username and password to be provided.

OAuth2

This is a protocol that allows applications to access user resources without needing to know the user's password. To do this, you first need to register an app with the service that you want to use, and the service must support OAuth 2.0. When setting up the app, you will need to provide a Callback URL or Redirect URI. This is:

https://app.gogrow.com/api/data-source/auth/CustomRESTAPI/callback

The data that must be provided by this service once the app is registered:

• Client Id
• Client Secret

In addition, the following information will also be required, which is usually found in the API documentation.

• Authorization URL
• Token URL
• Scopes
• Grant type (Grow only supports authorization_code and client_credentials flow).
• Client Authentication (documentation should specify whether credentials should be included in the header or the body of the request).

OAuth

OAuth 1.0 is an older protocol that also allows applications to access user resources without knowing the user's password. However, it is more complex than OAuth 2.0 due to its security requirements. Here’s a basic breakdown of what you need to implement OAuth 1.0.

Just like OAuth 2.0, you need to register your application with the service provider that offers OAuth 1.0. During this process, you will need to provide a Callback URL or Redirect URI which is the same as in OAuth 2.0:

https://app.gogrow.com/api/data-source/auth/CustomRESTAPI/callback

After the app is registered, these are the details you will need to create the connection in Grow:

Consumer Key (similar to the client_id in OAuth 2.0)

Consumer Secret (similar to the client_secret in OAuth 2.0)

In addition, the following information will also be required, which is usually found in the API documentation.

• Temporary Token URL
• Authorization URL
• Token URL

In case the authorization URL needs to include scopes, these must be concatenated in the Authorization URL , example:

https://example.com/api/authorize?scope=read%20write

In this case %20 represents the space character encoded in a URL using percent-encoding (URL encoding).

Base URL

This is the URL where the requests will be directed. Example:

https://example.com/api/v1

In the Endpoint Setup step where we specify the endpoint to which requests will be sent, it will be concatenated with the Base URL and its parameters (if any) behind the scenes to form the full request URL.

Health Endpoint

This option is available for NONE, Authorization Header and Basic Auth authentication methods in order to validate that inserted data is correct.

Endpoint Setup

Request method

Accepted methods are GET, POST, PUT, and PATCH.

Pagination

None

• Description: No pagination. Data will be retrieved in a single iteration.
• Fields to Complete: None

Next Page URL

• Description: There is a field in the response that indicates the URL of the next page to be retrieved. The URL can be absolute or relative, and Grow will handle it automatically. If the next page URL field name is not found in the response body, Grow will automatically check the response header.
• Fields to Complete:
  • Next Page Path: Enter the path to the field containing the next page URL, using dot notation for nested values.
  • Run Until: Choose when the request should stop running.

Cursor

• Description: This method involves using a cursor, typically an encoded string, to keep track of the current position in the dataset. The API response includes the cursor value for the next page, allowing you to retrieve subsequent pages of data by passing the cursor value in subsequent requests.

Fields to Complete:

• Next cursor path: Enter the path to the field containing the cursor value, using dot notation for nested values.
• Cursor key: Specify the name of the parameter(described in API documentation).
• Run Until: Choose when the request should stop running.

Page Parameter

• Description: A simple approach where you specify the page number you want to retrieve as a parameter in the API request. Grow will add those values automatically in each request.

Fields to Complete:

• Page Parameter: Specify the name of the parameter(described in API documentation)
• Run Until: Choose when the request should stop running.

Limit & Offset

• Description: This method specifies the number of results to skip (offset) and the maximum number of results to return (limit) in the API request.

Fields to Complete:

• Limit Key: Specify the name of the parameter(described in API documentation)
• Offset Key: Specify the name of the parameter(described in API documentation)
• Limit Value: Specify the value of records to be requested per page
• Run Until: Choose when the request should stop running.

Limit & Offset (Body)

• Description: Similar to Limit & Offset, but the parameters are included in the body of the API request. Grow will add those values automatically in each request.

Fields to Complete:

• Limit Key: Specify the name of the parameter(described in API documentation)
• Offset Key: Specify the name of the parameter(described in API documentation)
• Limit Value: Specify the value of records to be requested per page
• Run Until: Choose when the request should stop running.

Page Parameter (Body)

• Description: Similar to Page Parameter, but the page number parameter is included in the body of the API request. Grow will add those values automatically in each request.

Fields to Complete:

• Page Parameter: Specify the name of the parameter(described in API documentation)
• Run Until: Choose when the request should stop running.

Run Until

The "Run until" option tells when to stop looping through your paginated requests.

• Page value equals: Run your request a specific number of times.
• Response field empty: Run your request until a specific field is no longer populated. Choose a field that appears in every record of your desired results set, e.g. an next page url field, ID or name. When this field is no longer populated, the request will stop looping.
• No data returned: Run your request until the API stops returning data.

Query & Header Parameters

Use Parent as Stream

Overview

The "Use Parent Stream as Source" feature allows users to leverage an existing warehouse table as the source for setting up a new endpoint. This feature is designed to streamline the process of creating new endpoints by reusing existing data.

Prerequisites

Before using this feature, ensure the following:

You have an existing source table in the warehouse.

You have identified the column in the source table that will be used for the endpoint setup.

Setup

1. Click on Add Custom Table to set a new endpoint
2. Enable the Use parent stream as source option
3. Select the warehouse table you want to use as the parent source from the dropdown menu.
4. Select the column that will work as the source of the new endpoint, this column will be referred to as {{column_name}}.
5. Define the endpoint pattern using {{column_name}}. This pattern will dynamically incorporate values from the selected source column. Example:
   /surveys/{{column_name}}
6. OPTIONAL. Test your settings by submitting a request.

Video Demo

Connecting to a REST API

Each API is different, but there are a couple things you will need almost every time: URL and Tokens/Keys.

• The API URL tells the website's API what data you want. Each service or website will have documentation on what the URLs look like and what info they can give back to you. Look for reports that use the GET data method. These are the endpoints you will bring into Grow.
• The API token or key is unique to a person's account and is usually generated or found inside that service's website. It acts like a password, but another level of security for the API above your username and password for that service. The key tells the service's API that you do have authorization to access their data. Your account's API information is often located on a tab or section labeled "API" or something similar. Search their help documentation for more information.

Troubleshooting Tips

• To see if a service has an option to connect via an API, search for the software API docs/documentation on their website, or just Google "[service name] API documentation".
• If you cannot find any API documentation on the service website, you might need to register somewhere for it or reach out to their support to get access to it.
• You will need a URL and a header or parameter which is usually some kind of authorization key, sometimes an "secret key" or "API token". Sometimes the authentication is included in part of the URL or the query parameters.
• If the API tokens are not working to authorize, you might need to encode your API tokens and/or headers into Base64.
• The reports that work the best are just a list of something, like "orders" or "customers". If the API URL needs some kind of ID, you will need to find that ID usually present in another report, and enter it in the URL.
  Example: https://api.convertkit.com/v3/forms/<form_id>/subscriptions

FAQs

Why is my REST API bringing in only one line of data?

Sometimes when you pull data in from a REST API, it condenses it onto one line. In order to see the data like a table, you need to enter in some additional information. Every API is different, and they can put the list of data anywhere they want in their response. You will need to find the common string in each of the column headers and enter that in the JSON Path to Data field.

There is no way for Grow to know which list of data you want to see, so we use JSON path to data to specify where the list is located within the response from the API.

In the example below, we are trying to view all the conversations that have come in to us through Zendesk's Guide API.

If we scroll along the one line of data, we find that there is a recurring string: articles.

The data being returned in the API has a list of conversations, all labeled with articles. So we need to specify that we want that list.

After you have identified what list you want, go to Data Settings in the Smart Builder. Enter the string in the field labeled JSON path to data, then press Get Data at the bottom of the page.

If you need to, you can try a few different strings until you get the data you want. The JSON path to data may be nested deeper into the original response from the REST API. For example, it could have been under theData.conversations (not just conversations). In order to return the list you want to see, you would need to put the entire string theData.conversations into the JSON path to data field.

Can I use a dynamic date in the parameters?

If one of the parameters deals with some kind of date (like a start or end date) you can use the same syntax as in the date interpolator to make it a dynamic date based on the current day instead of entering in a static date. This could be placed in the URL itself, like this:

/apiEndpoint/stuff?start={{date('-7days', 'YYYY-MM-DD')}}

Or you can use it in the parameter fields like, by entering start in Parameter Key and entering {{date('-7days', 'YYYY-MM-DD')}} in Parameter Value fields, respectively.

Why am I not getting all the data and only seeing a specific number of rows? Does the Grow connector support pagination?

Many APIs paginate the data responses. This means they will only return a certain amount of data per call, so you might end up with only 100 rows of data, for example. Grow's API connector does not support pagination to return all the records in a single report.

If the API limits the amount of records returned per endpoint, you may need to create multiple reports by using either a page or an offset parameter, or a combination of the two. There could also be a per_page or limit parameter that can allow you to define how many rows can be returned. You can then create a Master SQL report and use the Union join to create one full report containing all of the pages.

I cannot find any API documentation for the datasource I would like to connect

Sometimes companies do not publish their API documentation online but if you reach out to their customer support or your contact within the company they can provide you with API documentation. We do occasionally run into companies that do not yet have an API or do not allow external platforms to connect to it. In this case we recommend exporting your data into excel files and pulling your data into Grow this way.

My datasource is in SOAP, OAuth2, etc. can I still connect?

No, our connector only supports Basic Auth (not OAuth 2) and REST APIs (not SOAP).

Custom REST API can handle JSON, XML, CSV

Custom Rest can't handle Excel files getting returned by an API at this time.

Header Authentication and Encoding in Base64

You will first need enter in an API URL. In the Key field, enter the word Accept. This tells the system what format data needs to come back in. So in the Value field, enter application/json.

Afterwards, press the plus button underneath the Value field. This will add another header that we can use for the authorization.

The second field will let you authenticate to the system with your API key. The only problem is that JSON does not let you just enter your API key, so we need to encode it to base64 first.

The actual process involves combining the username with a colon, followed by the password, and then running the whole string through the base64 encoding algorithm.

First, you will want to have your API Key handy. Go to base64encode.org, or another website like it and type in user:yourAPIkey, filling in "yourAPIkey" with your actual API key.

After you encode it, you will see an encoded value appear. Copy this value.

In Grow, put Authorization into the Key field. In the Value field, enter Basic your-encoded-api-key, filling in your-encoded-api-key with your actual base64-encoded API key. Be sure to note that there is a space between Basic and your encoded API key.

Simple REST Connection Example

Go ahead and follow along in your own Grow account. This will help you become more familiar with the steps, things to look for, and what to do if you run into errors.

We are going create a metric for your dashboard, using a weather API that anyone can access to pull in weather for your city. The API we are going to use is http://openweathermap.org/current.

You can ask the API to give you the weather info in a variety of different ways. Let's use the weather by zip code. You can either click on this option on the side, or scroll down to "By ZIP Code."

If we want to make an API call for the weather by zip code, we would use the following call: api.openweathermap.org/data/2.5/weather?zip={zip code},{country code} but replacing the { } with the actual info (zip and country codes).

Using the zip code for Grow's location (Orem, Utah), I would form the URL like this: api.openweathermap.org/data/2.5/weather?zip=84097,us

So let's go try that. Log in to your Grow account, click Add Metric, then select Custom REST API from the list of data sources. Enter the URL and press the blue Connect button.

But we get an error. The error says Error Invalid URI "api.openweathermap.org/data/2.5/weather?zip=84097,us"

So our URL is invalid. We have to add the http:// in front. So our new URL is: http://api.openweathermap.org/data/2.5/weather?zip=84097,us

Go ahead and press the blue Connect button again.

And we hit another error. This time our error message says Unauthorized: {"cod":401, "message": "Invalid API key. Please see http://openweathermap.org/faq#error401 for more info."}

So let's go to the URL they give and find out how to fix this problem. We find there that we need a valid AppID, which we can register for free.

So let's register and get our AppID. Once you have registered, you can find your API keys under the tab labeled API keys.

So I have an API key, but I still don't know how to use it. A little searching on the site and I find these instructions about how to use a key.

Per these instructions, we need to add the key to our previous URL. Their example is: http://api.openweathermap.org/data/2.5/forecast/city?id=524901&APPID={APIKEY}

So our new URL would look like this: http://api.openweathermap.org/data/2.5/weather?zip=84097,us&APPID=02cxxx

(Here, you would insert your own API key.)

When we try this URL, we get data back!

Go ahead and press the blue Continue to make a metric with this data.

However, we hit one more problem. The temperature in the field main.temp comes in as really high. Our example shows that it is currently 300.119 degrees, which is clearly not correct.

Reading the documentation, we find out that the default units is in Kelvin. They do, however, give us the conversion to specify what format we want the temperature in.

To get imperial units, we need to add units=imperial to our URL. So our new URl looks like this: http://api.openweathermap.org/data/2.5/weather?zip=84097,us&units=imperial&APPID=02cxxx

In Grow, go to Data Settings in the left-hand panel and enter that new URL, then press the blue Connect button.

This time, the temperature comes back as 80.67. For mid-June, that's not too bad!

To finish building your metric, go ahead and change the chart type to Single Value. Select that cell as your data value for your metric. You can either leave the value as is, or set the number formatting to round it. Give it a label and a metric title, then click Save.