Surveys

Name: Surveyplanet
Price range: $

Create a survey

Creates a single survey.

POST

/v1/survey

Request Body

Name	Type	Description
title	`String`	The survey title.
email	`String`	optional String indicating whether an email address is need to take the survey. Options: `required`, `optional`, or `anonymous` Default value: optional
anonymous	`Boolean`	optional Whether the survey is completely anonymous. It will not save any identifying information about the participant including IP address, location, referrer, browser details or operating system. Default value: false
welcome	`Object`	optional Welcome slide details.
welcome.msg	`String`	optional The welcome message.
welcome.img	`String`	optional The welcome image.
success	`Object`	optional Success slide details.
success.msg	`String`	optional The success message.
success.img	`String`	optional The success image.
success.url	`String`	optional The alternate success url.
branding	`Object`	optional The branding details for the survey.
branding.logo	`String`	optional An alternative logo url for the survey.
branding.url	`String`	optional The url associated with the logo.
display	`Object`	optional The display details for the survey.
display.style	`String`	optional Whether the survey should be displayed all questions at once (”multiple”) or one question at a time (”single”). Default value: single
display.options	`Object`	optional Additional display options.
questions	`ObjectId[]`	optional All the question ids for the survey. See Questions for details.
theme	`String`	optional The unique theme id for the survey. See Themes for details.
active	`Boolean`	optional Whether the survey is active or not. Default value: false
language	`Object`	The language definitions for the survey. See Languages for details.
notify	`Object`	notification flags
notify.complete	`Boolean`	optional Whether to notify survey created when survey has been created. Default value: false

Examples

curl https://api.surveyplanet.com/v1/survey 
--request POST 
--header "Content-Type: application/json" 
--header "Authorization: Bearer <ACCESS_TOKEN>"
--data '{"title":"My new survey" <...>}'

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/survey`, {
  method: "POST"
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
  }
  body: JSON.stringify({"title":"My new survey" <...>})
})
  .then( response => response.json() )
  .then( res => console.log(res.data) )
  .catch( err => console.error(err) );

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.post(
  'https://api.surveyplanet.com/v1/survey',
  headers = {
    "Content-Type": "application/json"
    "Authorization": "Bearer <ACCESS_TOKEN>"
  }
  data = {"title":"My new survey" <...>}
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "type": "ok",
  "message": "Request worked as expected."
  "data": {
    "_id": "62b9db151489dd913aeaa22f",
    "id": "Sa5i5vi7b",
    "user": "62bb20e8afac21b873847d7f",
    "title": "Uncle Joe's Fruit Stand",
    "welcome": {
      "msg": "Thanks for visiting Uncle Joe's Fruit Stand. Please help us improve by completing this short survey.",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/60930fc8d02d9e2210eb0975.jpeg"
    },
    "success": {
      "msg": "Thank you for your help! Tell us the coupon code below for **50% off** your next purchase: *Grape Escape*",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/6093119638dfd6785d5beed8.jpeg",
      "url": null,
      "delay": null
    },
    "branding": {
      "url": null,
      "logo": null
    },
    "display": {
      "options": {
        "previous": false
      },
      "style": "single"
    },
    "notify": {
      "sms": "never",
      "email": "never"
    },
    "email": "optional",
    "preventDuplicates": false,
    "anonymous": false,
    "questions": [
      "62bb4e5aafac21b873847d82",
      "62bb4e5aafac21b873847d83",
      "62bb4e5aafac21b873847d84",
      "62bb4e5aafac21b873847d85",
      "62bb4e5aafac21b873847d86"
    ],
    "theme": "62bb50c9afac21b873847d87",
    "active": true,
    "language": "en",
    "preview": "62bb2c99afac21b873847d80",
    "updated": "2021-07-26T19:55:04.491Z",
    "created": "2021-05-05T20:42:59.561Z",
    "archived": false,
    "categories": []
  }
}

Delete a survey

Delete a single survey. If you are not the survey creator and only have access to it through a Team deleting the survey will only remove you from the Team and not delete the survey itself; only the owner can delete a survey.

DELETE

/v1/survey/:id

Parameters - `Parameter`

Name	Type	Description
id	`String`	The unique id of the survey to delete.

Examples

curl https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f 
--request DELETE 
--header "Content-Type: application/json" 
--header "Authorization: Bearer <ACCESS_TOKEN>"

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f`, {
  method: "DELETE"
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
  }
})
  .then( response => response.json() )
  .then( res => console.log(res.data) )
  .catch( err => console.error(err) );

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.delete(
  'https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f',
  headers = {
    "Content-Type": "application/json"
    "Authorization": "Bearer <ACCESS_TOKEN>"
  }
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "type": "ok",
  "message": "Request worked as expected."
  "data": {
    "_id": "62b9db151489dd913aeaa22f",
    "id": "Sa5i5vi7b",
    "user": "62bb20e8afac21b873847d7f",
    "title": "Uncle Joe's Fruit Stand",
    "welcome": {
      "msg": "Thanks for visiting Uncle Joe's Fruit Stand. Please help us improve by completing this short survey.",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/60930fc8d02d9e2210eb0975.jpeg"
    },
    "success": {
      "msg": "Thank you for your help! Tell us the coupon code below for **50% off** your next purchase: *Grape Escape*",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/6093119638dfd6785d5beed8.jpeg",
      "url": null,
      "delay": null
    },
    "branding": {
      "url": null,
      "logo": null
    },
    "display": {
      "options": {
        "previous": false
      },
      "style": "single"
    },
    "notify": {
      "sms": "never",
      "email": "never"
    },
    "email": "optional",
    "preventDuplicates": false,
    "anonymous": false,
    "questions": [
      "62bb4e5aafac21b873847d82",
      "62bb4e5aafac21b873847d83",
      "62bb4e5aafac21b873847d84",
      "62bb4e5aafac21b873847d85",
      "62bb4e5aafac21b873847d86"
    ],
    "theme": "62bb50c9afac21b873847d87",
    "active": true,
    "language": "en",
    "preview": "62bb2c99afac21b873847d80",
    "updated": "2021-07-26T19:55:04.491Z",
    "created": "2021-05-05T20:42:59.561Z",
    "archived": false,
    "categories": []
  }
}

