Introduction

The quintly API is made for you to access all data points you already know from our tool. You need to have a quintly business account in order to access this API. Please get in touch with our support if you like to get access.

Authenticating

For authentication we use Basic Auth via HTTPS. For the username you have to send your quintly client id and for the password your API secret. If you don't have these details yet, please get in touch with our support.

Handling errors

In case of errors, the HTTP status code returns either 404 for a non-existing resource or 500 for any other error. You can expect the following JSON response to be sent in the response's body. There is success set to false and errors and errors.reason holding more specific information about the error. In most cases errors.errorType will return a unique identifier you can use to identify the specific type of error. 

{
  "success": false,
  "errors": {
    "reason": "The underlying SQL query failed: no such table: instagramInsight",
    "errorType": "qqlMalformed"
  }
}

Requesting endpoints

All endpoints can be requested using both GET and POST requests. We recommend using POST requests because of much higher request size limits. Using POST, parameters need to be passed within the body of the request in application/x-www-form-urlencoded format.

Rate limits

So far rate limits have been set very loose and you should not hit any limits at all.

Understanding the concept of spaces

Business accounts can be split into fully isolated environments named spaces. By default, an account starts by having a single space named "Main". When it comes to operations like adding profiles, you need to specify the space a new profile should be added to.

Using the following endpoint you can access the list of available spaces within your account. 

https://api.quintly.com/v0.9/list-spaces

Managing users

Access the list of users in your account using the following endpoint. Certain operations require you to specify a user in whoms name the operation will be performed, for example when creating a new profile. 

https://api.quintly.com/v0.9/list-users

Managing profiles

There is full support to search, add, remove and list profiles within your account via the API.

Searching profiles

Before adding a new profile, you will need to uniquely identify the profile to be added. For this purpose, you can use the following endpoint for search. For Facebook, Twitter, YouTube and LinkedIn you can use free text search to find profiles by name or term. For Instagram, use the profile's username. For all these networks, you can also search by using the profile URL (e.g., https://www.facebook.com/quintly). TikTok and Snapchat Shows are special, because they are not searchable by name or URL and require authentication instead (read Adding profiles for TikTok and Snapchat Shows). 

https://api.quintly.com/v0.9/search-profiles?q=quintly
https://api.quintly.com/v0.9/search-profiles?q=quintly&network=facebook
https://api.quintly.com/v0.9/search-profiles?q=https%3A%2F%2Fwww.facebook.com%2Fquintly

Adding profiles for Facebook, Twitter, YouTube and LinkedIn

To add profiles, please specify the ID of the space you would like to add the new profile to (read Understanding the concept of spaces), and the social network URL for the profile to be added. Usually you will use the search-profiles endpoint described above to identify the social network URL of a profile. 

https://api.quintly.com/v0.9/add-profile?userId=1&spaceId=1&q=https%3A%2F%2Fwww.facebook.com%2Fquintly

Adding profiles for TikTok or Snapchat Shows

Adding TikTok or Snapchat Show profiles requires authentication. You can use the following endpoint to generate a link that can be shared with an external user. On this page, the external user can grant access to their TikTok or Snapchat Show profile. This page does not require credentials and it does not expire. It can safely be used and sent to all users you need to authenticate externally for the purpose of profile adding later on. The quintly user specified by its id (parameter "userId") will be notified, whenever access to new profiles has been granted. 

https://api.quintly.com/v0.9/generate-private-statistics-authentication-link?spaceId=1&userId=1

With the following endpoint you can list all profiles, that have recently been authenticated by external users on the pages generated via the endpoint above. 

https://api.quintly.com/v0.9/list-recent-private-statistics-authentications-for-profile-adding?spaceId=1

Finally, you can add a profile available in the list of recently authenticated profiles, by using the following endpoint and the "platformType" and "platformId" attributes of a specific profile returned by the endpoint described above. 

https://api.quintly.com/v0.9/add-profile-from-recent-private-statistics-authentication?userId=1&spaceId=1&platformType=facebook&platformId=128340270541979

Removing profiles

To remove an existing profile from your account, provide the space and profile id to be deleted. Use the list-profiles endpoint to obtain the profile id. 

https://api.quintly.com/v0.9/remove-profile?userId=1&spaceId=1&profileId=92

Listing profiles

For listing all profiles within your account, use the following endpoint. Here you can also obtain the profile ids necessary to fetch data later on. Parameters "spaceId" and "groupId" are optional and can be used to filter the list of profiles. 

https://api.quintly.com/v0.9/list-profiles?spaceId=1&groupId=1

Accessing private statistics

