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 unlimited requests 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. Only logged-in users of the SurveyMonkey team the app is registered to can see the app in the App Directory. 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.

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 No
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 Max Requests Per Day
120 500

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 500 calls/day. 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.
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 Bad Gateway Error Network was unable to connect to server.

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:

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_platinum",
  "date_created": "2021-05-27T16:29:00+00:00",
  "date_last_login": "2021-06-21T13:57:15.657000+00:00",
  "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"
  ],
  "href": "https://api.surveymonkey.com/v3/users/me"
}

Response Schema

Status Code 200

Name Type Description
account_type string SurveyMonkey plan the user has
email_verified boolean Email address for user’s account has been verified
date_created string Date user’s account was created
last_name string User’s last name
date_last_login string Date user last logged in
language string ISO 639-1 code for the language set for the user’s account
id string User Id
scopes object Contains two arrays: available, listing the scopes available to the user and granted, listing the scopes the user has approved during Oauth
available [string]
granted [string]
href string
sso_connections [string]
first_name string User’s first name
email string Email address for user’s account
username string Username

GET /users/{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/{id}/workgroups

Available Methods

Optional Query Strings for GET

Name Type Required Description
per_page string false Number of resources to return per page
page string false Which page of resources to return. Defaults to 1

Example Response for GET /users/{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
        }
      ],
      "shares": [],
      "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": 4,
  "links": {
    "self": "https://api.surveymonkey.com/v3/users/2/workgroups?page=1&per_page=50"
  }
}

Response Schema

Status Code 200

Name Type Description
per_page integer
total integer
data [object]
metadata object
is_visible boolean Whether the workgroup is publicly visible or only visible to its members and administrators
description string Description of the workgroup
created_at string Datetime when the workgroup was created
default_role object The default role for the workgroup
is_enabled boolean
metadata object
name string
description string
id string ID of the workgroup
membership object Membership information for the requested user
is_owner boolean
status string
shares_count integer Number of resources shared with the workgroup
shares [string]
updated_at string Datetime when the workgroup was last updated
members [object] The active members of the workgroup
user_id string
is_owner boolean
organization_id string
name string Name of the workgroup
members_count integer Number of members in the workgroup (includes non-active)
id string
links object
self string
page integer

GET /users/{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/{id}/shared

Available Methods

Optional Query Strings for GET

Name Type Required Description
per_page string false Number of resources to return per page
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: permissions, resource_details

Example Response for GET /users/{id}/shared

{
  "per_page": 50,
  "total": 1,
  "data": [
    {
      "workgroup_id": "71d9d408d1914c9ca85ffcda8330d675",
      "privileges": [
        "design.read_only",
        "collect.read_only",
        "analyze.read_only"
      ],
      "share_id": "0ca749c2893245c5b96a128eee4c2d42",
      "resource_type": "survey",
      "resource_id": "101101101"
    }
  ],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/users/61003234/shared?page=1&per_page=50"
  }
}

Response Schema

Status Code 200

Name Type Description
per_page integer
total integer
data [object]
workgroup_id string ID of the workgroup that was shared with
share_id string ID of the share record
owner_user_id string The ID of the user who shared the resource
resource_type string-ENUM 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 array An array of scoped privileges granted to the user by this share record
links object
self string
page integer

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 string false Number of resources to return per page
page string false Which page of resources to return. Defaults to 1

Example Response for GET /groups

{
  "data": [
    {
      "id": "1",
      "name": "group name",
      "href": "https://api.surveymonkey.com/v3/groups/1"
    }
  ],
  "per_page": 50,
  "page": 1,
  "total": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/groups?page=1&per_page=50"
  }
}

Response Schema

Status Code 200

Name Type Description
per_page integer
total integer
data [object]
name string Group name
id string Group id
href string Resource API URL
links object
self string
page integer

