Contact Us
Quote Request
  • App Support
    • Knowledge Base
      • API Documentation
      • Classic Portal Documentation
      • App Developer Account Info
      • Video Tutorials – Classic
      • Onboarding Documentation
      • New Portal Documentation
      • Video Tutorials – New
      • App Version Update Notes
    • App Success Tips
      • App Launch Success Guide​
      • Populate Your App For Launch
      • Train Your App Administrators
      • Prepare and Plan Your Marketing Launch Activities
      • Keep Your App Fresh
      • Consistently Remind Your Community about Your App
      • Turn Your App Administrators into Super-Users
      • Ensure Your App Is a Must-Have for Your Community
  • Additional Services
    • Additional Training
    • Content & Design
      • Blog Posts
      • Infographics
      • Content Packages
      • Assessments
      • Editorial Services
      • Whiteboard Video
    • Marketing Support
Menu
  • App Support
    • Knowledge Base
      • API Documentation
      • Classic Portal Documentation
      • App Developer Account Info
      • Video Tutorials – Classic
      • Onboarding Documentation
      • New Portal Documentation
      • Video Tutorials – New
      • App Version Update Notes
    • App Success Tips
      • App Launch Success Guide​
      • Populate Your App For Launch
      • Train Your App Administrators
      • Prepare and Plan Your Marketing Launch Activities
      • Keep Your App Fresh
      • Consistently Remind Your Community about Your App
      • Turn Your App Administrators into Super-Users
      • Ensure Your App Is a Must-Have for Your Community
  • Additional Services
    • Additional Training
    • Content & Design
      • Blog Posts
      • Infographics
      • Content Packages
      • Assessments
      • Editorial Services
      • Whiteboard Video
    • Marketing Support

API Documentation

  • API Documentation
  • Assessments & Quiz API Sample
  • Forms & Reporting API Sample
  • Side Menu API Sample

Classic Portal Documentation

  • Advantages
  • Alerts
  • Assessments and Quizzes
  • Checklists
  • Content Authoring Tool
  • Creating a Quiz
  • eGuide Library
  • Events
  • FAQ Module
  • Form Elements Breakdown
  • How to Create a Scored Assessment
  • Logging In to Your Portal
  • Module Access Codes
  • News
  • PDF Library
  • Reporting and Forms
  • Resources Module
  • Text Module / Welcome Message
  • User Management
  • Videos

App Developer Account Info

  • Apple Developer Program Letter Request
  • Enrolling in the Apple Developer Program
  • Getting Started with Developer Accounts
  • Granting QuickSeries Access to Your App Store Connect
  • Granting QuickSeries Access to Your Google Play Console
  • Register for a Google Play Developer account
  • Transferring Your App: How to Accept the Transfer
  • Transferring Your App: How to Initiate the Transfer

Video Tutorials - Classic

  • FAQ Module
  • Module Access Codes
  • News Module
  • Reports and Forms

Onboarding Documentation

  • 12 Steps of Onboarding
  • Installing Your Test App on Android (Firebase)
  • Installing Your Test App on iOS (TestFlight)

New Portal Documentation

  • Alerts
  • Assessments
  • Checklists
  • eGuide Library / Bundles
  • FAQ
  • Form Elements Breakdown
  • Forms & Reporting
  • Make Your Plan
  • Maps
  • Module Access Codes
  • News
  • NWS / FEMA Alerts
  • PDF Library
  • Privacy Policy and Terms and Conditions editor
  • QuickConnect Workspaces
  • Resources
  • Side Menu Customization
  • User Management
  • User Onboarding
  • Video Library
  • Welcome Message

Video Tutorials - New

  • Access Codes
  • Alerts Module
  • App User Onboarding
  • Assessment & Quiz Module
  • Checklist Module
  • FAQ Module
  • Library Module
  • Make Your Plan Module
  • Maps: How to create zones
  • News Module
  • NWS and FEMA Alerts
  • Privacy Policy and Terms and Conditions editor
  • QuickConnect Workspaces
  • Reporting Module
  • Resources Module
  • Side Menu Customization
  • Video Library Module
  • Welcome Message Module

App Success Tips

  • App Launch Success Guide​
  • Consistently Remind Your Community about Your App
  • Ensure Your App Is a Must-Have for Your Community
  • Keep Your App Fresh
  • Populate Your App For Launch
  • Prepare and Plan Your Marketing Launch Activities
  • Train Your App Administrators
  • Turn Your App Administrators into Super-Users

