Developer API Portal

Overview

SurveyOL API Docs allow developers to integrate data from SurveyOL into their own applications or websites.

Authentication

SurveyOL API uses OAuth 2.0 for authentication.

API Access Token

To get access to SurveyOL API data, you need to create an API access token under My Account. When making a request, you need to put your generated access token in your request header as a "bearer token", such as "Authorization: Bearer Your_ACCESS_TOKEN".

Format

SurveyOL API request parameters need to be in JSON format. The response will be in JSON format as well.

Scopes

By means of SurveyOL API, you have access to your account, contact, survey, collector and response objects.

Endpoints & Methods

Account

Update Account

POST

https://api.surveyol.com/v1/account/me

Parameters:
email, type: string
firstName, type: string
lastName, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/account/me
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

--data '{
    "email": "bob@account.com",
    "firstName":"Bob",
    "lastName":"Smith",
}'

Response Example

{
    "email": "bob@account.com",
    "firstName":"Bob",
    "lastName":"Smith"
}

View Account

GET

https://api.surveyol.com/v1/account/me

Parameters: None

Request Example

curl --request GET
--url https://api.surveyol.com/v1/account/me
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

Response Example

{
    "email": "john@account.com",
    "firstName":"John",
    "lastName":"Smith"
}

Contacts

Add Contact

POST

https://api.surveyol.com/v1/contact

Parameters:
email, type: string
firstName, type: string
lastName, type: string

Request Example

curl --request POST
--url https://api.surveyol.com/v1/contact 
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

--data '{
    "email": "cindy@contact.com",
    "firstName":"Cindy",
    "lastName":"Smith"
}'

Response Example

{
    "id": "17df8254-4153-4348-8490-77b841b14024",
    "email": "cindy@contact.com",
    "firstName":"Cindy",
    "lastName":"Smith"
}

Delete Contact

DELETE

https://api.surveyol.com/v1/contact/{contactId}

Parameters:
contactId, type: string

Request Example

curl --request DELETE 
--url https://api.surveyol.com/v1/contact/17df8254-4153-4348-8490-77b841b14024 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    success: true
}

List Contacts

GET

https://api.surveyol.com/v1/contacts

Parameters: None

Request Example

curl --request GET
--url https://api.surveyol.com/v1/contacts 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

[{
    "id": "3b9af40c-38ff-41bf-b121-f5b17a633907",
    "email": "cindy@contact.com",
    "firstName":"Cindy",
    "lastName":"Smith"
},
{
    "id": "d2091126-0351-42a0-b12b-5d7aa8e524b7",
    "email": "jimmy@contact.com",
    "firstName":"Jimmy",
    "lastName":"Smith"
},
{
    "id": "7f9e86ae-0399-493f-94c9-045ac84173bb",
    "email": "elizabeth@contact.com",
    "firstName":"Elizabeth",
    "lastName":"Smith"
}]

Update Contact

POST

https://api.surveyol.com/v1/contact/{contactId}

Parameters:
contactId, type: string
email, type: string
firstName, type: string
lastName, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/contact/17df8254-4153-4348-8490-77b841b14024 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json' 

--data '{
    "email": "cindy@contact.com",
    "firstName":"Cindy",
    "lastName":"Smith"
}'

Response Example

{
    "id": "17df8254-4153-4348-8490-77b841b14024",
    "email": "cindy@contact.com"
    "firstName":"Cindy",
    "lastName":"Smith"
}

View Contact

GET

https://api.surveyol.com/v1/contact/{contactId}

Parameters:
contactId, type: string

Request Example

curl --request GET
--url https://api.surveyol.com/v1/contact/3b9af40c-38ff-41bf-b121-f5b17a633907
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

Response Example

{
    "id": "3b9af40c-38ff-41bf-b121-f5b17a633907",
    "email": "cindy@contact.com",
    "firstName":"Cindy",
    "lastName":"Smith"
}

Surveys

Add Survey

POST

https://api.surveyol.com/v1/survey

Parameters:
title, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/survey 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json' 

--data '{
    "title":"Customer Satisfaction Survey"
}'

Response Example

{
    "id": "bf92a312-cc65-4126-8298-bcb5c957bddd",
    "title":"Customer Satisfaction Survey"
}

Add Survey Page

POST

https://api.surveyol.com/v1/survey/{surveyId}/page

Parameters:
surveyId, type: string
title, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/survey/f04e6345-dd11-4342-8975-0a718d853505/page 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json' 

--data '{
    "title":"Your Workplace"
}'

Response Example

{
    "id": "925c5b5a-3aae-4845-8eaf-595b14f85a43",
    "title":"Your Workplace",
    "pageIndex": 0
}

Add Survey Question

POST

https://api.surveyol.com/v1/page/{pageId}/question

