SurveyMonkey API
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Overview
Getting Started
The SurveyMonkey API is REST-based, employs OAuth 2.0, and returns responses in JSON. Our documentation is organized by endpoint, has code examples in Python and cURL, and provides a Postman collection with calls for each available method. We also have a quick start guide outlining flows for some common use cases.
To use our API, you’ll need to register a draft app to your SurveyMonkey account. You have a 90-day window to develop in a draft app, after which you’ll need to deploy publicly or privately. Public apps are available to anyone with a SurveyMonkey account and published in our App Directory. If you’re building an app for yourself or your organization, you can deploy a Private app.
Public Apps
Public apps extend features to SurveyMonkey users. All apps must be reviewed and approved by SurveyMonkey and adhere to our terms of use before they can be published in our App Directory.
Public apps use scopes to request permissions from app users during OAuth. Some scopes require your app’s users to have a paid SurveyMonkey plan.
Public apps published in our App Directory can make up to 500,000 requests per day to our API. When a Public app is in draft (during development), it’s subject to draft request limits.
Private Apps
Private apps don’t need to be reviewed by SurveyMonkey. Private apps are subject to our terms of use. Private apps have API request limits and higher limits are available for purchase.
All users of a Private app must belong to the same SurveyMonkey team and have a paid SurveyMonkey plan that offers direct API access.
Registering an App
Anyone with a SurveyMonkey account can register an app. Registering creates a draft app with an access token you can use to query against your account for 90 days. No other SurveyMonkey accounts can authenticate a draft app. Before the 90-day period ends, you must deploy your app as either Public or Private and upgrade your account as needed.
Deploying an App
Before the 90-day draft period ends, you must deploy your app or it’ll be disabled. If your app is disabled, you must deploy it or contact us at our help center to request an extension.
Scopes
Scopes allow apps to access particular resources on behalf of a user. For example, the Create/Modify surveys scope allows your app to create a survey in a user’s account. During the OAuth process, a user is asked to grant permission to scopes your app is requesting access to.
Some scopes require your app’s users to have SurveyMonkey paid plans. If your Public app uses scopes tied to paid plans, any accounts attempting to authenticate without the necessary plan will be asked to upgrade to proceed. Our request headers include the scopes available to users’ plan, as well as those they’ve granted your app permission to.
You can set scopes to be required, optional, or not required in your app’s settings. All required scopes must be approved by and available to the user for the OAuth process to succeed.
Two scopes, Create/Modify Responses and Create/Modify Surveys, require SurveyMonkey’s approval to use in a Public app. If you’ve deployed a Public app and want to change your scope requirements to include these, you’ll need to contact us at our help center to tell us more about your app and use case.
Create/Modify Collectors requires a paid SurveyMonkey plan to create any collector that is not a weblink collector.
Scope Label | Scope Description (text shown during OAuth, “you” refers to owner of authenticating account) | Scope Name | Requires Paid SurveyMonkey Account? |
---|---|---|---|
View Surveys | View your surveys and those shared with you | surveys_read | No |
Create/Modify Surveys | Create or edit surveys in your account | surveys_write | No |
View Collectors | View collectors for your surveys and those shared with you | collectors_read | No |
Create/Modify Collectors | Create or edit collectors for surveys in your account | collectors_write | Yes (Except for weblink collectors) |
View Contacts | View your contacts and contact lists | contacts_read | No |
Create/Modify Contacts | Create or edit contacts in your account | contacts_write | No |
View Responses | View if surveys in your account have responses and their metadata | responses_read | No |
View Response Details | View answers along with responses and answer counts and trends | responses_read_detail | Yes |
Create/Modify Responses | Create or edit survey responses in your account | responses_write | Yes |
View Webhooks | View webhooks to receive notifications when there are changes in your account | webhooks_read | No |
Create/Modify Webhooks | Create and edit webhooks to receive notifications when there are changes in your account | webhooks_write | No |
View Users | View your user information | users_read | No |
View Teams | View teams you belong to | groups_read | Yes |
View Library Assets | View your library of survey themes and templates | library_read | No |
View Workgroups | View the workgroups in your team | workgroups_read | Yes |
Create/Modify Workgroups | Create or edit workgroups in your team | workgroups_write | Yes |
View Workgroup Members | View the members in a workgroup | workgroups_members_read | Yes |
Create/Modify Workgroup Members | Add or remove members from a workgroup | workgroups_members_write | Yes |
View Roles | View the roles available to assign to members in your team | roles_read | Yes |
Create/Modify Roles | Create or edit roles for your team | roles_write | Yes |
View Workgroups Shared Resources | View resources shared within a workgroup | workgroups_shares_read | Yes |
Create/Modify Workgroups Shared Resources | Add or remove resources shared within a workgroup | workgroups_shares_write | Yes |
Request and Response Limits
Draft and Private apps are subject to rate limits:
Max Requests Per Minute | Requests per day* (starting at) |
---|---|
120 | 500 *Sign in to view limits |
The API limit is reset at 12:00 AM Greenwich Mean Time (GMT) every day. We permit three violations of up to 150% within a 30-day window. We begin to enforce limits at 100% once your app exceeds its limits three times within 30 days.
We return your app’s rate limits, requests remaining, and seconds to reset in our request headers.
In addition, requests made to the API to create contacts or send invite messages are subject to our sending and contact limits.
Increasing Limits
All Draft and Private apps will initially be subject to request limits of 120 calls/minute and starting at 500 calls/day (contact sales). If you think you may be in danger of exceeding your request-limit threshold and only require a temporary increase contact our help center otherwise, click here and then the “Talk with us” button to contact our Enterprise Sales Team. SurveyMonkey will review all requests within 5 business days. Additional fees may apply for increased rate limits.
Response Limits
We also have global response limits for database utilization fair use.
Property | Limit |
---|---|
Max Page Size | 1000 resources, unless otherwise specified |
Max Survey Size | 1000 questions, surveys over limit will return a 413 |
Authentication
If you have a Private app and will only access your own SurveyMonkey account, you can use the access token, generated when you registered your app, as part of your app’s configuration. Obtain this token in the Settings of your app in the MY APPS tab.
If your app will access many SurveyMonkey accounts, implement the OAuth 2.0 three-step flow outlined below to allow users to authorize your app to access their accounts. This flow generates a long-lived access token your app can use with every API call to the associated SurveyMonkey account. It’s important to note the access token only grants access when used in combination with your API credentials (client ID) and only to the SurveyMonkey account which was authorized. Your app will need to obtain additional access tokens for each SurveyMonkey account you wish to access.
If your app has required scopes, users will need to approve all of them and may need a paid SurveyMonkey plan to successfully OAuth into your app.
OAuth 2.0 Flow
Step 1: Direct user to SurveyMonkey’s OAuth authorization page
Your app should send the user whose SurveyMonkey account you wish to access to a specially crafted OAuth link at https://api.surveymonkey.com. The page presented to the user will identify your app, ask them to log into SurveyMonkey if they aren’t already, and ask them to authorize any required scopes.
The OAuth link should be https://api.surveymonkey.com/oauth/authorize
with urlencoded parameters: redirect_uri
, client_id
, response_type
and state
.
response_type
will always be set to the valuecode
client_id
the unique SurveyMonkey client id you got when registering your appredirect_uri
URL encoded OAuth redirect URI you registered for your app (can be found and edited here)state
(recommended) A value included in the request that will also be returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks.
Example OAuth Link
https://api.surveymonkey.com/oauth/authorize?response_type=code&redirect_uri=https%3A%2F%2Fapi.surveymonkey.com%2Fapi_console%2Foauth2callback&client_id=SurveyMonkeyApiConsole%2Fstate=uniquestring
SM_API_BASE = "https://api.surveymonkey.com"
AUTH_CODE_ENDPOINT = "/oauth/authorize"
def oauth_dialog(client_id, redirect_uri):
url_params = urllib.urlencode({
"redirect_uri": redirect_uri,
"client_id": client_id,
"response_type": "code"
})
auth_dialog_uri = SM_API_BASE + AUTH_CODE_ENDPOINT + "?" + url_params
print "\nThe OAuth dialog url was " + auth_dialog_uri + "\n"
# Insert code here that redirects user to OAuth Dialog url
var SM_API_BASE = "https://api.surveymonkey.com";
var AUTH_CODE_ENDPOINT = "/oauth/authorize";
function oauth_dialog(client_id, redirect_uri) {
var auth_dialog_uri = SM_API_BASE + AUTH_CODE_ENDPOINT + "?redirect_uri=" + redirect_uri + "&client_id=" + client_id + "&response_type=" + code;
// Insert code here that redirects user to OAuth Dialog url
}
Step 2: User authorization generates short-lived code
Once the user makes their choice whether to authorize access or not, SurveyMonkey will generate a 302 redirect sending their browser to your redirect URI along with a short-lived code included as a query parameter (as well as the state parameter if it was specified originally). Your app needs to use that code to make another API request before it expires (5 minutes). In that request, you’ll send us the code you received, along with your client secret, client ID, and redirect URI. We’ll verify all that information. If it’s good, we’ll return a long-lived access token in exchange.
Generate Short Code or Deny Access
"Access Authorized" redirect: `https://api.surveymonkey.com/api_console/oauth2callback?code=SHORTLIVEDCODE&state=uniquestring`
"Access Denied" redirect: `https://api.surveymonkey.com/api_console/oauth2callback?error_description=Resource+owner+canceled+the+request&error=access_denied`
def handle_redirect(redirect_uri):
# Parse authorization code out of url
query_string = urlparse.urlsplit(redirect_uri).query
authorization_code = urlparse.parse_qs(query_string).get("code", [])
# parse_qs returns a list for every query param, just get the first one
if not authorization_code:
return
return authorization_code[0]
function handle_redirect(redirect_uri) {
// Parse authorization code out of url
var urlParams = new URLSearchParams(window.location.search);
return urlParams.get('code');
}
Step 3: Exchanging for a long-lived access token
Create a form-encoded HTTP POST request to https://api.surveymonkey.com/oauth/token
with the following encoded form fields: client_id
, client_secret
, code
, redirect_uri
and grant_type
. The grant type must be set to “authorization_code”. The client_secret
can be found here.
If successful, the access token will be returned encoded as JSON in the response body of your POST request. The key will be access_token
and the value can be passed to our API as an HTTP header in the format Authorization: bearer YOUR_ACCESS_TOKEN
. The value of the header must be “bearer” followed by a single space and then your access token.
Exchange for long-lived token
curl -i -X POST https://api.surveymonkey.com/oauth/token -d \
"client_secret=YOUR_CLIENT_SECRET \
&code=AUTH_CODE \
&redirect_uri=YOUR_REDIRECT_URI \
&client_id=YOUR_CLIENT_ID \
&grant_type=authorization_code"
SM_API_BASE = "https://api.surveymonkey.com"
ACCESS_TOKEN_ENDPOINT = "/oauth/token"
def exchange_code_for_token(auth_code, client_secret, client_id, redirect_uri):
data = {
"client_secret": client_secret,
"code": auth_code,
"redirect_uri": redirect_uri,
"client_id": client_id,
"grant_type": "authorization_code"
}
access_token_uri = SM_API_BASE + ACCESS_TOKEN_ENDPOINT
access_token_response = requests.post(access_token_uri, data=data)
access_json = access_token_response.json()
if "access_token" in access_json:
return access_json["access_token"]
else:
print access_json
return None
var SM_API_BASE = "https://api.surveymonkey.com";
var ACCESS_TOKEN_ENDPOINT = "/oauth/token";
async function exchange_code_for_token(auth_code, client_secret, client_id, redirect_uri) {
var data = {
"client_secret": client_secret,
"code": auth_code,
"redirect_uri": redirect_uri,
"client_id": client_id,
"grant_type": "authorization_code"
}
access_token_uri = SM_API_BASE + ACCESS_TOKEN_ENDPOINT;
var access_token_response = await fetch(access_token_uri, {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": JSON.stringify(data)
});
var access_json = access_token_response.json();
return access_json["access_token"];
}
Token expiration and revocation
Our access tokens don’t currently expire but may in the future. We’ll warn all developers before making changes.
Access tokens can be revoked by the user. If this happens, you’ll get a JSON-encoded response body including a key status
with a value of 1
and a key errmsg
with the value of Client revoked access grant
when making an API request. If you get this response, you’ll need to complete OAuth again.
Access URL
Depending on the originating datacenter of the SurveyMonkey account, the API access URL may be different than https://api.surveymonkey.com
.
The API for the EU datacenter is https://api.eu.surveymonkey.com
and the API for the Canadian datacenter is https://api.surveymonkey.ca
.
The correct API access URL for each SurveyMonkey account is returned in the response body of the code for token exchange under the access_url
key.
Unauthorizing an app
To unauthorize an app:
- Log into the linked SurveyMonkey account
- Select My Account from the username dropdown in the upper right
- Scroll to Linked Accounts and click Remove next to the app you want to unauthorize
Quick Start Guide: Two Common Use Cases
Export the Results of a Survey
While a call to /surveys/{id}/responses/bulk returns responses with ids for all answers chosen, your use case likely involves associating this with the values chosen. The following example takes you through exporting the results of a survey and associating responses with the corresponding answer values.
- Fetch the first 1,000 surveys in a SurveyMonkey account with a GET /surveys. This call returns a list resource containing survey ids.
- Using a survey id from the previous call, make a GET to /surveys/{id}/details. This call returns the survey’s design with all question ids and answer option ids, as well as the values associated with them. Cache these values on your end to limit future calls and economize your request and response limits.
- Using the same survey id, fetch the first 100 responses to your survey with a GET to /surveys/{id}/responses/bulk?per_page=100. This endpoint returns question ids and the id of the selected answer or choice for each response. You can use these to associate the selected answer id to those returned from your GET to /surveys/{id}/details and match question values to the answers selected.
- Fetch the next page of 100 responses using the resource url returned in the
links.next
field.
To export the results of all surveys in an account, iterate through all surveys ids returned in step 1, completing steps 2 through 4.
To export the results of a single collector, a GET to /surveys/{id}/collectors returns a list collector ids associated with a given survey. A GET to /surveys/{id}/details returns responses from a single collector.
Send an Email Invitation Message
The following example takes you through creating an Email Invitation Collector and sending it to a list of recipients.
- Fetch the first 1,000 surveys in a SurveyMonkey account with a GET /surveys. This call returns a list resource containing survey ids.
- Using a survey id from the previous call, create a collector of type
email
by making a POST to /surveys/{id}/collectors. - Create and format an email message with a POST to /collectors/{id}/messages.
- Upload recipients to receive the message with a POST to /collectors/{id}/messages/{id}/recipients/bulk.
- Send your message with a POST to /collectors/{id}/messages/{id}/send.
Pagination
When requesting list resources, you can set the size of a page by using per_page=#
and indicate which page to return with page=#
. So a request to https://api.surveymonkey.com/v3/surveys?page=2&per_page=5
will return the second page of five surveys.
Any request to a list resource returns the following pagination fields, if available:
Name | Description | Type |
---|---|---|
per_page | Number of resources per page | Integer |
total | Total number of resources available | Integer |
page | Indicates which page is being returned | Integer |
links.self | Resource URL for the current page | String |
links.prev | Resource URL for the previous page of results | String |
links.next | Resource URL for the subsequent page of results | String |
links.first | Resource URL for the first page of results | String |
links.last | Resource URL for the last page of results | String |
Headers
Our API returns the following custom headers:
Header | Description |
---|---|
X-OAuth-Scopes-Available | Which scopes are available to the user using an app |
X-OAuth-Scopes-Granted | Which scopes the user has granted permission to, to the app |
X-Ratelimit-App-Global-Day-Limit | Per day request limit the app has |
X-Ratelimit-App-Global-Day-Remaining | Number of remaining requests app has before hitting daily limit |
X-Ratelimit-App-Global-Day-Reset | Number of seconds until the rate limit remaining resets |
X-Ratelimit-App-Global-Minute-Limit | Per minute request limit the app has |
X-Ratelimit-App-Global-Minute-Remaining | Number of remaining requests app has before hitting per minute limit |
X-Ratelimit-App-Global-Minute-Reset | Number of seconds until the rate limit remaining resets |
Data Types
Our API uses the following data types:
Data Type | Description |
---|---|
Integer | An integer number with a maximum value of 2147483647. Negatives are disallowed unless otherwise specified. |
String | A string of text. |
String-ENUM | Predefined string values. Values are defined per field throughout our documentation. |
Boolean | A boolean value: true or false. In JSON it will be represented using the native boolean type. |
Date string | Dates are usually in the format YYYY-MM-DDTHH:MM:SS+HH:MM. Any deviations from this are shown in the documentation. All date strings are implicitly in UTC. |
Phone number string | Phone numbers must be in the format +1XXXYYYZZZZ |
Hex string | Must be in the format #HHH or #HHHHHH where each H represents hexadecimal format |
Array | A simple list of values. In JSON this will be an array. |
Object | A collection of name/value pairs. In JSON this will be an object. |
Null | A null value. In JSON this is represented as the native null type. |
Error Codes
Example Error Response
{
"error": {
"docs": "https://developer.surveymonkey.com/api/v3/#error-codes",
"message": "Oh bananas! We couldn’t process your request.",
"id": "1050",
"name": "Internal Server Error",
"http_status_code": 500
}
}
Error Code | HTTP Status Code | Message |
---|---|---|
1000 | 400 Bad Request | Unable to process the request with the provided input. |
1001 | 400 Bad Request | The body provided was not a proper JSON string. |
1002 | 400 Bad Request | Invalid schema in the body provided. |
1003 | 400 Bad Request | Invalid URL parameters. |
1004 | 400 Bad Request | Invalid request headers. |
1005 | 402 Payment Required | Account must be upgraded to access this feature. |
1010 | 401 Authorization Error | The authorization token was not provided. |
1011 | 401 Authorization Error | The authorization token provided was invalid. |
1012 | 401 Authorization Error | The authorization token provided has expired. |
1013 | 401 Authorization Error | Client revoked access to the authorization token provided. |
1014 | 403 Permission Error | Permission has not been granted by the user to make this request. |
1015 | 403 Permission Error | The user does not have the required plan to make this request. |
1016 | 403 Permission Error | The user does not have permission to access the resource. |
1017 | 403 Permission Error | The user has hit a quota limit on this resource. |
1018 | 403 Permission Error | The user does not have permission to access the host in this region. See Access URL |
1020 | 404 Resource Not Found | There was an error retrieving the requested resource. |
1025 | 409 Resource Conflict | Unable to complete the request due to a conflict. Check the settings for the resource. |
1026 | 409 Resource Conflict | The requested resource already exists. |
1030 | 413 Request Entity Too Large | The requested entity is too large, it can not be returned. |
1040 | 429 Rate Limit Reached | Too many requests were made, try again later. |
1050 | 500 Internal Server Error | Oh bananas! We couldn’t process your request. |
1051 | 503 Internal Server Error | Service unreachable. Please try again later. |
1052 | 404 User Soft Deleted | The user you are making this request for has been soft deleted. |
1053 | 410 User Deleted | The user you are making this request for has been deleted. |
1054 | 502 Bad Gateway Error | Network was unable to connect to server. |
1055 | 504 Gateway Timeout | Service connection has timed out. Please try again later. |
1056 | 400 Bad Request | Too many recipients supplied for this message. |
1057 | 401 Authorization Error | Authorization token has no grants. |
1058 | 403 Permission Error | The user’s email must be verified before performing this request. |
1059 | 400 Bad Request | Trying to send a Message but no recipient was provided |
1060 | 400 Bad Request | Embedded Body not saved |
1061 | 405 Method Not Allowed | The specified HTTP method is not allowed. |
1062 | 400 Bad Request | Request limit exceeded for this resource |
1063 | 401 Bad Unauthorized | User is not authorized to perform this action. Please review the request details and try again. |
Help and Resources
SurveyMonkey lists code examples on Github. If you have an SDK or example you would like added, let us know. We also offer support through our help center.
API Endpoints
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Base URLs:
Default
Users and Teams
Use these endpoints to get user’s account information, any teams a user belongs to, the account information for the team’s owner, and other members including their roles and whether or not they have accepted an invite into the team (are active
).
GET /users/me
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/users/me \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/users/me", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/users/me", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /users/me
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns the current user’s account details including their plan. Public App users need access to the View Users scope parameters:
Example Response for GET /users/me
{
"id": "1",
"username": "username",
"first_name": "firstName",
"last_name": "lastName",
"language": "en",
"email": "firstnamelastname@surveymonkey.com",
"email_verified": false,
"account_type": "enterprise",
"date_created": "2021-05-27T16:29:00+00:00",
"date_last_login": "2021-06-21T13:57:15.657000+00:00",
"question_types": {
"comment_box_question_type": true,
"file_upload_question_type": true,
"matrix_question_type": true,
"ranking_question_type": true,
"rating_question_type": false,
"slider_question_type": true,
"star_rating_question_type": true,
"textbox_multiple_question_type": true,
"video_question_type": false
},
"scopes": {
"granted": [
"surveys_write",
"surveys_read"
],
"available": [
"users_read",
"surveys_read",
"collectors_read",
"collectors_write",
"contacts_read",
"contacts_write",
"surveys_write",
"responses_read",
"responses_read_detail",
"responses_write",
"groups_read",
"groups_write",
"webhooks_read",
"webhooks_write",
"library_read",
"workgroups_read",
"workgroups_write",
"workgroups_members_read",
"workgroups_members_write",
"roles_read",
"roles_write",
"workgroups_shares_read",
"workgroups_shares_write"
]
},
"sso_connections": [
"enterprise_saml"
],
"features": {
"collector_create_limit": "unlimited",
"collector_email_enabled": true,
"collector_thank_you_enabled": true,
"create_question_limit": "unlimited",
"num_free_responses": "unlimited"
},
"href": "https://api.surveymonkey.com/v3/users/me"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | User Id |
username | string | Username |
first_name | string | User’s first name |
last_name | string | User’s last name |
language | string | ISO 639-1 code for the language set for the user’s account |
string | Email address for user’s account | |
email_verified | boolean | Email address for user’s account has been verified |
account_type | string | The user’s SurveyMonkey plan |
date_created | string | Date user’s account was created |
date_last_login | string | Date user last logged in |
question_types | object | Question types available to the user, identified by boolean values |
scopes | object | Contains the scopes the user has available to them, and the scopes that are granted |
granted | [string] | Lists the scopes the user has approved during OAuth |
available | [string] | Lists the scopes available to the user |
sso_connections | [string] | Third-party connections |
features | object | Features available to the user. They are identified by string or boolean values. |
href | string | The link associated with this endpoint |
GET /users/{user_id}/workgroups
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/users/1234/workgroups \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/users/1234/workgroups", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/users/1234/workgroups", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /users/{user_id}/workgroups
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns the workgroups that a specific user is in. Public App users need access to the View Workgroups scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | string | false | Number of resources to return per page. Defaults to 50 |
page | string | false | Which page of resources to return. Defaults to 1 |
Example Response for GET /users/{user_id}/workgroups
{
"data": [
{
"id": "1",
"name": "name",
"description": "some description",
"is_visible": true,
"metadata": {},
"created_at": "2019-05-22T17:38:58",
"updated_at": "2020-07-29T20:32:33",
"members": [
{
"user_id": "2",
"is_owner": true
},
{
"user_id": "1",
"is_owner": false
}
],
"membership": {
"status": "active",
"is_owner": true
},
"shares_count": 3,
"members_count": 2,
"default_role": {
"id": "2",
"name": "Viewer",
"description": "",
"is_enabled": true,
"metadata": {}
},
"organization_id": "1"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/users/2/workgroups?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | Contains the information associated with the workgroups |
id | string | ID of the user |
name | string | Name of the workgroup |
description | string | Description of the workgroup |
is_visible | boolean | Whether the workgroup is publicly visible or only visible to its members and administrators |
metadata | object | Extra data related to the workgroup |
created_at | string | Datetime when the workgroup was created |
updated_at | string | Datetime when the workgroup was last updated |
members | [object] | The active members of the workgroup |
user_id | string | The user ID of the active member |
is_owner | boolean | The active member is the owner of the workgroup |
membership | object | Membership information for the requested user |
is_owner | boolean | The user is the owner of the workgroup |
status | string | The status of the user. One of [active , pending ] |
shares_count | integer | Number of resources shared with the workgroup |
members_count | integer | Number of members in the workgroup (includes non-active) |
default_role | object | The default role for the workgroup |
id | string | ID of the workgroup |
name | string | The type of the default role. One of Analyzer , Collector , Full Access , Viewer , Editor |
description | string | Extra information about the default role |
is_enabled | boolean | The default role is enabled |
metadata | object | Extra metadata of the default role |
organization_id | string | The ID of the organization this workgroup belongs to. |
per_page | integer | Number of resources returned per page |
page | integer | Page of the resources returned |
total | integer | Number of workgroups returned |
links | object | Contains this endpoint’s links |
self | string | The link associated with this endpoint |
GET /users/{user_id}/shared
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/users/1234/shared \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/users/1234/shared", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/users/1234/shared", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /users/{user_id}/shared
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns the resources shared with the user across all workgroups. Public App users need access to the View Workgroup Shares scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | string | false | Number of resources to return per page. Defaults to 50 |
page | string | false | Which page of resources to return. Defaults to 1 |
resource_type | string | false | The type of the shared resource, one of: survey |
resource_id | string | false | Comma-separated IDs of shared resources (must be used with resource_type) |
include | string | false | Specify additional fields to return for each resource. One of permissions , resource_details . permissions shows collector and survey action permissions of each workgroup and resource_details shows more information about each shared resource |
Example Response for GET /users/{user_id}/shared
{
"data": [
{
"share_id": "0ca749c2893245c5b96a128eee4c2d42",
"workgroup_id": "71d9d408d1914c9ca85ffcda8330d675",
"resource_type": "survey",
"resource_id": "101101101",
"privileges": [
"design.read_only",
"collect.read_only",
"analyze.read_only"
]
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/users/61003234/shared?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | Contains the shared resources with their information |
share_id | string | ID of the share record |
workgroup_id | string | ID of the workgroup that was shared with |
resource_type | string | The type of the shared resource (e.g. survey ) |
resource_id | string | The ID of the shared resource (e.g. the ID of a survey) |
privileges | [string] | An array of scoped privileges granted to the user by this share record |
per_page | integer | Number of resources returned per page |
page | integer | Page of the resource returned |
total | integer | Number of shared resources returned |
links | object | Contains this endpoint’s links |
self | string | The link associated with this endpoint |
GET /groups
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/groups \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/groups", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /groups
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of groups. Public App users need access to the View Teams scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | integer | false | Number of resources to return per page. Defaults to 50 |
page | integer | false | Which page of resources to return. Defaults to 1 |
Example Response for GET /groups
{
"data": [
{
"href": "https://api.surveymonkey.com/v3/groups/1231511",
"id": "1231511",
"name": "Your Group"
}
],
"links": {
"self": "https://api.surveymonkey.com/v3/groups?per_page=50&page=1"
},
"page": 1,
"per_page": 50,
"total": 1
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
total | integer | |
page | integer | |
data | [object] | |
id | string | Group id |
href | string | Resource API URL |
name | string | Group name |
links | object | |
self | string |
GET /groups/{group_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/groups/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/groups/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /groups/{group_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns group information. Public App users need access to the View Teams scope
Example Response for GET /groups/{group_id}
{
"date_created": "2333-01-07T21:27:32+00:00",
"href": "https://api.surveymonkey.com/v3/groups/123",
"id": "123",
"max_invites": 0,
"member_count": 10,
"name": "Group Name"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
date_created | string | |
href | string | |
id | string | |
max_invites | integer | |
member_count | integer | |
name | string |
GET /groups/{group_id}/activities
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/groups/1234/activities \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/groups/1234/activities", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups/1234/activities", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /groups/{group_id}/activities
Available Methods
GET
: Returns a list of activity related data for the specified group. Public App users must be admin.
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
limit | integer | false | amount of activites returned |
offset | integer | false | offset of the returned list |
start_date | string | false | the start date of activites |
end_date | string | false | list all activites up to the end date |
Example Response for GET /groups/{group_id}/activities
{
"limit": 2,
"offset": 0,
"results": [
{
"activity_msg": "<span>Installed app <span class=\"notranslate\"><b>mpt testing</b></span></span>",
"activity_type": "grant_info_created",
"city": null,
"country": null,
"date_created": "2023-12-05 20:49:49",
"division_name": null,
"email": "test@surveymonkey.com",
"group_id": 2093412,
"ip_address": null,
"member_type": "<span>(Primary Admin)</span>",
"user_id": 12312,
"user_name": "Testing"
}
],
"sl_translate": "activity_msg,member_type",
"total": 1932
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
limit | integer | |
offset | integer | |
sl_translate | string | |
total | integer | |
results | [object] | |
activity_msg | string | |
activity_type | string | |
city | string | |
country | string | |
date_created | string | |
division_name | string | |
string | ||
group_id | integer | |
ip_address | string | |
member_type | string | |
user_id | integer | |
user_name | string |
GET /groups/{group_id}/activities/{action_type}
Code samples
curl --request GET \
--url 'https://api.surveymonkey.com/v3/groups/1234/activities/member_joined?interval=daily' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/groups/1234/activities/member_joined?interval=daily", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups/1234/activities/member_joined?interval=daily", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /groups/{group_id}/activities/{action_type}
Available Methods
GET
: Returns a count of a specific activity by interval for the specified group given an action type enum value. Public App users must be admin
Action Type Enum Values
- authentication_succeeded
- authentication_failed
- authentication_signout
- group_info_updated_group_name
- invite_created
- invite_resent
- member_deleted
- member_joined
- survey_info_create
- survey_info_delete
- survey_info_copy
- survey_info_update
- survey_info_transfer
- collector_info_created
- collector_info_deleted
- collector_info_updated
- member_updated_group_member_type
- permission_created
- permission_updated
- shared_view_created
- shared_view_updated
- export_export_create
- export_downloaded
- respondent_updated
- respondent_deleted
- grant_info_created
- grant_info_deleted
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
interval | string | true | The selected timing interval of the chosen action type |
start_date | string | false | the start date of activites |
end_date | string | false | list all activites up to the end date |
Enumerated Values
Parameter | Value |
---|---|
interval | daily |
interval | weekly |
interval | monthly |
interval | yearly |
Example Response for GET /groups/{group_id}/activities/{action_type}
{
"interval": "yearly",
"series": [
2,
7
],
"times": [
"2023",
"2022"
]
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
interval | string | |
series | [integer] | |
times | [string] |
GET /groups/{group_id}/members
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/groups/1234/members \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/groups/1234/members", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups/1234/members", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /groups/{group_id}/members
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of users who have been added as members of the specified group. Public App users need access to the View Teams scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | integer | false | Number of resources to return per page. Defaults to 50 |
page | integer | false | Which page of resources to return. Defaults to 1 |
division_ids | string | false | optional list of member ids |
include | string | false | whether or not to include properties options are first_name, last_name, user_id, email, type, language, status |
Detailed descriptions
include: whether or not to include properties options are first_name, last_name, user_id, email, type, language, status
Example Response for GET /groups/{group_id}/members
{
"data": [
{
"id": "1",
"username": "user1",
"href": "https://api.surveymonkey.com/v3/groups/1/members/1"
},
{
"id": "2",
"username": "user2",
"href": "https://api.surveymonkey.com/v3/groups/1/members/2"
}
],
"per_page": 50,
"page": 1,
"total": 2,
"links": {
"self": "https://api.surveymonkey.com/v3/groups/1/members?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
total | integer | |
data | [object] | |
id | string | Member id |
href | string | Resource API URL |
username | string | Member username |
links | object | |
self | string | |
page | integer |
GET /groups/{group_id}/members/{member_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/groups/1234/members/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/groups/1234/members/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups/1234/members/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /groups/{group_id}/members/{member_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a group member’s details including theirrole
andstatus
. Public App users need access to the View Teams scope
Example Response for GET /groups/{group_id}/members/{member_id}
{
"id": "1",
"username": "username",
"email": "username@surveymonkey.com",
"type": "regular",
"status": "active",
"user_id": "1",
"language": "en",
"first_name": "firstname",
"last_name": "lastname",
"date_created": "2021-06-24T18:27:33+00:00",
"href": "https://api.surveymonkey.com/v3/groups/1/members/1"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
user_id | string | User ID of the group member |
date_created | string | Date and time when member was created |
last_name | string | |
language | string | |
id | string | Member id |
href | string | |
type | string | Which type of role the member has: regular , account_owner , or admin |
first_name | string | |
string | User’s email address | |
username | string | Member username |
status | string | A members status (if they have accepted an invitation into the group): active , pending |
PATCH /groups/{group_id}/members/{member_id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/groups/1234/members/1234 \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"email":"string"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"email\":\"string\"}"
headers = {
'Content-Type': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/groups/1234/members/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups/1234/members/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"email\":\"string\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /groups/{group_id}/members/{member_id}
PATCH
: Update a group members email address
GET /workgroups
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/workgroups \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/workgroups", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/workgroups", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /workgroups
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of all workgroups that are available. Public App users need access to the View Workgroup Shares scopePOST
: Add a new shared resource to the workgroup. Public App users need access to the Create/Modify Workgroup Shares scope
200 Response
{
"data": [
{
"created_at": "string",
"default_role": {
"description": "string",
"id": "string",
"is_enabled": true,
"metadata": {},
"name": "string"
},
"id": "string",
"description": "string",
"is_visible": true,
"members": [
{
"is_owner": true,
"user_id": "string"
}
],
"members_count": 0,
"membership": {
"is_owner": true,
"status": "string"
},
"name": "string",
"organization_id": "string",
"share_count": "string",
"updated_at": "string"
}
],
"per_page": 0,
"page": 0,
"total": 0,
"links": {
"self": "string"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | Contains the list of workgroups |
created_at | string | date and time when the workgroup group was created |
default_role | object | The default role for the workgroup |
description | string | |
id | string | |
is_enabled | boolean | |
metadata | object | |
name | string | |
id | string | ID of the workgroup that was shared with |
description | string | Description of the workgroup |
is_visible | boolean | Visablity status of the workgroup |
members | [object] | |
is_owner | boolean | |
user_id | string | |
members_count | integer | amount of memebers in the workgroup |
membership | object | The current user membership status in the workgroup |
is_owner | boolean | |
status | string | |
name | string | The name of the workgroup |
organization_id | string | The ID of the organization |
share_count | string | The amount of shared resources with this group |
updated_at | string | The last time the workgroup was updated |
per_page | integer | Number of resources returned per page |
page | integer | Page of the resource returned |
total | integer | Number of shared resources returned |
links | object | Contains this endpoint’s links |
self | string | The link associated with this endpoint |
POST /workgroups
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/workgroups \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"Brand Awareness","description":"Spreading the company brand","is_visible":true,"metadata":{}}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"name\":\"Brand Awareness\",\"description\":\"Spreading the company brand\",\"is_visible\":true,\"metadata\":{}}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/workgroups", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/workgroups", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"name\":\"Brand Awareness\",\"description\":\"Spreading the company brand\",\"is_visible\":true,\"metadata\":{}}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /workgroups
Body parameter
{
"name": "Brand Awareness",
"description": "Spreading the company brand",
"is_visible": true,
"metadata": {}
}
Request Body for POST /workgroup
Name | Type | Required | Description |
---|---|---|---|
name | string | true | Name of the workgroup |
is_visible | boolean | true | visiblilty of the workgroup to other org members |
metadata | object | undefined | Key-pair data that can be attached to the workgroup. This is a required field. |
Example Response for POST /workgroups
{
"created_at": "2022-12-01T18:03:45",
"default_role": {
"description": "",
"id": "40825440989a41cfaf8c50704",
"is_enabled": true,
"metadata": {},
"name": "Full Access"
},
"description": "Spreading the company brand",
"id": "9bccda1faa0d45363edb7fc22",
"is_visible": true,
"members": [
{
"is_owner": true,
"user_id": "101592"
}
],
"members_count": 1,
"membership": {
"is_owner": true,
"status": "active"
},
"metadata": {
"something": "ok"
},
"name": "Creating workgroup via api",
"organization_id": "2112",
"shares_count": 0,
"updated_at": "2022-12-05T18:03:45"
}
Response Schema
Status Code 201
Name | Type | Description |
---|---|---|
data | [object] | Contains the list of workgroups |
created_at | string | date and time when the workgroup group was created |
default_role | object | The default role for the workgroup |
description | string | |
id | string | |
is_enabled | boolean | |
metadata | object | |
name | string | |
id | string | ID of the workgroup that was shared with |
description | string | Description of the workgroup |
is_visible | boolean | Visablity status of the workgroup |
members | [object] | |
is_owner | boolean | |
user_id | string | |
members_count | integer | amount of memebers in the workgroup |
membership | object | The current user membership status in the workgroup |
is_owner | boolean | |
status | string | |
name | string | The name of the workgroup |
organization_id | string | The ID of the organization |
share_count | string | The amount of shared resources with this group |
updated_at | string | The last time the workgroup was updated |
GET /workgroups/{workgroup_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/workgroups/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/workgroups/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/workgroups/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /workgroups/{workgroup_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns information on the selected workgroup View Workgroup Shares scopePATCH
: modify information on the workgroup. Public App users need access to the Create/Modify Workgroup Shares scopeDELTE
: Remove the workgroup. Public App users need access to the Create/Modify Workgroup Shares scope
Example Response for GET /workgroups/{workgroup_id}/shares
{
"created_at": "2022-02-24T19:36:28",
"default_role": {
"description": "",
"id": "40825449a41cfaf8c50df160bf704",
"is_enabled": true,
"metadata": {},
"name": "Full Access"
},
"description": "Spreading the company brand",
"id": "8bd869a4ac84d945fa7d16e",
"is_visible": false,
"members": [
{
"is_owner": true,
"user_id": "91111084"
}
],
"members_count": 1,
"membership": {
"is_owner": false,
"status": null
},
"metadata": {},
"name": "sample test workgroup3",
"organization_id": "211112",
"shares_count": 0,
"updated_at": "2022-03-24T19:36:28"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
created_at | string | date and time when the workgroup group was created |
default_role | object | The default role for the workgroup |
description | string | |
id | string | |
is_enabled | boolean | |
metadata | object | |
name | string | |
id | string | ID of the workgroup that was shared with |
description | string | Description of the workgroup |
is_visible | boolean | Visablity status of the workgroup |
members | [object] | |
is_owner | boolean | |
user_id | string | |
members_count | integer | amount of memebers in the workgroup |
membership | object | The current user membership status in the workgroup |
is_owner | boolean | |
status | string | |
name | string | The name of the workgroup |
organization_id | string | The ID of the organization |
share_count | string | The amount of shared resources with this group |
updated_at | string | The last time the workgroup was updated |
PATCH /workgroups/{workgroup_id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/workgroups/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"Patching the company brand","description":"string","is_visible":false,"metadata":{}}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"name\":\"Patching the company brand\",\"description\":\"string\",\"is_visible\":false,\"metadata\":{}}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/workgroups/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/workgroups/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"name\":\"Patching the company brand\",\"description\":\"string\",\"is_visible\":false,\"metadata\":{}}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /workgroups/{workgroup_id}
Body parameter
{
"name": "Patching the company brand",
"description": "string",
"is_visible": false,
"metadata": {}
}
Request Body for POST /workgroup
Name | Type | Required | Description |
---|---|---|---|
name | string | false | Name of the workgroup |
is_visible | boolean | false | visiblilty of the workgroup to other org members |
metadata | object | undefined | Key-pair data that can be attached to the workgroup |
Example Response for PATCH /workgroups/{workgroup_id}/shares
{
"created_at": "2022-02-24T19:36:28",
"default_role": {
"description": "",
"id": "40825449a41cfaf8c50df160bf704",
"is_enabled": true,
"metadata": {},
"name": "Full Access"
},
"description": "Spreading the company brand",
"id": "8bd869a4ac84d945fa7d16e",
"is_visible": false,
"members": [
{
"is_owner": true,
"user_id": "91111084"
}
],
"members_count": 1,
"membership": {
"is_owner": false,
"status": null
},
"metadata": {},
"name": "sample test workgroup3",
"organization_id": "211112",
"shares_count": 0,
"updated_at": "2022-03-24T19:36:28"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
created_at | string | date and time when the workgroup group was created |
default_role | object | The default role for the workgroup |
description | string | |
id | string | |
is_enabled | boolean | |
metadata | object | |
name | string | |
id | string | ID of the workgroup that was shared with |
description | string | Description of the workgroup |
is_visible | boolean | Visablity status of the workgroup |
members | [object] | |
is_owner | boolean | |
user_id | string | |
members_count | integer | amount of memebers in the workgroup |
membership | object | The current user membership status in the workgroup |
is_owner | boolean | |
status | string | |
name | string | The name of the workgroup |
organization_id | string | The ID of the organization |
share_count | string | The amount of shared resources with this group |
updated_at | string | The last time the workgroup was updated |
GET /workgroups/{workgroup_id}/shares
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/v3/workgroups/1234/shares \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/v3/workgroups/1234/shares", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/v3/workgroups/1234/shares", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /v3/workgroups/{workgroup_id}/shares
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns the resources shared with the user across all workgroups. Public App users need access to the View Workgroup Shares scopePOST
: Add a new shared resource to the workgroup. Public App users need access to the Create/Modify Workgroup Shares scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | string | false | Number of resources to return per page. Defaults to 50 |
page | string | false | Which page of resources to return. Defaults to 1 |
Example Response for GET /workgroups/{workgroup_id}/shares
{
"per_page": 50,
"total": 1,
"data": [
{
"workgroup_id": "71d9d408d19ffcda8330d675",
"organization_id": "54321",
"owner_user_id": "1234567",
"resource_id": "101101101",
"created_at": "2018-04-21T14:36:38",
"id": "0ca749c2893245c5b96a128eee4c2d42",
"resource_type": "survey"
}
],
"page": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/workgroups/71d9d408d19ffcda8330d675/shares?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | Contains the shared resources with their information |
workgroup_id | string | ID of the workgroup that was shared with |
organization_id | string | ID of the organization |
owner_user_id | string | User of ID of the resource owner |
resource_type | string | The type of the shared resource (e.g. survey ) |
created_at | string | The type of the shared resource (e.g. survey ) |
resource_id | string | The ID of the shared resource (e.g. the ID of a survey) |
per_page | integer | Number of resources returned per page |
page | integer | Page of the resource returned |
total | integer | Number of shared resources returned |
links | object | Contains this endpoint’s links |
self | string | The link associated with this endpoint |
POST /workgroups/{workgroup_id}/shares
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/v3/workgroups/1232141/shares \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"resource_type":"survey","resource_id":"string"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"resource_type\":\"survey\",\"resource_id\":\"string\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/v3/workgroups/1232141/shares", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/v3/workgroups/1232141/shares", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"resource_type\":\"survey\",\"resource_id\":\"string\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /v3/workgroups/{workgroup_id}/shares
Body parameter
{
"resource_type": "survey",
"resource_id": "string"
}
Request Body for POST /workgroups/{workgroup_id}/shares
Name | Type | Required | Description |
---|---|---|---|
resource_type | string | true | The type of resource that is supported, currently only sharing surveys is possible |
resource_id | string | true | The id of the resource to share |
Example Response for POST /workgroups/{workgroup_id}/shares
{
"created_at": "2020-10-37T22:30:00",
"id": "877829572434442b315097477094369",
"organization_id": "93112",
"owner_user_id": "13392",
"resource_id": "120335",
"resource_type": "survey",
"workgroup_id": "8b9a4ac84492f9c5d8d947d16e",
"workgroup_name": "sample test workgroup"
}
Response Schema
Status Code 201
Name | Type | Description |
---|---|---|
created_at | string | The date and time the share was created |
id | string | The ID of the share that was created |
organization_id | string | The ID of the organization the new shared resource belongs too |
owner_user_id | string | The ID of the User that owns the resource |
resource_id | string | The ID of the User that owns the resource |
resource_type | string | The type of resource currently, only supports surveys |
workgroup_id | string | The ID of the workgroup that the resource is shared with |
workgroup_name | string | The name of the workgroup the resources is shared too. |
GET /workgroups/{workgroup_id}/shares/{share_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/v3/workgroups/string/shares/string \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/v3/workgroups/string/shares/string", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/v3/workgroups/string/shares/string", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /v3/workgroups/{workgroup_id}/shares/{share_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a resource shared with the user across all workgroups. Public App users need access to the View Workgroup Shares scopeDELETE
: Remove a resource from being shared within a workgroup. Public App users need access to the Create/Modify Workgroup Shares scope
Example Response for GET /workgroups/{workgroup_id}/shares/{share_id}
{
"workgroup_id": "71d9d408d19ffcda8330d675",
"organization_id": "54321",
"owner_user_id": "1234567",
"resource_id": "101101101",
"created_at": "2018-04-21T14:36:38",
"id": "0ca749c2893245c5b96a128eee4c2d42",
"resource_type": "survey"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
workgroup_id | string | ID of the workgroup that was shared with |
organization_id | string | ID of the organization |
owner_user_id | string | User of ID of the resource owner |
resource_type | string | The type of the shared resource (e.g. survey ) |
created_at | date time string of when the shared resource was created | The type of the shared resource (e.g. survey ) |
resource_id | string | The ID of the shared resource (e.g. the ID of a survey) |
id | string | The ID of the share itself |
POST /workgroups/{workgroup_id}/shares/bulk
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/v3/workgroups/1232141/shares/bulk \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"shares":[{"resource_type":"survey","resource_id":"string"}]}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"shares\":[{\"resource_type\":\"survey\",\"resource_id\":\"string\"}]}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/v3/workgroups/1232141/shares/bulk", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/v3/workgroups/1232141/shares/bulk", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"shares\":[{\"resource_type\":\"survey\",\"resource_id\":\"string\"}]}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /v3/workgroups/{workgroup_id}/shares/bulk
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsPOST
: Add bulk amount of shared resource to the workgroup. Public App users need access to the Create/Modify Workgroup Shares scope
Body parameter
{
"shares": [
{
"resource_type": "survey",
"resource_id": "string"
}
]
}
Request Body for POST /workgroups/{workgroup_id}/shares/bulk
Name | Type | Required | Description |
---|---|---|---|
resource_type | string | true | The type of resource that is supported, currently only sharing surveys is possible |
resource_id | string | true | The id of the resource to share |
Example Response for POST /workgroups/{workgroup_id}/shares/bulk
{
"data": [
{
"created_at": "2023-11-27T22:30:32",
"id": "87786e957e454442b315097477094369",
"organization_id": "2093412",
"owner_user_id": "101549492",
"resource_id": "120472435",
"resource_type": "survey",
"workgroup_id": "8bd869a4ac84492f9c5d8d945fa7d16e",
"workgroup_name": "sample test workgroup3"
},
{
"created_at": "2023-11-28T19:03:05",
"id": "8c01cc349f8d69404b43f68543793",
"organization_id": "2093412",
"owner_user_id": "10492",
"resource_id": "12445",
"resource_type": "survey",
"workgroup_id": "869a4ac84492f9c5d945fa7d16e",
"workgroup_name": "sample test workgroup3"
}
],
"links": {
"self": "https://api.surveymonkey.com/v3/workgroups/8bd869a4ac84492f9c5d8d945fa7d16e/shares/bulk?per_page=50&page=1"
},
"page": 1,
"per_page": 50,
"total": 2
}
Response Schema
Status Code 201
Name | Type | Description |
---|---|---|
page | integer | |
per_page | integer | |
total | integer | |
links | object | |
self | string | |
data | [object] | |
created_at | string | The date and time the share was created |
id | string | The ID of the share that was created |
organization_id | string | The ID of the organization the new shared resource belongs too |
owner_user_id | string | The ID of the User that owns the resource |
resource_id | string | The ID of the User that owns the resource |
resource_type | string | The type of resource currently, only supports surveys |
workgroup_id | string | The ID of the workgroup that the resource is shared with |
workgroup_name | string | The name of the workgroup the resources is shared too. |
Survey Pages and Questions
Folders are used to organize surveys. The following endpoints let you retreive and create folders. Add surveys to a certain folder with a POST, PUT, or PATCH to /surveys including it’s folder_id
. You can also filter surveys by folders using folder_id
as a query parameter on GET /surveys.
GET /surveys
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of surveys owned or shared with the authenticated user. Public App users need access to the View Surveys scopePOST
: Creates a new empty survey or, if a template id or an existing survey id is specified, a survey prepopulated with pages and questions. Public App users need access to the Create/Modify Surveys scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
sort_by | string-Enum | false | Field used to sort returned survey list: title , date_modified , or num_responses |
sort_order | string-Enum | false | Sort order: ASC or DESC |
include | comma seperated string-Enum | false | Use to filter survey list: shared_with , shared_by , or owned (useful for teams) or use to specify additional fields to return per survey: response_count , date_created , date_modified , language , question_count , analyze_url , preview , collect_stats |
title | string | false | Search survey list by survey title |
start_modified_at | string | false | Surveys must be last modified after this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
end_modified_at | string | false | Surveys must be last modified before this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
folder_id | string | false | Specify the id of a folder to only return surveys in it. |
Example response for GET /surveys
{
"data": [
{
"id": "1234",
"title": "My Survey",
"nickname": "",
"href": "https://api.surveymonkey.com/v3/surveys/1234"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/surveys?page=1&per_page=50",
"next": "https://api.surveymonkey.com/v3/surveys?page=2&per_page=50",
"last": "https://api.surveymonkey.com/v3/surveys?page=5&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
total | integer | |
data | [object] | |
id | string | Id of survey |
title | string | Title of survey |
nickname | string | Survey nickname |
href | string | Resource URL for survey |
links | object | |
next | string | |
last | string | |
self | string | |
page | integer |
POST /surveys
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/surveys \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"New Survey","from_template_id":"","from_survey_id":"","from_team_template_id":"","nickname":"My Survey","language":"en","buttons_text":{"next_button":"string","prev_button":"string","exit_button":"string","done_button":"string"},"custom_variables":{},"footer":true,"folder_id":"","theme_id":1506280,"quiz_options":{"is_quiz_mode":true,"default_question_feedback":{"correct_text":"string","incorrect_text":"string","partial_text":"string"},"show_results_type":"string","feedback":{"ranges_type":"string","ranges":[{"min":0,"max":0,"message":"string"}]}},"pages":[{"questions":["See formatting question types for more details"]}]}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"New Survey\",\"from_template_id\":\"\",\"from_survey_id\":\"\",\"from_team_template_id\":\"\",\"nickname\":\"My Survey\",\"language\":\"en\",\"buttons_text\":{\"next_button\":\"string\",\"prev_button\":\"string\",\"exit_button\":\"string\",\"done_button\":\"string\"},\"custom_variables\":{},\"footer\":true,\"folder_id\":\"\",\"theme_id\":1506280,\"quiz_options\":{\"is_quiz_mode\":true,\"default_question_feedback\":{\"correct_text\":\"string\",\"incorrect_text\":\"string\",\"partial_text\":\"string\"},\"show_results_type\":\"string\",\"feedback\":{\"ranges_type\":\"string\",\"ranges\":[{\"min\":0,\"max\":0,\"message\":\"string\"}]}},\"pages\":[{\"questions\":[\"See formatting question types for more details\"]}]}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/surveys", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"New Survey\",\"from_template_id\":\"\",\"from_survey_id\":\"\",\"from_team_template_id\":\"\",\"nickname\":\"My Survey\",\"language\":\"en\",\"buttons_text\":{\"next_button\":\"string\",\"prev_button\":\"string\",\"exit_button\":\"string\",\"done_button\":\"string\"},\"custom_variables\":{},\"footer\":true,\"folder_id\":\"\",\"theme_id\":1506280,\"quiz_options\":{\"is_quiz_mode\":true,\"default_question_feedback\":{\"correct_text\":\"string\",\"incorrect_text\":\"string\",\"partial_text\":\"string\"},\"show_results_type\":\"string\",\"feedback\":{\"ranges_type\":\"string\",\"ranges\":[{\"min\":0,\"max\":0,\"message\":\"string\"}]}},\"pages\":[{\"questions\":[\"See formatting question types for more details\"]}]}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /surveys
Call Types:
Blank
: Creating a survey from scratchCopy
: Creating a survey by Copying an existing survey/templateBulk
: Creating multiple surveys at once
Body parameter
{
"title": "New Survey",
"from_template_id": "",
"from_survey_id": "",
"from_team_template_id": "",
"nickname": "My Survey",
"language": "en",
"buttons_text": {
"next_button": "string",
"prev_button": "string",
"exit_button": "string",
"done_button": "string"
},
"custom_variables": {},
"footer": true,
"folder_id": "",
"theme_id": 1506280,
"quiz_options": {
"is_quiz_mode": true,
"default_question_feedback": {
"correct_text": "string",
"incorrect_text": "string",
"partial_text": "string"
},
"show_results_type": "string",
"feedback": {
"ranges_type": "string",
"ranges": [
{
"min": 0,
"max": 0,
"message": "string"
}
]
}
},
"pages": [
{
"questions": [
"See formatting question types for more details"
]
}
]
}
Request Body for POST /surveys
Name | Type | Required | Call | Description |
---|---|---|---|---|
title | string | false | Copy Blank Bulk |
Survey title (default=“New Survey”) |
from_template_id | string | false | Copy |
Survey template to Copy from. See /survey_templates (required if from_survey_id not provided) |
from_survey_id | string | false | Copy |
Survey id to Copy from (required if from_template_id not provided) |
from_team_template_id | string | false | Copy |
Team survey template to Copy from. See /team_survey_templates |
nickname | string | false | Blank Bulk (default=’’) |
Survey nickname |
language | string | false | Blank Bulk (default=‘en’) |
Survey language |
buttons_text | object | false | Blank Bulk |
Survey Buttons text container |
next_button | string | false | Blank Bulk |
Button text |
prev_button | string | false | Blank Bulk |
Button text |
exit_button | string | false | Blank Bulk |
Button text. If set to an empty string, button will be ommitted from survey |
done_button | string | false | Blank Bulk |
Button text |
custom_variables | object | false | Blank |
Dictionary of survey variables |
footer | boolean | false | Blank |
If false, SurveyMonkey’s footer is not displayed. (default=true) |
folder_id | string | false | Blank |
If specified, adds the survey to the folder with that id. |
theme_id | integer | false | Blank |
If specified, creates the survey using the theme provided |
quiz_options | object | false | Blank |
An object describing the quiz settings, if this survey is a quiz |
is_quiz_mode | boolean | true | Blank |
On/off toggle for setting this survey as a quiz |
default_question_feedback | object | false | Blank |
An object containing the default feedback for newly created questions in this survey |
correct_text | string | true | Blank |
Text to show when answer is correct |
incorrect_text | string | true | Blank |
Text to show when answer is incorrect |
partial_text | string | true | Blank |
Text to show when answer is partially correct |
show_results_type | string | true | Blank |
What to reveal to the user when they complete the quiz: disabled , results_only or results_and_answers |
feedback | object | true | Blank |
Text to show the user when they complete the quiz |
ranges_type | string | true | Blank |
Configure whether the following parameters use percentage or points . Note that these ranges are inclusive and may not overlap |
ranges | [object] | true | Blank |
The ranges at which to show users certain feedback |
min | integer | true | Blank |
Minimum score for this feedback |
max | integer | true | Blank |
Maximum score for this feedback |
message | string | true | Blank |
Feedback message |
pages | [object] | true | Bulk |
Pages to be created |
questions | array | true | Bulk |
Questions to be created |
Example response for POST /surveys
{
"title": "New Survey",
"nickname": "",
"language": "en",
"folder_id": "0",
"category": "",
"question_count": 0,
"page_count": 1,
"response_count": 0,
"date_created": "2021-07-26T14:18:00",
"date_modified": "2021-07-26T14:18:00",
"id": "309683094",
"buttons_text": {
"next_button": "Next",
"prev_button": "Prev",
"done_button": "Done",
"exit_button": "Exit"
},
"is_owner": true,
"footer": true,
"custom_variables": {},
"href": "https://api.surveymonkey.com/v3/surveys/309683094",
"analyze_url": "https://www.surveymonkey.com/analyze/tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"edit_url": "https://www.surveymonkey.com/create/?sm=tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"collect_url": "https://www.surveymonkey.com/collect/list?sm=tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"summary_url": "https://www.surveymonkey.com/summary/tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"preview": "https://www.surveymonkey.com/r/Preview/?sm=B20TAhiT8YpGuFWTVyhmu1Rpxe5fj_2BBP0hSy_2BKVTKwuW4gN4Rf6YxaaZ5KNey_2BAv"
}
Response Schema
Status Code 201
Name | Type | Description |
---|---|---|
id | string | Survey id |
title | string | Survey title |
nickname | string | Survey nickname |
custom_variables | object | Dictionary of survey variables |
category | string | Survey category chosen when creating the survey |
language | string | ISO 639-1 code for survey language |
question_count | integer | Number of questions in survey |
page_count | integer | Number of pages in survey |
date_created | string | Date and time when survey was created. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
date_modified | string | Date and time when survey was last modified. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
buttons_text | object | |
next_button | string | Button text |
prev_button | string | Button text |
exit_button | string | Button text |
done_button | string | Button text |
preview | string | Survey preview URL |
folder_id | string | If applicable, the id of the folder the survey is in |
edit_url | string | Survey edit URL |
collect_url | string | Survey collect URL |
analyze_url | string | Survey analyze URL |
summary_url | string | Survey summary URL |
href | string | Resource API URL |
response_count | integer | Number of responses survey has received |
footer | boolean | Whether or not SurveyMonkey’s footer is not displayed |
theme_id | integer | The ID of the theme used to create the survey, if a theme was used. |
template_id | integer | The ID of the template used to create the survey, if a template was used. |
GET /surveys/{id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a survey’s details. To get an expanded version showing all pages and questions use /surveys/{survey_id}/details. Requires View Surveys scopePATCH
: Modifies a survey’s title, nickname or language. Public App users need access to the Create/Modify Surveys scopePUT
: Replaces a survey. Request body arguments the same as POST /surveys. Public App users need access to the Create/Modify Surveys scopeDELETE
: Deletes a survey. Public App users need access to the Create/Modify Surveys scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
include | comma seperated string-Enum | false | Use to specify additional information. Supported values: collect_stats for detailed collector status. |
Example response for calling GET, PUT, or PATCH /surveys
{
"title": "New Survey",
"nickname": "",
"language": "en",
"folder_id": "0",
"category": "",
"question_count": 0,
"page_count": 1,
"response_count": 0,
"date_created": "2021-07-26T14:18:00",
"date_modified": "2021-07-26T14:18:00",
"id": "309683094",
"buttons_text": {
"next_button": "Next",
"prev_button": "Prev",
"done_button": "Done",
"exit_button": "Exit"
},
"is_owner": true,
"footer": true,
"custom_variables": {},
"href": "https://api.surveymonkey.com/v3/surveys/309683094",
"analyze_url": "https://www.surveymonkey.com/analyze/tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"edit_url": "https://www.surveymonkey.com/create/?sm=tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"collect_url": "https://www.surveymonkey.com/collect/list?sm=tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"summary_url": "https://www.surveymonkey.com/summary/tdx6osJq3_2BVcoKKHn_2BZbgTOq9Dj4_2BqWejehwAh1_2BfQA_3D",
"preview": "https://www.surveymonkey.com/r/Preview/?sm=B20TAhiT8YpGuFWTVyhmu1Rpxe5fj_2BBP0hSy_2BKVTKwuW4gN4Rf6YxaaZ5KNey_2BAv"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Survey id |
title | string | Survey title |
nickname | string | Survey nickname |
custom_variables | object | Dictionary of survey variables |
category | string | Survey category chosen when creating the survey |
language | string | ISO 639-1 code for survey language |
question_count | integer | Number of questions in survey |
page_count | integer | Number of pages in survey |
date_created | string | Date and time when survey was created. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
date_modified | string | Date and time when survey was last modified. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
buttons_text | object | |
next_button | string | Button text |
prev_button | string | Button text |
exit_button | string | Button text |
done_button | string | Button text |
preview | string | Survey preview URL |
folder_id | string | If applicable, the id of the folder the survey is in |
edit_url | string | Survey edit URL |
collect_url | string | Survey collect URL |
analyze_url | string | Survey analyze URL |
summary_url | string | Survey summary URL |
href | string | Resource API URL |
response_count | integer | Number of responses survey has received |
footer | boolean | Whether or not SurveyMonkey’s footer is not displayed |
theme_id | integer | The ID of the theme used to create the survey, if a theme was used. |
template_id | integer | The ID of the template used to create the survey, if a template was used. |
PUT /surveys/{id}
Code samples
curl --request PUT \
--url https://api.surveymonkey.com/v3/surveys/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"New Survey","from_template_id":"","from_survey_id":"","from_team_template_id":"","nickname":"My Survey","language":"en","buttons_text":{"next_button":"string","prev_button":"string","exit_button":"string","done_button":"string"},"custom_variables":{},"footer":true,"folder_id":"","theme_id":1506280,"quiz_options":{"is_quiz_mode":true,"default_question_feedback":{"correct_text":"string","incorrect_text":"string","partial_text":"string"},"show_results_type":"string","feedback":{"ranges_type":"string","ranges":[{"min":0,"max":0,"message":"string"}]}},"pages":[{"questions":["See formatting question types for more details"]}]}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"New Survey\",\"from_template_id\":\"\",\"from_survey_id\":\"\",\"from_team_template_id\":\"\",\"nickname\":\"My Survey\",\"language\":\"en\",\"buttons_text\":{\"next_button\":\"string\",\"prev_button\":\"string\",\"exit_button\":\"string\",\"done_button\":\"string\"},\"custom_variables\":{},\"footer\":true,\"folder_id\":\"\",\"theme_id\":1506280,\"quiz_options\":{\"is_quiz_mode\":true,\"default_question_feedback\":{\"correct_text\":\"string\",\"incorrect_text\":\"string\",\"partial_text\":\"string\"},\"show_results_type\":\"string\",\"feedback\":{\"ranges_type\":\"string\",\"ranges\":[{\"min\":0,\"max\":0,\"message\":\"string\"}]}},\"pages\":[{\"questions\":[\"See formatting question types for more details\"]}]}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PUT", "/v3/surveys/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234", {
"method": "PUT",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"New Survey\",\"from_template_id\":\"\",\"from_survey_id\":\"\",\"from_team_template_id\":\"\",\"nickname\":\"My Survey\",\"language\":\"en\",\"buttons_text\":{\"next_button\":\"string\",\"prev_button\":\"string\",\"exit_button\":\"string\",\"done_button\":\"string\"},\"custom_variables\":{},\"footer\":true,\"folder_id\":\"\",\"theme_id\":1506280,\"quiz_options\":{\"is_quiz_mode\":true,\"default_question_feedback\":{\"correct_text\":\"string\",\"incorrect_text\":\"string\",\"partial_text\":\"string\"},\"show_results_type\":\"string\",\"feedback\":{\"ranges_type\":\"string\",\"ranges\":[{\"min\":0,\"max\":0,\"message\":\"string\"}]}},\"pages\":[{\"questions\":[\"See formatting question types for more details\"]}]}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PUT /surveys/{id}
Request body identical to POST /surveys
PATCH /surveys/{id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/surveys/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"New Survey","nickname":"My Survey","language":"en","buttons_text":{"next_button":"string","prev_button":"string","exit_button":"string","done_button":"string"},"custom_variables":{},"footer":true,"folder_id":""}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"New Survey\",\"nickname\":\"My Survey\",\"language\":\"en\",\"buttons_text\":{\"next_button\":\"string\",\"prev_button\":\"string\",\"exit_button\":\"string\",\"done_button\":\"string\"},\"custom_variables\":{},\"footer\":true,\"folder_id\":\"\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/surveys/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"New Survey\",\"nickname\":\"My Survey\",\"language\":\"en\",\"buttons_text\":{\"next_button\":\"string\",\"prev_button\":\"string\",\"exit_button\":\"string\",\"done_button\":\"string\"},\"custom_variables\":{},\"footer\":true,\"folder_id\":\"\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /surveys/{id}
Body parameter
{
"title": "New Survey",
"nickname": "My Survey",
"language": "en",
"buttons_text": {
"next_button": "string",
"prev_button": "string",
"exit_button": "string",
"done_button": "string"
},
"custom_variables": {},
"footer": true,
"folder_id": ""
}
Request Body for PATCH /surveys/{id}
Name | Type | Required | Description |
---|---|---|---|
title | string | false | Survey title (PUT default=“New Survey”) |
nickname | string | false | Survey nickname (PUT default="") |
language | string | false | Survey language (PUT default=“en”) |
buttons_text | object | false | Survey Buttons text container |
next_button | string | false | Button text |
prev_button | string | false | Button text |
exit_button | string | false | Button text. If set to an empty string, button will be ommitted from survey |
done_button | string | false | Button text |
custom_variables | object | false | Dictionary of survey variables |
footer | boolean | false | If false, SurveyMonkey’s footer is not displayed (default=true) |
folder_id | string | false | If specified, adds the survey to the folder with that id. |
GET /surveys/{id}/details
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/details \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/details", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/details", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{id}/details
Available Methods
GET
: Returns an expanded survey resource with apages
element containing a list of all page objects, each containing a list of questions objects. Public App users need access to the View Surveys scope
Example Response for GET /surveys/{id}/details
{
"title": "New Survey",
"nickname": "",
"language": "en",
"folder_id": "0",
"category": "",
"question_count": 0,
"page_count": 1,
"response_count": 0,
"date_created": "2021-07-26T18:09:00",
"date_modified": "2021-07-26T19:32:00",
"id": "1",
"buttons_text": {
"next_button": "Next",
"prev_button": "Prev",
"done_button": "Done",
"exit_button": "Exit"
},
"is_owner": true,
"footer": true,
"custom_variables": {},
"href": "https://api.surveymonkey.com/v3/surveys/1",
"analyze_url": "https://www.surveymonkey.com/analyze/gel_2BAICXZEi4rH4ITcFzAin50QyBg8dHsw877lCBjYlk_3D",
"edit_url": "https://www.surveymonkey.com/create/?sm=gl_2BAICXZEi4rH4ITcFzAAin50QyBg8dHsw877lCBjYlk_3D",
"collect_url": "https://www.surveymonkey.com/collect/list?sm=gl_2BAICXZEi4rH4ITcFzAAin50QyBg8dHsw877lCBjYlk_3D",
"summary_url": "https://www.surveymonkey.com/summary/gl_2BAICCXZEi4rH4ITcFzAin50QyBg8dHsw877lCBjYlk_3D",
"preview": "https://www.surveymonkey.com/r/Preview/?sm=UY_2BlACesAm789uYe_2B0Zln_2Fs_2F9GndhH015uffhkTaxfBCBn3Gcj_2BTQrIRea7upQwrz",
"pages": [
{
"title": "",
"description": "",
"position": 1,
"question_count": 0,
"id": "1",
"href": "https://api.surveymonkey.com/v3/surveys/1/pages/1",
"questions": []
}
]
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
preview | string | |
response_count | integer | |
collect_url | string | |
buttons_text | object | |
exit_button | string | |
prev_button | string | |
done_button | string | |
next_button | string | |
footer | boolean | |
date_created | string | |
is_owner | boolean | |
custom_variables | object | |
language | string | |
title | string | |
question_count | integer | |
pages | [object] | |
question_count | integer | |
questions | [string] | |
description | string | |
position | integer | |
id | string | |
href | string | |
title | string | |
date_modified | string | |
nickname | string | |
edit_url | string | |
id | string | |
href | string | |
folder_id | string | |
category | string | |
analyze_url | string | |
summary_url | string | |
page_count | integer |
POST /surveys/{survey_id}/share
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/surveys/111/share \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"title","description":"share description","modes":["summary","trends"],"enabled":true,"is_public":true,"branded":true,"hide_open_ended":true,"password":"p6nehgv2**3ddd","domain":"www.surveymonkey.com"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"title\",\"description\":\"share description\",\"modes\":[\"summary\",\"trends\"],\"enabled\":true,\"is_public\":true,\"branded\":true,\"hide_open_ended\":true,\"password\":\"p6nehgv2**3ddd\",\"domain\":\"www.surveymonkey.com\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/surveys/111/share", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/111/share", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"title\",\"description\":\"share description\",\"modes\":[\"summary\",\"trends\"],\"enabled\":true,\"is_public\":true,\"branded\":true,\"hide_open_ended\":true,\"password\":\"p6nehgv2**3ddd\",\"domain\":\"www.surveymonkey.com\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /surveys/{survey_id}/share
Available Methods
POST
: Create a survey results page link. Public App users need access to the View Responses scopePUT
: Update an existing survey results page link. Public App users need access to the View Responses scope
Body parameter
{
"title": "title",
"description": "share description",
"modes": [
"summary",
"trends"
],
"enabled": true,
"is_public": true,
"branded": true,
"hide_open_ended": true,
"password": "p6nehgv2**3ddd",
"domain": "www.surveymonkey.com"
}
Request Body for POST /surveys/{survey_id}/share
Name | Type | Required | Description |
---|---|---|---|
title | string | true | Title of the survey results page |
description | string | false | Description of the survey results page. Defaults to empty string. |
modes | [string] | false | Defines the modes available on the survey results pages. Defaults to [summary ]. |
enabled | boolean | false | If the link to be created should be enabled. If false, the link will redirect to /unavailable . Defaults to true |
is_public | boolean | false | Determines if the share results page is public. Defaults to true |
branded | boolean | false | If the branding is turned on (has the SurveyMonkey logo) on the survey results page. Defaults to true (branded). Custom branding is not supported. User must have a paid plan to hide branding |
hide_open_ended | boolean | false | Display text responses on the share results page. Defaults to true |
password | string | false | If set, it creates a password for the survey results page for access control. Must be 4-35 characters. User must have a paid plan to set a password |
domain | string | false | The domain hosting the shared link. Use this together with the shared view key to generate your shared URL, we will default to using “www.surveymonkey.com” |
Example Response for POST /surveys/{survey_id}/share
{
"enabled": true,
"is_public": true,
"hide_open_ended": true,
"modes": [
"summary"
],
"type": "weblink",
"title": "Survey Results",
"description": "Survey Results Description",
"branding": "none",
"password": "p6nehgv2**3ddd",
"id": 89202,
"date_created": "2023-08-03T16:50:02.877000+00:00",
"num_of_views": 0,
"survey_id": "111",
"key": "SM-2mkV76m9_2F_0BXyxsk99XjICXg_0D_3D",
"has_password": true
}
Response Schema
Status Code 201
Name | Type | Description |
---|---|---|
enabled | boolean | If the link is enabled. If false, the results link will default to /unavailable |
is_public | boolean | The share results page is public view |
modes | [string] | Defines the modes available on the survey results page. |
type | string | Defines what the share results type is out of the options: weblink |
title | string | Title of the survey results page |
description | string | Description of the survey results page |
branding | string | The branding is on: default or off: none |
password | string | The password for the survey results page |
id | number | The id of the survey results |
date_created | string | Date the share results were created |
num_of_views | number | The number of views the share results has |
survey_id | string | Id of the survey the share results are created for |
key | string | The key used in the share results url of the form: domain/results/{key}, where the domain is the associated survey domain. Note that the domain is not customizable via this endpoint. |
has_password | booolean | If the share results url has a password |
GET /surveys/{survey_id}/share_list
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/111/share_list \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/111/share_list", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/111/share_list", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/share_list
Available Methods
GET
: Return a list of survey results page links generated for the survey with thissurvey_id
.
Example Response for POST /surveys/{survey_id}/share
[
{
"enabled": true,
"is_public": true,
"hide_open_ended": true,
"modes": [
"summary"
],
"type": "weblink",
"title": "Survey Results",
"description": "Survey Results Description",
"branding": "none",
"password": "p6nehgv2**3ddd",
"id": 89202,
"date_created": "2023-08-03T16:50:02.877000+00:00",
"num_of_views": 0,
"survey_id": "111",
"key": "SM-2mkV76m9_2F_0BXyxsk99XjICXg_0D_3D",
"has_password": true
}
]
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
enabled | boolean | If the link is enabled. If false, the results link will default to /unavailable |
is_public | boolean | The share results page is public view |
modes | [string] | Defines the modes available on the survey results page. |
type | string | Defines what the share results type is out of the options: weblink |
title | string | Title of the survey results page |
description | string | Description of the survey results page |
branding | string | The branding is on: default or off: none |
password | string | The password for the survey results page |
id | number | The id of the survey results |
date_created | string | Date the share results were created |
num_of_views | number | The number of views the share results has |
survey_id | string | Id of the survey the share results are created for |
key | string | The key used in the share results url of the form: domain/results/{key}, where the domain is the associated survey domain. Note that the domain is not customizable via this endpoint. |
has_password | booolean | If the share results url has a password |
GET /survey_categories
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/survey_categories \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/survey_categories", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/survey_categories", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /survey_categories
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of survey categories that can be used to filter survey templates. Public App users need access to the View Library Assets scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
language | string | false | ISO 639-1 code for language to filter by (default=en) |
Example Response for GET /survey_categories
{
"page": 1,
"per_page": 1,
"total": 1,
"data": [
{
"name": "Category Name",
"id": "community"
}
],
"links": {
"self": "https://api.surveymonkey.com/v3/survey_categories?page=1&per_page=1"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
page | integer | |
total | integer | |
data | [object] | |
name | string | Resource name |
id | string | Resource id |
links | object | |
self | string |
GET /survey_templates
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/survey_templates \
--header 'Accept: schema' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "schema",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/survey_templates", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/survey_templates", {
"method": "GET",
"headers": {
"Accept": "schema",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /survey_templates
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of survey templates. Survey template ids can be used as an argument toPOST
a new survey. Public App users need access to the View Library Assets scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
language | string | false | ISO 639-1 code for language to filter by (default=en) |
category | string | false | Category to filter by, see /survey_categories for a list of available categories if not specified, all categories are returned |
Example Response for GET /survey_templates
{
"page": 1,
"per_page": 1,
"total": 1,
"data": [
{
"category": "community",
"name": "Template Name",
"title": "Template Name",
"available": true,
"id": "49",
"num_questions": 10,
"description": "Template description",
"preview_link": "https://www.surveymonkey.com/r/Preview/?sm=ID"
}
],
"links": {
"self": "https://api.surveymonkey.com/v3/survey_templates?page=1&per_page=1"
}
}
Response Schema
GET /team_survey_templates
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/team_survey_templates \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/team_survey_templates", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/team_survey_templates", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /team_survey_templates
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of team survey templates corresponding to the team to which the calling user belongs. Team survey template ids (team_template_id) can be used as an argument toPOST
a new survey. Public App users need access to the View Library Assets scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
Example Response for GET /team_survey_templates
{
"page": 1,
"per_page": 1,
"total": 1,
"data": [
{
"name": "Template Name",
"team_template_id": "49",
"survey_id": "50"
}
],
"links": {
"self": "https://api.surveymonkey.com/v3/survey_templates?page=1&per_page=1"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
page | integer | |
total | integer | |
data | [object] | |
name | string | Name of the team template |
team_template_id | string | Team template ID (can be used when posting a new survey) |
survey_id | string | ID of the survey from which this team template was derived |
links | object | |
self | string |
GET /survey_languages
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/survey_languages \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/survey_languages", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/survey_languages", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /survey_languages
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of survey languages that can be used to generate translations for multilingual surveys
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
Example Response for GET /survey_languages
{
"page": 1,
"per_page": 1,
"total": 1,
"data": [
{
"name": "English",
"native_name": "English",
"id": "en"
}
],
"links": {
"self": "https://api.surveymonkey.com/v3/survey_languages?page=1&per_page=1"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
page | integer | |
total | integer | |
data | [object] | |
name | string | Name of language |
id | string | Language code |
native_name | string | Name of language in native language |
links | object | |
self | string |
GET /surveys/{survey_id}/pages
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/pages \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/pages", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/pages
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a page’s details. Public App users need access to the View Surveys scopePOST
: Creates a new, empty page, see /surveys/{id}/pages/{id}/questions to add questions to pages. Public App users need access to the Create/Modify Surveys scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | integer | false | Number of resources to return per page. Defaults to 50 |
page | integer | false | Which page of resources to return. Defaults to 1 |
Example Response for GET /surveys/{id}/pages
{
"data": [
{
"title": "",
"description": "",
"position": 1,
"id": "172949600",
"href": "https://api.surveymonkey.com/v3/surveys/309695619/pages/172949600"
},
{
"title": "My Folder1",
"description": "",
"position": 2,
"id": "173176852",
"href": "https://api.surveymonkey.com/v3/surveys/309695619/pages/173176852"
}
],
"per_page": 50,
"page": 1,
"total": 3,
"links": {
"self": "https://api.surveymonkey.com/v3/surveys/309695619/pages?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | |
title | string | Name of the page |
description | string | Description of the page |
position | integer | Position of the page in the survey |
id | string | ID of the page |
href | string | Link to the page |
per_page | integer | Number of resources per page |
page | integer | Page of the resource returned |
total | integer | Number of resources returned |
links | object | Contains this endpoint’s links |
self | string | The link associated with this endpoint |
POST /surveys/{survey_id}/pages
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/surveys/1234/pages \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"Page title","description":"","position":3}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"Page title\",\"description\":\"\",\"position\":3}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/surveys/1234/pages", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"Page title\",\"description\":\"\",\"position\":3}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /surveys/{survey_id}/pages
Body parameter
{
"title": "Page title",
"description": "",
"position": 3
}
Request Body for POST /surveys/{survey_id}/pages
Name | Type | Required | Description |
---|---|---|---|
title | string | false | Page title |
description | string | false | Page description |
position | integer | false | Page position in survey |
GET /surveys/{survey_id}/pages/{page_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/pages/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/pages/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/pages/{page_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a page’s details. Public App users need access to the View Surveys scopePATCH
: Modifies a page (updates any fields accepted as arguments toPOST
/surveys{id}/pages). Public App users need access to the Create/Modify Surveys scopePUT
: Replaces a page (same arguments and requirements asPOST
/surveys{id}/pages). Public App users need access to the Create/Modify Surveys scopeDELETE
: Deletes a page. Public App users need access to the Create/Modify Surveys scope
Example Response for GET, PATCH, PUT /surveys/{survey_id}/pages/{page_id}
{
"title": "My Page1",
"description": "",
"position": 4,
"question_count": 0,
"id": "173177756",
"href": "https://api.surveymonkey.com/v3/surveys/309695619/pages/173177756"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
title | string | Name of the page |
description | string | Description of the page |
position | integer | Position of the page in the survey |
question_count | integer | Number of questions on the page |
id | string | ID of the page |
href | string | Link to the page |
PATCH /surveys/{survey_id}/pages/{page_id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/surveys/1234/pages/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"Page title","description":"","position":3}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"Page title\",\"description\":\"\",\"position\":3}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/surveys/1234/pages/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"Page title\",\"description\":\"\",\"position\":3}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /surveys/{survey_id}/pages/{page_id}
PATCH
: Modifies a page (updates any fields accepted as arguments toPOST
/surveys{id}/pages). Public App users need access to the Create/Modify Surveys scope
PUT /surveys/{survey_id}/pages/{page_id}
Code samples
curl --request PUT \
--url https://api.surveymonkey.com/v3/surveys/1234/pages/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"Page title","description":"","position":3}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"Page title\",\"description\":\"\",\"position\":3}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PUT", "/v3/surveys/1234/pages/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages/1234", {
"method": "PUT",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"Page title\",\"description\":\"\",\"position\":3}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PUT /surveys/{survey_id}/pages/{page_id}
PUT
: Replaces a page (same arguments and requirements asPOST
/surveys{id}/pages). Public App users need access to the Create/Modify Surveys scope
GET /surveys/{survey_id}/pages/{page_id}/questions
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/pages/1234/questions", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/pages/{page_id}/questions
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of questions on a survey page. Public App users need access to the View Surveys scopePOST
: Creates a new question on a survey page, see formatting question types. Public App users need access to the Create/Modify Surveys scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | integer | false | Number of resources to return per page |
page | integer | false | Which page of resources to return. Defaults to 1 |
Example Response for GET /surveys/{survey_id}/pages/{page_id}/questions
{
"data": [
{
"heading": "Question 1",
"position": 1,
"id": "1",
"href": "https://api.surveymonkey.com/v3/surveys/1/pages/1/questions/1"
},
{
"heading": "Question 2",
"position": 2,
"id": "2",
"href": "https://api.surveymonkey.com/v3/surveys/1/pages/1/questions/2"
}
],
"per_page": 50,
"page": 1,
"total": 2,
"links": {
"self": "https://api.surveymonkey.com/v3/surveys/1/pages/1/questions?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
page | integer | |
per_page | integer | |
total | integer | Number of questions |
data | object | |
position | integer | Position of the question in the page |
id | string | ID of the question |
href | string | Link to the question |
heading | string | Heading of the question |
links | object | |
self | string |
POST /surveys/{survey_id}/pages/{page_id}/questions
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"headings":[{"heading":"Which monkey would you rather have as a pet?","description":"","image":{"url":"string"},"random_assignment":{"percent":0,"position":0,"variable_name":"string"}}],"position":0,"family":"single_choice","subtype":"vertical","sorting":{"type":"string","ignore_last":true},"required":false,"validation":{"type":"string","text":"string","min":"string","max":"string","sum":0,"sum_text":"string"},"forced_ranking":false,"quiz_options":{"scoring_enabled":true,"feedback":{},"feedback.correct_text":"string","feedback.incorrect_text":"string","feedback.partial_text":"string"},"answers":{"choices":[{"text":"Capuchin"},{"text":"Mandrill"}]},"display_options":{}}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"headings\":[{\"heading\":\"Which monkey would you rather have as a pet?\",\"description\":\"\",\"image\":{\"url\":\"string\"},\"random_assignment\":{\"percent\":0,\"position\":0,\"variable_name\":\"string\"}}],\"position\":0,\"family\":\"single_choice\",\"subtype\":\"vertical\",\"sorting\":{\"type\":\"string\",\"ignore_last\":true},\"required\":false,\"validation\":{\"type\":\"string\",\"text\":\"string\",\"min\":\"string\",\"max\":\"string\",\"sum\":0,\"sum_text\":\"string\"},\"forced_ranking\":false,\"quiz_options\":{\"scoring_enabled\":true,\"feedback\":{},\"feedback.correct_text\":\"string\",\"feedback.incorrect_text\":\"string\",\"feedback.partial_text\":\"string\"},\"answers\":{\"choices\":[{\"text\":\"Capuchin\"},{\"text\":\"Mandrill\"}]},\"display_options\":{}}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/surveys/1234/pages/1234/questions", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"headings\":[{\"heading\":\"Which monkey would you rather have as a pet?\",\"description\":\"\",\"image\":{\"url\":\"string\"},\"random_assignment\":{\"percent\":0,\"position\":0,\"variable_name\":\"string\"}}],\"position\":0,\"family\":\"single_choice\",\"subtype\":\"vertical\",\"sorting\":{\"type\":\"string\",\"ignore_last\":true},\"required\":false,\"validation\":{\"type\":\"string\",\"text\":\"string\",\"min\":\"string\",\"max\":\"string\",\"sum\":0,\"sum_text\":\"string\"},\"forced_ranking\":false,\"quiz_options\":{\"scoring_enabled\":true,\"feedback\":{},\"feedback.correct_text\":\"string\",\"feedback.incorrect_text\":\"string\",\"feedback.partial_text\":\"string\"},\"answers\":{\"choices\":[{\"text\":\"Capuchin\"},{\"text\":\"Mandrill\"}]},\"display_options\":{}}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /surveys/{survey_id}/pages/{page_id}/questions
Body parameter
{
"headings": [
{
"heading": "Which monkey would you rather have as a pet?",
"description": "",
"image": {
"url": "string"
},
"random_assignment": {
"percent": 0,
"position": 0,
"variable_name": "string"
}
}
],
"position": 0,
"family": "single_choice",
"subtype": "vertical",
"sorting": {
"type": "string",
"ignore_last": true
},
"required": false,
"validation": {
"type": "string",
"text": "string",
"min": "string",
"max": "string",
"sum": 0,
"sum_text": "string"
},
"forced_ranking": false,
"quiz_options": {
"scoring_enabled": true,
"feedback": {},
"feedback.correct_text": "string",
"feedback.incorrect_text": "string",
"feedback.partial_text": "string"
},
"answers": {
"choices": [
{
"text": "Capuchin"
},
{
"text": "Mandrill"
}
]
},
"display_options": {}
}
Request Body for POST /surveys/{survey_id}/pages/{page_id}/questions
Name | Type | Required | Description |
---|---|---|---|
headings | [object] | true | List of question headings objects |
heading | string | true | The title of the question, or empty string if random_assignment is defined |
description | string | false | If random_assignment is defined, and family is presentation_image this is the title |
image | object | false | Image data when question family is presentation_image |
url | string | false | URL of image when question family is presentation_image |
random_assignment | object | false | Random assignment data |
percent | integer | true | Percent chance of this random assignment showing up (must sum to 100) |
position | integer | false | Position of the random_assignment in survey creation page |
variable_name | string | false | Internal use name for question tracking, can be "" |
position | integer | false | Position of question on page (default=last) |
family | string | true | Question family determines the type of question, see formatting question types |
subtype | string | true | Question family’s subtype further specifies the type of question, see formatting question types |
sorting | object | false | Sorting details of answers |
type | string | true | Sort answer choices by: default , textasc , textdesc , resp_count_asc , resp_count_desc , random , flip |
ignore_last | boolean | false | If true, does not sort the last answer option (useful for “none of the above”, etc) |
required | object | false | Whether an answer is required for this question |
text | string | true | Text to display if a required question is not answered |
type | string | true | Specifies how much of the question must be answered: all , at_least , at_most , exactly , or range . Required if question is matrix_single, matrix_ranking, and matrix menu |
amount | string | true | The amount of answers required to be answered. If the required type is range then this is two numbers separated by a comma, as a string (e.g. “1,3” to represent the range of 1 to 3). Required if type is defined. |
validation | object | false | Whether the answer must pass certain validation parameters |
type | string | true | Type of validation to use: any , integer , decimal , date_us , date_intl , email , or text_length |
text | string | true | Text to display if validation fails |
min | string | true | Minimum value an answer can be to pass validation. Date string, integer, or null depending on validation.type |
max | string | true | Maximum value an answer can be to pass validation. Date string, integer, or null depending on validation.type |
sum | integer | false | Only accepted is family=open_ended and subtype=numerical, the exact integer textboxes must sum to in order to pass validation |
sum_text | string | false | Only accepted is family=open_ended and subtype=numerical, the message to display if textboxes do not sum to validation.sum |
forced_ranking | boolean | false | Required if type is matrix and subtype is rating or single, whether or not to force ranking |
quiz_options | object | false | Object containing the quiz properties of this question, if quiz-mode is enabled |
scoring_enabled | boolean | true | Whether this question is quiz-enabled |
feedback | object | true | Object containing the definitions for feedback on this quiz question |
feedback.correct_text | string | true | Text to show when answer is correct |
feedback.incorrect_text | string | true | Text to show when the ansewr is incorrect |
feedback.partial_text | string | true | Text to show when the answer is partially correct |
answers | object | true | Answers object, refer to Formatting Question Types. Required for all question types except open_ended_single |
display_options | object | false | Display option object, refer to Formatting Question Types. Required for File Upload, Slider, Image Choice, & Emoji/Star Rating question types |
200 Response
{
"headings": [
{
"heading": "string",
"description": "string",
"image": {
"url": "string"
},
"random_assignment": {
"percent": 0,
"position": 0,
"variable_name": "string",
"assignment_id": "string"
}
}
],
"position": 0,
"visible": true,
"family": "string",
"subtype": "string",
"sorting": {
"type": "string",
"ignore_last": true
},
"required": {
"text": "string",
"type": "string",
"amount": "string"
},
"validation": {
"type": "string",
"text": "string",
"min": "string",
"max": "string",
"sum": 0,
"sum_text": "string"
},
"forced_ranking": true,
"answers": {},
"id": "string"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
headings | [object] | List of question headings objects |
heading | string | The title of the question, or empty string if random_assignment is defined |
description | string | If random_assignment is defined, and family is presentation_image this is the title |
image | object | Image data when question family is presentation_image |
url | string | URL of image when question family is presentation_image |
random_assignment | object | Random assignment data |
percent | integer | Percent chance of this random assignment showing up (must sum to 100) |
position | integer | Position of the random_assignment in survey creation page |
variable_name | string | Internal use name for question tracking, can be "" |
assignment_id | string | Internal use id for question tracking |
position | integer | Position of question on page (default=last) |
visible | boolean | Whether the question is visible (corresponds with being deleted in the UI) |
family | string | Question family determines the type of question, see formatting question types |
subtype | string | Question family’s subtype further specifies the type of question, see formatting question types |
sorting | object | Sorting details of answers |
type | string | Sort answer choices by: default , textasc , textdesc , resp_count_asc , resp_count_desc , random , flip |
ignore_last | boolean | If true, does not sort the last answer option (useful for “none of the above”, etc) |
required | object | Whether an answer is required for this question |
text | string | Text to display if a required question is not answered |
type | string | Specifies how much of the question must be answered: all , at_least , at_most , exactly , or range . Required if question is matrix_single, matrix_ranking, and matrix menu |
amount | string | The amount of answers required to be answered. If the required type is range then this is two numbers separated by a comma, as a string (e.g. “1,3” to represent the range of 1 to 3). Required if type is defined |
validation | object | Whether the answer must pass certain validation parameters |
type | string | Type of validation to use: any , integer , decimal , date_us , date_intl , email , or text_length |
text | string | Text to display if validation fails |
min | string | Minimum value an answer can be to pass validation. Date string, integer, or null depending on validation.type |
max | string | Maximum value an answer can be to pass validation. Date string, integer, or null depending on validation.type |
sum | integer | Only accepted is family=open_ended and subtype=numerical, the exact integer textboxes must sum to in order to pass validation |
sum_text | string | Only accepted is family=open_ended and subtype=numerical, the message to display if textboxes do not sum to validation.sum |
forced_ranking | boolean | Required if type is matrix and subtype is rating or single, whether or not to force ranking |
answers | object | Answers object, refer to Formatting Question Types. Required for all question types except open_ended_single |
id | string | Question id |
GET /surveys/{survey_id}/pages/{page_id}/questions/{question_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/pages/1234/questions/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/pages/{page_id}/questions/{question_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a question. Requires View Surveys scopePATCH
: Updates a question (updates any fields accepted as arguments toPOST
/surveys/{id}/pages/questions. Public App users need access to the Create/Modify Surveys scopePUT
: Replaces a question (same arguments and requirements asPOST
/surveys/{id}/pages/questions. Public App users need access to the Create/Modify Surveys scopeDELETE
: Deletes a question. Public App users need access to the Create/Modify Surveys scope
200 Response
{
"headings": {
"heading": "string"
},
"position": 0,
"family": "string",
"subtype": "string",
"answers": {
"choices": [
{
"text": "string"
}
],
"others": [
{
"text": "string",
"num_chars": 0,
"num_lines": 0
}
]
}
}
Formatting Question Types
All questions have afamily
and subtype
that define their type and some questions have a display_type
and display_subtype
that further define their type. See below for example formatting of the answers object and display_options object for different question types. Read more about SurveyMonkey’s question types in our help center.
Family | Subtype | Display_Type | Display_Subtype |
---|---|---|---|
single_choice | ‘vertical’, ‘horiz’, ‘menu’ | ‘image_choice’ | NA |
matrix | ‘single’, ‘rating’, ‘ranking’, ‘menu’, ‘multi’ | ‘emoji’ (with ‘ranking’) | ‘star’ |
open_ended | ‘single’,‘multi’, ‘numerical’, ‘essay’ | ‘slider’, ‘file_upload’ (with ‘single’) | NA |
demographic | ‘international’, ‘us’, ‘address’, ‘phone’, ‘email’, ‘name’ | NA | NA |
datetime | ‘both’, ‘date_only’, ‘time_only’ | NA | NA |
multiple_choice | ‘vertical’ | ‘image_choice’ | NA |
presentation | ‘descriptive_text’, ‘image’ | NA | NA |
Single Choice
Single Choice
{
"headings": [
{
"heading": "Which monkey would you rather have as a pet?"
}
],
"position": 1,
"family": "single_choice",
"subtype": "vertical",
"answers": {
"choices":[
{
"text": "Capuchin"
},
{
"text": "Mandrill"
}
],
"other":[
{
"text": "Other",
"num_chars": 100,
"num_lines": 3
}
]
}
}
Name | Description | Data Type |
---|---|---|
choices (required) | List of available choices for the user | Array |
choices[_].text (required) | Choice for user selection | String |
choices[_].position (optional) | Position of the current choice | Integer |
other (optional) | List of other answer options | Object |
other[_].text | Text to display next to other option | String |
other[_].num_chars | Set a character limit to the option | Integer |
other[_].num_lines | Set a line limit to the option | Integer |
Multiple Choice
Multiple Choice
{
"headings": [
{
"heading": "Which monkeys would you like as pets?"
}
],
"position": 1,
"family": "multiple_choice",
"subtype": "vertical",
"answers": {
"choices":[
{
"text": "Capuchin"
},
{
"text": "Mandrill"
}
]
}
}
Name | Description | Data Type |
---|---|---|
choices (required) | List of available choices for the user | Array |
choices[_].text (required) | Choice for user selection | String |
choices[_].position (optional) | Position of the current choice | Integer |
other (optional) | List of other answer options | Object |
other[_].text | Text to display next to other option | String |
other[_].num_chars | Set a character limit to the option | Integer |
other[_].num_lines | Set a line limit to the option | Integer |
Image Choice
Image Choice
{
"headings": [
{
"heading": "Which monkey do you like more? Pick one or more"
}
],
"position": 1,
"family": "multiple_choice",
"subtype": "vertical",
"display_options": {
"display_type": "image_choice"
},
"answers": {
"choices":[
{
"text": "This is an image of a monkey",
"image":{
"url":"https://path.to.image/image.jpg"
}
},
{
"text": "This is the same picture of the same monkey",
"image":{
"url":"https://path.to.image/image.jpg"
}
}
]
}
}
Name | Description | Data Type |
---|---|---|
choices (required) | List of available choices for the user | Array |
choices[_].image (required) | Image choice | Object |
choices[_].image[_].url (required) | URL of image choice | String |
choices[_].text (optional) | Choice for user selection | String |
choices[_].position (optional) | Position of the current choice | Integer |
display_options (required) | Object of display options | Object |
display_options[_].display_type | Type of the display | String (“image_choice”) |
Matrix - Single
Matrix - Single
{
"headings": [
{
"heading": "What is each of your family members' favorite ice cream?"
}
],
"position": 1,
"family": "matrix",
"subtype": "single",
"forced_ranking": false,
"answers": {
"rows": [
{
"text": "Mother"
},
{
"text": "Father"
}
],
"choices": [
{
"text": "Chocolate"
},
{
"text": "Vanilla"
},
{
"text": "Strawberry"
}
]
}
}
Name | Description | Data Type |
---|---|---|
rows (required) | List of rows in the matrix | Array |
rows[_].text (required) | Text label for the row | String |
rows[_].position (optional) | Position of the row | Integer |
choices (required) | List of available choices for the user | Array |
choices[_].text (required) | Choice for user selection | String |
choices[_].position (optional) | Position of the current choice | Integer |
other (optional) | List of other answer options | Object |
other[_].text | Text to display next to other option | String |
other[_].num_chars | Set a character limit to the option | Integer |
other[_].num_lines | Set a line limit to the option | Integer |
Matrix - Rating
Matrix - Rating
{
"headings": [
{
"heading": "What is each of your family members' favorite ice cream?"
}
],
"position": 1,
"family": "matrix",
"subtype": "rating",
"forced_ranking": false,
"answers": {
"rows": [
{
"text": "Mother"
},
{
"text": "Father"
}
],
"choices": [
{
"text": "Chocolate",
"weight": 1
},
{
"text": "Vanilla",
"weight": 1
},
{
"text": "Strawberry",
"weight": 1
}
]
}
}
Name | Description | Data Type |
---|---|---|
rows (required) | List of rows in the matrix | Array |
rows[_].text (required) | Text label for the row | String |
rows[_].position (optional) | Position of the row | Integer |
choices (required) | List of available choices for the user | List |
choices[_].text (required) | Choice for user selection | String |
choices[_].weight (required) | Weight value of the choice | Integer |
choices[_].position (optional) | Position of the row | Integer |
other (optional) | List of other answer options | Object |
other[_].text | Text to display next to other option | String |
other[_].num_chars | Set a character limit to the option | Integer |
other[_].num_lines | Set a line limit to the option | Integer |
Matrix - Ranking
Matrix - Ranking
{
"headings": [
{
"heading": "Rank these flavors in terms of your preference!"
}
],
"position": 1,
"family": "matrix",
"subtype": "ranking",
"answers": {
"rows":[
{
"text": "Vanilla"
},
{
"text": "Chocolate"
},
{
"text": "Strawberry"
}
]
}
}
Name | Description | Data Type |
---|---|---|
rows (required) | List of rows in the matrix | Array |
rows[_].text (required) | Text label for the row | String |
rows[_].position (optional) | Position of the row | Integer |
Matrix - Menu
Matrix - Menu
{
"headings": [
{
"heading": "Which texture and taste do you prefer on your ice cream?"
}
],
"position": 1,
"family": "matrix",
"subtype": "menu",
"answers": {
"rows":[
{
"text": "Chocolate"
},
{
"text": "Cookies and Cream"
}
],
"cols":[
{
"text": "Texture",
"choices": [
{
"text": "Smooth",
"visible": true,
"position": 1
},
{
"text": "Chunky",
"visible": true,
"position": 2
}
]
},
{
"text": "Flavor",
"choices": [
{
"text": "Light",
"visible": true,
"position": 1
},
{
"text": "Full",
"visible": true,
"position": 2
}
]
}
]
}
}
Name | Description | Data Type |
---|---|---|
rows (required) | List of rows in the matrix | Array |
rows[_].text (required) | Text label for the row | String |
rows[_].position (optional) | Position of the row | Integer |
cols (required) | List of columns in the matrix | Array |
cols[_].text (required) | Text label for column | String |
cols[_].choices (required) | List of available choices for the user in dropdown menu | Array |
cols[_].choices[_].text (required) | Choice for user selection | String |
cols[_].choices[_].position (required) | Position of choice | Integer |
other (optional) | List of other answer options | Object |
other[_].text | Text to display next to other option | String |
other[_].num_chars | Set a character limit to the option | Integer |
other[_].num_lines | Set a line limit to the option | Integer |
Open Ended - Single or Essay
Open Ended - Single or Essay
{
"headings": [
{
"heading": "What's your favorite thing about monkeys?"
}
],
"position": 1,
"family": "open_ended",
"subtype": "single"
}
Only requires a heading
.
Open Ended - Multi
Open Ended - Multi
{
"headings": [
{
"heading": "What are your favorite monkey species?"
}
],
"position": 1,
"family": "open_ended",
"subtype": "multi",
"answers": {
"rows":[
{
"text": "Your favorite:"
},
{
"text": "Second favorite:"
}
]
}
}
Name | Description | data Type |
---|---|---|
rows (required) | List of textboxes | Array |
rows[_].text (required) | Text label for textbox | String |
rows[_].position (optional) | Position of the current row | Integer |
Open Ended - Numerical
Open Ended - Numerical
{
"headings": [
{
"heading": "If you could split 10 pounds of ice cream, how would you split it?"
}
],
"position": 1,
"family": "open_ended",
"subtype": "numerical",
"answers": {
"rows":[
{
"text": "Pounds for family:"
},
{
"text": "Pounds for friends:"
},
{
"text": "Pounds for self:"
}
]
},
"validation": {
"text": "Please enter a valid integer.",
"type": "integer",
"sum": 10,
"sum_text": "Your input must add up to 10 pounds!"
}
}
Name | Description | Data Type |
---|---|---|
rows (required) | List of textboxes | Array |
rows[_].text (required) | Text label for textbox | String |
rows[_].position (optional) | Position of the current row | Integer |
Demographic - international/us
Demographic - international/us
{
"headings": [
{
"heading": "What's your address?"
}
],
"position": 1,
"visible": true,
"family": "demographic",
"subtype": "international",
"answers": {
"choices": [
{
"visible": true,
"required": true,
"type": "name",
"text": "Your Name"
},
{
"visible": true,
"required": false,
"type": "company"
},
{
"visible": false,
"required": false,
"type": "address"
},
{
"visible": false,
"required": false,
"type": "address2"
},
{
"visible": true,
"required": true,
"type": "city"
},
{
"visible": true,
"required": true,
"type": "state"
},
{
"visible": true,
"required": true,
"type": "zip"
},
{
"visible": true,
"required": true,
"type": "country"
},
{
"visible": true,
"required": true,
"type": "email"
},
{
"visible": true,
"required": true,
"type": "phone"
}
]
}
}
This corresponds to the Contact Information question type in the SurveyMonkey UI.
Each type
represented in the example object must be included, to disable one, specify visible
as False
Name | Description | Data Type |
---|---|---|
choices | List of available demographic data | Array |
choices[_].visible (required) | Visibility of demographic data type | Boolean |
choices[_].required (required) | Whether demographic data type is required | Boolean |
choices[_].type (required) | Type of demographic data | String |
choices[_].text (optional) | Optional label of demographic data, will default to type | String |
Address
Address
{
"headings": [
{
"heading": "Address"
}
],
"position": 1,
"visible": true,
"family": "demographic",
"subtype": "address",
"answers": {
"choices": [
{
"visible": true,
"required": false,
"type": "address1_label",
"text": "Street"
},
{
"visible": true,
"required": false,
"type": "address2_label",
"text": "Street 2"
},
{
"visible": true,
"required": false,
"type": "city_label",
"text": "City"
},
{
"visible": true,
"required": false,
"type": "state_label",
"text": "State"
},
{
"visible": true,
"required": false,
"type": "zip_label",
"text": "Zip Code"
},
{
"visible": true,
"required": false,
"type": "country_label",
"text": "country"
}
]
}
}
This corresponds to the Address question type in the SurveyMonkey UI.
Each type
represented in the example object must be included, to disable one, specify visible
as False
Name | Description | Data Type |
---|---|---|
choices | List of available address data | Array |
choices[_].visible (required) | Visibility of address data type | Boolean |
choices[_].required (required) | Whether address data type is required | Boolean |
choices[_].type (required) | Type of address data | String |
choices[_].text (required) | Optional label of address data, will default to type | String |
choices[_].options | Optional address fields | Object |
choices[_].options[_].placeholder_text (optional) | Text that appears before the user types their answer in the fields | String |
choices[_].options[_].default_country (optional) | The default country code for the country_label type only | String |
Phone
Phone
{
"headings": [
{
"heading": "Phone number"
}
],
"position": 1,
"visible": true,
"family": "demographic",
"subtype": "phone",
"answers": {
"choices": [
{
"visible": true,
"type": "phone_number",
"text": "Please provide your phone number"
}
]
}
}
This corresponds to the Phone question type in the SurveyMonkey UI.
Each type
represented in the example object must be included, to disable one, specify visible
as False
Name | Description | Data Type |
---|---|---|
choices | List of available phone data | Array |
choices[_].visible (required) | Visibility of phone data type | Boolean |
choices[_].type (required) | Type of phone data | String |
choices[_].text (required) | Optional label of phone data, will default to type | String |
choices[_].options | Optional phone fields | Object |
choices[_].options[_].placeholder_text (optional) | Text that appears before the user types their answer in the fields | String |
{
"headings": [
{
"heading": "Email address"
}
],
"position": 1,
"visible": true,
"family": "demographic",
"subtype": "email",
"answers": {
"choices": [
{
"visible": true,
"type": "email_address",
"text": "Please provide your email address"
}
]
}
}
This corresponds to the Email question type in the SurveyMonkey UI.
Each type
represented in the example object must be included, to disable one, specify visible
as False
Name | Description | Data Type |
---|---|---|
choices | List of available email data | Array |
choices[_].visible (required) | Visibility of email data type | Boolean |
choices[_].type (required) | Must be email_address |
String |
choices[_].text (required) | Optional label for email field | String |
choices[_].options | Optional email fields | Object |
choices[_].options[_].placeholder_text (optional) | Text that appears before the user types their answer in the fields | String |
Name
Name
{
"headings": [
{
"heading": "Name"
}
],
"position": 1,
"visible": true,
"family": "demographic",
"subtype": "name",
"answers": {
"choices": [
{
"visible": true,
"required": true,
"type": "first_name",
"text": "Please provide your first name"
},
{
"visible": true,
"type": "last_name",
"text": "Please provide your last name"
},
{
"visible": true,
"type": "middle_name",
"text": "Please provide your middle name"
},
{
"visible": true,
"required": false,
"type": "title",
"text": "Please provide your title"
},
{
"visible": true,
"type": "suffix",
"text": "Please provide any name suffixes"
}
]
}
}
This corresponds to the Name question type in the SurveyMonkey UI.
Each type
represented in the example object must be included, to disable one, specify visible
as False
Name | Description | Data Type |
---|---|---|
choices | List of available name data | Array |
choices[_].visible (required) | Visibility of name data type | Boolean |
choices[_].required (optional) | Determines if the field needs have an to be answer. By deafult all fields are not required. | Boolean |
choices[_].type (required) | Type of name data, may be first_name , last_name , middle_name , title , or suffix . |
String |
choices[_].text (required) | Optional label of name data, will default to type | String |
choices[_].options | Optional name fields | Object |
choices[_].options[_].placeholder_text (optional) | Text that appears before the user types their answer in the fields | String |
DateTime
DateTime
{
"headings": [
{
"heading": "When did you last eat ice cream?"
}
],
"position": 1,
"visible": true,
"family": "datetime",
"subtype": "both",
"validation": {
"type": "date_us",
"text": "Please enter a date."
},
"answers": {
"rows": [
{
"text": "At:",
"position": 1
}
]
}
}
This corresponds to the DateTime question type in the SurveyMonkey UI.
validation
is required for DateTime questions and must include both type
and text
. type
can be one of date_us
or date_intl
.
Name | Description | Data Type |
---|---|---|
rows[_].text (required) | Label for date/time input box | String |
rows[_].position (optional) | Position of date/time input box | Integer |
Presentation
Presentation
{
"headings": [
{
"heading": "This is a monkey",
"image": {
"url": "http://surveymonkey.com/monkey.jpg"
}
}
],
"position": 1,
"family": "presentation",
"subtype": "image"
}
If image
is included, this corresponds to the Image question type in the SurveyMonkey UI. If not included, it corresponds to the Text question type.
Name | Description | Data Type |
---|---|---|
image (optional) | Image to present | Object |
image[_].image_url (required) | URL of image to present | String |
File Upload
File Upload
{
"headings": [
{
"heading": "Upload your favorite monkey picture."
}
],
"position": 1,
"family": "open_ended",
"subtype": "single",
"display_options": {
"display_type": "file_upload"
}
}
A open ended single answer with the display_options
object can become a File Upload
question.
Name | Description | Data Type |
---|---|---|
display_options[_].display_type (required) | Turns an open ended, single answer question into a file upload question. Always file_upload |
String-ENUM |
Slider
Slider
{
"headings": [
{
"heading": "On a scale of 1 to 100, how much do you like monkeys?"
}
],
"position": 1,
"family": "open_ended",
"subtype": "single",
"display_options": {
"display_type": "slider"
}
}
Slider Complex
{
"headings": [
{
"heading": "On a scale of 1 to 100, how much do you like monkeys?"
}
],
"position": 1,
"family": "open_ended",
"subtype": "single",
"display_options": {
"right_label": "",
"display_type": "slider",
"custom_options": {
"starting_position": 0,
"step_size": 1
},
"left_label": ""
},
"validation": {
"sum_text": "",
"min": 45,
"text": "Please enter a whole number between {0} and {1}.",
"max": 10000,
"type": "integer"
}
}
A open ended single answer with the display_options
object can become a slider
question.
Name | Description | Data Type |
---|---|---|
display_options[_].display_type (required) | Turns an open ended single answer question into a slider question. Always slider |
String-ENUM |
display_options[_].right_label (optional) | Label to place at the right end of the slider | String |
display_options[_].left_label (optional) | Label to place at the left end of the slider | String |
display_options[_].custom_options[_].starting_position (optional) | Where the slider marker is positioned by default | Integer |
display_options[_].custom_options[_].step_size (optional) | Step size the slider increments when moved | Integer |
Emoji (Star Rating)
Emoji (Star Rating)
{
"headings": [
{
"heading": "How many stars on the walk of fame should monkeys have?"
}
],
"position": 1,
"family": "matrix",
"subtype": "rating",
"display_options": {
"display_type": "emoji",
"display_subtype": "star"
},
"forced_ranking": false,
"answers":{
"rows": [
{
"visible": true,
"text": "",
"position": 1
}
],
"choices": [
{
"weight": 1,
"text": ""
},
{
"weight": 2,
"text": ""
},
{
"weight": 3,
"text": ""
},
{
"weight": 4,
"text": ""
},
{
"weight": 5,
"text": ""
}
]
}
}
A rating question with the display_options
object can become an emoji or Star Rating question.
Name | Description | Data Type |
---|---|---|
display_options[_].display_type (required) | Turns and open ended single answer question into an emoji question. Always emoji |
String-ENUM |
display_options[_].display_subtype (required) | Which emoji is displayed: star , smiley , heart , or thumb |
String-ENUM |
Quiz Questions
Quiz Questions
{
"headings": [
{
"heading": "Which monkeys are named after monks?"
}
],
"position": 1,
"family": "multiple_choice",
"subtype": "vertical",
"answers": {
"choices":[
{
"text": "Capuchin",
"quiz_options": {
"score": 10
}
},
{
"text": "Mandrill",
"quiz_options": {
"score": 0
}
}
]
},
"quiz_options": {
"scoring_enabled": true,
"feedback": {
"correct_text": "Nice! That's correct",
"incorrect_text": "Nope, that's wrong"
}
}
}
Quiz scores can be added to any question type with a choices
field.
Name | Description | Data Type |
---|---|---|
choices[_].quiz_options | The configuration object for quiz options | Object |
choices[_].quiz_options.score | How many points the respondent gets when answering this choice | Integer |
Question Bank Questions
Question Bank Questions
{
"question_bank": {
"question_bank_question_id": "669",
"modifier_options": {
"36628": null
}
}
}
Question bank questions can be created with just the question id. Modifier options are either null, or a string, depending on whether the modifier option has user input (e.g. “this company” would be null, “specify a company” would be String).
These question ids can be retrieved via the /v3/question_bank/questions
endpoint.
Name | Description | Data Type |
---|---|---|
question_bank | The configuration object for question bank options | Object |
question_bank[_].question_bank_question_id | The id of the question bank question to be created | String |
question_bank[_].modifier_options | Optional or required depending on the question, used to specify choices that would be in the dropdown menu in the ‘create survey’ page, not applicable for custom question bank. This object is a dictionary of String:String, or String:Null | Object |
question_bank[_].is_custom | Whether or not the question being created comes from a Team’s custom question bank, as opposed to the main Surveymonkey one, defaults to false |
Boolean |
Question Bank
The following endpoint lets you get a list of questions that exist in the question bank. You can then use these to create a question in a survey (See formatting question types).
GET /question_bank/questions
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/question_bank/questions \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/question_bank/questions", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/question_bank/questions", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /question_bank/questions
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of question bank questions available to the user
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page. Defaults to 50. |
locale | string-Enum | false | Return questions for this locale, (see /v3/survey_languages ), defaults to en_US |
search | string | false | Return only questions containing (or related to) this text |
custom | boolean | false | Whether to look through the regular Question Bank, or a Team’s Custom Question Bank, defaults to false |
Example Response for GET /question_bank/questions
{
"data": [
{
"modifiers": [
{
"modifier_type": "open_ended",
"options": [
{
"modifier_options_id": "34658",
"value": "this neighborhood"
},
{
"modifier_options_id": "34659",
"value": "Specify neighborhood"
}
],
"modifier_id": "13196"
}
],
"text": "Overall, how clean is ()?",
"locales": [
"en_AU",
"en_CA",
"en_US"
],
"question_id": "26073"
}
],
"per_page": 1,
"page": 1,
"total": 2598,
"links": {
"self": "https://api.surveymonkey.com/v3/question_bank/questions?page=1&per_page=1",
"next": "https://api.surveymonkey.com/v3/question_bank/questions?page=2&per_page=1",
"last": "https://api.surveymonkey.com/v3/question_bank/questions?page=2598&per_page=1"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
total | integer | |
data | [object] | |
modifiers | [object] | Modifiers that the question allows. e.g. (“this company”, “this brand, "this product”) (empty for Custom QB) |
modifier_type | string | |
options | [object] | |
modifier_options_id | string | |
value | string | |
modifier_id | string | |
locales | [string] | A list of locales that the question supports (empty for Custom QB) |
text | string | The text in the question |
question_id | string | id of the question, to be used in creating it |
links | object | |
next | string | |
last | string | |
self | string | |
page | integer |
Survey Folders
Folders are used to organize surveys. The following endpoints let you retreive and create folders. Add surveys to a certain folder with a POST, PUT, or PATCH to /surveys including it’s folder_id
. You can also filter surveys by folders using folder_id
as a query parameter on GET /surveys.
GET /survey_folders
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/survey_folders \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/survey_folders", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/survey_folders", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /survey_folders
Endpoint currently not available for Canadian users.
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsPOST
: CreatesGET
: Returns available folders
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
Example Response for GET /survey_folders
{
"data": [
{
"title": "SomeApp Polls",
"id": "1845492",
"num_surveys": 19,
"href": "https://api.surveymonkey.com/v3/survey_folders/1845492"
},
{
"title": "Teams Polls",
"id": "1846967",
"num_surveys": 29,
"href": "https://api.surveymonkey.com/v3/survey_folders/1846967"
}
],
"per_page": 50,
"page": 1,
"total": 2,
"links": {
"self": "https://api.surveymonkey.com/v3/survey_folders?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | Number of resources per page |
total | integer | |
data | [object] | |
num_surveys | integer | Number of surveys in the folder |
id | string | ID of the folder |
href | string | Link to the folder |
title | string | Name of the folder |
links | object | |
self | string | |
page | integer |
POST /survey_folders
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/survey_folders \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"title":"NPS Surveys"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"title\":\"NPS Surveys\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/survey_folders", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/survey_folders", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"title\":\"NPS Surveys\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /survey_folders
Endpoint currently not available for Canadian users.
Body parameter
{
"title": "NPS Surveys"
}
Request Body for POST /survey_folders
Name | Type | Required | Description |
---|---|---|---|
title | string | false | Title of the survey folder, used to house a collection of surveys |
Example Response for POST /survey_folders
{
"title": "My Folder",
"id": "1",
"num_surveys": 0,
"href": "https://api.surveymonkey.com/v3/survey_folders/1"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
title | string | Title of the folder |
href | string | Link to the folder |
id | string | ID of the folder |
num_surveys | integer | Number of surveys in the folder |
Translations for Multilingual Surveys
These endpoints let you view and create translations for a multilingual survey. Use GET /survey_languages to see all available languages and their codes, a GET to /surveys/{survey_id}/languages/{language_code} to get all strings for translation, and a POST to /surveys/{survey_id}/languages/{language_code} create a translation.
GET /surveys/{survey_id}/languages
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/languages \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/languages", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/languages", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/languages
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns all existing translations
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
Example Response for /surveys/{survey_id}/languages
{
"per_page": 50,
"total": 1,
"data": [
{
"stale_string_count": 0,
"translated_string_count": 4,
"href": "https://api.surveymonkey.com/v3/surveys/1234/languages/fr",
"inherited_string_count": 0,
"string_count": 8,
"name": "French",
"native_name": "français",
"enabled": true,
"id": "fr"
}
],
"page": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/surveys/1234/languages/?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
per_page | integer | |
page | integer | |
total | integer | |
data | [object] | |
stale_string_count | string | Count of strings that have been updated in the source language since the translation was last updated |
id | string | Language code for the translation |
translated_string_count | integer | Count strings that have translations |
href | string | Resource URL |
inherited_string_count | integer | Count of strings that have empty translations but have a parent translation with an existing translation they can fall back to |
string_count | integer | Count of strings in the array |
name | string | The name of the language in English |
native_name | string | The name of the language in the language itself |
enabled | boolean | If True, translation is available for respondents to select |
links | object | |
self | string |
GET /surveys/{survey_id}/languages/{language_code}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/languages/ \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/languages/", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/languages/", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/languages/{language_code}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns existing translations or the translation structurePOST
: Creates a translationPATCH
: Updates a translationDELETE
: Deletes a translation
Example Response for GET /surveys/{survey_id}/languages/{language_code}
{
"href": "https://api.surveymonkey.com/v3/surveys/1234/languages/fr",
"translations": [
{
"default": "Next",
"translation": "Suiv.",
"context": "survey_next",
"resource_id": "1234"
},
{
"default": "Prev",
"translation": "Préc.",
"context": "survey_prev",
"resource_id": "1234"
},
{
"default": "Done",
"translation": "Terminé",
"context": "survey_done",
"resource_id": "1234"
},
{
"default": "Exit",
"translation": "Quitter",
"context": "survey_exit",
"resource_id": "1234"
},
{
"default": "Thank you for completing our survey!",
"translation": "Merci d'avoir répondu à notre sondage!",
"context": "collector_disqualification",
"resource_id": "1234"
},
{
"default": "Are you multilingual?",
"translation": "",
"context": "question_heading",
"resource_id": "5678"
},
{
"default": "Yes",
"translation": "Oui",
"context": "question_option_text",
"resource_id": "8912"
},
{
"default": "No",
"translation": "Non",
"context": "question_option_text",
"resource_id": "3456"
},
{
"default": "My Survey",
"translation": "Mon Sondage",
"context": "survey_title_html",
"resource_id": "1234"
}
],
"enabled": true,
"id": "fr"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
href | string | |
enabled | boolean | |
id | string | |
translations | [object] | |
default | string | Untranslated text |
translation | string | Translated text shown when a respondent chooses the survey in this language. Translate a survey by filling in all empty translations, |
resource_id | string | Survey, question or answer option id related to the string |
context | integer | Describes the string’s role in the survey |
POST /surveys/{survey_id}/languages/{language_code}
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/surveys/1234/languages/ \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"enabled":true,"translations":[{"default":"Next","translation":"Suiv.","context":"survey_next","resource_id":"1234"},{"default":"Prev","translation":"Préc.","context":"survey_prev","resource_id":"1234"},{"default":"Done","translation":"Terminé","context":"survey_done","resource_id":"1234"},{"default":"Exit","translation":"Quitter","context":"survey_exit","resource_id":"1234"},{"default":"Thank you for completing our survey!","translation":"Merci d'\''avoir répondu à notre sondage!","context":"collector_disqualification","resource_id":"1234"},{"default":"Are you multilingual?","translation":"Êtes-vous multilingue?","context":"question_heading","resource_id":"5678"},{"default":"Yes","translation":"Oui","context":"question_option_text","resource_id":"8912"},{"default":"No","translation":"Non","context":"question_option_text","resource_id":"3456"},{"default":"My Survey","translation":"Mon Sondage","context":"survey_title_html","resource_id":"1234"}]}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"enabled\":true,\"translations\":[{\"default\":\"Next\",\"translation\":\"Suiv.\",\"context\":\"survey_next\",\"resource_id\":\"1234\"},{\"default\":\"Prev\",\"translation\":\"Préc.\",\"context\":\"survey_prev\",\"resource_id\":\"1234\"},{\"default\":\"Done\",\"translation\":\"Terminé\",\"context\":\"survey_done\",\"resource_id\":\"1234\"},{\"default\":\"Exit\",\"translation\":\"Quitter\",\"context\":\"survey_exit\",\"resource_id\":\"1234\"},{\"default\":\"Thank you for completing our survey!\",\"translation\":\"Merci d'avoir répondu à notre sondage!\",\"context\":\"collector_disqualification\",\"resource_id\":\"1234\"},{\"default\":\"Are you multilingual?\",\"translation\":\"Êtes-vous multilingue?\",\"context\":\"question_heading\",\"resource_id\":\"5678\"},{\"default\":\"Yes\",\"translation\":\"Oui\",\"context\":\"question_option_text\",\"resource_id\":\"8912\"},{\"default\":\"No\",\"translation\":\"Non\",\"context\":\"question_option_text\",\"resource_id\":\"3456\"},{\"default\":\"My Survey\",\"translation\":\"Mon Sondage\",\"context\":\"survey_title_html\",\"resource_id\":\"1234\"}]}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/surveys/1234/languages/", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/languages/", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"enabled\":true,\"translations\":[{\"default\":\"Next\",\"translation\":\"Suiv.\",\"context\":\"survey_next\",\"resource_id\":\"1234\"},{\"default\":\"Prev\",\"translation\":\"Préc.\",\"context\":\"survey_prev\",\"resource_id\":\"1234\"},{\"default\":\"Done\",\"translation\":\"Terminé\",\"context\":\"survey_done\",\"resource_id\":\"1234\"},{\"default\":\"Exit\",\"translation\":\"Quitter\",\"context\":\"survey_exit\",\"resource_id\":\"1234\"},{\"default\":\"Thank you for completing our survey!\",\"translation\":\"Merci d'avoir répondu à notre sondage!\",\"context\":\"collector_disqualification\",\"resource_id\":\"1234\"},{\"default\":\"Are you multilingual?\",\"translation\":\"Êtes-vous multilingue?\",\"context\":\"question_heading\",\"resource_id\":\"5678\"},{\"default\":\"Yes\",\"translation\":\"Oui\",\"context\":\"question_option_text\",\"resource_id\":\"8912\"},{\"default\":\"No\",\"translation\":\"Non\",\"context\":\"question_option_text\",\"resource_id\":\"3456\"},{\"default\":\"My Survey\",\"translation\":\"Mon Sondage\",\"context\":\"survey_title_html\",\"resource_id\":\"1234\"}]}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /surveys/{survey_id}/languages/{language_code}
Body parameter
{
"enabled": true,
"translations": [
{
"default": "Next",
"translation": "Suiv.",
"context": "survey_next",
"resource_id": "1234"
},
{
"default": "Prev",
"translation": "Préc.",
"context": "survey_prev",
"resource_id": "1234"
},
{
"default": "Done",
"translation": "Terminé",
"context": "survey_done",
"resource_id": "1234"
},
{
"default": "Exit",
"translation": "Quitter",
"context": "survey_exit",
"resource_id": "1234"
},
{
"default": "Thank you for completing our survey!",
"translation": "Merci d'avoir répondu à notre sondage!",
"context": "collector_disqualification",
"resource_id": "1234"
},
{
"default": "Are you multilingual?",
"translation": "Êtes-vous multilingue?",
"context": "question_heading",
"resource_id": "5678"
},
{
"default": "Yes",
"translation": "Oui",
"context": "question_option_text",
"resource_id": "8912"
},
{
"default": "No",
"translation": "Non",
"context": "question_option_text",
"resource_id": "3456"
},
{
"default": "My Survey",
"translation": "Mon Sondage",
"context": "survey_title_html",
"resource_id": "1234"
}
]
}
Request Body for POST /surveys/{survey_id}/languages/{language_code}
Name | Type | Required | Description |
---|---|---|---|
enabled | boolean | false | If True, translation is available for respondents to select |
translations | array | true | List of translation objects. Each object represents a string in the survey. At least one is required for POST and PATCH. See below for structure. |
200 Response
{}
PATCH /surveys/{survey_id}/languages/{language_code}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/surveys/1234/languages/ \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"enabled":true,"translations":[{"default":"Next","translation":"Suiv.","context":"survey_next","resource_id":"1234"},{"default":"Prev","translation":"Préc.","context":"survey_prev","resource_id":"1234"},{"default":"Done","translation":"Terminé","context":"survey_done","resource_id":"1234"},{"default":"Exit","translation":"Quitter","context":"survey_exit","resource_id":"1234"},{"default":"Thank you for completing our survey!","translation":"Merci d'\''avoir répondu à notre sondage!","context":"collector_disqualification","resource_id":"1234"},{"default":"Are you multilingual?","translation":"Êtes-vous multilingue?","context":"question_heading","resource_id":"5678"},{"default":"Yes","translation":"Oui","context":"question_option_text","resource_id":"8912"},{"default":"No","translation":"Non","context":"question_option_text","resource_id":"3456"},{"default":"My Survey","translation":"Mon Sondage","context":"survey_title_html","resource_id":"1234"}]}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"enabled\":true,\"translations\":[{\"default\":\"Next\",\"translation\":\"Suiv.\",\"context\":\"survey_next\",\"resource_id\":\"1234\"},{\"default\":\"Prev\",\"translation\":\"Préc.\",\"context\":\"survey_prev\",\"resource_id\":\"1234\"},{\"default\":\"Done\",\"translation\":\"Terminé\",\"context\":\"survey_done\",\"resource_id\":\"1234\"},{\"default\":\"Exit\",\"translation\":\"Quitter\",\"context\":\"survey_exit\",\"resource_id\":\"1234\"},{\"default\":\"Thank you for completing our survey!\",\"translation\":\"Merci d'avoir répondu à notre sondage!\",\"context\":\"collector_disqualification\",\"resource_id\":\"1234\"},{\"default\":\"Are you multilingual?\",\"translation\":\"Êtes-vous multilingue?\",\"context\":\"question_heading\",\"resource_id\":\"5678\"},{\"default\":\"Yes\",\"translation\":\"Oui\",\"context\":\"question_option_text\",\"resource_id\":\"8912\"},{\"default\":\"No\",\"translation\":\"Non\",\"context\":\"question_option_text\",\"resource_id\":\"3456\"},{\"default\":\"My Survey\",\"translation\":\"Mon Sondage\",\"context\":\"survey_title_html\",\"resource_id\":\"1234\"}]}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/surveys/1234/languages/", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/languages/", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"enabled\":true,\"translations\":[{\"default\":\"Next\",\"translation\":\"Suiv.\",\"context\":\"survey_next\",\"resource_id\":\"1234\"},{\"default\":\"Prev\",\"translation\":\"Préc.\",\"context\":\"survey_prev\",\"resource_id\":\"1234\"},{\"default\":\"Done\",\"translation\":\"Terminé\",\"context\":\"survey_done\",\"resource_id\":\"1234\"},{\"default\":\"Exit\",\"translation\":\"Quitter\",\"context\":\"survey_exit\",\"resource_id\":\"1234\"},{\"default\":\"Thank you for completing our survey!\",\"translation\":\"Merci d'avoir répondu à notre sondage!\",\"context\":\"collector_disqualification\",\"resource_id\":\"1234\"},{\"default\":\"Are you multilingual?\",\"translation\":\"Êtes-vous multilingue?\",\"context\":\"question_heading\",\"resource_id\":\"5678\"},{\"default\":\"Yes\",\"translation\":\"Oui\",\"context\":\"question_option_text\",\"resource_id\":\"8912\"},{\"default\":\"No\",\"translation\":\"Non\",\"context\":\"question_option_text\",\"resource_id\":\"3456\"},{\"default\":\"My Survey\",\"translation\":\"Mon Sondage\",\"context\":\"survey_title_html\",\"resource_id\":\"1234\"}]}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /surveys/{survey_id}/languages/{language_code}
Body parameter
{
"enabled": true,
"translations": [
{
"default": "Next",
"translation": "Suiv.",
"context": "survey_next",
"resource_id": "1234"
},
{
"default": "Prev",
"translation": "Préc.",
"context": "survey_prev",
"resource_id": "1234"
},
{
"default": "Done",
"translation": "Terminé",
"context": "survey_done",
"resource_id": "1234"
},
{
"default": "Exit",
"translation": "Quitter",
"context": "survey_exit",
"resource_id": "1234"
},
{
"default": "Thank you for completing our survey!",
"translation": "Merci d'avoir répondu à notre sondage!",
"context": "collector_disqualification",
"resource_id": "1234"
},
{
"default": "Are you multilingual?",
"translation": "Êtes-vous multilingue?",
"context": "question_heading",
"resource_id": "5678"
},
{
"default": "Yes",
"translation": "Oui",
"context": "question_option_text",
"resource_id": "8912"
},
{
"default": "No",
"translation": "Non",
"context": "question_option_text",
"resource_id": "3456"
},
{
"default": "My Survey",
"translation": "Mon Sondage",
"context": "survey_title_html",
"resource_id": "1234"
}
]
}
Request Body for PATCH /surveys/{survey_id}/languages/{language_code}
Name | Type | Required | Description |
---|---|---|---|
enabled | boolean | false | If True, translation is available for respondents to select |
translations | array | true | List of translation objects. Each object represents a string in the survey. At least one is required for POST and PATCH. See below for structure. |
200 Response
{}
Contacts and Contact Lists
If your application is using email collectors or sms collectors to collect survey responses, these endpoints let you create contacts and contact lists to send survey invite messages to by passing a contact_id
as an argument to POST
/collectors/{id}/messages/{id}/recipients. NOTE: Contacts can also be created if they are passed directly to /collectors/{id}/messages/{id}/recipients.
GET /contact_lists
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contact_lists \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contact_lists", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contact_lists
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns all contact lists. Public App users need access to the View Contacts scopePOST
: Creates a contact list, contacts can be sent survey invite messages using an email invite or sms collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
Example Response for GET /contact_lists
{
"data": [
{
"id": "1234",
"name": "contact list name",
"href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/contact_lists?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer | |
data | object | |
id | string | Contact list id |
name | string | Contact list name |
href | string | Resource API URL |
POST /contact_lists
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/contact_lists \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"My Contact list"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"name\":\"My Contact list\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/contact_lists", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"name\":\"My Contact list\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /contact_lists
Used to create a new contact list
Body parameter
{
"name": "My Contact list"
}
Request Body for POST /contact_lists
Name | Type | Required | Description |
---|---|---|---|
name | string | false | Contact list name (default=“New List”) |
Example Response for POST /contact_lists
{
"data": [
{
"id": "1234",
"name": "contact list name",
"href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/contact_lists?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer | |
data | object | |
id | string | Contact list id |
name | string | Contact list name |
href | string | Resource API URL |
GET /contact_lists/{contact_list_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contact_lists/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contact_lists/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contact_lists/{contact_list_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a contact list. Public App users need access to the View Contacts scopePATCH
: Modifies a contact list (updates any fields accepted as arguments toPOST
/contact_lists). Public App users need access to the Create/Modify Contacts scopePUT
: Replaces a contact listPOST
(same arguments and requirements asPOST
/contact_lists). Public App users need access to the Create/Modify Contacts scopeDELETE
: Deletes a contact list. Public App users need access to the Create/Modify Contacts scope
Example Response for GET, PATCH, or PUT /contact_lists/{id}
{
"name": "My Contact List",
"id": "1234",
"href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact list id |
name | string | Contact list name |
href | string | Resource API URL |
PATCH /contact_lists/{contact_list_id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/contact_lists/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"string"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"name\":\"string\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/contact_lists/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"name\":\"string\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /contact_lists/{contact_list_id}
PATCH
: Modifies a contact list name
Example Response for PATCH /contact_lists/{id}
{
"name": "My Contact List",
"id": "1234",
"href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact list id |
name | string | Contact list name |
href | string | Resource API URL |
PUT /contact_lists/{contact_list_id}
Code samples
curl --request PUT \
--url https://api.surveymonkey.com/v3/contact_lists/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"name":"string"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"name\":\"string\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PUT", "/v3/contact_lists/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234", {
"method": "PUT",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"name\":\"string\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PUT /contact_lists/{contact_list_id}
PUT
: Replaces a contact listPOST
(same arguments and requirements asPOST
/contact_lists). Public App users need access to the Create/Modify Contacts scope
Example Response for PUT /contact_lists/{contact_list_id}
{
"name": "My Contact List",
"id": "1234",
"href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact list id |
name | string | Contact list name |
href | string | Resource API URL |
POST /contact_lists/{contact_list_id}/copy
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/contact_lists/1234/copy \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/contact_lists/1234/copy", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234/copy", {
"method": "POST",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /contact_lists/{contact_list_id}/copy
Available Methods
POST
: Creates a copy of an existing contact list. Requires Create/Modify Contacts scope
Example Response for POST /contact_lists/{contact_list_id}/copy
{
"name": "My Contact List",
"id": "1234",
"href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact list id |
name | string | Contact list name |
href | string | Resource API URL |
POST /contact_lists/{contact_list_id}/merge
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/contact_lists/1234/merge \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"list_id":"1234"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"list_id\":\"1234\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/contact_lists/1234/merge", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234/merge", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"list_id\":\"1234\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /contact_lists/{contact_list_id}/merge
Available Methods
POST
: Copies contacts in the list specified in the request body and adds to the list specified in the resource URL. Public App users need access to the Create/Modify Contacts scope
Body parameter
{
"list_id": "1234"
}
Request Body for POST /contact_lists/{contact_list_id}/merge
Name | Type | Required | Description |
---|---|---|---|
list_id | string | true | A single contact list ID to merged with the contact list id pass in the url |
Example Response for POST /contact_lists/{contact_list_id}/merge
{
"name": "My Contact List",
"id": "1234",
"href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact list id |
name | string | Contact list name |
href | string | Resource API URL |
GET /contact_lists/{contact_list_id}/contacts
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contact_lists/1234/contacts \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contact_lists/1234/contacts", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234/contacts", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contact_lists/{contact_list_id}/contacts
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns all contacts in a contact list. Public App users need access to the View Contacts scopePOST
: Creates a new contact and adds them to a contact list, contacts can be sent survey invite messages using an email invite or sms collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
status | string | false | Filter by status (default=active): active , optout or bounced |
sort_by | string | false | Field used to sort returned contact list (default=email): email , first_name , last_name , 1 , …, 6 |
sort_order | string | false | Sort order with the following options [‘ASC’,‘asc’, 'DESC’,‘desc’] |
search_by | string | false | The search_bu parameter needs to be used with search . Field used to search the selected contact_list. user can seach by email, first_name, last_name, or phone_number |
search | string | false | Query used to search, the search parameter needs to be used with search_by |
Enumerated Values
Parameter | Value |
---|---|
status | active |
status | optout |
status | bounced |
sort_by | |
sort_by | first_name |
sort_by | last_name |
sort_order | ASC |
sort_order | asc |
sort_order | DESC |
sort_order | desc |
search_by | |
search_by | first_name |
search_by | last_name |
search_by | phone_number |
Response Example for GET and POST /contact_lists/{id}/contacts
{
"id": "1234",
"first_name": "John",
"last_name": "Doe",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156",
"custom_fields": {
"1": "Mr",
"2": "Company",
"3": "Address",
"4": "City",
"5": "Country",
"6": "Phone Number"
},
"href": "https://api.surveymonkey.com/v3/contacts/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
custom_fields | object | Contact custom fields |
href | string | Resource API URL |
POST /contact_lists/{contact_list_id}/contacts
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/contact_lists/1234/contacts \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/contact_lists/1234/contacts", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234/contacts", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /contact_lists/{contact_list_id}/contacts
Body parameter
{}
GET /contact_lists/{contact_list_id}/contacts/bulk
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contact_lists/1234/contacts/bulk \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contact_lists/1234/contacts/bulk", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234/contacts/bulk", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contact_lists/{contact_list_id}/contacts/bulk
Available Methods
GET
: Returns a list of all contacts in the list with all available fields. Public App users need access to the View Contacts scopePOST
: Creates multiple contacts and adds them to a list, contacts can be sent survey invite messages using an email invite or sms collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | integer | false | Page number. Defaults to 1 |
per_page | integer | false | Number of contacts to return per page |
sort_by | string | false | sort_by either email, first_name, or last_name |
status | string | false | Filter by status (default=active): active , optout , bounced |
sort_order | string | false | Sort order e.g. [‘ASC’, 'DESC’] |
search_by | string | false | Field used to search returned contact list: : email , first_name , last_name , 1 , …, 50 |
search | string | false | Query used to search |
Enumerated Values
Parameter | Value |
---|---|
sort_by | |
sort_by | first_name |
sort_by | last_name |
Example Response for GET and POST /contacts_lists/{contact_list_id}/contacts/bulk
{
"data": [
{
"id": "1",
"first_name": "",
"last_name": "",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/contacts/bulk?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | |
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean | |
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer |
POST /contact_lists/{contact_list_id}/contacts/bulk
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/contact_lists/1234/contacts/bulk \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"update_existing":true,"contacts":[{}]}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"update_existing\":true,\"contacts\":[{}]}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/contact_lists/1234/contacts/bulk", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists/1234/contacts/bulk", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"update_existing\":true,\"contacts\":[{}]}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /contact_lists/{contact_list_id}/contacts/bulk
Body parameter
{
"update_existing": true,
"contacts": [
{}
]
}
Request Body for POST /contact_lists/{id}/contacts/bulk
Name | Type | Required | Description |
---|---|---|---|
update_existing | boolean | false | Whether or not to update existing contacts |
contacts | [anyOf] | true | Contacts to add |
Example Response for POST /contact_lists/{id}/contacts/bulk
{
"succeeded": [
{
"first_name": "John",
"last_name": "Doe",
"id": "1234",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156",
"custom_fields": {
"1": "Mr",
"2": "Company",
"3": "Address",
"4": "City",
"5": "Country",
"6": "Phone Number"
}
}
],
"invalids": [
{}
],
"existing": [
{}
]
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
succeeded | array | List of successfully added contact objects |
succeeded.id | string | Id for the contact |
succeeded.email | string | Email address for the contact |
succeeded.phone_number | string | Phone number for the contact |
succeeded.first_name | string | First name for the contact |
succeeded.last_name | string | Last name for the contact |
invalids | array | List of invalid contact email addresses that were provided |
existing | array | List of contact email addresses that have already been added |
GET /contacts
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contacts \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contacts", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contacts", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contacts
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of all contacts. Public App users need access to the View Contacts scopePOST
: Creates a new contact, contacts can be sent survey invite messages using an email invite or sms collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | string | false | Which page of resources to return. Defaults to 1 |
per_page | string | false | Number of resources to return per page |
status | string | false | Filter by status (default=active): active , optout or bounced |
sort_by | string | false | Field used to sort returned contact list (default=email): email , first_name , last_name , 1 , …, 6 |
sort_order | string | false | Sort order with the following options [‘ASC’,‘asc’, 'DESC’,‘desc’] |
search_by | string | false | The search_bu parameter needs to be used with search . Field used to search the selected contact_list. user can seach by email, first_name, last_name, or phone_number |
search | string | false | Query used to search, the search parameter needs to be used with search_by |
Enumerated Values
Parameter | Value |
---|---|
status | active |
status | optout |
status | bounced |
sort_by | |
sort_by | first_name |
sort_by | last_name |
sort_order | ASC |
sort_order | asc |
sort_order | DESC |
sort_order | desc |
search_by | |
search_by | first_name |
search_by | last_name |
search_by | phone_number |
Example Response for GET /contacts
{
"data": [
{
"id": "1",
"first_name": "",
"last_name": "",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/contacts/bulk?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | |
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean | |
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer |
POST /contacts
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/contacts \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"first_name":"Quinn","last_name":"Doe","email":"test@surveymonkey.com","phone_number":"+1 202 555 0156"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"first_name\":\"Quinn\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":\"+1 202 555 0156\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/contacts", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contacts", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"first_name\":\"Quinn\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":\"+1 202 555 0156\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /contacts
Body parameter
{
"first_name": "Quinn",
"last_name": "Doe",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156"
}
Example Response for POST /contacts
{
"data": [
{
"id": "1",
"first_name": "",
"last_name": "",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/contacts/bulk?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | |
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean | |
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer |
GET /contacts/bulk
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contacts/bulk \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contacts/bulk", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contacts/bulk", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contacts/bulk
Available Methods
GET
: Returns a list of all contacts with all available fields. Public App users need access to the View Contacts scopePOST
: Creates multiple contacts, contacts can be sent survey invite messages using an email invite or sms collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | integer | false | Page number. Defaults to 1 |
per_page | integer | false | Number of contacts to return per page |
sort_by | string | false | Number of contacts to return per page |
status | string | false | Filter by status (default=active): active , optout , bounced |
sort_order | string | false | Sort order e.g. [‘ASC’, 'DESC’] |
search_by | string | false | Field used to search returned contact list: : email , first_name , last_name , 1 , …, 50 |
search | string | false | Query used to search |
Enumerated Values
Parameter | Value |
---|---|
sort_by | |
sort_by | first_name |
sort_by | last_name |
Example Response for GET /contacts/bulk
{
"data": [
{
"id": "1",
"first_name": "",
"last_name": "",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/contacts/bulk?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | |
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean | |
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer |
POST /contacts/bulk
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/contacts/bulk \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"update_existing":true,"contacts":[{}]}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"update_existing\":true,\"contacts\":[{}]}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/contacts/bulk", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contacts/bulk", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"update_existing\":true,\"contacts\":[{}]}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /contacts/bulk
Body parameter
{
"update_existing": true,
"contacts": [
{}
]
}
Request Body for POST /contacts/bulk
Name | Type | Required | Description |
---|---|---|---|
update_existing | boolean | false | Whether or not to update existing contacts |
contacts | [anyOf] | true | Contacts to add |
Example Response for POST /contacts/bulk
{
"data": [
{
"id": "1",
"first_name": "",
"last_name": "",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/contacts/bulk?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | [object] | |
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean | |
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer |
GET /contacts/{contact_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contacts/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contacts/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contacts/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contacts/{contact_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a contact. Public App users need access to the View Contacts scopePATCH
: Modifies a contact (updates any fields accepted as arguments toPOST
/contacts. Public App users need access to the Create/Modify Contacts scopePUT
: Replaces a contact (same arguments and requirements asPOST
/contacts). Public App users need access to the Create/Modify Contacts scopeDELETE
: Deletes a contact. Public App users need access to the Create/Modify Contacts scope
Example Response for GET, POST, and PATCH /contacts/{contact_id}
{
"first_name": "",
"last_name": "",
"email": "name@email.com",
"phone_number": "+1 202 555 0156",
"custom_fields": null,
"id": "1",
"status": "active",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean |
PATCH /contacts/{contact_id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/contacts/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"first_name":"Quinn","last_name":"Doe","email":"test@surveymonkey.com","phone_number":"+1 202 555 0156"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"first_name\":\"Quinn\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":\"+1 202 555 0156\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/contacts/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contacts/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"first_name\":\"Quinn\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":\"+1 202 555 0156\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /contacts/{contact_id}
PATCH
: Modifies a contact (updates any fields accepted as arguments toPOST
/contacts. Public App users need access to the Create/Modify Contacts scope
Body parameter
{
"first_name": "Quinn",
"last_name": "Doe",
"email": "test@surveymonkey.com",
"phone_number": "+1 202 555 0156"
}
update a contact information
Name | Type | Required | Description |
---|---|---|---|
first_name | string | undefined | Contact first name |
last_name | string | undefined | Contact last name |
string | undefined | Contact email address. Required if no phone_number | |
phone_number | string | undefined | Contact phone_number. Required if no email |
Example response for PATCH /contacts/{contact_id}
{
"first_name": "",
"last_name": "",
"email": "name@email.com",
"phone_number": "+1 202 555 0156",
"custom_fields": null,
"id": "1",
"status": "active",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean |
PUT /contacts/{contact_id}
Code samples
curl --request PUT \
--url https://api.surveymonkey.com/v3/contacts/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"first_name":"Quinn","last_name":"Doe","email":"test@surveymonkey.com","phone_number":"+1 202 555 0156"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"first_name\":\"Quinn\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":\"+1 202 555 0156\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PUT", "/v3/contacts/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contacts/1234", {
"method": "PUT",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"first_name\":\"Quinn\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":\"+1 202 555 0156\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PUT /contacts/{contact_id}
PUT
: Replaces a contact (same arguments and requirements asPOST
/contacts). Public App users need access to the Create/Modify Contacts scope
Example response for PUT /contacts/{contact_id}
{
"first_name": "",
"last_name": "",
"email": "name@email.com",
"phone_number": "+1 202 555 0156",
"custom_fields": null,
"id": "1",
"status": "active",
"href": "https://api.surveymonkey.com/v3/contacts/1"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact id |
first_name | string | Contact first name |
last_name | string | Contact last name |
string | Contact email address | |
phone_number | string | Contact phone number |
href | string | Resource API URL |
custom_fields | object | Custom fields |
status | boolean |
GET /contact_fields
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contact_fields \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contact_fields", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_fields", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contact_fields
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of all custom contacts fields. Public App users need access to the View Contacts scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | integer | false | Page number. Default is 1 |
per_page | integer | false | Number of contacts to return per page, Default is 50 |
Example Response for GET /contact_fields
{
"page": 1,
"per_page": 1,
"total": 1,
"data": [
{
"href": "https://api.surveymonkey.com/v3/contact_fields/1",
"id": "1",
"label": "Custom 1"
}
],
"links": {
"self": "https://api.surveymonkey.com/v3/contact_fields?page=1&per_page=1"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | object | |
id | string | Contact id |
label | string | Contact Field Label |
href | string | Resource API URL |
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer |
GET /contact_fields/{contact_field_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/contact_fields/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/contact_fields/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_fields/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /contact_fields/{contact_field_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns the specified custom contact field. Public App users need access to the View Contacts scopePATCH
: Modifies a custom contact field’s label. Public App users need access to the Create/Modify Contacts scope
Example Response for GET /contact_fields/{id}
{
"href": "https://api.surveymonkey.com/v3/contact_fields/1",
"id": "1",
"label": "Custom 1"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact id |
label | string | Contact Field Label |
href | string | Resource API URL |
PATCH /contact_fields/{contact_field_id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/contact_fields/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"label":"Custom 1"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"label\":\"Custom 1\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/contact_fields/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_fields/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"label\":\"Custom 1\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /contact_fields/{contact_field_id}
Body parameter
{
"label": "Custom 1"
}
Request Body for PATCH /contact_fields/{contact_field_id}
Name | Type | Required | Description |
---|---|---|---|
label | string | true | Label assigned to the custom contact field |
Example response for PATCH /contact_fields/{id}
{
"href": "https://api.surveymonkey.com/v3/contact_fields/1",
"id": "1",
"label": "Custom 1"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
id | string | Contact id |
label | string | Contact Field Label |
href | string | Resource API URL |
Collectors and Invite Messages
Collectors allow you to collect survey responses with a link to your survey. Many types
of collectors are available through the API such as sms
, weblink
, email
and general popup
collectors. Weblink collectors collectors give you a survey URL, email invitation collectors and sms invitation collectors send survey invite messages with a survey URL via the /messages endpoints, popup collectors let you embed surveys on your website. A variety of collector options are accepted as arguments to /surveys/{id}/collectors. All collectors except for weblink collectors and some collector options, for example, is_branding_enabled=False
require a SurveyMonkey paid plan.
GET /surveys/{survey_id}/collectors
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/surveys/1234/collectors \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/surveys/1234/collectors", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/collectors", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /surveys/{survey_id}/collectors
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a list of collectors for a given survey. Public App users need access to the View Collectors scopePOST
: Creates an sms, weblink, email collector or popup collector for a given survey. Public App users need access to the Create/Modify Collectors scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
page | integer | false | Which page of resources to return. Defaults to 1 |
per_page | integer | false | Number of resources to return per page |
sort_by | string | false | Field used to sort returned collector list e.g. [‘id’, ‘date_modified’, ‘type’, ‘status’, ‘name’] |
sort_order | string | false | Sort order e.g. [‘ASC’, ‘DESC’] |
name | string | false | Nickname of collector to search against |
start_date | string | false | Collectors must be created after this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
end_date | string | false | Collectors must be created before this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset) |
include | string | false | Specify additional fields to return per collector: ‘type’, ‘status’, ‘response_count’, ‘date_created’, ‘date_modified’, ‘url’ |
Example Response for GET /surveys/{survey_id}/collectors
{
"data": [
{
"name": "Teams Poll",
"id": "1",
"href": "https://api.surveymonkey.com/v3/collectors/1"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/surveys/309536605/collectors?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | object | |
id | string | Collector id |
name | string | Collector Name |
href | string | Resource API URL |
links | object | |
self | string | |
page | integer | |
per_page | integer | |
total | integer |
POST /surveys/{survey_id}/collectors
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/surveys/1234/collectors \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"type":"string","name":"string","thank_you_page":{"is_enabled":true,"message":"string"},"thank_you_message":"string","disqualification_message":"string","disqualification_url":"string","close_date":"string","closed_page_message":"string","redirect_url":"string","display_survey_results":true,"edit_response_type":"string","anonymous_type":"string","allow_multiple_responses":true,"password":"string","sender_email":"string","response_limit":0,"redirect_type":"string","width":0,"height":0,"border_color":"#FFFFFF","is_branding_enabled":true,"headline":"string","message":"string","sample_rate":0,"primary_button":{"bg_color":"#FFFFFF","text_color":"#000000","text":"string"},"secondary_button":{"bg_color":"#FFFFFF","text_color":"#000000","text":"string"},"respondent_authentication":false,"from_collector_id":"string"}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"type\":\"string\",\"name\":\"string\",\"thank_you_page\":{\"is_enabled\":true,\"message\":\"string\"},\"thank_you_message\":\"string\",\"disqualification_message\":\"string\",\"disqualification_url\":\"string\",\"close_date\":\"string\",\"closed_page_message\":\"string\",\"redirect_url\":\"string\",\"display_survey_results\":true,\"edit_response_type\":\"string\",\"anonymous_type\":\"string\",\"allow_multiple_responses\":true,\"password\":\"string\",\"sender_email\":\"string\",\"response_limit\":0,\"redirect_type\":\"string\",\"width\":0,\"height\":0,\"border_color\":\"#FFFFFF\",\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":0,\"primary_button\":{\"bg_color\":\"#FFFFFF\",\"text_color\":\"#000000\",\"text\":\"string\"},\"secondary_button\":{\"bg_color\":\"#FFFFFF\",\"text_color\":\"#000000\",\"text\":\"string\"},\"respondent_authentication\":false,\"from_collector_id\":\"string\"}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/surveys/1234/collectors", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/collectors", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"type\":\"string\",\"name\":\"string\",\"thank_you_page\":{\"is_enabled\":true,\"message\":\"string\"},\"thank_you_message\":\"string\",\"disqualification_message\":\"string\",\"disqualification_url\":\"string\",\"close_date\":\"string\",\"closed_page_message\":\"string\",\"redirect_url\":\"string\",\"display_survey_results\":true,\"edit_response_type\":\"string\",\"anonymous_type\":\"string\",\"allow_multiple_responses\":true,\"password\":\"string\",\"sender_email\":\"string\",\"response_limit\":0,\"redirect_type\":\"string\",\"width\":0,\"height\":0,\"border_color\":\"#FFFFFF\",\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":0,\"primary_button\":{\"bg_color\":\"#FFFFFF\",\"text_color\":\"#000000\",\"text\":\"string\"},\"secondary_button\":{\"bg_color\":\"#FFFFFF\",\"text_color\":\"#000000\",\"text\":\"string\"},\"respondent_authentication\":false,\"from_collector_id\":\"string\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /surveys/{survey_id}/collectors
Call Types:
Blank
: Creating a collector from scratchCopy
: Creating a collector by Copying an existing collector
Body parameter
{
"type": "string",
"name": "string",
"thank_you_page": {
"is_enabled": true,
"message": "string"
},
"thank_you_message": "string",
"disqualification_message": "string",
"disqualification_url": "string",
"close_date": "string",
"closed_page_message": "string",
"redirect_url": "string",
"display_survey_results": true,
"edit_response_type": "string",
"anonymous_type": "string",
"allow_multiple_responses": true,
"password": "string",
"sender_email": "string",
"response_limit": 0,
"redirect_type": "string",
"width": 0,
"height": 0,
"border_color": "#FFFFFF",
"is_branding_enabled": true,
"headline": "string",
"message": "string",
"sample_rate": 0,
"primary_button": {
"bg_color": "#FFFFFF",
"text_color": "#000000",
"text": "string"
},
"secondary_button": {
"bg_color": "#FFFFFF",
"text_color": "#000000",
"text": "string"
},
"respondent_authentication": false,
"from_collector_id": "string"
}
Request Body for POST /surveys/{survey_id}/collectors
Name | Type | Required | Description |
---|---|---|---|
type | string | undefined | 'sms, ‘weblink’, ‘email’. Popup Collectors: ‘popup_invitation’, ‘embedded_survey’, ‘popup_survey’ |
name | string | true | Collector name |
thank_you_page | object | is_enabled | Settings for a custom thank you page. This is a replacement for thank_you_message and should be used instead of that. Using thank_you_page supersedes thank_you_message . |
is_enabled | boolean | true | Whether to use the custom thank you message. This toggles the use of message . |
message | string | false | Custom message for the thank you page (default=‘Thank you for completing our survey!’), regardless of whether a custom thank you message is enabled. |
thank_you_message | string | false | Message for thank you page (default=‘Thank you for completing our survey!’). This is an older form of thank_you_page and should not be used. |
disqualification_message | string | false | Message for disqualification page (default=‘Thank you for completing our survey!’) |
disqualification_url | string | false | Redirect to this url for disqualification page |
close_date | string | false | Close date of collector |
closed_page_message | string | false | Message shown when a survey is closed (default=‘Thank you for completing our survey!’) |
redirect_url | string | false | Redirect to this url upon survey completion |
display_survey_results | boolean | false | Shows respondents survey instant results when they complete the survey (default=False) |
edit_response_type | string | false | When respondents can edit their response: ‘until_complete’, ‘never’, or ‘always’ (default=‘until_complete’) |
anonymous_type | string | false | Turns off IP tracking. For email collectors, also removes respondent email address and name from response: ‘not_anonymous’, ‘partially_anonymous’, ‘fully_anonymous’ (default=‘not_anonymous’) |
allow_multiple_responses | boolean | false | Allows respondents to take a survey more than once from the same browser on the same computer. Not available for email collectors (default=False) |
password | string | false | Set a password to restrict access to your survey |
sender_email | string | false | Sender email for email collectors |
response_limit | integer | false | Sets the collector to close after specified number of responses are collected |
redirect_type | string | false | Determines survey end page behavior: url (redirects to URL set in redirect_url or if none is set, shows standard SurveyMonkey thank you page), close (closes the survey window or tab), or loop (loops the survey back to the beginning, only available for weblink collectors with allow_multiple_responses :true) |
width | integer | false | Sets the width of your popup. Minimum 300, maximium 700 |
height | integer | false | Sets the height of your popup. Minimum 300, maximium 700 |
border_color | string | false | Changes border color surrounding the survey |
is_branding_enabled | boolean | false | Whether the popup has SurveyMonkey branding |
headline | string | false | Only applies to ‘popup_invitation’ and ‘popup_survey’. Represents the title of the modal window surrounding the survey |
message | string | false | Only applies to ‘popup_invitation’. Represents the message below the headline |
sample_rate | integer | false | Only applies to ‘popup_invitation’ and ‘popup_survey’. Determines the percentage of people who will see your popup. Must be between 1 and 100 |
primary_button | object | undefined | Only applies to ‘popup_invitation’. Users who click the primary button will be taken to the beginning of your survey |
bg_color | string | false | Primary button’s background color |
text_color | string | false | Primary button’s text color |
text | string | false | The text on the primary button |
secondary_button | object | undefined | Only applies to ‘popup_invitation’. The secondary button closes the popup. Once a user has seen the popup, they will not see it again |
bg_color | string | false | Secondary button’s background color |
text_color | string | false | Secondary button’s text color |
text | string | false | The text on the secondary button |
respondent_authentication | boolean | false | Indicates whether Respondent Authentication is required. This is used in conjunction with single sign-on (SSO) to require respondents to sign-in. You can use Respondent Authentication to send more secure internal surveys and track the people taking your survey with SSO metadata. |
from_collector_id | string | false | Collector ID to copy collector from |
Response for POST /surveys/{survey_id}/collectors
{
"status": "open",
"id": "1234",
"type": "weblink",
"name": "My Collector",
"thank_you_page": {
"is_enabled": true,
"message": "Thank you for taking my survey."
},
"thank_you_message": "Thank you for taking my survey.",
"disqualification_message": "Thank you for taking my survey.",
"disqualification_url": "https://www.surveymonkey.com",
"close_date": "2038-01-01T00:00:00+00:00",
"closed_page_message": "This survey is currently closed.",
"redirect_url": "https://www.surveymonkey.com",
"display_survey_results": false,
"edit_response_type": "until_complete",
"anonymous_type": "not_anonymous",
"allow_multiple_responses": false,
"date_modified": "2015-10-06T12:56:55+00:00",
"url": "https://www.surveymonkey.com/r/2Q3RXZB",
"open": true,
"date_created": "2015-10-06T12:56:55+00:00",
"password_enabled": false,
"sender_email": null,
"response_limit": null,
"redirect_type": "url",
"respondent_authentication": false,
"href": "https://api.surveymonkey.com/v3/collectors/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
response_count | integer | |
close_date | any | |
anonymous_type | string | |
type | string | |
allow_multiple_responses | boolean | |
id | string | |
href | string | |
closed_page_message | string | |
redirect_type | string | |
thank_you_page | object | Settings for a custom thank you page. This is a replacement for thank_you_message and should be used instead of that. Using thank_you_page supersedes thank_you_message . |
is_enabled | boolean | Whether to use the custom thank you message. This toggles the use of message . |
message | string | Custom message for the thank you page (default=‘Thank you for completing our survey!’), regardless of whether a custom thank you message is enabled. |
thank_you_message | string | |
sender_email | any | |
password_enabled | boolean | |
date_created | string | |
edit_response_type | string | |
disqualification_url | string | |
url | any | |
survey_id | string | |
response_limit | any | |
date_modified | string | |
disqualification_type | string | |
name | string | |
display_survey_results | boolean | |
redirect_url | string | |
status | string | |
disqualification_message | string | |
respondent_authentication | boolean |
GET /collectors/{collector_id}
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/collectors/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/collectors/1234", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /collectors/{collector_id}
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a collectorPATCH
: Modifies a collector (updates any fields accepted as arguments toPOST
/surveys/{survey_id}/collectors, with the addition ofstatus
and the removal oftype
). Public App users need access to the Create/Modify Collectors scopePUT
: Replaces a collector (same arguments and requirements asPOST
/surveys/{survey_id}/collectors, with the addition ofstatus
and the removal oftype
). Public App users need access to the Create/Modify Collectors scopeDELETE
: Deletes a collector. Public App users need access to the Create/Modify Collectors scope
Example Response for GET, PATCH, PUT /collectors/{collector_id}
{
"status": "open",
"id": "1234",
"survey_id": "123456789",
"type": "weblink",
"name": "My Collector",
"thank_you_message": "Thank you for taking my survey.",
"thank_you_page": {
"is_enabled": true,
"message": "Thank you for taking my survey."
},
"disqualification_message": "Thank you for taking my survey.",
"disqualification_url": "https://www.surveymonkey.com",
"close_date": "2038-01-01T00:00:00+00:00",
"closed_page_message": "This survey is currently closed.",
"redirect_url": "https://www.surveymonkey.com",
"display_survey_results": false,
"edit_response_type": "until_complete",
"anonymous_type": "not_anonymous",
"allow_multiple_responses": false,
"date_modified": "2015-10-06T12:56:55+00:00",
"url": "https://www.surveymonkey.com/r/2Q3RXZB",
"date_created": "2015-10-06T12:56:55+00:00",
"sender_email": null,
"password_enabled": false,
"response_limit": 100,
"redirect_type": "url",
"respondent_authentication": false,
"href": "https://api.surveymonkey.com/v3/collectors/1234"
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
status | string | Collector status: ‘open’ or ‘closed’ |
id | string | Collector id |
survey_id | string | ID of the survey the collector belongs to |
type | string | Collector type: ‘sms’, ‘weblink’ or ‘email’ |
name | string | Name of the collector |
thank_you_page | object | Settings for a custom thank you page. This is a replacement for thank_you_message and should be used instead of that. Using thank_you_page supersedes thank_you_message . |
is_enabled | boolean | Whether to use the custom thank you message. This toggles the use of message . |
message | string | Custom message for the thank you page (default=‘Thank you for completing our survey!’), regardless of whether a custom thank you message is enabled. |
thank_you_message | string | Message for thank you page |
disqualification_message | string | Message for disqualification page |
disqualification_url | string | Redirect to this url for disqualification page |
close_date | string | Close date of collector |
closed_page_message | string | Message shown when someone visits a closed survey |
redirect_url | string | Redirects respondent to this url upon survey completion |
display_survey_results | boolean | Shows respondents survey instant results when they complete the survey |
edit_response_type | string | When respondents can edit their response: ‘until_complete’, ‘never’, or ‘always’ |
anonymous_type | string | Turns off IP tracking. For email collectors, also removes respondent email address and name from response: ‘not_anonymous’, ‘partially_anonymous’, ‘fully_anonymous’ |
allow_multiple_responses | boolean | Allows respondents to take a survey more than once from the same browser on the same computer. Only available for weblink collectors. |
date_modified | string | Date collector was last modified |
url | string | If collector is a Web Collector (type ‘weblink’) then the url for the collector |
date_created | string | Date collector was created |
password_enabled | boolean | True if the collector is password protected |
sender_email | string | Sender email for email collectors. User’s email is used if null |
redirect_type | string | Determines survey end page behavior: url (redirects to URL set in redirect_url or if none is set, shows standard SurveyMonkey thank you page), close (closes the survey window or tab), or loop (loops the survey back to the beginning, only available for weblink collectors with allow_multiple_responses :true) |
href | string | Resource API URL |
width | integer | Width of your popup |
height | integer | Height of your popup |
border_color | Hex string | Border color surrounding the survey |
is_branding_enabled | boolean | Whether the popup has SurveyMonkey branding |
headline | string | Title of the modal window surrounding the survey |
message | string | The message below the headline |
sample_rate | string | The percentage of people who will see your popup |
primary_button | object | The primary button of your popup |
bg_color | Hex string | Primary button’s background color |
text_color | Hex string | Primary button’s text color |
text | string | The text on the primary button |
secondary_button | object | The secondary button of your popup |
bg_color | Hex string | Secondary button’s background color |
text_color | Hex string | Secondary button’s text color |
text | string | The text on the secondary button |
respondent_authentication | boolean | Indicates whether Respondent Authentication is required. This is used in conjunction with single sign-on (SSO) to require respondents to sign-in. You can use Respondent Authentication to send more secure internal surveys and track the people taking your survey with SSO metadata. |
PATCH /collectors/{collector_id}
Code samples
curl --request PATCH \
--url https://api.surveymonkey.com/v3/collectors/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"status":"open","name":"string","thank_you_message":"string","thank_you_page":{"is_enabled":true,"message":"string"},"disqualification_message":"string","disqualification_url":"string","close_date":"string","closed_page_message":"string","redirect_url":"string","display_survey_results":true,"edit_response_type":"string","anonymous_type":"string","allow_multiple_responses":true,"password":"string","sender_email":"string","response_limit":0,"redirect_type":"string","width":0,"height":0,"border_color":"string","is_branding_enabled":true,"headline":"string","message":"string","sample_rate":0,"primary_button":{"bg_color":"string","text_color":"string","text":"string"},"secondary_button":{"bg_color":"string","text_color":"string","text":"string"},"respondent_authentication":false}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"status\":\"open\",\"name\":\"string\",\"thank_you_message\":\"string\",\"thank_you_page\":{\"is_enabled\":true,\"message\":\"string\"},\"disqualification_message\":\"string\",\"disqualification_url\":\"string\",\"close_date\":\"string\",\"closed_page_message\":\"string\",\"redirect_url\":\"string\",\"display_survey_results\":true,\"edit_response_type\":\"string\",\"anonymous_type\":\"string\",\"allow_multiple_responses\":true,\"password\":\"string\",\"sender_email\":\"string\",\"response_limit\":0,\"redirect_type\":\"string\",\"width\":0,\"height\":0,\"border_color\":\"string\",\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":0,\"primary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"secondary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"respondent_authentication\":false}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/v3/collectors/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234", {
"method": "PATCH",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"status\":\"open\",\"name\":\"string\",\"thank_you_message\":\"string\",\"thank_you_page\":{\"is_enabled\":true,\"message\":\"string\"},\"disqualification_message\":\"string\",\"disqualification_url\":\"string\",\"close_date\":\"string\",\"closed_page_message\":\"string\",\"redirect_url\":\"string\",\"display_survey_results\":true,\"edit_response_type\":\"string\",\"anonymous_type\":\"string\",\"allow_multiple_responses\":true,\"password\":\"string\",\"sender_email\":\"string\",\"response_limit\":0,\"redirect_type\":\"string\",\"width\":0,\"height\":0,\"border_color\":\"string\",\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":0,\"primary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"secondary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"respondent_authentication\":false}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PATCH /collectors/{collector_id}
PATCH
: Modifies a collector (updates any fields accepted as arguments toPOST
/surveys/{survey_id}/collectors, with the addition ofstatus
and the removal oftype
). Public App users need access to the Create/Modify Collectors scope
PUT /collectors/{collector_id}
Code samples
curl --request PUT \
--url https://api.surveymonkey.com/v3/collectors/1234 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"status":"open","name":"string","thank_you_message":"string","thank_you_page":{"is_enabled":true,"message":"string"},"disqualification_message":"string","disqualification_url":"string","close_date":"string","closed_page_message":"string","redirect_url":"string","display_survey_results":true,"edit_response_type":"string","anonymous_type":"string","allow_multiple_responses":true,"password":"string","sender_email":"string","response_limit":0,"redirect_type":"string","width":0,"height":0,"border_color":"string","is_branding_enabled":true,"headline":"string","message":"string","sample_rate":0,"primary_button":{"bg_color":"string","text_color":"string","text":"string"},"secondary_button":{"bg_color":"string","text_color":"string","text":"string"},"respondent_authentication":false}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"status\":\"open\",\"name\":\"string\",\"thank_you_message\":\"string\",\"thank_you_page\":{\"is_enabled\":true,\"message\":\"string\"},\"disqualification_message\":\"string\",\"disqualification_url\":\"string\",\"close_date\":\"string\",\"closed_page_message\":\"string\",\"redirect_url\":\"string\",\"display_survey_results\":true,\"edit_response_type\":\"string\",\"anonymous_type\":\"string\",\"allow_multiple_responses\":true,\"password\":\"string\",\"sender_email\":\"string\",\"response_limit\":0,\"redirect_type\":\"string\",\"width\":0,\"height\":0,\"border_color\":\"string\",\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":0,\"primary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"secondary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"respondent_authentication\":false}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("PUT", "/v3/collectors/1234", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234", {
"method": "PUT",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"status\":\"open\",\"name\":\"string\",\"thank_you_message\":\"string\",\"thank_you_page\":{\"is_enabled\":true,\"message\":\"string\"},\"disqualification_message\":\"string\",\"disqualification_url\":\"string\",\"close_date\":\"string\",\"closed_page_message\":\"string\",\"redirect_url\":\"string\",\"display_survey_results\":true,\"edit_response_type\":\"string\",\"anonymous_type\":\"string\",\"allow_multiple_responses\":true,\"password\":\"string\",\"sender_email\":\"string\",\"response_limit\":0,\"redirect_type\":\"string\",\"width\":0,\"height\":0,\"border_color\":\"string\",\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":0,\"primary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"secondary_button\":{\"bg_color\":\"string\",\"text_color\":\"string\",\"text\":\"string\"},\"respondent_authentication\":false}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
PUT /collectors/{collector_id}
PUT
: Replaces a collector (same arguments and requirements asPOST
/surveys/{survey_id}/collectors, with the addition ofstatus
and the removal oftype
). Public App users need access to the Create/Modify Collectors scope
GET /collectors/{collector_id}/messages
Code samples
curl --request GET \
--url https://api.surveymonkey.com/v3/collectors/1234/messages \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
headers = {
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("GET", "/v3/collectors/1234/messages", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages", {
"method": "GET",
"headers": {
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
}
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
GET /collectors/{collector_id}/messages
Available Methods
HEAD
: Checks if resource is availableOPTIONS
: Returns available methods and optionsGET
: Returns a message. Public App users need access to the View Collectors scopePOST
: Creates a message. See /collectors/{id}/messages/{id}/recipients to add recipients and /collectors/{id}/messages/{id}/send to send or schedule. Public App users need access to the Create/Modify Collectors scope
Optional Query Strings for GET
Name | Type | Required | Description |
---|---|---|---|
per_page | integer | false | Number of resources to return per page |
page | integer | false | Which page of resources to return. Defaults to 1 |
Example Response for GET, PATCH, PUT /collectors/{collector_id}/messages
{
"data": [
{
"status": "sent",
"type": "invite",
"id": "86554397",
"href": "https://api.surveymonkey.com/v3/collectors/401356528/messages/86554397"
}
],
"per_page": 50,
"page": 1,
"total": 1,
"links": {
"self": "https://api.surveymonkey.com/v3/surveys/277387623/collectors/401356528/messages?page=1&per_page=50"
}
}
Response Schema
Status Code 200
Name | Type | Description |
---|---|---|
data | object | |
status | string | Message status |
type | string | Message type |
id | integer | Message id |
href | string | Resource link |
per_page | integer | |
page | integer | |
total | integer | |
links | object | |
self | string |
POST /collectors/{collector_id}/messages
Code samples
curl --request POST \
--url https://api.surveymonkey.com/v3/collectors/1234/messages \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"type":"invite","from_collector_id":"","from_message_id":"","include_recipients":false,"recipient_status":"","subject":"Share your opinion with us","body_text (for email invitations)":"We want your opinion!","body_text (for sms messages)":"We want your opinion!","body_html":"","embed_first_question":true,"is_branding_enabled":true}'
import http.client
conn = http.client.HTTPSConnection("api.surveymonkey.com")
payload = "{\"type\":\"invite\",\"from_collector_id\":\"\",\"from_message_id\":\"\",\"include_recipients\":false,\"recipient_status\":\"\",\"subject\":\"Share your opinion with us\",\"body_text (for email invitations)\":\"We want your opinion!\",\"body_text (for sms messages)\":\"We want your opinion!\",\"body_html\":\"\",\"embed_first_question\":true,\"is_branding_enabled\":true}"
headers = {
'Content-Type': "application/json",
'Accept': "application/json",
'Authorization': "Bearer {access-token}"
}
conn.request("POST", "/v3/collectors/1234/messages", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access-token}"
},
"body": "{\"type\":\"invite\",\"from_collector_id\":\"\",\"from_message_id\":\"\",\"include_recipients\":false,\"recipient_status\":\"\",\"subject\":\"Share your opinion with us\",\"body_text (for email invitations)\":\"We want your opinion!\",\"body_text (for sms messages)\":\"We want your opinion!\",\"body_html\":\"\",\"embed_first_question\":true,\"is_branding_enabled\":true}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});
POST /collectors/{collector_id}/messages
Body parameter
{
"type": "invite",
"from_collector_id": "",
"from_message_id": "",
"include_recipients": false,
"recipient_status": "",
"subject": "Share your opinion with us",
"body_text (for email invitations)": "We want your opinion!",
"body_text (for sms messages)": "We want your opinion!",
"body_html": "",
"embed_first_question": true,
"is_branding_enabled": true
}
Request Body for POST /collectors/{collectr_id}/messages
Name | Type | Required | Description |
---|---|---|---|
type | string | false | Message type: ‘sms’, ‘invite’, ‘reminder’, or ‘thank_you’. Required if from_collector_id and from_message_id are not provided. |