API Documentation

Overview

To start using the Quill Engage API, sign up for a FREE Plan. Once in the application, go to the Accounts page to set up API access.

Basic and Premium customers also have access to the API in the Accounts page in the application.

Our API pricing is billed monthly. Pricing is per report and the breakdown is as follows:


# of Reports per Month                      Price Per Report                                     

1-5                                                             $0.00

6-55                                                           $1.00

56-255                                                       $0.80

256-505                                                     $0.70

506-1005                                                   $0.60

1006+                                                         $0.50


Below is the technical reference guide for the Quill Engage API. It provides complete details on queries and responses for Quill Engage reports.

Each section in this guide defines the request method and response for a single endpoint. Requests are all shown in REST format.

Authentication

To authenticate against the Quill Engage API, first login to the application and enable API access in the "Account" page. There, you will be granted an API Key. When making requests to the Quill Engage API, supply this key in the x-api-key header of each request.

Request Report

Kicks off the process of gathering data from Google Analytics and writing a report. Each successful request to this endpoint will count towards your monthly request total. We will never bill you for failed reports.

Request


POST https://api.quillengage.com/v1/report

Request Body

{
  "type": string,
  "view": string,
  "end_date": datetime,
  "segment": string
}
Property Name Value Description
type string Type of report being requested. Accepts 'weekly' or 'monthly'
view string View id for the report to be written about.
end_date (optional) datetime End date of the time period being written about. If this parameter is not provided, the report generated will be about the most recent reporting period. Note that the reporting period is inclusive of the end date. So, for example, if you would like to request a report for the month of March 2016, you should request a monthly report with an end date of 2016-03-31.
segment (optional) string Optional segment to be applied to the view. Defaults to none.

Response


If successful, the endpoint will return status information about the story that was requested.

{
  "state": string,
  "type": string,
  "id": string,
  "status_url": string,
  "reporting_period": {
    "start": datetime,
    "end": datetime
  }
}
Property Name Value Description
state string Current state of the report. Can be 'success', pending', or 'failed'.
type string Type of report ('weekly' or 'monthly')
id string Report ID.
status_url string URL which will can be used to query the status of the report.
reporting_period object Details for the reporting period.
reporting_period.start datetime Start date of the reporting period.
reporting_period.end datetime End date of the reporting period.

Report Status

Returns the status of a requested report.

Request


GET https://api.quillengage.com/v1/report/reportId/status

Request Parameters

Parameter Name Value Description
reportId string ID of the report being queried.

Request Body

Response

The response of this endpoint will have identical structure to the response provided by the Request Report endpoint. If the status of the report is success, you may retrieve your report.

Retrieve Report

Retrieves a specific report rendered with user-defined preferences. Users can specify a number of customizations with this endpoint.

API users are not charged per request against this endpoint. We encourage our users to experiment with section and KPI configuration, as well as branding customization. This flexibility is particularly useful for integrations which require white-labeling or flexibility in how content is displayed.

Request


POST https://api.quillengage.com/v1/report/retrieve

Request Parameters