Parameters:
pageId, type: string
type, type: string
properties, type: object (data will be varied based on question type)

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/page/925c5b5a-3aae-4845-8eaf-595b14f85a43/question 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json' 

--data '{
    "type": "Star Rating",
    "properties": {
        "title": "How would you rate us?",
        "length": 5,
        "color": "#F5A623",
        "half": false
    }
}'

Response Example

{
    "id": "e1a760f9-dcf1-4c6d-b516-639c4b803a61",
    "type": "Star Rating",
    "questionIndex": 0,
    "properties": {
        "title": "How would you rate us?",
        "length": 5,
        "color": "#F5A623",
        "half": false
    }
}

Copy Survey

POST

https://api.surveyol.com/v1/survey/{surveyId}/copy

Parameters: None

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/survey/bf92a312-cc65-4126-8298-bcb5c957bddd/copy
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    "id": "20c50d92-0c57-4682-b150-bb5851096c4b",
    "title":"Customer Satisfaction Survey"
}

Delete Survey

DELETE

https://api.surveyol.com/v1/survey/{surveyId}

Parameters:
surveyId, type: string

Request Example

curl --request DELETE 
--url https://api.surveyol.com/v1/survey/bf92a312-cc65-4126-8298-bcb5c957bddd 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    success: true
}

Delete Survey Page

DELETE

https://api.surveyol.com/v1/page/{pageId}

Parameters:
pageId, type: string

Request Example

curl --request DELETE 
--url https://api.surveyol.com/v1/page/6b47b5e3-01f7-44a1-ae61-c858c00dd3ac 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    success: true
}

Delete Survey Question

DELETE

https://api.surveyol.com/v1/question/{questionId}

Parameters:
questionId, type: string

Request Example

curl --request DELETE 
--url https://api.surveyol.com/v1/question/e1a760f9-dcf1-4c6d-b516-639c4b803a61 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    success: true
}

List Surveys

GET

https://api.surveyol.com/v1/surveys

Parameters: None

Request Example

curl --request GET 
--url https://api.surveyol.com/v1/surveys 
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

Response Example

[{
    "id": "abdfa473-c05b-4312-9e06-c04cad4568e5",
    "title":"Market Research Survey"
},
{
    "id": "bf92a312-cc65-4126-8298-bcb5c957bddd",
    "title":"Customer Satisfaction Survey"
},
{
    "id": "cabfc1e0-7931-4c2a-82de-b06b01719dcb",
    "title":"Employee Engagement Survey"
}]

List Survey Pages

GET

https://api.surveyol.com/v1/survey/{surveyId}/pages

Parameters:
surveyId, type: string

Request Example

curl --request GET
--url https://api.surveyol.com/v1/survey/f04e6345-dd11-4342-8975-0a718d853505/pages
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

[{
    "id": "925c5b5a-3aae-4845-8eaf-595b14f85a43",
    "title":"Your Workplace",
    "pageIndex": 0
},
{
    "id": "4d02a67a-571c-44ed-87e0-8e0a42c8f560",
    "title":"Your Supervisor"
    "pageIndex": 1
},
{
    "id": "6b47b5e3-01f7-44a1-ae61-c858c00dd3ac",
    "title":"Your Peers"
    "pageIndex": 2
}]

List Survey Questions

GET

https://api.surveyol.com/v1/page/{pageId}/questions

Parameters:
pageId, type: string

Request Example

curl --request GET 
--url https://api.surveyol.com/v1/page/925c5b5a-3aae-4845-8eaf-595b14f85a43/questions 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

[{
    "id": "e1a760f9-dcf1-4c6d-b516-639c4b803a61",
    "type": "Star Rating",
    "questionIndex": 0,
    "properties": {
        "title": "How would you rate us?",
        "length": 5,
        "color": "#F5A623",
        "half": false
        "requireAnswer": true
    }
},
{
    "id": "22bdcb2b-12e8-4c54-991c-deff4e7f07e0",
    "type": "Multiple Choice",
    "questionIndex": 1,
    "properties": {
        "title": "Who is your favorite trainer?",
        "choices": ["Jeff", "Tom", "Cindy", "Jennifer"]
        "multiSelect": false
        "requireAnswer": false
    }
},
{
    "id": "0553d7c7-55ad-47ad-887b-257377f5b52a",
    "type": "Comment Box",
    "questionIndex": 2,
    "properties": {
        "title": "Please leave us your feedback.",
        "requireAnswer": false
    }
}]

Update Survey

POST

https://api.surveyol.com/v1/survey/{surveyId}

Parameters:
surveyId, type: string
title, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/survey/bf92a312-cc65-4126-8298-bcb5c957bddd 
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json' 

--data '
    "title":"Customer Excellence Survey"
}'

