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, list, add and remove profiles within your account via the API.

Usually before adding a new profile, you will need to uniquely identify this profile. For this use case and also to search profiles via all the search endpoints of the social networks, you can use the following endpoint for search. Some networks do not support free text search and you will need to use explicit social network URLs for the profile in question instead.

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

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.

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

The following parameters are available when listing profiles.

  • spaceId (optional): If set, only lists profiles belonging to the specified space.
  • groupId (optional): If set, only lists profiles belonging to the specified group.

For adding profiles, please specify the ID of the space you would like to add the new profile to (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

To remove an existing profile from your account, provide the space and profile id to be deleted.

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

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.

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, yearly, 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.
  • profileIds: 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"}

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 share links of dashboards

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. You can list all shared links in your account using the following endpoint.

https://api.quintly.com/v0.9/list-dashboard-share-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, yearly, 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

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, yearly, 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

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>