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.
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
GETdata 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 bring 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.
