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

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

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.
  • 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}
  ]
}