Get a survey

Retrieves a single survey.

GET

/v1/survey/:id

Parameters - `Parameter`

Name	Type	Description
id	`String`	The unique id of the survey to retrieve.

Examples

curl https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f 
--header "Authorization: Bearer <ACCESS_TOKEN>"

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f`, {
	headers: { Authorization: 'Bearer <ACCESS_TOKEN>' },
})
	.then((response) => response.json())
	.then((res) => console.log(res.data))
	.catch((err) => console.error(err));

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.get(
  "https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f",
  headers={"Authorization": "Bearer <ACCESS_TOKEN>"}
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "type": "ok",
  "message": "Request worked as expected."
  "data": {
    "_id": "62b9db151489dd913aeaa22f",
    "id": "Sa5i5vi7b",
    "user": "62bb20e8afac21b873847d7f",
    "title": "Uncle Joe's Fruit Stand",
    "welcome": {
      "msg": "Thanks for visiting Uncle Joe's Fruit Stand. Please help us improve by completing this short survey.",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/60930fc8d02d9e2210eb0975.jpeg"
    },
    "success": {
      "msg": "Thank you for your help! Tell us the coupon code below for **50% off** your next purchase: *Grape Escape*",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/6093119638dfd6785d5beed8.jpeg",
      "url": null,
      "delay": null
    },
    "branding": {
      "url": null,
      "logo": null
    },
    "display": {
      "options": {
        "previous": false
      },
      "style": "single"
    },
    "notify": {
      "sms": "never",
      "email": "never"
    },
    "email": "optional",
    "preventDuplicates": false,
    "anonymous": false,
    "questions": [
      "62bb4e5aafac21b873847d82",
      "62bb4e5aafac21b873847d83",
      "62bb4e5aafac21b873847d84",
      "62bb4e5aafac21b873847d85",
      "62bb4e5aafac21b873847d86"
    ],
    "theme": "62bb50c9afac21b873847d87",
    "active": true,
    "language": "en",
    "preview": "62bb2c99afac21b873847d80",
    "updated": "2021-07-26T19:55:04.491Z",
    "created": "2021-05-05T20:42:59.561Z",
    "archived": false,
    "categories": []
  }
}

List all surveys

Retrieves all the surveys for the authenticated user. Note: does include shared surveys.

GET

/v1/surveys

Query Parameters

Name	Type	Description
reverse	`Boolean`	optional Sort list in reverse chronological order
after	`String`	optional The unique id which defines a cursor for paginating. When defined only retrieve list after this id.
before	`String`	optional The unique id which defines a cursor for paginating. When defined only retrieve list before this id.
select	`String`	optional A URL encoded string of properties to include. If not specified all fields are returned. Use a `-` to exclude a specific field e.g:`-title`.

Examples

curl https://api.surveyplanet.com/v1/surveys 
--header "Authorization: Bearer <ACCESS_TOKEN>"

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/surveys`, {
	headers: { Authorization: 'Bearer <ACCESS_TOKEN>' },
})
	.then((response) => response.json())
	.then((res) => console.log(res.data))
	.catch((err) => console.error(err));

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.get(
  "https://api.surveyplanet.com/v1/surveys",
  headers={"Authorization": "Bearer <ACCESS_TOKEN>"}
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "data": [
    { "_id": "62b9e7467854aef07faa746a",...},
    { "_id": "55d8aa7f2c5105f22fea7cbf",...},
    [...],
  ],
 "more": true,
 "type": "ok",
 "message": "Request worked as expected."
}