Response Example

{
    "id": "bf92a312-cc65-4126-8298-bcb5c957bddd",
    "title":"Customer Excellence Survey"
}

Update Survey Page

POST

https://api.surveyol.com/v1/page/{pageId}

Parameters:
pageId, type: string
title, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/page/6b47b5e3-01f7-44a1-ae61-c858c00dd3ac 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

--data '{
    "title":"Your Coworkers"
}'

Response Example

{
    "id": "6b47b5e3-01f7-44a1-ae61-c858c00dd3ac",
    "title":"Your Coworkers",
    "pageIndex": 0
}

Update Survey Question

POST

https://api.surveyol.com/v1/question/{questionId}

Parameters:
questionId, type: string
properties, type: object (data will be varied based on question type)

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/question/e1a760f9-dcf1-4c6d-b516-639c4b803a61 
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

--data '{
    "properties": {
        "title": "How would you rate us?",
        "length": 3,
        "color": "#C1403D",
        "half": false
        "requireAnswer": true
    }
}'

Response Example

{
    "id": "e1a760f9-dcf1-4c6d-b516-639c4b803a61",
    "type": "Star Rating",
    "questionIndex": 0,
    "properties": {
        "title": "How would you rate us?",
        "length": 3,
        "color": "#C1403D",
        "half": false
        "requireAnswer": true
    }
}

View Survey

GET

https://api.surveyol.com/v1/survey/{surveyId}

Parameters:
surveyId, type: string

Request Example

curl --request GET 
--url https://api.surveyol.com/v1/survey/bf92a312-cc65-4126-8298-bcb5c957bddd
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

Response Example

{
    "id": "bf92a312-cc65-4126-8298-bcb5c957bddd",
    "title":"Customer Satisfaction Survey"
}

View Survey Page

GET

https://api.surveyol.com/v1/page/{pageId}

Parameters:
pageId, type: string

Request Example

curl --request GET 
--url https://api.surveyol.com/v1/page/6b47b5e3-01f7-44a1-ae61-c858c00dd3ac 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    "id": "6b47b5e3-01f7-44a1-ae61-c858c00dd3ac",
    "title":"Your Coworkers",
    "pageIndex": 0
}

View Survey Question

GET

https://api.surveyol.com/v1/question/{questionId}

Parameters:
questionId, type: string

Request Example

curl --request GET 
--url https://api.surveyol.com/v1/question/e1a760f9-dcf1-4c6d-b516-639c4b803a61 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    "id": "e1a760f9-dcf1-4c6d-b516-639c4b803a61",
    "type": "Star Rating",
    "questionIndex": 0,
    "properties": {
        "title": "How would you rate us?",
        "length": 3,
        "color": "#C1403D",
        "half": false
        "requireAnswer": true
    }
}

Collectors

Add Collector

POST

https://api.surveyol.com/v1/survey/{surveyId}/collector

Parameters:
type, type: string
title, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/survey/f04e6345-dd11-4342-8975-0a718d853505/collector 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json' 

--data '{
    "type": "Web Link",
    "title":"My Web Link"
}'

Response Example

{
    "id": "47323f35-197e-4707-a310-6684ab2932bc",
    "type": "Web Link",
    "title":"My Web Link"
}

Delete Collector

DELETE

https://api.surveyol.com/v1/collector/{collectorId}

Parameters:
collectorId, type: string

Request Example

curl --request DELETE
--url https://api.surveyol.com/v1/collector/47323f35-197e-4707-a310-6684ab2932bc 
--header 'Authorization: Bearer <token>'
--header 'Content-Type: application/json'

Response Example

{
    success: true
}

List Collectors

GET

https://api.surveyol.com/v1/survey/{surveyId}/collectors

Parameters:
surveyId, type: string

Request Example

curl --request GET 
--url https://api.surveyol.com/v1/survey/f04e6345-dd11-4342-8975-0a718d853505/collectors 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

[{
    "id": "47323f35-197e-4707-a310-6684ab2932bc",
    "type": "Web Link",
    "title":"My Web Link"
},
{
    "id": "108d1f36-101c-4188-b4c4-54c32cfedfc3",
    "type": "Email",
    "title":"My Email"
},
{
    "id": "0e79129c-03c3-4d84-a604-c49bde3aead3",
    "type": "Website Embedding",
    "title":"My Website Embedding"
}]

Update Collector

POST

https://api.surveyol.com/v1/collector/{collectorId}

Parameters:
collectorId, type: string
title, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/collector/47323f35-197e-4707-a310-6684ab2932bc 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json' 

--data '{
    "title":"My Web Link 2"
}'

Response Example

{
    "id": "47323f35-197e-4707-a310-6684ab2932bc",
    "type": "Web Link",
    "title":"My Web Link 2"
}