GET /groups/{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/{id}

Available Methods

Example Response for GET /groups/{id}

{
  "id": "1",
  "name": "group name",
  "member_count": 5,
  "max_invites": 0,
  "date_created": "2018-08-08T21:58:32+00:00",
  "href": "https://api.surveymonkey.com/v3/groups/1"
}

Response Schema

Status Code 200

Name Type Description
max_invites integer Maximum number of members that can be in the group
date_created string Date and time when group was created
name string Group name
id string Group id
href string
member_count integer Number of members in the group

GET /groups/{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/{id}/members

Available Methods

Optional Query Strings for GET

Name Type Required Description
per_page string false Number of resources to return per page
page string false Which page of resources to return. Defaults to 1

Example Response for GET /groups/{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

GET /groups/{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/{id}/activities

Available Methods

Optional Query Strings for GET

Name Type Required Description
limit integer false Max number of rows returned. Defaults to 50
offset integer false Offset for the results, i.e., the number of rows skipped
start_date Date false The start date for the activity related data query
end_date Date false The end date for the activity related data query

Example Response for GET /groups/{id}/activities

{
  "sl_translate": "activity_msg,member_type",
  "total": 1,
  "offset": 0,
  "limit": 1,
  "results": [
    {
      "date_created": "2021-07-16 16:07:14",
      "user_id": 1,
      "user_name": "username",
      "email": "email@surveymonkey.com",
      "member_type": "<span>(Primary Admin)</span>",
      "group_id": 1,
      "activity_type": "survey_info_delete",
      "activity_msg": "<span>Deleted survey <span class=\"notranslate\"><b>put req name change</b></span></span>",
      "ip_address": "11.11.11.111",
      "city": "Theed",
      "country": "Naboo",
      "division_name": null
    }
  ]
}

Response Schema

Status Code 200

Name Type Description
sl_translate string
total integer
offset integer
limit integer
results [object]
member_type string Member type for activity
country string
user_id integer User ID logged for activity
group_id integer Group ID logged for activity
city string
date_created Date Activity creation date
user_name string Username logged for activity
activity_type string Type of activity
division_name any
activity_msg string Message for activity
ip_address string IP logged for activity
email string Email logged for activity

GET /groups/{id}/activities/{activity_type}

Code samples

curl --request GET \
  --url 'https://api.surveymonkey.com/v3/groups/1234/activities/grant_info_deleted?interval=1' \
  --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/grant_info_deleted?interval=1", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/groups/1234/activities/grant_info_deleted?interval=1", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /groups/{id}/activities/{activity_type}

Available Methods

Activity Type Enum Values

Optional Query Strings for GET

Name Type Required Description
interval string-ENUM yes Interval of the series data to return (One of “daily”, “weekly”, “monthly”, “yearly”)
start_date Date false The start date for the activity related data query
end_date Date false The end date for the activity related data query

Example Response for GET /groups/{id}/activities/{activity_type}

{
  "series": [
    86,
    193
  ],
  "times": [
    "2020",
    "2019"
  ],
  "interval": "yearly"
}

Response Schema

Status Code 200

Name Type Description
series array Series data of the count of the specified activity type per interval period
times array Labels of times for series data set
interval string The interval for the returned series

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
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":null,"from_survey_id":null,"nickname":null,"language":null,"buttons_text":null,"custom_variables":null,"footer":null,"folder_id":null,"quiz_options":null,"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\":null,\"from_survey_id\":null,\"nickname\":null,\"language\":null,\"buttons_text\":null,\"custom_variables\":null,\"footer\":null,\"folder_id\":null,\"quiz_options\":null,\"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\":null,\"from_survey_id\":null,\"nickname\":null,\"language\":null,\"buttons_text\":null,\"custom_variables\":null,\"footer\":null,\"folder_id\":null,\"quiz_options\":null,\"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": null,
  "from_survey_id": null,
  "nickname": null,
  "language": null,
  "buttons_text": null,
  "custom_variables": null,
  "footer": null,
  "folder_id": null,
  "quiz_options": null,
  "pages": [
    {
      "questions": [
        "See formatting question types for more details"
      ]
    }
  ]
}

Request Body for POST /surveys

Name Type Required Call Description
title string no Copy Blank Bulk Survey title (default=“New Survey”)
from_template_id string no Copy Survey template to Copy from. See /survey_templates (required if from_survey_id not provided)
from_survey_id string no Copy Survey id to Copy from (required if from_template_id not provided)
nickname string no Blank Bulk (default=‘’) Survey nickname
language string no Blank Bulk (default=‘en’) Survey language
buttons_text object no Blank Bulk Survey Buttons text container
next_button string no Blank Bulk Button text
prev_button string no Blank Bulk Button text
exit_button string no Blank Bulk Button text. If set to an empty string, button will be ommitted from survey
done_button string no Blank Bulk Button text
custom_variables object no Blank Dictionary of survey variables
footer boolean no Blank If false, SurveyMonkey’s footer is not displayed. (default=true)
folder_id string no Blank If specified, adds the survey to the folder with that id.
quiz_options object no Blank An object describing the quiz settings, if this survey is a quiz
is_quiz_mode boolean yes Blank On/off toggle for setting this survey as a quiz
default_question_feedback object no Blank An object containing the default feedback for newly created questions in this survey
correct_text string yes Blank Text to show when answer is correct
incorrect_text string yes Blank Text to show when answer is incorrect
partial_text string yes Blank Text to show when answer is partially correct
show_results_type string yes Blank What to reveal to the user when they complete the quiz: disabled, results_only or results_and_answers
feedback object yes Blank Text to show the user when they complete the quiz
ranges_type string yes Blank Configure whether the following parameters use percentage or points. Note that these ranges are inclusive and may not overlap
ranges [object] yes Blank The ranges at which to show users certain feedback
min integer yes Blank Minimum score for this feedback
max integer yes Blank Maximum score for this feedback
message string yes Blank Feedback message
pages [object] yes Bulk Pages to be created
questions array yes 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

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

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

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":null,"from_survey_id":null,"nickname":null,"language":null,"buttons_text":null,"custom_variables":null,"footer":null,"folder_id":null,"quiz_options":null,"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\":null,\"from_survey_id\":null,\"nickname\":null,\"language\":null,\"buttons_text\":null,\"custom_variables\":null,\"footer\":null,\"folder_id\":null,\"quiz_options\":null,\"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\":null,\"from_survey_id\":null,\"nickname\":null,\"language\":null,\"buttons_text\":null,\"custom_variables\":null,\"footer\":null,\"folder_id\":null,\"quiz_options\":null,\"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":null,"language":null,"buttons_text":null,"custom_variables":null,"footer":null,"folder_id":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"title\":\"New Survey\",\"nickname\":null,\"language\":null,\"buttons_text\":null,\"custom_variables\":null,\"footer\":null,\"folder_id\":null}"

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\":null,\"language\":null,\"buttons_text\":null,\"custom_variables\":null,\"footer\":null,\"folder_id\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

PATCH /surveys/{id}

Body parameter

{
  "title": "New Survey",
  "nickname": null,
  "language": null,
  "buttons_text": null,
  "custom_variables": null,
  "footer": null,
  "folder_id": null
}

Request Body for PATCH /surveys/{id}

Name Type Required Description
title string no Survey title (PUT default=“New Survey”)
nickname string no Survey nickname (PUT default=“”)
language string no Survey language (PUT default=“en”)
buttons_text object no Survey Buttons text container
next_button string no Button text
prev_button string no Button text
exit_button string no Button text. If set to an empty string, button will be ommitted from survey
done_button string no Button text
custom_variables object no Dictionary of survey variables
footer boolean no If false, SurveyMonkey’s footer is not displayed (default=true)
folder_id string no 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

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-Enum 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: 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_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": "application/json",
    "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-Enum false ISO 639-1 code for language to filter by (default=en)
category string-Enum 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

Status Code 200

Name Type Description
per_page integer
page integer
total integer
data [object]
name string Resource name
id string Resource id
title string Survey title
available boolean Template is available to user
num_questions integer Number of questions in the template
preview_link string Template preview URL
description string Template description
category string Template category
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/{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/{id}/pages

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/{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
per_page integer Number of resources per page
total integer
data [object]
position integer Position of the page in the survey
id string ID of the page
href string Link to the page
title string Name of the page
description string Description of the page
links object
self string
page integer

POST /surveys/{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":null,"position":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"title\":\"Page title\",\"description\":null,\"position\":null}"

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\":null,\"position\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /surveys/{id}/pages

Body parameter

{
  "title": "Page title",
  "description": null,
  "position": null
}

Request Body for POST /surveys/{id}/pages

Name Type Required Description
title string no Page title
description string no Page description
position integer no 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
position integer Position of the page in the survey
id string ID of the page
href string Link to the page
title string Name of the page
description string Description of the page
question_count integer Number of questions on 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":null,"position":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"title\":\"Page title\",\"description\":null,\"position\":null}"

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\":null,\"position\":null}"
})
.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":null,"position":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"title\":\"Page title\",\"description\":null,\"position\":null}"

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\":null,\"position\":null}"
})
.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":null,"image":null,"random_assignment":null}],"position":null,"family":"single_choice","subtype":"vertical","sorting":null,"required":false,"validation":null,"forced_ranking":null,"quiz_options":null,"answers":{"choices":[{"text":"Capuchin"},{"text":"Mandrill"}]},"display_options":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"headings\":[{\"heading\":\"Which monkey would you rather have as a pet?\",\"description\":null,\"image\":null,\"random_assignment\":null}],\"position\":null,\"family\":\"single_choice\",\"subtype\":\"vertical\",\"sorting\":null,\"required\":false,\"validation\":null,\"forced_ranking\":null,\"quiz_options\":null,\"answers\":{\"choices\":[{\"text\":\"Capuchin\"},{\"text\":\"Mandrill\"}]},\"display_options\":null}"

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\":null,\"image\":null,\"random_assignment\":null}],\"position\":null,\"family\":\"single_choice\",\"subtype\":\"vertical\",\"sorting\":null,\"required\":false,\"validation\":null,\"forced_ranking\":null,\"quiz_options\":null,\"answers\":{\"choices\":[{\"text\":\"Capuchin\"},{\"text\":\"Mandrill\"}]},\"display_options\":null}"
})
.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": null,
      "image": null,
      "random_assignment": null
    }
  ],
  "position": null,
  "family": "single_choice",
  "subtype": "vertical",
  "sorting": null,
  "required": false,
  "validation": null,
  "forced_ranking": null,
  "quiz_options": null,
  "answers": {
    "choices": [
      {
        "text": "Capuchin"
      },
      {
        "text": "Mandrill"
      }
    ]
  },
  "display_options": null
}

Request Body for POST /surveys/{survey_id}/pages/{page_id}/questions

Name Type Required Description
headings [object] yes List of question headings objects
heading string yes The title of the question, or empty string if random_assignment is defined
description string no If random_assignment is defined, and family is presentation_image this is the title
image object no Image data when question family is presentation_image
url string no URL of image when question family is presentation_image
random_assignment object no Random assignment data
percent integer yes Percent chance of this random assignment showing up (must sum to 100)
position integer no Position of the random_assignment in survey creation page
variable_name string no Internal use name for question tracking, can be ""
position integer no Position of question on page (default=last)
family string yes Question family determines the type of question, see formatting question types
subtype string yes Question family’s subtype further specifies the type of question, see formatting question types
sorting object no Sorting details of answers
type string yes Sort answer choices by: default, textasc, textdesc, resp_count_asc, resp_count_desc, random, flip
ignore_last boolean no If true, does not sort the last answer option (useful for “none of the above”, etc)
required object no Whether an answer is required for this question
text string yes Text to display if a required question is not answered
type string yes 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 yes 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 no Whether the answer must pass certain validation parameters
type string yes Type of validation to use: any, integer, decimal, date_us, date_intl, regex, email, or text_length
text string yes Text to display if validation fails
min string yes Minimum value an answer can be to pass validation. Date string, integer, or null depending on validation.type
max string yes Maximum value an answer can be to pass validation. Date string, integer, or null depending on validation.type
sum integer no Only accepted is family=open_ended and subtype=numerical, the exact integer textboxes must sum to in order to pass validation
sum_text string no Only accepted is family=open_ended and subtype=numerical, the message to display if textboxes do not sum to validation.sum
forced_ranking boolean no 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 yes Whether this question is quiz-enabled
feedback object yes Object containing the definitions for feedback on this quiz question
feedback.correct_text string yes Text to show when answer is correct
feedback.incorrect_text string yes Text to show when the ansewr is incorrect
feedback.partial_text string yes Text to show when the answer is partially correct
answers object yes Answers object, refer to Formatting Question Types. Required for all question types except open_ended_single
display_options object yes 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, regex, 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’ 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 Array
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 Array
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 Array
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 Array
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 Array
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