Update survey

Update a single survey.

PUT

/v1/survey/:id

Parameters - `Parameter`

Name	Type	Description
id	`String`	The unique id of the survey to update.

Request Body

Name	Type	Description
title	`String`	The survey title.
email	`String`	optional String indicating whether an email address is need to take the survey. Options: `required`, `optional`, or `anonymous` Default value: optional
anonymous	`Boolean`	optional Whether the survey is completely anonymous. It will not save any identifying information about the participant including IP address, location, referrer, browser details or operating system. Default value: false
welcome	`Object`	optional Welcome slide details.
welcome.msg	`String`	optional The welcome message.
welcome.img	`String`	optional The welcome image.
success	`Object`	optional Success slide details.
success.msg	`String`	optional The success message.
success.img	`String`	optional The success image.
success.url	`String`	optional The alternate success url.
branding	`Object`	optional The branding details for the survey.
branding.logo	`String`	optional An alternative logo url for the survey.
branding.url	`String`	optional The url associated with the logo.
display	`Object`	optional The display details for the survey.
display.style	`String`	optional Whether the survey should be displayed all questions at once (”multiple”) or one question at a time (”single”). Default value: single
display.options	`Object`	optional Additional display options.
questions	`ObjectId[]`	optional All the question ids for the survey. See Questions for details.
theme	`String`	optional The unique theme id for the survey. See Themes for details.
active	`Boolean`	optional Whether the survey is active or not. Default value: false
language	`Object`	The language definitions for the survey. See Languages for details.
notify	`Object`	notification flags
notify.complete	`Boolean`	optional Whether to notify survey created when survey has been created. Default value: false

Examples

curl https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f 
--request PUT 
--header "Content-Type: application/json" 
--header "Authorization: Bearer <ACCESS_TOKEN>"
--data '{"title":"A brand new survey title."}'

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f`, {
  method: "PUT"
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
  }
  body: JSON.stringify({"title":"A brand new survey title."})
})
  .then( response => response.json() )
  .then( res => console.log(res.data) )
  .catch( err => console.error(err) );

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.put(
  'https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f',
  headers = {
    "Content-Type": "application/json"
    "Authorization": "Bearer <ACCESS_TOKEN>"
  }
  data = {"title":"A brand new survey title."}
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "type": "ok",
  "message": "Request worked as expected."
  "data": {
    "_id": "62b9db151489dd913aeaa22f",
    "id": "Sa5i5vi7b",
    "user": "62bb20e8afac21b873847d7f",
    "title": "Uncle Joe's Fruit Stand",
    "welcome": {
      "msg": "Thanks for visiting Uncle Joe's Fruit Stand. Please help us improve by completing this short survey.",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/60930fc8d02d9e2210eb0975.jpeg"
    },
    "success": {
      "msg": "Thank you for your help! Tell us the coupon code below for **50% off** your next purchase: *Grape Escape*",
      "alignment": "center",
      "img": "https://media.surveyplanet.com/5bede5cde8dd7e5d5df79aa9/6093119638dfd6785d5beed8.jpeg",
      "url": null,
      "delay": null
    },
    "branding": {
      "url": null,
      "logo": null
    },
    "display": {
      "options": {
        "previous": false
      },
      "style": "single"
    },
    "notify": {
      "sms": "never",
      "email": "never"
    },
    "email": "optional",
    "preventDuplicates": false,
    "anonymous": false,
    "questions": [
      "62bb4e5aafac21b873847d82",
      "62bb4e5aafac21b873847d83",
      "62bb4e5aafac21b873847d84",
      "62bb4e5aafac21b873847d85",
      "62bb4e5aafac21b873847d86"
    ],
    "theme": "62bb50c9afac21b873847d87",
    "active": true,
    "language": "en",
    "preview": "62bb2c99afac21b873847d80",
    "updated": "2021-07-26T19:55:04.491Z",
    "created": "2021-05-05T20:42:59.561Z",
    "archived": false,
    "categories": []
  }
}

Update survey active status

Activate or deactivate a survey.

PUT

/v1/survey/:id/status/:status?

Parameters - `Parameter`

Name	Type	Description
id	`String`	The unique survey id to change status of.
status	`String`	optional Survey status, use ‘on’ or ‘true’ to activate the survey, leave blank or use any other value to deactivate it.

Examples

curl https://api.surveyplanet.com/v1/62b9db151489dd913aeaa22f/status/on 
--request PUT 
--header "Content-Type: application/json" 
--header "Authorization: Bearer <ACCESS_TOKEN>"

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/62b9db151489dd913aeaa22f/status/on`, {
  method: "PUT"
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
  }
})
  .then( response => response.json() )
  .then( res => console.log(res.data) )
  .catch( err => console.error(err) );

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.put(
  'https://api.surveyplanet.com/v1/62b9db151489dd913aeaa22f/status/on',
  headers = {
    "Content-Type": "application/json"
    "Authorization": "Bearer <ACCESS_TOKEN>"
  }
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "type": "ok",
  "message": "Request worked as expected."
  "data": {
    success: true,
    active: true,
  }
}