View Collector

GET

https://api.surveyol.com/v1/collector/{collectorId}

Parameters:
collectorId, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/collector/47323f35-197e-4707-a310-6684ab2932bc 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    "id": "47323f35-197e-4707-a310-6684ab2932bc",
    "type": "Web Link",
    "title":"My Web Link 2"
}

Responses

Add Response

POST

https://api.surveyol.com/v1/survey/{surveyId}/response

Parameters:
collectorId, type: string, optional
questions, type: [object]
guid, type: string
answer, type: string

Request Example

curl --request POST 
--url https://api.surveyol.com/v1/survey/f04e6345-dd11-4342-8975-0a718d853505/response 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json' 

--data '{
    "collectorId": "47323f35-197e-4707-a310-6684ab2932bc",
    "questions": [
        {
            "guid":"b4ba1bac-1385-4d1b-a4ca-b839e0e433c5",
            "answer":"GM"
        },
        {
            "guid":"7d37b894-a7bf-444d-befb-a34bad8e2e68",
            "answer":"Avatar"
        }
    ],
    "completedDate": "2022-01-01"
}'

Response Example

{
    "id": "12052052-1242-4993-a8f7-d2274e011626",
    "collectorId": "47323f35-197e-4707-a310-6684ab2932bc",
    "questions": [
        {
            "guid":"b4ba1bac-1385-4d1b-a4ca-b839e0e433c5",
            "answer":"GM"
        },
        {
            "guid":"7d37b894-a7bf-444d-befb-a34bad8e2e68",
            "answer":"Avatar"
        }
    ],
    "completedDate": "2022-01-01T00:00:00"
}

Delete Response

DELETE

https://api.surveyol.com/v1/response/{responseId}

Parameters:
responseId, type: string

Request Example

curl --request DELETE
--url https://api.surveyol.com/v1/response/12052052-1242-4993-a8f7-d2274e011626
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    success: true
}

List Responses

GET

https://api.surveyol.com/v1/survey/{surveyId}/responses

Parameters:
surveyId, type: string

Request Example

curl --request GET 
--url https://api.surveyol.com/v1/survey/f04e6345-dd11-4342-8975-0a718d853505/collectors
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

[{
    "id": "12052052-1242-4993-a8f7-d2274e011626",
    "collectorId": "47323f35-197e-4707-a310-6684ab2932bc",
    "questions": [
        {
            "guid":"b4ba1bac-1385-4d1b-a4ca-b839e0e433c5",
            "answer":"GM"
        },
        {
            "guid":"7d37b894-a7bf-444d-befb-a34bad8e2e68",
            "answer":"Avatar"
        }
    ],
    "completedDate": "2022-01-01T00:00:00"
},
{
    "id": "2cdd3e26-cd05-4437-a117-69e93873f9b0",
    "collectorId": "47323f35-197e-4707-a310-6684ab2932bc",
    "questions": [
        {
            "guid":"8b328cb3-9e65-4ec8-b02b-746feb3e858c",
            "answer":"Chevy"
        },
        {
            "guid":"5a43da47-2e89-4b63-a468-f5b71348e465",
            "answer":"The Hunger Games"
        }
    ],
    "completedDate": "2022-01-03T00:00:00"
},
{
    "id": "4928751d-9ae6-4016-b5cf-625707295cb5",
    "collectorId": "47323f35-197e-4707-a310-6684ab2932bc",
    "questions": [
        {
            "guid":"32c49d7c-5528-40e8-803c-675ca2dedc27",
            "answer":"Cadillac"
        },
        {   
            "guid":"9113c09e-0ea7-4610-b503-a8b86a4cfa8e",
            "answer":"Harry Potter"
        }
    ],
    "completedDate": "2022-01-07T00:00:00"
}]

View Response

GET

https://api.surveyol.com/v1/response/{responseId}

Parameters:
responseId, type: string

Request Example

curl --request POST
--url https://api.surveyol.com/v1/response/12052052-1242-4993-a8f7-d2274e011626 
--header 'Authorization: Bearer <token>' 
--header 'Content-Type: application/json'

Response Example

{
    "id": "12052052-1242-4993-a8f7-d2274e011626",
    "collectorId": "47323f35-197e-4707-a310-6684ab2932bc",
    "questions": [
        {
            "guid":"b4ba1bac-1385-4d1b-a4ca-b839e0e433c5",
            "answer":"GM"
        },
        {   
            "guid":"7d37b894-a7bf-444d-befb-a34bad8e2e68",
            "answer":"Avatar"
        }
    ],
    "completedDate": "2022-01-01T00:00:00"
}

Rate Limit

By default, you are limited to 10 calls per minute and 1,000 calls per day. Please contact our support team for additional API requests.