Demographic

{
    "headings": [
        {
            "heading": "What's your address?"
        }
    ],
    "position": 1,
    "visible": true,
    "family": "demographic",
    "subtype": "international",
    "answers": {
        "rows": [
            {
                "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
rows List of available demographic data Array
rows[_].visible (required) Visibility of demographic data type Boolean
rows[_].required (required) Whether demographic data type is required Boolean
rows[_].type (required) Type of demographic data String
rows[_].text (optional) Optional label of demographic data, will default to type String

DateTime

DateTime

{
    "headings": [
        {
            "heading": "When did you last eat ice cream?"
        }
    ],
    "position": 1,
    "visible": true,
    "family": "datetime",
    "subtype": "both",
    "answers": {
        "rows": [
            {
                "text": "At:",
                "position": 1
            }
        ]
    }
}

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
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]
locales [string] A list of locales that the question supports (empty for Custom QB)
text string The text in the question
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
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

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 /survey_folders

{
  "data": [
    {
      "title": "Slack 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":"Folder Title"}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"title\":\"Folder Title\"}"

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\":\"Folder Title\"}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /survey_folders

Body parameter

{
  "title": "Folder Title"
}

Request Body for POST /survey_folders

Name Type Required Description
title string no Title of the folder

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 no If True, translation is available for respondents to select
translations array yes 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 no If True, translation is available for respondents to select
translations array yes 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

Body parameter

{
  "name": "My Contact list"
}

Request Body for POST /contact_lists

Name Type Required Description
name string no Contact list name (default=“New List”)

Example Response for POST /contact_lists

{
  "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/{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/{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/{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/{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/{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/{id}

Example Response for 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

POST /contact_lists/{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/{id}/copy

Available Methods

Example Response for POST /contact_lists/{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/{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/{id}/merge

Available Methods

Body parameter

{
  "list_id": "1234"
}

Request Body for POST /contact_lists/{id}/merge

Name Type Required Description
list_id string yes List id to be merged over

Example Response for POST /contact_lists/{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/{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/{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, 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 e.g. [‘ASC’, 'DESC’]
search_by string false Field used to search returned contact list: : email, first_name, last_name, 1, …, 6
search string false Query used to search

Response Example for GET and POST /contact_lists/{id}/contacts

{
  "id": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "phone_number": null,
  "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 Phone number string Contact phone number
custom_fields object Contact custom fields
href string Resource API URL

POST /contact_lists/{id}/contacts

Code samples

curl --request POST \
  --url https://api.surveymonkey.com/v3/contact_lists//contacts \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"first_name":"John","last_name":"Doe","email":"test@surveymonkey.com","phone_number":null,"custom_fields":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("POST", "/v3/contact_lists//contacts", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/contact_lists//contacts", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /contact_lists/{id}/contacts

Body parameter

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "phone_number": null,
  "custom_fields": null
}

Request Body for POST /contact_lists/{id}/contacts

Name Type Required Description
first_name string yes Contact first name
last_name string yes Contact last name
email string yes Contact email address. Required if no phone_number
phone_number Phone number string yes Contact phone_number. Required if no email
custom_fields object no Contact custom fields

GET /contact_lists/{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/{id}/contacts/bulk

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, 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 e.g. [‘ASC’, 'DESC’]
search_by string false Field used to search returned contact list: : email, first_name, last_name, 1, …, 6
search string false Query used to search

Example Response for GET and POST /contacts_lists/{id}/contacts/bulk

{
  "data": [
    {
      "id": "1",
      "first_name": "",
      "last_name": "",
      "email": "test@papi.com",
      "phone_number": null,
      "href": "https://api.surveymonkey.com/v3/contacts/1",
      "custom_fields": {},
      "status": "active"
    }
  ],
  "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 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/{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 '{"data":[{"first_name":"John","last_name":"Doe","email":"test@surveymonkey.com","phone_number":null,"custom_fields":null}]}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"data\":[{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}]}"

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": "{\"data\":[{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}]}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /contact_lists/{id}/contacts/bulk

Body parameter

{
  "data": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "test@surveymonkey.com",
      "phone_number": null,
      "custom_fields": null
    }
  ]
}

Request Body for POST /contact_lists/{id}/contacts/bulk

Name Type Required Description
data [object] yes Contacts to add
first_name string yes Contact first name
last_name string yes Contact last name
email string yes Contact email address. Required if no phone_number
phone_number Phone number string yes Contact phone_number. Required if no email
custom_fields object no Contact custom fields

Example Response for POST /contact_lists/{id}/contacts/bulk

{
  "succeeded": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "id": "1234",
      "email": "test@surveymonkey.com",
      "phone_number": null,
      "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 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 integer false Page number. Defaults to 1
per_page integer false Number of contacts 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: ASC or DESC
search_by string false Field used to search returned contact list: email, first_name, last_name, 1, …, 6
search string false Query used to search

Example Response for GET /contacts

{
  "data": [
    {
      "id": "1",
      "first_name": "",
      "last_name": "",
      "email": "test@papi.com",
      "phone_number": null,
      "href": "https://api.surveymonkey.com/v3/contacts/1",
      "custom_fields": {},
      "status": "active"
    }
  ],
  "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 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":"John","last_name":"Doe","email":"test@surveymonkey.com","phone_number":null,"custom_fields":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"

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\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /contacts

Body parameter

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "phone_number": null,
  "custom_fields": null
}

Request Body for POST /contacts

Name Type Required Description
first_name string yes Contact first name
last_name string yes Contact last name
email string yes Contact email address. Required if no phone_number
phone_number Phone number string yes Contact phone number. Required if no email
custom_fields object no Contact custom field

Example Response for POST /contacts

{
  "data": [
    {
      "id": "1",
      "first_name": "",
      "last_name": "",
      "email": "test@papi.com",
      "phone_number": null,
      "href": "https://api.surveymonkey.com/v3/contacts/1",
      "custom_fields": {},
      "status": "active"
    }
  ],
  "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 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

Example Response for GET /contacts/bulk

{
  "data": [
    {
      "id": "1",
      "first_name": "",
      "last_name": "",
      "email": "test@papi.com",
      "phone_number": null,
      "href": "https://api.surveymonkey.com/v3/contacts/1",
      "custom_fields": {},
      "status": "active"
    }
  ],
  "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 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 '{"data":[{"first_name":"John","last_name":"Doe","email":"test@surveymonkey.com","phone_number":null,"custom_fields":null,"update_existing":null}]}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"data\":[{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null,\"update_existing\":null}]}"

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": "{\"data\":[{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null,\"update_existing\":null}]}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /contacts/bulk

Body parameter

{
  "data": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "test@surveymonkey.com",
      "phone_number": null,
      "custom_fields": null,
      "update_existing": null
    }
  ]
}

Request Body for POST /contacts/bulk

Name Type Required Description
data [object] Yes Contacts to add
first_name string yes Contact first name
last_name string yes Contact last name
email string yes Contact email. Required if no phone_number
phone_number Phone number string yes Contact phone number. Required if no email
custom_fields object no Custom contact fields
update_existing boolean no Whether or not to update existing contacts

Example Response for POST /contacts/bulk

{
  "data": [
    {
      "id": "1",
      "first_name": "",
      "last_name": "",
      "email": "test@papi.com",
      "phone_number": null,
      "href": "https://api.surveymonkey.com/v3/contacts/1",
      "custom_fields": {},
      "status": "active"
    }
  ],
  "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 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/{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/{id}

Available Methods

Example Response for GET, POST, and PATCH /contacts/{id}

{
  "first_name": "",
  "last_name": "",
  "email": "name@email.com",
  "phone_number": null,
  "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 Phone number string Contact phone number
href string Resource API URL
custom_fields object Custom fields
status boolean

PATCH /contacts/{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":"John","last_name":"Doe","email":"test@surveymonkey.com","phone_number":null,"custom_fields":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"

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\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

PATCH /contacts/{id}

Example response for PATCH /contacts/{id}

{
  "first_name": "",
  "last_name": "",
  "email": "name@email.com",
  "phone_number": null,
  "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 Phone number string Contact phone number
href string Resource API URL
custom_fields object Custom fields
status boolean

PUT /contacts/{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":"John","last_name":"Doe","email":"test@surveymonkey.com","phone_number":null,"custom_fields":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"

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\":\"John\",\"last_name\":\"Doe\",\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"custom_fields\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

PUT /contacts/{id}

Example response for PUT /contacts/{id}

{
  "first_name": "",
  "last_name": "",
  "email": "name@email.com",
  "phone_number": null,
  "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 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. Defaults to 1
per_page integer false Number of contacts to return per page

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/{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/{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/{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/{id}

Body parameter

{
  "label": "Custom 1"
}

Request Body for PATCH /contact_fields/{id}

Name Type Required Description
label string yes 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. Some collector options, for example, is_branding_enabled=False require a SurveyMonkey paid plan.

GET /surveys/{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/{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/{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/{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 '{"from_collector_id":"string","type":"string","name":"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":null,"is_branding_enabled":true,"headline":"string","message":"string","sample_rate":"string","primary_button":{"bg_color":null,"text_color":null,"text":"string"},"secondary_button":{"bg_color":null,"text_color":null,"text":"string"}}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"from_collector_id\":\"string\",\"type\":\"string\",\"name\":\"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\":null,\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":\"string\",\"primary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"},\"secondary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"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": "{\"from_collector_id\":\"string\",\"type\":\"string\",\"name\":\"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\":null,\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":\"string\",\"primary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"},\"secondary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"}}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /surveys/{id}/collectors

Call Types:

Response for POST /surveys/{id}/collectors

{
  "status": "open",
  "id": "1234",
  "type": "weblink",
  "name": "My Collector",
  "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",
  "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_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

GET /collectors/{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/{id}

Available Methods

Example Response for GET, PATCH, PUT /collectors/{id}

{
  "status": "open",
  "id": "1234",
  "survey_id": "123456789",
  "type": "weblink",
  "name": "My Collector",
  "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",
  "date_created": "2015-10-06T12:56:55+00:00",
  "sender_email": null,
  "password_enabled": false,
  "response_limit": 100,
  "redirect_type": "url",
  "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_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

PATCH /collectors/{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 '{"from_collector_id":"string","status":"string","name":"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":null,"is_branding_enabled":true,"headline":"string","message":"string","sample_rate":"string","primary_button":{"bg_color":null,"text_color":null,"text":"string"},"secondary_button":{"bg_color":null,"text_color":null,"text":"string"}}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"from_collector_id\":\"string\",\"status\":\"string\",\"name\":\"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\":null,\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":\"string\",\"primary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"},\"secondary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"}}"

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": "{\"from_collector_id\":\"string\",\"status\":\"string\",\"name\":\"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\":null,\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":\"string\",\"primary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"},\"secondary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"}}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

PATCH /collectors/{id}

PUT /collectors/{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 '{"from_collector_id":"string","status":"string","name":"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":null,"is_branding_enabled":true,"headline":"string","message":"string","sample_rate":"string","primary_button":{"bg_color":null,"text_color":null,"text":"string"},"secondary_button":{"bg_color":null,"text_color":null,"text":"string"}}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"from_collector_id\":\"string\",\"status\":\"string\",\"name\":\"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\":null,\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":\"string\",\"primary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"},\"secondary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"}}"

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": "{\"from_collector_id\":\"string\",\"status\":\"string\",\"name\":\"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\":null,\"is_branding_enabled\":true,\"headline\":\"string\",\"message\":\"string\",\"sample_rate\":\"string\",\"primary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"},\"secondary_button\":{\"bg_color\":null,\"text_color\":null,\"text\":\"string\"}}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

PUT /collectors/{id}

GET /collectors/{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/{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/{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/{id}/messages

Code samples

curl --request POST \
  --url https://api.surveymonkey.com/v3/collectors//messages \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"type":"invite","recipient_status":null,"subject":null,"body_text (for email invitations)":null,"body_text (for sms messages)":null,"body_html":null,"embed_first_question":null,"is_branding_enabled":null,"from_collector_id":null,"from_message_id":null,"include_recipients":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"type\":\"invite\",\"recipient_status\":null,\"subject\":null,\"body_text (for email invitations)\":null,\"body_text (for sms messages)\":null,\"body_html\":null,\"embed_first_question\":null,\"is_branding_enabled\":null,\"from_collector_id\":null,\"from_message_id\":null,\"include_recipients\":null}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("POST", "/v3/collectors//messages", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors//messages", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"type\":\"invite\",\"recipient_status\":null,\"subject\":null,\"body_text (for email invitations)\":null,\"body_text (for sms messages)\":null,\"body_html\":null,\"embed_first_question\":null,\"is_branding_enabled\":null,\"from_collector_id\":null,\"from_message_id\":null,\"include_recipients\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /collectors/{id}/messages

Body parameter

{
  "type": "invite",
  "recipient_status": null,
  "subject": null,
  "body_text (for email invitations)": null,
  "body_text (for sms messages)": null,
  "body_html": null,
  "embed_first_question": null,
  "is_branding_enabled": null,
  "from_collector_id": null,
  "from_message_id": null,
  "include_recipients": null
}

Request Body for POST /collectors/{id}/messages

Name Type Required Call Description
type string yes Blank Message type: ‘sms’, ‘invite’, ‘reminder’, or ‘thank_you’
recipient_status string No. If type is ‘reminder’, acceptable values are: ‘has_not_responded’ or ‘partially_responded’, with the default being ‘has_not_responded’. If type is ‘thank_you’, acceptable values are :‘completed’, ‘responded’, or ‘partially_responded’, with the default being ‘completed’ Blank Set of recipients to send to
subject string no Blank Subject of the email message to be sent to recipients (default=‘We want your opinion’)
body_text (for email invitations) string no Blank The plain text body of the email message to be sent to recipients. Message must include [SurveyLink], [OptOutLink], [PrivacyLink] and [FooterLink] and the opt-out and privacy links must be clearly labeled.
body_text (for sms messages) string no Blank Make your custom message 30 characters or less (including spaces) to keep your entire text invitation together as one text. Every text you send through SurveyMonkey will include the following default text, which counts toward the overall limit: Reply HELP for info. STOP to opt out. Msg&DataRatesMayApply
body_html string no Blank The html body of the email message to be sent to recipients. This overrides body_text. Message must include [SurveyLink], [OptOutLink], [PrivacyLink] and [FooterLink] and the opt-out and privacy links must be clearly labeled.
embed_first_question boolean no Blank If collector ‘type’ is ‘invite’ then setting to ‘true’ will embed first question into email body
is_branding_enabled boolean no Blank Whether the email has SurveyMonkey branding
from_collector_id string yes Copy Collector ID to copy message from
from_message_id string yes Copy Message ID to copy from
include_recipients boolean no Copy Include recipients attached to existing message

Example response for POST /collectors/{id}/messages

{
  "status": "not_sent",
  "body": "\n<html>\n\n<body style=\"margin:0; padding: 0;\">\n    <div align=\"center\">\n        <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" width=\"100%\" style=\"font-family: Arial,Helvetica,sans-serif; max-width: 700px;\">\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td>\n                <td align=\"center\" style=\"font-size: 29px; color:#FFFFFF; font-weight: normal; letter-spacing: 1px; line-height: 1;                           text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.2); font-family: Arial,Helvetica,sans-serif;\"> Survey Title </td>\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr>\n                <td height=\"10\" colspan=\"5\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\" align=\"left\" valign=\"top\" style=\"color:#666666; font-size: 13px;\"> \n                    <p>We're conducting a survey and your input would be appreciated. Click the button below to start the survey. Thank you for your participation!</p>  </td>\n                <td> </td> </tr> \n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\">\n                    <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" style=\"background:#A7BC38; border-radius: 4px; border: 1px solid #BBBBBB; color:#FFFFFF; font-size:14px; letter-spacing: 1px; text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.8); padding: 10px 18px;\">\n                        <tr>\n                            <td align=\"center\" valign=\"center\"> <a href=\"[SurveyLink]\" target=\"_blank\" style=\"color:#FFFFFF; text-decoration:none;\">Begin Survey</a> </td> </tr> </table> </td>\n                <td> </td> </tr>\n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr> \n            <tr valign=\"top\" style=\"color: #666666;font-size: 10px;\">\n                <td> </td>\n                <td valign=\"top\" align=\"center\" colspan=\"3\">\n                    <p>Please do not forward this email as its survey link is unique to you.\n                        <br><a href=\"[PrivacyLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Privacy</a> | <a href=\"[OptOutLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Unsubscribe</a> from this list</p> </td>\n                <td> </td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr>\n            <tr style=\"color: #999999;font-size: 10px;\">\n                <td align=\"center\" colspan=\"5\">[FooterLink]</td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr> </table></div></body>\n\n</html>\n",
  "recipient_status": null,
  "is_branding_enabled": true,
  "href": "https://api.surveymonkey.com/v3/collectors/1234/messages/1234",
  "is_scheduled": false,
  "scheduled_date": null,
  "date_created": "2016-08-17T23:47:37+00:00",
  "type": "invite",
  "id": "31454399",
  "subject": "We want your opinion"
}

Response Schema

Status Code 200

Name Type Description
status string Status of the message
body string Email body
recipient_status string Set of recipients to send to
subject string Subject of the email message to be sent to recipients
is_branding_enabled boolean Whether the email has SurveyMonkey branding
is_scheduled boolean Whether the email is scheduled
schedule_date date Date email is scheduled to send
date_created date Date email was created
type string Type of message
id integer Id of the message

GET /collectors/{collector_id}/messages/{message_id}

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/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/messages/1234", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/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}/messages/{message_id}

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/{id}/messages{id}

{
  "status": "not_sent",
  "body": "\n<html>\n\n<body style=\"margin:0; padding: 0;\">\n    <div align=\"center\">\n        <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" width=\"100%\" style=\"font-family: Arial,Helvetica,sans-serif; max-width: 700px;\">\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td>\n                <td align=\"center\" style=\"font-size: 29px; color:#FFFFFF; font-weight: normal; letter-spacing: 1px; line-height: 1;                           text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.2); font-family: Arial,Helvetica,sans-serif;\"> Survey Title </td>\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr>\n                <td height=\"10\" colspan=\"5\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\" align=\"left\" valign=\"top\" style=\"color:#666666; font-size: 13px;\"> \n                    <p>We're conducting a survey and your input would be appreciated. Click the button below to start the survey. Thank you for your participation!</p>  </td>\n                <td> </td> </tr> \n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\">\n                    <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" style=\"background:#A7BC38; border-radius: 4px; border: 1px solid #BBBBBB; color:#FFFFFF; font-size:14px; letter-spacing: 1px; text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.8); padding: 10px 18px;\">\n                        <tr>\n                            <td align=\"center\" valign=\"center\"> <a href=\"[SurveyLink]\" target=\"_blank\" style=\"color:#FFFFFF; text-decoration:none;\">Begin Survey</a> </td> </tr> </table> </td>\n                <td> </td> </tr>\n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr> \n            <tr valign=\"top\" style=\"color: #666666;font-size: 10px;\">\n                <td> </td>\n                <td valign=\"top\" align=\"center\" colspan=\"3\">\n                    <p>Please do not forward this email as its survey link is unique to you.\n                        <br><a href=\"[PrivacyLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Privacy</a> | <a href=\"[OptOutLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Unsubscribe</a> from this list</p> </td>\n                <td> </td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr>\n            <tr style=\"color: #999999;font-size: 10px;\">\n                <td align=\"center\" colspan=\"5\">[FooterLink]</td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr> </table></div></body>\n\n</html>\n",
  "recipient_status": null,
  "is_branding_enabled": true,
  "href": "https://api.surveymonkey.com/v3/collectors/1234/messages/1234",
  "is_scheduled": false,
  "scheduled_date": null,
  "date_created": "2016-08-17T23:47:37+00:00",
  "type": "invite",
  "id": "31454399",
  "subject": "We want your opinion"
}

Response Schema

Status Code 200

Name Type Description
status string Status of the message
body string Email body
recipient_status string Set of recipients to send to
subject string Subject of the email message to be sent to recipients
is_branding_enabled boolean Whether the email has SurveyMonkey branding
is_scheduled boolean Whether the email is scheduled
schedule_date date Date email is scheduled to send
date_created date Date email was created
type string Type of message
id integer Id of the message

PATCH /collectors/{collector_id}/messages/{message_id}

Code samples

curl --request PATCH \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/1234 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"type":"invite","recipient_status":null,"subject":null,"body_text (for email invitations)":null,"body_text (for sms messages)":null,"body_html":null,"embed_first_question":null,"is_branding_enabled":null,"from_collector_id":null,"from_message_id":null,"include_recipients":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"type\":\"invite\",\"recipient_status\":null,\"subject\":null,\"body_text (for email invitations)\":null,\"body_text (for sms messages)\":null,\"body_html\":null,\"embed_first_question\":null,\"is_branding_enabled\":null,\"from_collector_id\":null,\"from_message_id\":null,\"include_recipients\":null}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("PATCH", "/v3/collectors/1234/messages/1234", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/1234", {
  "method": "PATCH",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"type\":\"invite\",\"recipient_status\":null,\"subject\":null,\"body_text (for email invitations)\":null,\"body_text (for sms messages)\":null,\"body_html\":null,\"embed_first_question\":null,\"is_branding_enabled\":null,\"from_collector_id\":null,\"from_message_id\":null,\"include_recipients\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

PATCH /collectors/{collector_id}/messages/{message_id}

Example response for PATCH /collectors/{collector_id}/messages/{message_id}

{
  "status": "not_sent",
  "body": "\n<html>\n\n<body style=\"margin:0; padding: 0;\">\n    <div align=\"center\">\n        <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" width=\"100%\" style=\"font-family: Arial,Helvetica,sans-serif; max-width: 700px;\">\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td>\n                <td align=\"center\" style=\"font-size: 29px; color:#FFFFFF; font-weight: normal; letter-spacing: 1px; line-height: 1;                           text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.2); font-family: Arial,Helvetica,sans-serif;\"> Survey Title </td>\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr>\n                <td height=\"10\" colspan=\"5\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\" align=\"left\" valign=\"top\" style=\"color:#666666; font-size: 13px;\"> \n                    <p>We're conducting a survey and your input would be appreciated. Click the button below to start the survey. Thank you for your participation!</p>  </td>\n                <td> </td> </tr> \n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\">\n                    <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" style=\"background:#A7BC38; border-radius: 4px; border: 1px solid #BBBBBB; color:#FFFFFF; font-size:14px; letter-spacing: 1px; text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.8); padding: 10px 18px;\">\n                        <tr>\n                            <td align=\"center\" valign=\"center\"> <a href=\"[SurveyLink]\" target=\"_blank\" style=\"color:#FFFFFF; text-decoration:none;\">Begin Survey</a> </td> </tr> </table> </td>\n                <td> </td> </tr>\n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr> \n            <tr valign=\"top\" style=\"color: #666666;font-size: 10px;\">\n                <td> </td>\n                <td valign=\"top\" align=\"center\" colspan=\"3\">\n                    <p>Please do not forward this email as its survey link is unique to you.\n                        <br><a href=\"[PrivacyLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Privacy</a> | <a href=\"[OptOutLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Unsubscribe</a> from this list</p> </td>\n                <td> </td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr>\n            <tr style=\"color: #999999;font-size: 10px;\">\n                <td align=\"center\" colspan=\"5\">[FooterLink]</td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr> </table></div></body>\n\n</html>\n",
  "recipient_status": null,
  "is_branding_enabled": true,
  "href": "https://api.surveymonkey.com/v3/collectors/1234/messages/1234",
  "is_scheduled": false,
  "scheduled_date": null,
  "date_created": "2016-08-17T23:47:37+00:00",
  "type": "invite",
  "id": "31454399",
  "subject": "We want your opinion"
}

Response Schema

Status Code 200

Name Type Description
status string Status of the message
body string Email body
recipient_status string Set of recipients to send to
subject string Subject of the email message to be sent to recipients
is_branding_enabled boolean Whether the email has SurveyMonkey branding
is_scheduled boolean Whether the email is scheduled
schedule_date date Date email is scheduled to send
date_created date Date email was created
type string Type of message
id integer Id of the message

PUT /collectors/{collector_id}/messages/{message_id}

Code samples

curl --request PUT \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/1234 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"type":"invite","recipient_status":null,"subject":null,"body_text (for email invitations)":null,"body_text (for sms messages)":null,"body_html":null,"embed_first_question":null,"is_branding_enabled":null,"from_collector_id":null,"from_message_id":null,"include_recipients":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"type\":\"invite\",\"recipient_status\":null,\"subject\":null,\"body_text (for email invitations)\":null,\"body_text (for sms messages)\":null,\"body_html\":null,\"embed_first_question\":null,\"is_branding_enabled\":null,\"from_collector_id\":null,\"from_message_id\":null,\"include_recipients\":null}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("PUT", "/v3/collectors/1234/messages/1234", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/1234", {
  "method": "PUT",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"type\":\"invite\",\"recipient_status\":null,\"subject\":null,\"body_text (for email invitations)\":null,\"body_text (for sms messages)\":null,\"body_html\":null,\"embed_first_question\":null,\"is_branding_enabled\":null,\"from_collector_id\":null,\"from_message_id\":null,\"include_recipients\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

PUT /collectors/{collector_id}/messages/{message_id}

Example response for PUT /collectors/{id}/messages/{id}

{
  "status": "not_sent",
  "body": "\n<html>\n\n<body style=\"margin:0; padding: 0;\">\n    <div align=\"center\">\n        <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" width=\"100%\" style=\"font-family: Arial,Helvetica,sans-serif; max-width: 700px;\">\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td>\n                <td align=\"center\" style=\"font-size: 29px; color:#FFFFFF; font-weight: normal; letter-spacing: 1px; line-height: 1;                           text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.2); font-family: Arial,Helvetica,sans-serif;\"> Survey Title </td>\n                <td width=\"20\"> </td>\n                <td width=\"20\"> </td> </tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\"> </td> </tr>\n            <tr>\n                <td height=\"10\" colspan=\"5\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\" align=\"left\" valign=\"top\" style=\"color:#666666; font-size: 13px;\"> \n                    <p>We're conducting a survey and your input would be appreciated. Click the button below to start the survey. Thank you for your participation!</p>  </td>\n                <td> </td> </tr> \n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr>\n            <tr>\n                <td> </td>\n                <td colspan=\"3\">\n                    <table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" align=\"center\" style=\"background:#A7BC38; border-radius: 4px; border: 1px solid #BBBBBB; color:#FFFFFF; font-size:14px; letter-spacing: 1px; text-shadow: -1px -1px 1px rgba(0, 0, 0, 0.8); padding: 10px 18px;\">\n                        <tr>\n                            <td align=\"center\" valign=\"center\"> <a href=\"[SurveyLink]\" target=\"_blank\" style=\"color:#FFFFFF; text-decoration:none;\">Begin Survey</a> </td> </tr> </table> </td>\n                <td> </td> </tr>\n            <tr>\n                <td colspan=\"5\" height=\"30\"> </td> </tr> \n            <tr valign=\"top\" style=\"color: #666666;font-size: 10px;\">\n                <td> </td>\n                <td valign=\"top\" align=\"center\" colspan=\"3\">\n                    <p>Please do not forward this email as its survey link is unique to you.\n                        <br><a href=\"[PrivacyLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Privacy</a> | <a href=\"[OptOutLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Unsubscribe</a> from this list</p> </td>\n                <td> </td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr>\n            <tr style=\"color: #999999;font-size: 10px;\">\n                <td align=\"center\" colspan=\"5\">[FooterLink]</td> </tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\"> </td> </tr> </table></div></body>\n\n</html>\n",
  "recipient_status": null,
  "is_branding_enabled": true,
  "href": "https://api.surveymonkey.com/v3/collectors/1234/messages/1234",
  "is_scheduled": false,
  "scheduled_date": null,
  "date_created": "2016-08-17T23:47:37+00:00",
  "type": "invite",
  "id": "31454399",
  "subject": "We want your opinion"
}

Response Schema

Status Code 200

Name Type Description
status string Status of the message
body string Email body
recipient_status string Set of recipients to send to
subject string Subject of the email message to be sent to recipients
is_branding_enabled boolean Whether the email has SurveyMonkey branding
is_scheduled boolean Whether the email is scheduled
schedule_date date Date email is scheduled to send
date_created date Date email was created
type string Type of message
id integer Id of the message

POST /collectors/{collector_id}/messages/{message_id}/send

Code samples

curl --request POST \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/1234/send \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"scheduled_date":"2015-10-06T12:56:55+00:00"}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"scheduled_date\":\"2015-10-06T12:56:55+00:00\"}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("POST", "/v3/collectors/1234/messages/1234/send", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/1234/send", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"scheduled_date\":\"2015-10-06T12:56:55+00:00\"}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /collectors/{collector_id}/messages/{message_id}/send

Available Methods

Body parameter

{
  "scheduled_date": "2015-10-06T12:56:55+00:00"
}

Request Body for POST /collectors/{collector_id}/messages/{message_id}/send

Name Type Required Description
scheduled_date string no Date when the message should send. If not specified, message sends immediately

Example Response for POST /collectors/{collector_id}/messages{message_id}/send

{
  "is_scheduled": true,
  "scheduled_date": "2015-11-04T12:56:55+00:00",
  "body": "<html>...</html>",
  "subject": "We want your opinion",
  "recipients": [
    "1234",
    "1234"
  ],
  "recipient_status": null,
  "type": "invite"
}

Response Schema

Status Code 200

Name Type Description
is_scheduled boolean If a message has been scheduled to send
scheduled_date string Date message was scheduled to be sent
body string The plain text body of the email or sms message to be sent to recipients.
subject string Subject of the email message to be sent to recipients
recipients array List of recipient ids
type string Message type: ‘sms’, ‘invite’, ‘reminder’, or ‘thank_you’
recipient_status string Recipient filter: ‘reminder’ or ‘thank_you’

GET /collectors/{collector_id}/messages/{message_id}/recipients

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients \
  --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/1234/recipients", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients", {
  "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/{message_id}/recipients

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
include string false Specify additional fields to return per recipient: survey_response_status, mail_status, custom_fields, remove_link, extra_fields, survey_link

Example Response for GET /collectors/{id}/messages/{id}/recipients

{
  "per_page": 1,
  "total": 1,
  "data": [
    {
      "phone_number": null,
      "href": "https://api.surveymonkey.com/v3/collectors/1234/recipients/1234",
      "id": "1234",
      "email": "test@surveymonkey.com"
    }
  ],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/collectors/1234/recipients/1234?page=1&per_page=1"
  }
}

Response Schema

Status Code 200

Name Type Description
links object
self string
page integer
per_page integer
total integer
data object
survey_response_status string If the recipient has completed the survey: not_responded, partially_responded, completely_responded
mail_status string If an invite message to the recipient has been: sent, not_sent, or is processing
custom_fields object Contact details for recipient
id string Recipient’s id
remove_link string Unsubscribe link
extra_fields object Extra fields
survey_link string Link to the survey

POST /collectors/{collector_id}/messages/{message_id}/recipients

Code samples

curl --request POST \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"email":"test@surveymonkey.com","phone_number":null,"first_name":"John","last_name":"Doe","custom_fields":null,"extra_fields":null,"duplicates":null,"contact_id":null}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"first_name\":\"John\",\"last_name\":\"Doe\",\"custom_fields\":null,\"extra_fields\":null,\"duplicates\":null,\"contact_id\":null}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("POST", "/v3/collectors/1234/messages/1234/recipients", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"first_name\":\"John\",\"last_name\":\"Doe\",\"custom_fields\":null,\"extra_fields\":null,\"duplicates\":null,\"contact_id\":null}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /collectors/{collector_id}/messages/{message_id}/recipients

Body parameter

{
  "email": "test@surveymonkey.com",
  "phone_number": null,
  "first_name": "John",
  "last_name": "Doe",
  "custom_fields": null,
  "extra_fields": null,
  "duplicates": null,
  "contact_id": null
}

Request Body for POST /collectors/{collector_id}/messages/{message_id}/recipients

Name Type Required Call Description
email string no without contact_id Email of the recipient. Required if email collector
phone_number Phone number string no without contact_id Phone number of the recipient. Required if sms collector
first_name string no without contact_id First name of the recipient
last_name string no without contact_id Last name the recipient
custom_fields object no without contact_id Custom fields for the recipient contact
extra_fields object no without contact_id Extra fields needed for the message body
duplicates string no with contact_id without contact_id Intended behavior while adding duplicate recipient (add (default), add_if_not_in_message, add_if_not_in_collector)
contact_id string yes with contact_id Id of the contact

Example Response for POST /collectors/{collector_id}/messages/{message_id}/recipients

{
  "survey_response_status": "not_responded",
  "mail_status": "not_sent",
  "email": "test@surveymonkey.com",
  "phone_number": null,
  "first_name": "John",
  "last_name": "Doe",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  },
  "id": "1234",
  "remove_link": "https://www.surveymonkey.com/optout?sm=1234",
  "extra_fields": {
    "favorite_color": "Red",
    "second_favorite_color": "Black",
    "third_favorite_color": "Green"
  },
  "survey_link": "https://www.surveymonkey.com/r/?sm=1234",
  "href": "https://api.surveymonkey.com/v3/collectors/1234/recipients/1234"
}

Response Schema

Status Code 200

Name Type Description
first_name string First name of the recepient
last_name string Last name of the recepient
email string Email of the recepient
survey_response_status string If the recipient has completed the survey: not_responded, partially_responded, completely_responded
mail_status string If an invite message to the recipient has been: sent, not_sent, or is processing
custom_fields object Contact details for recipient
id string Recipient’s id
remove_link string Unsubscribe link
extra_fields object Extra fields
survey_link string Link to the survey
href string Link to Recepient Resource

POST /collectors/{collector_id}/messages/{message_id}/recipients/bulk

Code samples

curl --request POST \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients/bulk \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"contact_ids":null,"contact_list_ids":null,"contacts":[{"email":"test@surveymonkey.com","phone_number":null,"first_name":"John","last_name":"Doe","custom_fields":null,"extra_fields":null}]}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"contact_ids\":null,\"contact_list_ids\":null,\"contacts\":[{\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"first_name\":\"John\",\"last_name\":\"Doe\",\"custom_fields\":null,\"extra_fields\":null}]}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("POST", "/v3/collectors/1234/messages/1234/recipients/bulk", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients/bulk", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"contact_ids\":null,\"contact_list_ids\":null,\"contacts\":[{\"email\":\"test@surveymonkey.com\",\"phone_number\":null,\"first_name\":\"John\",\"last_name\":\"Doe\",\"custom_fields\":null,\"extra_fields\":null}]}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /collectors/{collector_id}/messages/{message_id}/recipients/bulk

Available Methods

Body parameter

{
  "contact_ids": null,
  "contact_list_ids": null,
  "contacts": [
    {
      "email": "test@surveymonkey.com",
      "phone_number": null,
      "first_name": "John",
      "last_name": "Doe",
      "custom_fields": null,
      "extra_fields": null
    }
  ]
}

Request Body for POST /collectors/{collector_id}/messages/{message_id}/recipients/bulk

Name Type Required Description
contact_ids array no Contact ids
contact_list_ids array no Contact list ids
contacts [object] no New contacts
email string no Contact’s email address
phone_number Phone number string no Contact’s phone number
first_name string no Contact’s first name
last_name string no Contact’s last name
custom_fields object no Custom fields for contact
extra_fields object no Extra fields needed for the message body

Example Response for POST /collectors/{collector_id}/messages/{message_id}/recipients/bulk

{
  "succeeded": [
    {
      "phone_number": null,
      "id": "1234",
      "email": "test@surveymonkey.com",
      "href": "https://api.surveymonkey.com/v3/collectors/1234/recipients/1234"
    }
  ],
  "invalids": [],
  "existing": [],
  "bounced": [],
  "opted_out": [],
  "duplicate": []
}

Response Schema

Status Code 200

Name Type Description
succeeded array List of successfully added recipient objects
succeeded.id string Contact id for the recipient
succeeded.email string Email address for the recipient
succeeded.phone_number Phone number string Phone number for the recipient
succeeded.href string API resource URL for the recipient
invalids array List of invalid recipient email addresses that were provided
existing array List of recipients email addresses that have already been added
bounced array List of recipients email addresses that have previously bounced
opted_out array List of recipients email addresses that have opted out of receiving emails
duplicate array List of recipients email addresses recipients that were provided

GET /collectors/{id}/recipients

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/recipients \
  --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/recipients", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/recipients", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /collectors/{id}/recipients

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
include string false Specify additional fields to return per recipient: survey_response_status, mail_status, custom_fields, remove_link, extra_fields, survey_link

Example Response for GET /collectors/{id}/recipients

{
  "per_page": 1,
  "total": 1,
  "data": [
    {
      "phone_number": null,
      "href": "https://api.surveymonkey.com/v3/collectors/1234/recipients/1234",
      "id": "1234",
      "email": "test@surveymonkey.com"
    }
  ],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/collectors/1234/recipients/1234?page=1&per_page=1"
  }
}

Response Schema

Status Code 200

Name Type Description
links object
self string
page integer
per_page integer
total integer
data object
survey_response_status string If the recipient has completed the survey: not_responded, partially_responded, completely_responded
mail_status string If an invite message to the recipient has been: sent, not_sent, or is processing
custom_fields object Contact details for recipient
id string Recipient’s id
remove_link string Unsubscribe link
extra_fields object Extra fields
survey_link string Link to the survey

GET /collectors/{collector_id}/recipients/{recipient_id}

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/recipients/ \
  --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/recipients/", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/recipients/", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /collectors/{collector_id}/recipients/{id}

Available Methods

Example Response for GET /collectors/{collector_id}/recipients/{recipient_id}

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "survey_response_status": "not_responded",
  "mail_status": "not_sent",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  },
  "id": "1234",
  "remove_link": "https://www.surveymonkey.com/optout?sm=1234",
  "extra_fields": {
    "favorite_color": "Red",
    "second_favorite_color": "Black",
    "third_favorite_color": "Green"
  },
  "survey_link": "https://www.surveymonkey.com/r/?sm=1234"
}

Response Schema

Status Code 200

Name Type Description
first_name string First name of the recepient
last_name string Last name of the recepient
email string Email of the recepient
survey_response_status string If the recipient has completed the survey: not_responded, partially_responded, completely_responded
mail_status string If an invite message to the recipient has been: sent, not_sent, or is processing
custom_fields object Contact details for recipient
id string Recipient’s id
remove_link string Unsubscribe link
extra_fields object Extra fields
survey_link string Link to the survey

GET /collectors/{id}/stats

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/stats \
  --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/stats", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/stats", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /collectors/{id}/stats

Same as /collectors/{id}/messages/{id}/stats but returns stats for all messages sent from the collector.

GET /collectors/{collector_id}/messages/{message_id}/stats

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/messages/1234/stats \
  --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/1234/stats", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/messages/1234/stats", {
  "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/{message_id}/stats

Available Methods

Example Response for GET /collectors/{collector_id}/messages/{message_id}/stats

{
  "survey_response_status": {
    "completely_responded": 0,
    "not_responded": 0,
    "partially_responded": 0
  },
  "mail_status": {
    "opened": 0,
    "opted_out": 0,
    "not_sent": 1,
    "sent": 0,
    "bounced": 0,
    "link_clicked": 0
  },
  "recipients": 1
}

Response Schema

Status Code 200

Name Type Description
survey_response_status object
completely_responded integer Count of recipients who have completed a survey response
not_responded integer Count of recipients who have not started the survey
partially_responded integer Count of recipients who have begun the survey but not completed it
mail_status object
opened integer Count of recipients that have opened the message
opted_out integer Count of recipients that’ve clicked on the opt out link
not_sent integer Count of recipients that’ve been added but their message has not been delivered
sent integer Count of recipients that messages have been sent to
bounced integer Count of recipients with messages that bounced
link_clicked integer Count of messages where the included survey link was clicked on
recipients integer Count of recipients included in the stats

Survey Responses

These endpoints let you create responses directly via the API and view responses you have collected through any collector type.

GET /surveys/{id}/responses

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/surveys/1234/responses \
  --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/responses", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/responses", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /surveys/{id}/responses

Available Methods

Example response for GET /surveys/{id}/responses

{
  "per_page": 50,
  "total": 2,
  "data": [
    {
      "href": "https://api.surveymonkey.com/v3/surveys/1234/responses/1234",
      "id": "1234"
    },
    {
      "href": "https://api.surveymonkey.com/v3/surveys/1234/responses/1234",
      "id": "1234"
    }
  ],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/surveys/1234/responses?page=1&per_page=50"
  }
}

Response Schema

Status Code 200

Name Type Description
data object
id string Response id
href string Response API URL
links object
self string
page integer
per_page integer
total integer

GET /collectors/{id}/responses

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/responses \
  --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/responses", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/responses", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /collectors/{id}/responses

Available Methods

Optional Query Strings for GET

Name Type Required Description
page integer false Page of resources to return. Defaults to 1
per_page integer false Number of resources to return per page
start_created_at DateString false Responses started after this date
end_created_at DateString false Responses started before this date
start_modified_at DateString false Responses modified after this date
end_modified_at DateString false Responses modified before this date
status string false Status of the response: completed, partial, overquota, disqualified
email string false Email of the recipient
first_name string false First Name of the recipient
last_name string false Last Name of the recipient
ip string false The IP the response was taken from
custom string false The custom value associated with the response
total_time_max integer false The maximum amount of time spent on the response
total_time_min integer false The minimum amount of time spent on the response
total_time_units string false Unit of time for total_time_min and total_time_max: second, minute, hour
sort_order string false Sort order: ASC or DESC]
sort_by string false Field used to sort returned responses: date_modified

Example response for GET /collectors/{id}/responses

{
  "per_page": 50,
  "total": 2,
  "data": [
    {
      "href": "https://api.surveymonkey.com/v3/surveys/1234/responses/1234",
      "id": "1234"
    },
    {
      "href": "https://api.surveymonkey.com/v3/surveys/1234/responses/1234",
      "id": "1234"
    }
  ],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/surveys/1234/responses?page=1&per_page=50"
  }
}

Response Schema

Status Code 200

Name Type Description
data object
id string Response id
href string Response API URL
links object
self string
page integer
per_page integer
total integer

POST /collectors/{id}/responses

Code samples

curl --request POST \
  --url https://api.surveymonkey.com/v3/collectors/1234/responses \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --data '{"custom_variables":null,"custom_value":null,"date_created":null,"response_status":null,"ip_address":null,"recipient_id":null,"pages":[{"id":"1234","questions":[{"id":"1234","variable_id":null,"answers":{"choice_id":"Yes","row_id":null,"col_id":null,"other_id":null,"text":null}}]}]}'
import http.client

conn = http.client.HTTPSConnection("api.surveymonkey.com")

payload = "{\"custom_variables\":null,\"custom_value\":null,\"date_created\":null,\"response_status\":null,\"ip_address\":null,\"recipient_id\":null,\"pages\":[{\"id\":\"1234\",\"questions\":[{\"id\":\"1234\",\"variable_id\":null,\"answers\":{\"choice_id\":\"Yes\",\"row_id\":null,\"col_id\":null,\"other_id\":null,\"text\":null}}]}]}"

headers = {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'Authorization': "Bearer {access-token}"
    }

conn.request("POST", "/v3/collectors/1234/responses", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/responses", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  },
  "body": "{\"custom_variables\":null,\"custom_value\":null,\"date_created\":null,\"response_status\":null,\"ip_address\":null,\"recipient_id\":null,\"pages\":[{\"id\":\"1234\",\"questions\":[{\"id\":\"1234\",\"variable_id\":null,\"answers\":{\"choice_id\":\"Yes\",\"row_id\":null,\"col_id\":null,\"other_id\":null,\"text\":null}}]}]}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

POST /collectors/{id}/responses

Body parameter

{
  "custom_variables": null,
  "custom_value": null,
  "date_created": null,
  "response_status": null,
  "ip_address": null,
  "recipient_id": null,
  "pages": [
    {
      "id": "1234",
      "questions": [
        {
          "id": "1234",
          "variable_id": null,
          "answers": {
            "choice_id": "Yes",
            "row_id": null,
            "col_id": null,
            "other_id": null,
            "text": null
          }
        }
      ]
    }
  ]
}

Request Body for POST /collectors/{id}/responses

Name Type Required Description
custom_variables object no Values to any available custom variables in the survey
custom_value string no A custom value to attach to the response for a weblink collector
date_created DateString no Date the response was created
response_status string no Status of the response: completed, partial, overquota, disqualified
ip_address string no IP Address the response was taken from
recipient_id integer no The recipient ID from an email collector. See collector recipient
pages [object] yes Pages from the survey and their associated responses
id string yes The ID of the page with responses
questions [object] yes The questions on that page with responses
id string yes ID of the question with responses
variable_id string no ID of the random assignment variable for the question
answers object yes The answers for the question with responses. See formatting question types
choice_id string no The choice selected
row_id string no The row selected
col_id string no The column selected
other_id string no The other text choice selected
text string no Any open ended text

Example response for POST /collectors/{id}/responses

{
  "total_time": 144,
  "href": "https://api.surveymonkey.com/v3/surveys/1234/responses/1234",
  "ip_address": "192.168.4.16",
  "recipient_id": "",
  "id": "5007154402",
  "logic_path": {},
  "metadata": {},
  "date_modified": "2015-12-28T21:59:38+00:00",
  "response_status": "completed",
  "custom_variables": {
    "custvar_1": "one",
    "custvar_2": "two"
  },
  "edit_url": "https://www.surveymonkey.com/r/",
  "analyze_url": "https://www.surveymonkey.com/analyze/browse/",
  "custom_value": "custom identifier for the response",
  "page_path": [],
  "pages": [
    {
      "id": "12345678",
      "questions": [
        {
          "answers": [
            {
              "choice_id": "12345678"
            }
          ],
          "id": "12345678"
        },
        {
          "answers": [
            {
              "row_id": "12345678",
              "choice_id": "12345678"
            }
          ],
          "id": "12345678"
        },
        {
          "answers": [
            {
              "row_id": "12345678",
              "col_id": "12345678",
              "choice_id": "12345678"
            }
          ],
          "id": "12345678"
        },
        {
          "answers": [
            {
              "text": "Sample Text Response"
            }
          ],
          "id": "12345678"
        },
        {
          "answers": [
            {
              "row_id": "12345678",
              "text": "Sample Text Response"
            }
          ],
          "id": "12345678"
        }
      ]
    }
  ],
  "collector_id": "50253690",
  "date_created": "2015-12-28T21:57:14+00:00",
  "survey_id": "105724755",
  "collection_mode": "default"
}

Response Schema

Status Code 200

Name Type Description
id string Response id
href string URL for the response resource
survey_id string ID of the survey the response was taken for
collector_id string ID of the collector the response was taken for
recipient_id string ID of the recipient (only for email collectors). See collector recipient
total_time integer Total time in seconds spent on the survey
custom_value string Custom value associated with a response
edit_url string Weblink to the survey taking page to edit the response
analyze_url string Weblink to the analyze page to view the response
ip_address string IP Address the response was taken from
custom_variables object Values to any available custom variables in the survey
response_status string Status of the response: completed, partial, overquota, or disqualified
collection_mode string The collection mode of the response: default, preview, data_entry, survey_preview, or edit
date_created DateString Date the response was created
date_modified object Date the response was last modified
pages [object] Pages from the survey and their associated responses
id integer The ID of the page with responses
questions [object] The questions on that page with responses
id integer ID of the question with responses
variable_id integer ID of the random assignment variable for the question
answers [object] The answers for the question with responses
choice_id integer The choice selected
row_id integer The row selected
col_id integer The column selected
other_id integer The other text choice selected
text string Any open ended text
download_url string Download URL for file_upload question
content_type string MIME type for download_url

GET /surveys/{id}/responses/bulk

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/surveys/1234/responses/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/surveys/1234/responses/bulk", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/surveys/1234/responses/bulk", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /surveys/{id}/responses/bulk

Same as /collectors/{id}/responses/bulk

GET /collectors/{id}/responses/bulk

Code samples

curl --request GET \
  --url https://api.surveymonkey.com/v3/collectors/1234/responses/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/collectors/1234/responses/bulk", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
fetch("https://api.surveymonkey.com/v3/collectors/1234/responses/bulk", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer {access-token}"
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

GET /collectors/{id}/responses/bulk

Available Methods

Optional Query Strings for GET

Name Type Required Description
page integer false Page of resources to return. Defaults to 1
per_page integer false Number of resources to return per page. Max of 100 allowed per page. Defaults to 50
simple string false When ‘true’, this includes the question and answer text, in addition to IDs.
collector_ids string false Only include responses for this list of collector IDs
start_created_at DateString false Responses started after this date
end_created_at DateString false Responses started before this date
start_modified_at DateString false Responses modified after this date
end_modified_at DateString false Responses modified before this date
status string false Status of the response: completed, partial, overquota, disqualified
email string