To access private stats for a profile, it is important to understand the concept of private stats use cases. In order to not ask for too wide permissions when accessing private stats data of your profiles, we have introduced different use cases when accessing this data. E.g., the use case of Facebook Basic Insights allows you to fetch basic Page and Post Insights. You can explore all available private stats use cases using the following endpoint. 

https://api.quintly.com/v0.9/list-private-stats-use-cases

Once you have identified the use cases covering the data points you would like to access, you have to activate these use cases for a specific profile. Use the following endpoint to do so. 

https://api.quintly.com/v0.9/activate-private-stats-use-cases?userId=1&spaceId=1&profileId=1&useCaseIds=1,2

After having activated use cases for a specific profile, you have to fulfill this use case by authenticating and granting the required permissions. You can retrieve an authentication link to do so using the following endpoint. This link can be shared with an external user and does not require credentials. It expires 7 days after creation. 

https://api.quintly.com/v0.9/generate-private-statistics-authentication-link?spaceId=1&profileId=1&userId=1&useCaseIds=1,2

To deactivate a profile's private stats use cases, use the following endpoint. 

https://api.quintly.com/v0.9/deactivate-private-stats-use-cases?userId=1&spaceId=1&profileId=1&useCaseIds=1,2

Fetching data

Loading data is handled via the qql endpoint. We recommend using the Metric Builder to easily build API requests. After you pressed Run QQL within Metric Builder, there is an API section within the Query results tab holding the complete API request for this metric and the current selection (profile, date and additional filters).

The qql endpoint offers the following parameters:

  • qqlQuery: The QQL query describing the data to be loaded. Find further information on how to write QQL queries in our knowledge base.
  • startTime: The beginning of the period you want to get the data for in format YYYY-MM-DD
  • endTime: The end of the period you want to get the data for in format YYYY-MM-DD
  • interval: The aggregation interval used for the analysis (daily, weekly, monthly, total)
  • timezone (optional): By default our API does fetch and aggregate data using the timezone setting of the admin user of your quintly account. We strongly recommend to set an explicit timezone to not rely on settings of one of your users. The list of supported timezones can be found here. E.g. for fetching data in UTC timezone just use "UTC" here.
  • sortBy (optional): Represents the qql field which will be used for sorting the data.
  • sortDir (optional): Represents the sorting direction which will be used to sort the data. Expected values are 'asc' or 'desc'.
  • start (optional): Represents the index of the first item of the requested data.This parameter can be used for pagination in combination with the 'limit' parameter.
  • limit (optional): Represents the value to limit the requested data. This parameter can be also used for pagination in combination with the 'start' parameter.
  • adAccountIds (optional): A comma-separated list of ad account ids (you can find the id of an ad account by using the list-ad-accounts endpoint described above). You can only fetch data for ad accounts added to your quintly account.
  • profileIds (optional): A comma-separated list of profile ids (you can find the id of a profile by using the list-profiles endpoint described above). You can only fetch data for profiles added to your quintly account.
  • postTags (optional): A configuration in JSON format describing what post tags to filter post/item-level data by. E.g. {"conjunction":"any","values":[<tagId1>,<tagId2>],"untagged":false}
  • postText (optional): A configuration in JSON format describing what text to filter post/item-level data by. E.g. {"values":["keyword1", "keyword2"],"conjunction":"any"}
  • adCampaign (optional): A configuration in JSON format describing what ad campaigns to filter ad data sources by. E.g. {"values":["Campaign name A", "Campaign name B"],"conjunction":"any"}

The following is an example for fetching the number of Page Likes for Facebook Pages. 

https://api.quintly.com/v0.9/qql?qqlQuery=SELECT%20profileId,%20time,%20fans%20FROM%20facebook&startTime=2014-01-01&endTime=2014-01-31&interval=weekly&profileIds=13,14

The response will be sent in JSON format. Here is a sample response for the example above. 

{
  "success":true,
  "data":[
    {"profileId":13,"time":"2013-12-30 00:00:00","fans":1372},
    {"profileId":14,"time":"2013-12-30 00:00:00","fans":218},
    {"profileId":13,"time":"2014-01-06 00:00:00","fans":1371},
    {"profileId":14,"time":"2014-01-06 00:00:00","fans":219},
    {"profileId":13,"time":"2014-01-13 00:00:00","fans":1371},
    {"profileId":14,"time":"2014-01-13 00:00:00","fans":219},
    {"profileId":13,"time":"2014-01-20 00:00:00","fans":1371},
    {"profileId":14,"time":"2014-01-20 00:00:00","fans":219},
    {"profileId":13,"time":"2014-01-27 00:00:00","fans":1372},
    {"profileId":14,"time":"2014-01-27 00:00:00","fans":219}
  ]
}