{
  "id": string,
  "formats": [
    string
  ],
  "kpis": [
    string
  ],
  "sections": [
    string
  ],
  "label": string,
  "color": string,
  "logo": {
    "data": string,
    "mimetype": string
  }
}
Property Name Value Description
id string The id of the report to fetch
label string The title of the report
color (Optional) string The primary color to be used while rendering the report. The color must be a standard hexadecimal color code, prefixed with the "#" sign. If not provided, the color will default to Narrative Science green, #86CA24.
logo (Optional) object Logo to include on the report
logo.data string A base64-encoded logo image. Must be less than 3MB and should be landscape or square in orientation for best results. All standard image MIME types (image/*) are accepted.
logo.mimetype string The MIME type of the logo image. All standard image MIME types are accepted, eg image/gif, image/png, image/jpeg.
formats (optional) list of string The format the report should be returned in. In the case that mutliple formats are requested, a multipart/mixed response will be generated. If no format is specified, all report formats will be rendered and returned to the client.

Supported Formats:
  • application/pdf - Returns a base64-encoded fully-rendered PDF report in portrait mode.
  • text/html - Returns a fully-rendered HTML report with images and CSS inline.
  • application/json - Returns a JSON version of the report.
  • text/xml - Returns an XML version of the report.
kpis (optional) list of string The Key Performance Indicators (KPIs) desired for the report. KPIs describe the performance for a given metric period-over-period. For example, if you request the sessions KPI, a KPI object will be returned describing your reports number of sessions this period versus last period. A maximum of three KPIs may be requested. Quill Engage always returns three KPIs, even if the user does not specify this parameter. Our Artificial Intelligence engine, Quill, will identify what it believes to be the most interesting KPIs when fewer than three are specified. If this key is specified in the POST body, at least one KPI must be present. Note that order is important in the KPI list. The order in which KPIs are specified defines the order in which they will appear in the report.

Supported KPIs:
  • sessions - Summarizes the performance of your report's sessions
  • ad_cost - Summarizes the cost of your report's Google AdWords Ad Cost.
  • impressions - Summarizes the number of impressions your report has received.
  • ctr - Summarizes the Click-Through-Rate (CTR) of your report.
  • avg_time_on_site - Summarizes the Average Time On Site for your report's users.
  • pages_per_pession - Summarizes the number of pages viewed per session for your report.
  • pageviews - Summarizes the number of pageviews overall for your report.
  • bounce_rate - Summarizes the bounce rate for your report.
  • most_interesting - Quill will decide which of the previously defined KPIs is most relevant to your report and return it. By default, all three KPIs are set to most_interesting.
sections (optional) list of string Specifies which sections to include in the report. Note that the report overview is always returned. The order of the specified sections in the list will determine the order in which they appear in the response document(s). Sections may not be duplicated.

The definitions of the sections are as follows:
  • traffic - Describes the type and quantity of traffic which the Google Analytics view received during the reporting period.
  • new_referrals - Describes the types and sources of new referrals which the Google Analytics view started receiving in the last reporting period versus the prior reporting periods.
  • users - Describes the types of users and their origins which engaged with your Google Analytics view last reporting period.
  • traffic_by_device - Breaks down sessions for your Google Analytics view by source device over the last reporting period.
  • locations - Descrives the locations of users who visited your Google Analytics view period over period.
  • paid_search - Describes the performance of your Google AdWords campaign with relation to this Google Analytics view over the past period.
  • goals - Describes the performance of your Google Analytics goals over the past period for the specified Google Analytics view.
  • events - Describes the performance of your Google Analytics events over the past period for the specified Google Analytics view.
  • ecommerce - Describes the performance of your Google Analytics ecommerce over the past period for the specified Google Analytics view.

Response


If successful, the endpoint will return the rendered report(s).

By default, or if more than one type of document is requested, this endpoint will return all requested documents with a Content-Type: multipart/mixed header and document body delimited by the boundary delimiter. Alternatively, if a single document format is requested, such as application/json, the return response will have a Content-Type: application/json header. For more information regarding multipart/mixed response handling, please read the Wikipedia entry on multipart responses or for a more formal definition please reference RFC 1341

Please note that PDF reports are Base64 Encoded. You will need to decode the PDF before attempting to open.

Report Completion Webhook

Webhooks for the Quill Engage API may be optionally configured. When an API user makes a request to start a report, Quill Engage will POST to the configured webhook when the report completes regardless if the report was written successfully or not. Users may take advantage of this behavior to avoid polling for completed reports.

Authentication is not performed by the webhook endpoint. Instead, the report ID is specified on the event body. If users are concerned about trusting these webhook events for security reasons, they can make a second request to the /v1/report/retrieve/reportId/status endpoint to retrieve the same information.

Upon configuration in our application, your web server must accept and respond with a 2XX response to a test webhook command. Test webhooks will always POST a JSON payload with the following body:

{
  {
  "state": null,
  "type": "test",
  "status_url": null,
  "id": null,
  "reporting_period": {
    "start": null,
    "end": null
  }
}

Request


POST https://yourdomain/yourwebhookpath

Request Body

{
  {
  "state": string,
  "type": string,
  "id": string,
  "status_url": string,
  "reporting_period": {
    "start": datetime,
    "end": datetime
  }
}
Parameter Name Value Description
state string The state of the report, either 'success' or 'error'.
id string The ID of the report that was completed.
type string Type of report ('weekly' or 'monthly')
status_url string URL which will can be used to query the status of the report.
reporting_period object Details for the reporting period.
reporting_period.start datetime Start date of the reporting period.
reporting_period.end datetime End date of the reporting period.

Response


A 2XX response is expected from the server. If your server does not respond with a 2XX response, webhook configuration will fail and Quill Engage will not POST report status updates to your website.