Quilgo API Documentation
Your first API call
All API calls start with
https://quilgo.com
(for example
https://quilgo.com/v1/forms
) and support the following REST methods:
GET
,POST
and
DELETE
. API always responds with a JSON object. Successful API calls always return status
200
.To make your first test API call simply do:
Example response
{
version: '1.0.0 beta'
}
Authentication
The test method shown above is the only method that does not require authentication. To make other API calls you need to provide your API token that can be obtained from your Quilgo Dashboard.
To get your API key, click on your email address in the right top corner and choose "Integrate via API" item.
The token must be provided as an
X-API-KEY
header. You need to provide the token within every call (except the test one).
Once the token is provided you may test the successfull authentication by calling:
Example response
Error handling
If API returns a code other than
200
, then something went wrong. The JSON returned will contain an information about an error, here is an example:
{
code: 'unauthorized',
message: 'Invalid form ID'
}
If the method you try to access doesn't exist, then API will return the
400
code with the following JSON:
{
code: 'invalid_request',
message: 'Unknown method or invalid method structure'
}
If the data you are attempting to send is not a valid JSON, then API will return the
400
code with the following JSON:
{
code: 'invalid_request',
message: 'The request must contain a valid JSON'
}
There are also limits on the amount of calls per minute
per method. Please refer to the
Limitations section to learn more.
API Methods
The following API methods allow you to work with your forms and Quilgo links. Please do not forget to provide
X-API-KEY
header within every API call.
Get forms
This method allows you to fetch all imported forms.
Example response
{
object: 'list',
data: [
{
id: 1,
name: 'Form name',
url: 'https://quilgo.com/link/wefih3487',
text_color: '998833',
background_color: '883344',
welcome_text: 'Hello world!',
button_text: 'Start!'
},
...
]
}
Get form
This method allows you to fetch a form by its ID.
Example response
{
id: 1,
name: 'Form name',
url: 'https://docs.google.com/forms/d/3248',
text_color: '998833',
background_color: '883344',
welcome_text: 'Welcome to my form',
button_text: 'Start!'
}
Create links
This method allows you to create links for a specified form.
POST
/v1/forms/{{Form ID}}/links/bulk
Request data
| JSON parameter | Required | Value type |
|---|
| time_limit | Yes | Integer |
| hide_timer | No | Boolean |
| camera_tracking | No | Boolean |
| auto_close | No | Boolean |
| respondents | Yes | | JSON parameter | Required | Value type |
|---|
| name | Yes, if email not specified | String | | email | Yes, if name not specified | String, valid email |
Please note, the amount of respondents is capped at 100.
If you need to create more links, you will need to make several API calls.
|
Example request data
{
time_limit: 60,
hide_timer: true,
camera_tracking: true,
auto_close: true,
respondents: [
{
name: 'John Doe',
email: '
[email protected]'
},
{
name: 'Jack Black'
},
{
email: '
[email protected]'
}
]
}
Example response
Error handling
| Status | Code | Message |
|---|
| 400 | invalid_parameter_format | Invalid form ID format |
| 400 | parameter_required | No time_limit provided |
| 400 | invalid_parameter_format | Invalid auto_close format |
| 400 | invalid_parameter_format | Invalid camera_tracking format |
| 400 | invalid_parameter_format | Invalid hide_timer format |
| 400 | invalid_request | "hide_timer" and "auto_close" parameters cannot be "true" at the same time |
| 400 | parameter_required | No respondents provided |
| 400 | invalid_parameter_format | Invalid respondents format |
| 400 | parameter_required | No either respondent email or name provided |
| 400 | invalid_parameter_format | Invalid respondent (1) name format |
| 400 | invalid_parameter_format | Invalid respondent (1) email format |
| 403 | unauthorized | Invalid form ID |
| 400 | invalid_parameter_format | The number of links to create in one call is limited to 100 |
| 400 | invalid_parameter_format | time_limit parameter cannot be greater than 1440 |
| 400 | invalid_request | There are duplicates for name-email pairs in the respondents list |
| 400 | invalid_request | Either not yet sent or opened links with the same email addresses already exist for this form |
Get links
This method allows you to fetch all links connected to a specified form.
GET
/v1/forms/{{Form ID}}/links
| Query parameter | Required | Value type |
|---|
| filter_name | No | String * |
| filter_email | No | String * |
| filter_auto_close | No | Boolean |
| filter_hide_timer | No | Boolean |
| filter_camera_tracking | No | Boolean |
* Case insensitive search. You can also use asterisks either at the start or the end of the string. For example, to match both Susanna and Randy, please use *an*. To match [email protected] and [email protected], but not [email protected], simply use je*. To match strictly, omit the asterisks.
Example response
{
object: 'list',
data: [
{
id: 1,
name: 'John Snow',
email: '
[email protected]',
url: 'https://quilgo.com/link/1234',
hide_timer: false,
camera_tracking: true,
auto_close: false,
opened_at: 'Sun Mar 31 2019 14:31:38 GMT+0100',
submitted_at: 'Sun Mar 31 2019 14:38:44 GMT+0100',
unfocused: 2,
score: 42,
form_id: 1
},
...
]
}
Error handling
| Status | Code | Message |
|---|
| 403 | unauthorized | Invalid form ID |
| 400 | invalid_parameter_format | Invalid form ID format |
Get link
This method allows you to fetch a link by its ID.
Example response
{
id: 3,
name: 'John Snow',
email: '
[email protected]',
url: 'https://quilgo.com/link/1234',
hide_timer: false,
camera_tracking: true,
auto_close: false,
opened_at: 'Sun Mar 31 2019 14:31:38 GMT+0100',
submitted_at: 'Sun Mar 31 2019 14:38:44 GMT+0100',
unfocused: 2,
score: 42,
form_id: 1
}
Error handling
| Status | Code | Message |
|---|
| 403 | unauthorized | Invalid link ID |
| 400 | invalid_parameter_format | Invalid link ID format |
Delete link
This method allows you to delete a link by its ID.
DELETE
/v1/links/{{Link ID}}
Example response
Error handling
| Status | Code | Message |
|---|
| 403 | unauthorized | Invalid link ID |
| 400 | invalid_parameter_format | Invalid link ID format |
Limitations
Some API methods have limitations and the exact numbers depend on the plan you are currently subscribed for. The figures below represent the amounts of calls allowed per minute per each listed method. Other methods do not have limitations.
| Method / Plan | FREE | Any personal plan | Any business plan |
|---|
| Get Forms | 10 | 10 | 600 |
|---|
| Get Form | 10 | 10 | 600 |
|---|
| Get Links | 10 | 10 | 600 |
|---|
| Get Link | 10 | 10 | 600 |
|---|
| Create Links | 0 | 2 | 60 |
|---|
| Delete Link | 10 | 10 | 600 |
|---|
If the limit is reached, API will return the following error:
| Status | Code | Message |
|---|
| 406 | api_call_limit_error | This method can be called only {{ X }} times per minute according to your current plan |
If this error is returned, the call is not executed and you will need to wait to execute it again. Alternatively, you may upgrade your plan or simply contact us to dicsuss custom limitation figures.