API Documentation

QuickPrint

QuickSeries API Documentation

Use the QuickSeries REST APIs to automate your Resource App and build integrations between existing products and services.

Compatibility guidelines

The REST API is versioned with a version number. The latest version is v3.12. We version our APIs because backward-incompatible changes require this version number to change.

New features, improvements, security patches and bug fixes are released in tandem with the Resource App portal.

All deprecations and changes between versions are in the documentation.

Current version

In order to use the latest API, the version number must be part of the path: https://api.quickseries.com/v3.12.

Only API version v3.12 and up is available.

How to use the API

All API access is over HTTPS, and accessed from https://api.quickseries.com. All data is sent and received as JSON with the exception of file download endpoints.

All API requests must include up to 4 path parameters:

• The version number. For example, the root of the API is at https://api.quickseries.com/{apiVersion}.
• The {appId}. For example, https://api.quickseries.com/v3.12/apps/{appId}.
• The module type along with its {cmoduleId} (custom module ID). For example, https://api.quickseries.com/v3.12/apps/{appId}/news/{cmoduleId}.
• And sometimes, the item’s ID, which may be named differently per API endpoint. For example: https://api.quickseries.com/v3.12/apps/{appId}/news/{cmoduleId}/posts/{postId}.

Your {appId} and a list of all your module {cmoduleId} are provided in the “Variables” tab.

Authentication

All API requests require authentication.

You can create an API key from your Resource App portal settings, and pass that API key to all requests via an HTTP header.

Example of using an API key in a header:

curl -H "qs-api-key: <your_api_key>" \
     -I "https://api qa.quickseries.com/v3/apps/{your_app_id}/news/{new_module_id}/posts"

Valid API request

Given that you have created an API key from your Resource App portal settings, the following is an example of a valid request:

curl -I "https://api.quickseries.com/v3.12/apps/{your_app_id}/reporting/{your_module_id}/incoming-reports"

HTTP verbs

Where possible, the API v3.12 strives to use the appropriate HTTP verbs for each action.

Status codes

The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.

The following table shows the possible return codes for the API requests.

Path parameters

If an endpoint has path parameters, the documentation displays them with curly braces.

For example:

DELETE /v3.12/apps/{appId}/checklists/{cmoduleId}/categories/{categoryId}

The {appId} path parameter needs to be replaced with your App ID, the {cmoduleId} needs to be replaced by the module ID and the {categoryId} needs to be replaced by the category ID. The {} should not be included.

The resulting cURL request for an app ID 5, a module ID 283 and a category ID 47 is:

curl -X DELETE \
     -H "qs-api-key: <your_api_key>" \
     -I "https://api.quickseries.com/v3.12/apps/5/checklists/283/categories/47"

Path parameters that are required to be URL-encoded must be followed. Otherwise, it doesn’t match an API endpoint and responds with a 404.

Request payload

API requests can use parameters sent as query strings or as payload body. GET requests usually send a query string, while PUT and POST requests usually send the payload body.

Query string:

curl -X GET \
     -H "qs-api-key: <your_api_key>" \
     -I "https://api.quickseries.com/v3.12/apps/5/assessments/283/categories/47/assessments?status=<example-status>"

Request payload (JSON):

curl -X POST \
     -H "qs-api-key: <your_api_key>" \
     -d '{ \
        "eid": "<example-eid>", \
        "custom_module_eid": "<example-module-eid>", \
        "title": "<example-title>", \
        "answer": "<example-answer>" \
     }' \
     -I "https://api.quickseries.com/v3.12/apps/5/news/283/posts"

Data validation and error reporting

When working with an API you may encounter errors, in which case the API returns an HTTP 400 error.

Such errors appear in the following cases:

• A required attribute of the API request is missing (for example, the title of a news article isn’t given).
• An attribute did not pass the validation (for example, the user email isn’t valid).

When an attribute is missing, you receive something like:

> HTTP/1.1 400 Bad Request
> Content-Type: application/json
> {
>   "message": "Authorization error. Authorization header is missing.",
>   "id": <error_id>
> }

When a validation error occurs, error messages are different. They hold all the details of validation errors:

> HTTP/1.1 400 Bad Request
> Content-Type: application/json
> {
>   "message": "<error-message>"
>   "id": <error_id>,
>   "data": {
>     "errors": {
>       "<property-name>": {
>         "name": "ValidatorError",
>         "message": "<validation-message>",
>         "kind": "<error-type>",
>         "path": "<property-name>"
>       }
>     },
>     "name": "ValidationError",
>     "message": "<full-error-message>"
>   }
> }

Unknown route

When you attempt to access an API URL that doesn’t exist, you receive a 404 Not Found message.

> HTTP/1.1 404 Not Found
> Content-Type: application/json
> Path not found

Pagination

Only 1 endpoint currently supports pagination through a POST.

$ curl -X POST
       -d '{ \
          "filter": "john", \
          "sortBy": "email", \
          "sort": "ASC", \
          "page": 0, \
          "count": 20 \
       }' \
       -H "qs-api-key: <your_api_key>" \
       -I https://api.quickseries.com/v3.12/apps/{appId}/private-user-registration/{cmoduleId}/users-by-email

Rate limits

In order to continuously provide a performant API, we limit the number of requests you can perform to 300 requests per minute, up to 18,000 per hour. Requests are associated with the App under which an API key was created. This means that all API keys created in an App share the same quota of 300 requests per minute.

The returned HTTP headers of any API request show your current rate limit status:

$ curl -I https://api.quickseries.com/v3.12/apps/{appId}/news/{cmoduleId}/posts

> HTTP/1.1 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> X-RateLimit-Limit: 300
> X-RateLimit-Remaining: 56
> X-RateLimit-Reset: 1372700873000

If you need the time in a different format, any modern programming language can get the job done. For example, if you open up the console on your web browser, you can easily get the reset time as a JavaScript Date object.

new Date(1372700873000)
// => Mon Jul 01 2013 13:47:53 GMT-0400 (Eastern Daylight Time)

If you exceed the rate limit, an error response returns:

> HTTP/1.1 429
> Date: Tue, 20 Aug 2013 14:50:41 GMT
> X-RateLimit-Limit: 300
> X-RateLimit-Remaining: 0
> X-RateLimit-Reset: 1372700873000

> {
>    "message": "API rate limit exceeded. Please retry your request again later."
> }

Staying within the rate limit

If you exceed your rate limit, you can likely fix the issue by caching API responses and using conditional requests.

Conditional requests

Most responses return an ETag header. You can use the value of this header to make subsequent requests to those resources using the If-None-Match header. If the resource has not changed, the server will return a 304 Not Modified.

Note: In order for the server to return 304 Not Modified, make sure that the Cache-Control header is not provided or contains value that isn’t no-cache.

$ curl -X GET \
       -H "qs-api-key: <your_api_key>" \
       -H 'If-None-Match: "<your_etag_here>"'
       -I https://api.quickseries.com/v3.12/apps/{appId}/news/{cmoduleId}/posts

> HTTP/1.1 304 Not Modified
> Server: nginx
> Date: Wed, 10 Nov 2021 16:59:08 GMT
> Connection: keep-alive
> X-Powered-By: Express
> ETag: W/"2d2-362cHBOjEr/lnKAW0ai1jX33jjc"

Content type

The Resource App API supports the application/json content type by default, though some API endpoints generally used to download files support application/pdf, application/zip, text/csv and other file content types (mime types).

multipart/form-data

Some API endpoints support file uploads, such as the Reports endpoints. These endpoints expect you to send the data in multipart/form-data format rather than json.

Example of using multipart in JavaScript:

class AssessmentService {  
  createFormData(data, file) {
    const fd = new FormData();
    
    if (data.image) {
      fd.append('image', file);
    }
    
    // If the image was added to the data object, it must be removed before
    // submitting the data.
    delete data.image;
    
    fd.append('data', JSON.stringify(data));
    
    return fd;
  }
  
  submit(data) {
    const request = new XMLHttpRequest();
    const formData = this.createFormData(data, data.file);
    
    request.open('POST', 'https://api.quickseries.com/v3.12/apps/{appId}/news/{cmoduleId}/posts');
    request.send(formData);
  }
}