Update survey archive status

Archive or unarchive a survey.

PUT

/v1/survey/:id/archive/:status?

Parameters - `Parameter`

Name	Type	Description
id	`String`	The unique survey id to archive or unarchive.
status	`String`	optional Archive status, use ‘on’ or ‘true’ to archive the survey, leave blank or use any other value to unarchive it.

Examples

curl https://api.surveyplanet.com/v1/62b9db151489dd913aeaa22f/status/on 
--request PUT 
--header "Content-Type: application/json" 
--header "Authorization: Bearer <ACCESS_TOKEN>"

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/62b9db151489dd913aeaa22f/status/on`, {
  method: "PUT"
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
  }
})
  .then( response => response.json() )
  .then( res => console.log(res.data) )
  .catch( err => console.error(err) );

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.put(
  'https://api.surveyplanet.com/v1/62b9db151489dd913aeaa22f/status/on',
  headers = {
    "Content-Type": "application/json"
    "Authorization": "Bearer <ACCESS_TOKEN>"
  }
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "type": "ok",
  "message": "Request worked as expected."
  "data": {
    success: true,
    archive: true,
  }
}

Update survey url

Change the url path (altId) of a survey.

PUT

/v1/survey/:id/url

Parameters - `Parameter`

Name	Type	Description
id	`String`	The unique survey id to set the new url path for.

Request Body

Name	Type	Description
path	`String`	The new url path to set e.g.: `apples` or `fruit/peaches`. If no path is given the path is unset and default short id is used.

Examples

curl https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f/url 
--request PUT 
--header "Content-Type: application/json" 
--header "Authorization: Bearer <ACCESS_TOKEN>"
--data '{"path":"apples"}'

// For Node.js considering using the 'node-fetch' library: npm info node-fetch
fetch(`https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f/url`, {
  method: "PUT"
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <ACCESS_TOKEN>",
  }
  body: JSON.stringify({"path":"apples"})
})
  .then( response => response.json() )
  .then( res => console.log(res.data) )
  .catch( err => console.error(err) );

# This code sample uses the 'requests' library: pip show requests
import requests
response = requests.put(
  'https://api.surveyplanet.com/v1/survey/62b9db151489dd913aeaa22f/url',
  headers = {
    "Content-Type": "application/json"
    "Authorization": "Bearer <ACCESS_TOKEN>"
  }
  data = {"path":"apples"}
)
print(response.text)

Success response example

Success response example - `Response`

{
  "status": 200,
  "type": "ok",
  "message": "Request worked as expected."
  "data": {
    "success": true
  }
}

Surveys

Create a survey

Request Body

Examples

Success response example

Success response example - Response

Delete a survey

Parameters - Parameter

Examples

Success response example

Success response example - Response

Get a survey

Parameters - Parameter

Examples

Success response example

Success response example - Response

List all surveys

Query Parameters

Examples

Success response example

Success response example - Response

Update survey

Parameters - Parameter

Request Body

Examples

Success response example

Success response example - Response

Update survey active status

Parameters - Parameter

Examples

Success response example

Success response example - Response

Update survey archive status

Parameters - Parameter

Examples

Success response example

Success response example - Response

Update survey url

Parameters - Parameter

Request Body

Examples

Success response example

Success response example - Response

Success response example - `Response`

Parameters - `Parameter`

Success response example - `Response`

Parameters - `Parameter`

Success response example - `Response`

Success response example - `Response`

Parameters - `Parameter`

Success response example - `Response`

Parameters - `Parameter`

Success response example - `Response`

Parameters - `Parameter`

Success response example - `Response`

Parameters - `Parameter`

Success response example - `Response`