Public API Documentation

Use the QuickSeries REST APIs to automate your QuickConnect 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 QuickConnect 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 QuickConnect 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 QuickConnect 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.

Verb

Description

HEAD

Can be issued against any resource to get just the HTTP header info.

GET

Used for retrieving resources.

POST

Used for creating resources.

PATCH

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

PUT

Used for replacing resources or collections.

DELETE

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

Description

200 OK

The 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, PUTor POST: The resource describing the result of the action is transmitted in the message body.

202 Accepted

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

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

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

The server could not understand the request due to invalid syntax.

401 Unauthorized

Although the HTTP standard specifies “unauthorized”, semantically this response means “unauthenticated”. That is, the client must authenticate itself to get the requested response.

403 Forbidden

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

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

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

This response is sent when a request conflicts with the current state of the server.

417 Expectation Failed

This response code means the expectation indicated by the Expect request header field cannot be met by the server.

500 Server Error

The server has encountered a situation it does not know how to handle.

503 Service Unavailable

The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.

504 Gateway Timeout

This 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
				
			

Key

Type

Description

filter

String

Used 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: ""

sortBy

String

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

Default: email

User model:

 
1 {
2 "eid": "string",
3 "appEid": "string",
4 "email": "string",
5 "avatar": "string",
6 "fullName": "string", 7 "registrationData": {},
8 "status": "string",
9 "confirmedAt": "string",
10 "createdAt": "string" 11 }

sort

ASC or DESC

This property sets whether users will be sorted in ascending or descending order, based on the sortBy value.

Default: ASC

page

Number

Current page returned.

Default: 0

count

Number

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

Description

X-RateLimit-Limit

The maximum number of requests you’re permitted to make per minute.

X-RateLimit-Remaining

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

The 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 QuickConnect 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);
  }
}
				
			
Scroll to Top
A Mobile App can be your answer doc cover page
Our white papers are created with the communicator in mind.

Download Our White Papers​

*mandatory field