NAV ☰
cURL Python JavaScript

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.

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 statuswith 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:

  1. Log into the linked SurveyMonkey account
  2. Select My Account from the username dropdown in the upper right
  3. 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.

  1. Fetch the first 1,000 surveys in a SurveyMonkey account with a GET /surveys. This call returns a list resource containing survey ids.
  2. 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.
  3. 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.
  4. 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.

  1. Fetch the first 1,000 surveys in a SurveyMonkey account with a GET /surveys. This call returns a list resource containing survey ids.
  2. Using a survey id from the previous call, create a collector of type email by making a POST to /surveys/{id}/collectors.
  3. Create and format an email message with a POST to /collectors/{id}/messages.
  4. Upload recipients to receive the message with a POST to /collectors/{id}/messages/{id}/recipients/bulk.
  5. 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

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
email 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

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

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

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

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

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
email 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

Action Type Enum Values

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

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

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
email 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}

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

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

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

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

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

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

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:

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

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

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

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

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

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

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

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

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

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

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}

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}

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

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

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
                }
        ]
    }
}

Single Choice

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"
            }
        ]
    }
}

Multiple Choice

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"
                }
            }
        ]
    }
}

Image Choice

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"
            }
        ]
    }
}

Matrix Single

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
            }
        ]
    }
}

Matrix Rating

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"
            }
        ]
    }
}

Matrix Ranking

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
                    }
                ]
            }
        ]
    }
}

Matrix Menu

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"
}

Open Ended 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:"
            }
        ]
    }
}

Open Ended Multi

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!"
    }
}

Open Ended Numerical

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"
            }
        ]
    }
}

Demographic

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

Email

Email

{
    "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.

DateTime

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"
}

Presentation

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"
    }
}

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"
    }
}

Slider

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": ""
      }
    ]
  }
}

emoji (star rating)

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

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

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

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

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

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

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}

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}

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

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

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

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 email
sort_by first_name
sort_by last_name
sort_order ASC
sort_order asc
sort_order DESC
sort_order desc
search_by email
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
email 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

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 email
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
email 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

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 email
sort_by first_name
sort_by last_name
sort_order ASC
sort_order asc
sort_order DESC
sort_order desc
search_by email
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
email 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
email 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

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 email
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
email 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
email 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

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
email 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}

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
email 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
email 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}

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
email 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

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

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

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:

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

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}

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}

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

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.