Managing interactive shared dashboards links

Once you have created dashboards in the tool, there are several ways to share them. One option is to share the dashboard as an interactive version in form of a link.

Listing shared dashboard links

You can list all shared links in your account using the following endpoint. 

https://api.quintly.com/v0.9/list-dashboard-share-links

Creating shared dashboard links

You can create a new link to share an interactive version of a dashboard using the following endpoint. 

https://api.quintly.com/v0.9/create-dashboard-share-link

The following parameters are available for link creation.

  • dashboardId: The ID of the dashboard to create an interactive version to be shared as a link. You usually extract the ID of a dashboard from its URL in the tool.
  • userId: The ID of the user to be shown as the creator of the shared link
  • groupId or profileIds: Provide either the ID of a group or a list of concrete profiles as a comma-separated list of profile IDs
  • startTime, endTime or dynamicDate: Provide either a fixed time period in the form of a start and end time (in YYYY-MM-DD format) or provide a relative date definition using the dynamic date parameter (e.g., "last 30 days"). The dynamic date parameters supports all inputs accepted in the "Custom range" input of our date selector.
  • interval: The aggregation interval used for the analysis (daily, weekly, monthly, total)
  • timezone: The timezone used for the analysis. The list of supported timezones can be found here. E.g. for fetching data in UTC timezone just use "UTC" here.
  • postTags (optional): A configuration in JSON format describing what post tags to filter post/item-level data by. E.g. {"conjunction":"any","values":[<tagId1>,<tagId2>],"untagged":false}
  • postText (optional): A configuration in JSON format describing what text to include post/item-level data by. E.g. {"values":["keyword1", "keyword2"],"conjunction":"any"}
  • postTextExclude (optional): A configuration in JSON format describing what text to exclude post/item-level data by. E.g. {"values":["keyword1", "keyword2"],"conjunction":"any"}
  • hasExpiry (optional): If set to 1, the link will expire at the provided valid until date. The default is no expiry.
  • validUntil (optional): If the link is set to expire, provide the expiration date in YYYY-MM-DD format
  • isPasswordProtected (optional): If set to 1, a password is required to access the interactive version of the dashboard. The default is no password.
  • password (optional): If the link requires a password, provide the password here

Updating shared dashboard links

Similar to creating a new shared link, you can also update existing ones. 

https://api.quintly.com/v0.9/update-dashboard-share-link

The following parameters are available for updating links.

  • id: The ID of the link to be updated
  • groupId or profileIds: Provide either the ID of a group or a list of concrete profiles as a comma-separated list of profile IDs
  • startTime, endTime or dynamicDate: Provide either a fixed time period in the form of a start and end time (in YYYY-MM-DD format) or provide a relative date definition using the dynamic date parameter (e.g., "last 30 days"). The dynamic date parameters supports all inputs accepted in the "Custom range" input of our date selector.
  • interval: The aggregation interval used for the analysis (daily, weekly, monthly, total)
  • timezone: The timezone used for the analysis. The list of supported timezones can be found here. E.g. for fetching data in UTC timezone just use "UTC" here.
  • postTags (optional): A configuration in JSON format describing what post tags to filter post/item-level data by. E.g. {"conjunction":"any","values":[<tagId1>,<tagId2>],"untagged":false}
  • postText (optional): A configuration in JSON format describing what text to include post/item-level data by. E.g. {"values":["keyword1", "keyword2"],"conjunction":"any"}
  • postTextExclude (optional): A configuration in JSON format describing what text to exclude post/item-level data by. E.g. {"values":["keyword1", "keyword2"],"conjunction":"any"}
  • hasExpiry (optional): If set to 1, the link will expire at the provided valid until date. The default is no expiry.
  • validUntil (optional): If the link is set to expire, provide the expiration date in YYYY-MM-DD format
  • isPasswordProtected (optional): If set to 1, a password is required to access the interactive version of the dashboard. The default is no password.
  • password (optional): If the link requires a password, provide the password here

Removing shared dashboard links

To remove an existing link, use the following endpoint. 

https://api.quintly.com/v0.9/remove-dashboard-share-link?id=<ID of the shared link>

Fetching data source meta data

Please use the following endpoint to access meta data for all available data sources. 

https://api.quintly.com/v0.9/list-data-sources

Fetching data push task configurations

Please use the following endpoint to access meta data for your data push task configurations. 

https://api.quintly.com/v0.9/list-data-push-tasks

To fetch recent logs for a data push task, use the following endpoint. 

https://api.quintly.com/v0.9/list-data-push-task-logs?dataPushTaskId=<ID of the data push task>