API
Content
General Information
- API Domain: https://api.surveyninja.io/service
- Data Return Format: JSON
- Authorization: oauth2, all requests must include an Authorization header with the access key
- To access the API, have: Client ID and Client Secret. Issued upon request at customer support on the "Premium" plan
- Provide: a working redirect_uri to customer support
Authorization
https://api.surveyninja.io/oauth/authorize get
Request Parameters
{
"client_id": "{CLIENT_ID}",
"state": "1650379667.97685997745",
"redirect_uri": "",
"response_type": "code",
}
"client_id": "{CLIENT_ID}",
"state": "1650379667.97685997745",
"redirect_uri": "",
"response_type": "code",
}
If the request is successful, you will be redirected to the specified redirect_uri with parameters state, code.
For increased security, the state should be compared with the value stored in the user's session to ensure authentication.
Use the received code in the request to obtain a token.
https://api.surveyninja.io/oauth/token post
Request Parameters
{
"code": "{CODE}",
"client_id": "{CLIENT_ID}",
"client_secret": "{CLIENT_SECRET}",
"grant_type": "authorization_code",
"redirect_uri": "{REDIRECT_URI}"
}
"code": "{CODE}",
"client_id": "{CLIENT_ID}",
"client_secret": "{CLIENT_SECRET}",
"grant_type": "authorization_code",
"redirect_uri": "{REDIRECT_URI}"
}
Response Result
{
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "",
"refresh_token": ""
}
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "",
"refresh_token": ""
}
Store the received access_token and use it in the Authorization header for subsequent requests.
Get List of Surveys
https://api.surveyninja.io/ api/service/quiz get
Response Result
{
"id": "ID survey",
"name": "name survey",
"url_shared": "url survey",
"is_published": true,
"folder": {
"id": 384,
"workspace_id": 384,
"user_id": 12,
"name": "My surveys",
"pos": 1,
"is_default": true,
"created_at": "2024-04-01T08:37:14.000000Z",
"updated_at": "2024-04-27T15:46:27.000000Z",
"deleted_at": null
}
}
"id": "ID survey",
"name": "name survey",
"url_shared": "url survey",
"is_published": true,
"folder": {
"id": 384,
"workspace_id": 384,
"user_id": 12,
"name": "My surveys",
"pos": 1,
"is_default": true,
"created_at": "2024-04-01T08:37:14.000000Z",
"updated_at": "2024-04-27T15:46:27.000000Z",
"deleted_at": null
}
}
Get Data of a Specific Survey
https://api.surveyninja.io/api/service/quiz/{id} get
Response Result
{
"id": "ID survey",
"answer_count": "number of responses",
"name": "name survey",
"url_shared": "url survey",
"widgets": "question",
"hidden_options": "hidden opt :)",
"folder": {
"id": 384,
"workspace_id": 384,
"user_id": 12,
"name": "My surveys",
"pos": 1,
"is_default": true,
"created_at": "2024-04-01T08:37:14.000000Z",
"updated_at": "2024-04-27T15:46:27.000000Z",
"deleted_at": null
}
}
"id": "ID survey",
"answer_count": "number of responses",
"name": "name survey",
"url_shared": "url survey",
"widgets": "question",
"hidden_options": "hidden opt :)",
"folder": {
"id": 384,
"workspace_id": 384,
"user_id": 12,
"name": "My surveys",
"pos": 1,
"is_default": true,
"created_at": "2024-04-01T08:37:14.000000Z",
"updated_at": "2024-04-27T15:46:27.000000Z",
"deleted_at": null
}
}
Get List of Responses for a Specified Survey
https://api.surveyninja.io/api/service/quiz/{id}/answers get
Request Parameters
limit - type: integer; default: 20;
offset - type: integer; default: 20;
date - type: date_format: Y-m-d;
offset - type: integer; default: 20;
date - type: date_format: Y-m-d;
Response Result
[
{
"id": 4813,
"visit_id": 46139,
"date": "2024-08-24T12:51:33.466162",
"date_start": "2024-08-24T12:51:33.466162",
"date_end": "2024-08-24T12:51:28.275591",
"is_complete": true,
"extra_fields": null,
"answers": [
{
"type": "yesno",
"rowId": "3ec8521a-3af8-4fec-b11e-7409d38eab33",
"title": "yes or no?",
"result": [
{
"uuid": "adbe1d5f-29e2-468c-863b-5b136a519ad1",
"label": "Yes"
}
],
"max_val": null,
"hidden_options": []
},
{
"type": "slider",
"rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
"title": "slider",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "file",
"rowId": "0753c3d8-3898-458c-9de1-32f7a6efc89b",
"title": "message",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "userInfo",
"title": null,
"result": {
"ip": "199.99.99.9",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.84Safari/537.36",
"password_number": null
}
}
],
"over_upload_limit": false
},
{
"id": 4812,
"visit_id": 46137,
"date": "2024-08-24T16:43:20.07436",
"date_start": "2024-08-24T16:43:20.07436",
"date_end": "2024-08-24T16:43:15.686992",
"extra_fields": null,
"is_complete": false,
"answers": [
{
"type": "yesno",
"rowId": "3ec8521a-3af8-4fec-b11e-7409d38eab33",
"title": "yes or no?",
"result": [
{
"uuid": "adbe1d5f-29e2-468c-863b-5b136a519ad1",
"label": "Yes"
}
],
"max_val": null,
"hidden_options": []
},
{
"type": "slider",
"rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
"title": "slider",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "file",
"rowId": "0753c3d8-3898-458c-9de1-32f7a6efc89b",
"title": "message",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "userInfo",
"title": null,
"result": {
"ip": "199.99.99.9",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.102Safari/537.36",
"password_number": null
}
}
],
"over_upload_limit": false
},
{
"id": 4811,
"visit_id": 46136,
"date": "2024-08-24T16:47:05.660563",
"date_start": "2024-08-24T16:47:05.660563",
"date_end": "2024-08-24T16:46:59.852849",
"extra_fields": null,
"is_complete": true,
"answers": [
{
"type": "slider",
"rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
"title": "slider",
"result": 57,
"max_val": null,
"hidden_options": []
},
{
"type": "userInfo",
"title": null,
"result": {
"ip": "199.99.99.9",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.102Safari/537.36",
"password_number": null
}
}
],
"over_upload_limit": false
}
]
{
"id": 4813,
"visit_id": 46139,
"date": "2024-08-24T12:51:33.466162",
"date_start": "2024-08-24T12:51:33.466162",
"date_end": "2024-08-24T12:51:28.275591",
"is_complete": true,
"extra_fields": null,
"answers": [
{
"type": "yesno",
"rowId": "3ec8521a-3af8-4fec-b11e-7409d38eab33",
"title": "yes or no?",
"result": [
{
"uuid": "adbe1d5f-29e2-468c-863b-5b136a519ad1",
"label": "Yes"
}
],
"max_val": null,
"hidden_options": []
},
{
"type": "slider",
"rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
"title": "slider",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "file",
"rowId": "0753c3d8-3898-458c-9de1-32f7a6efc89b",
"title": "message",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "userInfo",
"title": null,
"result": {
"ip": "199.99.99.9",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/99.0.4844.84Safari/537.36",
"password_number": null
}
}
],
"over_upload_limit": false
},
{
"id": 4812,
"visit_id": 46137,
"date": "2024-08-24T16:43:20.07436",
"date_start": "2024-08-24T16:43:20.07436",
"date_end": "2024-08-24T16:43:15.686992",
"extra_fields": null,
"is_complete": false,
"answers": [
{
"type": "yesno",
"rowId": "3ec8521a-3af8-4fec-b11e-7409d38eab33",
"title": "yes or no?",
"result": [
{
"uuid": "adbe1d5f-29e2-468c-863b-5b136a519ad1",
"label": "Yes"
}
],
"max_val": null,
"hidden_options": []
},
{
"type": "slider",
"rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
"title": "slider",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "file",
"rowId": "0753c3d8-3898-458c-9de1-32f7a6efc89b",
"title": "message",
"result": null,
"max_val": null,
"hidden_options": []
},
{
"type": "userInfo",
"title": null,
"result": {
"ip": "199.99.99.9",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.102Safari/537.36",
"password_number": null
}
}
],
"over_upload_limit": false
},
{
"id": 4811,
"visit_id": 46136,
"date": "2024-08-24T16:47:05.660563",
"date_start": "2024-08-24T16:47:05.660563",
"date_end": "2024-08-24T16:46:59.852849",
"extra_fields": null,
"is_complete": true,
"answers": [
{
"type": "slider",
"rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
"title": "slider",
"result": 57,
"max_val": null,
"hidden_options": []
},
{
"type": "userInfo",
"title": null,
"result": {
"ip": "199.99.99.9",
"browser": "Chrome",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.102Safari/537.36",
"password_number": null
}
}
],
"over_upload_limit": false
}
]
Hidden Variables
Retrieve a Hidden Variable
https://api.surveyninja.io/ api/service/quiz/{id}/hidden/options get
Send a Hidden Variable
https://api.surveyninja.io/ api/service/quiz/{id}/hidden/options/create post
Request Parameters
{
"name": "productType",
"value": "clientShop"
}
"name": "productType",
"value": "clientShop"
}
Update a Hidden Variable
https://api.surveyninja.io/ api/service/quiz/{id}/hidden/options/update/{id} post
Request Parameters
{
"name": "productType",
"value": "clientShop"
}
"name": "productType",
"value": "clientShop"
}
Delete a Hidden Variable
https://api.surveyninja.io/ api/service/quiz/{id}/hidden/options/delete/{id} post
Parameters of Hidden Variables in Questions
Retrieve a Hidden Variable in a Question
https://api.surveyninja.io/ api/service/quiz/{id}/widgets/hidden/options get
Send a Hidden Variable in a Question
https://api.surveyninja.io/ api/service/quiz/{id}/widgets/hidden/options/create post
Request Parameters:
{
"name": "productType",
"value": "clientShop",
"widget_uuid": "c63b9a88-2f1b-4735-a7ab-0b5fd84c90c2"
}
"name": "productType",
"value": "clientShop",
"widget_uuid": "c63b9a88-2f1b-4735-a7ab-0b5fd84c90c2"
}
Update a Hidden Variable in a Question
https://api.surveyninja.io/ api/service/quiz/{id}/widgets/hidden/options/update/{opt_id} post
Request Parameters:
{
"name": "productType",
"value": "clientShop"
}
"name": "productType",
"value": "clientShop"
}
Delete a Hidden Variable in a Question
https://api.surveyninja.io/ api/service/quiz/{id}/widgets/hidden/delete/{opt_id} post
We welcome suggestions for API improvements, please contact us.