Flex Connector Configuration Template

Grin API

Configuration Parameters

Any instance where an entry in the below configuration has a leading $ represents a parameter that needs to be replaced with a static value.

Parameters in this document:

$api_key - The API Key will provide access to the Grin API. To view and manage your API keys, you can visit your Grin Account Settings, and full details on Authentication can be found here.
$resource_name - The Resource Name represents the name of the resource to be appended and used as part of the Destination Table name. Each Resource Name value can be found on the resource's page at the top as a bold, as shown in the List all Contacts example, where "contacts" is the Resource Name.
$incremental_starting_value - The Incremental Starting Value represents the earliest date that data should be collected for, given in yyyy-mm-DD format. For example, if you would like your historical data to go back to the start of 2021, this value would be set to 2021-01-01.

API Resources

For a list of API Resources available for the Grin API, please refer to the list of top-level categories found below, where the link associated with each category will lead you to the home page for that set of resources. From there, you can navigate to specific resources on the lefthand-side of the screen. For the purposes of this documentation, we will focus on resources that begin with "List all" (e.g. List all Contacts, List all Activations, etc.). If you are interested in ingesting data from a resource that does not meet this format, please reach out to our Support Team and we'd be happy to assist in formatting the Flex Connector accordingly. Additionally, if you would like to collect data from a resource whose page is List all "x" for a "y" (e.g. List all Affiliate Links for a Contact), reach out to our Support Team for assistance.

Connector configuration

Base url: https://app.grin.co/api/rest/v1/$resource_name
Method: GET

URL Parameters for the Grin API will vary with each resource, and will be found on the main page of a given resource under the Query Parameters section of the page. For a thorough walkthrough on filtering with these parameters, see the Grin documentation here. When combining multiple filters into a single Flex Connector configuration, the filter components should be separated by an & (e.g. limit=250&expand=stats,contact,media-library-content). As shown in the example, in order to minimize the number of API calls used in a given collection, the URL Parameter of limit=250 should be used in all configurations.

Incremental Collections

When filtering by a date in an effort to collect incremental data, the filter component should be entered as {inckey}=gte:{incval}.

"Expand" parameter

For some resources, a parameter of expand will appear as an option, which can bring in additional supplemental data for a given resource. For example, if you want to collect the Contacts resource along with each contact's associated Tags and Affiliate Links, a URL Parameter of expand=tags,affiliate-links can be added to collect the additional data all within a single Flex Connector.

Destination Table naming convention is ultimately up to you as the data owner. One common structure used for this API is grin_$resourcename

Authorization

Authorization: Bearer Token
Token: $api_key

Pagination

Enable:
Get next page value: Static (integer to be incremented)
Start page: 1
Page step: 1
Use next page value: As a URL parameter value
URL/body key: page
Stop iterating when: Empty data

Advanced Settings

Data key: data
Errors waiting time: 429=30

The Incremental Key is an optional URL Parameter that can be used to limit the amount of data being ingested with each collection of data into Panoply. When using an Incremental Key, be sure to also include {inckey}=gte:{incval} as a URL Parameter. The below list represents resources for which incremental collection is NOT available:

Custom Properties
Custom Property Options
Custom Property Values
Product Options
Product Option Values
Product Variants
Relationship Stages
Tags

NOTE:
For the Affiliate Page Views resource, the Column name below should be set to lastTimeSucceed instead of updated_at.

Column name	Column value
updated_at	$incremental_starting_value

When entering a Column Value to the incremental key feature, you will need to use the following format: yyyy-mm-DD. Upon ingesting the first set of data, the Column Value will automatically update to ensure only new and newly updated records are ingested in subsequent collections.

Grin