App Version Update Notes

  • Version 3.11.0
  • Version 3.11.2
  • Version 3.12.2
  • Version 3.13.2
  • Version 3.7.1
  • Version 3.8.0
  • Version 3.9.0
  • Home
  • Knowledge Base
  • API Documentation

API Documentation

Table of Contents
  • QuickSeries API Documentation
    • Compatibility guidelines
    • Current version
    • How to use the API
    • Authentication
    • Valid API request
    • HTTP verbs
    • Status codes
    • Path parameters
    • Request payload
    • Data validation and error reporting
    • Unknown route
    • Pagination
    • Rate limits
      • Staying within the rate limit
      • Conditional requests
    • Content type
    • multipart/form-data
Print Friendly, PDF & EmailQuickPrint

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.

VerbDescription
HEADCan be issued against any resource to get just the HTTP header info.
GETUsed for retrieving resources.
POSTUsed for creating resources.
PATCHUsed for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource.
PUTUsed for replacing resources or collections.
DELETEUsed for deleting resources.

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.

Return valuesDescription
200 OKThe request succeeded. The result meaning of “success” depends on the HTTP method:

 

  • GET: The resource has been fetched and transmitted in the message body.
  • HEAD: The representation headers are included in the response without any message body.
  • PATCH, PUT or POST: The resource describing the result of the action is transmitted in the message body.
202 AcceptedThe request has been received but not yet acted upon. It is noncommittal, since there is no way in HTTP to later send an asynchronous response indicating the outcome of the request. It is intended for cases where another process or server handles the request, or for batch processing.
204 No ContentThere is no content to send for this request, but the headers may be useful. The user agent may update its cached headers for this resource with the new ones.
304 Not ModifiedThis is used for caching purposes. It tells the client that the response has not been modified, so the client can continue to use the same cached version of the response.
400 Bad RequestThe server could not understand the request due to invalid syntax.
401 UnauthorizedAlthough the HTTP standard specifies “unauthorized”, semantically this response means “unauthenticated”. That is, the client must authenticate itself to get the requested response.
403 ForbiddenThe client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client’s identity is known to the server.
404 Not FoundThe server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. The API may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client.
408 Request TimeoutThis response is sent on an idle connection by some servers, even without any previous request by the client. It means that the server would like to shut down this unused connection.
409 ConflictThis response is sent when a request conflicts with the current state of the server.
417 Expectation FailedThis response code means the expectation indicated by the Expect request header field cannot be met by the server.
500 Server ErrorThe server has encountered a situation it does not know how to handle.
503 Service UnavailableThe server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.
504 Gateway TimeoutThis error response is given when the server is acting as a gateway and cannot get a response in time.

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
KeyTypeDescription
filterStringUsed as a search field. This can be left empty (i.e.: “”). It will filter the results based on the property the user email address.

 

Default: “”

sortByStringThis property identifies which user model key to use as its sorting value.

 

Default: email

User model:

{
“eid”: “string”,
“appEid”: “string”,
“email”: “string”,
“avatar”: “string”,
“fullName”: “string”,
“registrationData”: {},
“status”: “string”,
“confirmedAt”: “string”,
“createdAt”: “string”
}
sortASC or DESCThis property sets whether users will be sorted in ascending or descending order, based on the sortBy value.

 

Default: ASC

pageNumberCurrent page returned.

 

Default: 0

countNumberNumber of users returned on a given page.

 

Default: 20

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
Header NameDescription
X-RateLimit-LimitThe maximum number of requests you’re permitted to make per minute.
X-RateLimit-RemainingThe number of requests remaining in the current rate limit window.
X-RateLimit-ResetThe time at which the current rate limit window resets in UTC epoch seconds.

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);
  }
}
Still stuck? How can we help?

How can we help?

Table of Contents
  • QuickSeries API Documentation
    • Compatibility guidelines
    • Current version
    • How to use the API
    • Authentication
    • Valid API request
    • HTTP verbs
    • Status codes
    • Path parameters
    • Request payload
    • Data validation and error reporting
    • Unknown route
    • Pagination
    • Rate limits
      • Staying within the rate limit
      • Conditional requests
    • Content type
    • multipart/form-data

|

Reliable Content.
Innovative Delivery.

App Support

  • Knowledge Base
  • App Success Tips

Additional Services

  • Additional Training
  • Content & Design
  • Marketing Support

Legal

  • Legal Policies
  • SLA Agreement

This website and its contents is copyright of QuickSeries Inc.
© QuickSeries 2021.

All rights reserved. Any redistribution or reproduction of part or all of the contents in any form is prohibited.