NAV ¢

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 api-support@surveymonkey.com 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 api-support@surveymonkey.com 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

Request and Response Limits

Draft and Private apps are subject to rate limits:

Max Requests Per Minute Max Requests Per Day
120 500

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

If you think you may be in danger of frequently exceeding your request-limit threshold, please fill out this form with an estimate of your anticipated API activity. 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, and response_type.

  • response_type will always be set to the value code
  • client_id the unique SurveyMonkey client id you got when registering your app
  • redirect_uri URL encoded OAuth redirect URI you registered for your app (can be found and edited here)

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

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. 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`
"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]

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

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 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}/respones/bulk. 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 Number of pages 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.
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.

Help and Resources

SurveyMonkey lists code examples on Github and monitors questions tagged as surveymonkey on StackOverflow. If you have an SDK or example you would like added, let us know. We also offer email support at api-support@surveymonkey.com.

Change Log

All noteworthy changes and additions made to the V3 API are listed below. For changes that are not backwards compatible, developers will be informed via email well in advance, and an adequate transition period will be put in place to insure zero downtime. If you have any questions regarding a change, please contact api-support@surveymonkey.com.

March 30th, 2016

Add Contact Search Capabilities

Description of Changes: Add search and search_by query parameters to contact resource list endpoints.

Endpoints Affected: /contact_lists/{id}/contacts, /contacts

Developer Actions Required: None

Add an Additional Scope Requirement for Response Details

Description of Changes: Add “View Response Details” scope, and make it a requirent for viewing response answers. Make “View Responses” scope available to all plans.

Endpoints Affected: /surveys/{id}/responses/{id}/details, /collectors/{id}/responses/{id}/details, /surveys/{id}/responses/bulk, /collectors/{id}/responses/bulk

Developer Actions Required: Reauthorization of every user using an application that makes use of the affected endpoints.

Provide Complete Group Info to Groups Admins

Description of Changes: Fix bug preventing group admins from seeing additional group information.

Endpoints Affected: /groups/{id}

Developer Actions Required: None

Allow Adding Contact List to Email Collector Message

Description of Changes: Allow adding a list of contacts lists to an email collector list by passing their ids.

Endpoints Affected: /collectors/{id}/messages/{id}/recipients/bulk

Developer Actions Required: None

April 13th, 2016

Add Copying of Existing Surveys

Description of Changes: Allow creation of a survey using an existing survey available to the user.

Endpoints Affected: /surveys

Developer Actions Required: None

Allow Setting of Survey Custom Variables

Description of Changes: Allow creation, modification, and deletion of survey custom variables.

Endpoints Affected: /surveys, /surveys/{id}

Developer Actions Required: None

Enforce Contact and Response Limits

Description of Changes: Enforce contact import limits and response export limits based on a user’s plan.

Endpoints Affected: /contact_lists/{id}/contacts, /contact_lists/{id}/contacts/bulk, /contacts, /contacts/bulk, /surveys/{id}/responses/{id}, /surveys/{id}/responses/bulk, /surveys/{id}/responses/{id}/details, /collectors/{id}/responses/{id}, /collectors/{id}/responses/bulk, /collectors/{id}/responses/{id}/details

Developer Actions Required: None

Add Survey Preview URL

Description of Changes: Provide survey preview URL as part of survey details.

Endpoints Affected: /surveys/{id}, /surveys/{id}/details

Developer Actions Required: None

April 21st, 2016

Introduce Application Status

Description of Changes: Add Draft, Public, Private, and Disabled statuses to applications. More info can be found here.

Endpoints Affected: All

Developer Actions Required: All existing applications will be set to Draft. Applications making calls on behalf of users within the same group as the developer should be switched to Private. Applications making calls on behalf of users outside the developer’s group should be switched to Public.

Allow Setting of Response Status

Description of Changes: Allow modification of response_status response field.

Endpoints Affected: /surveys/{id}/responses, /collectors/{id}/responses, /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}

Developer Actions Required: None

Fix Inconsistent Response Status

Description of Changes: In some cases the list of possible response status included ‘new’ instead of 'partial’. Consistently return a response status that is one of 'completed’, 'partial’, 'overquota’, or 'disqualified’.

Endpoints Affected: /collectors/{id}/responses, /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}, /surveys/{id}/responses/{id}/details, /collectors/{id}/responses/{id}/details, /surveys/{id}/responses/bulk, /collectors/{id}/responses/bulk

Developer Actions Required: Remove any application dependencies on the 'response_status’ being set to 'new’.

Return Edit URL for Responses

Description of Changes: Provide 'edit_url’ field for responses that can be used to edit the response by taking or retaking the survey.

Endpoints Affected: /collectors/{id}/responses, /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}, /surveys/{id}/responses/{id}/details, /collectors/{id}/responses/{id}/details, /surveys/{id}/responses/bulk, /collectors/{id}/responses/bulk

Developer Actions Required: None

April 28th, 2016

Improve Resource Pagination

Description of Changes: Return 'total’ and 'links’ fields for all resource list endpoints. 'total’ represents the total number of resources items available, and 'links’ includes all pagination links.

Endpoints Affected: All resource list endpoints.

Developer Actions Required: None

May 12th, 2016

Add Survey Navigation URLs

Description of Changes: Return survey navigation URLs for edit('edit_url’), collect('collect_url’), analyze('analyze_url’), and summary('summary_url’). User needs to be logged in to visit the URL.

Endpoints Affected: /surveys, /surveys/{id}, /surveys/{id}/details

Developer Actions Required: None

Streamline OAuth Scope Additions

Description of Changes: If a developer adds scopes to an app that a user has already authorized, the authorization page will highlight the additional scopes asked for.

Endpoints Affected: None

Developer Actions Required: None

Allow for Erasing of Question Responses

Description of Changes: Providing the question ID and omitting the answers during a PATCH will now delete the response for the specified question.

Endpoints Affected: /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}

Developer Actions Required: Remove any application dependencies that rely on the existing functionality.

Allow for Erasing of Response Pages

Description of Changes: Omitting pages during a PUT will now delete the response for the omitted pages.

Endpoints Affected: /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}

Developer Actions Required: Remove any application dependencies that rely on the existing functionality.

May 24th, 2016

Fix Webhook Subscription URL PATCH

Description of Changes: Allow the webhook subscription URL to be modified via PATCH.

Endpoints Affected: /webhooks/{id}

Developer Actions Required: None

Provide Recipient Info in Bulk Response Dump

Description of Changes: Return recipient information withing the 'metadata’ field for the bulk response endpoints.

Endpoints Affected: /surveys/{id}/responses/bulk, /collectors/{id}/responses/bulk

Developer Actions Required: None

Fix Inconsistent Collection Mode

Description of Changes: In some cases the list of possible collection modes included 'normal’, 'manual’, and 'edited’. Consistently return a collection mode that is 'default’, 'preview’, 'data_entry’, 'survey_preview’, or 'edit’.

Endpoints Affected: /collectors/{id}/responses, /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}, /surveys/{id}/responses/{id}/details, /collectors/{id}/responses/{id}/details, /surveys/{id}/responses/bulk, /collectors/{id}/responses/bulk

Developer Actions Required: Remove any application dependencies on the 'collection_mode’ being set to 'normal’, 'manual’, or 'edited’.

Enable Groups Access for Platinum

Description of Changes: Allow access to group endpoints for users with the Platinum plan.

Endpoints Affected: /groups, /groups/{id}, /groups/{id}/members, /groups/{id}/members/{id}

Developer Actions Required: None

June 2nd, 2016

Fix Updating Survey Custom Variables

Description of Changes: Previously, modifying custom variables for a survey would completely remove the existing variables and add them as a new set of variables. This would wipe all variable values stored on the responses for that survey, and prevent the ability to modify or add variables for new responses. Moving forward, if the name of the variable is the same, the variable will not be deleted during a PATCH or PUT.

Endpoints Affected: /surveys, /surveys/{id}

Developer Actions Required: None

Update Response Endpoints

Description of Changes: Update all response endpoints to start with ’/surveys/{id}’ or ’/collectors/{id}’.

Endpoints Affected: /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}, /surveys/{id}/responses/{id}/details, /collectors/{id}/responses/{id}/details

Developer Actions Required: Update all apps currently pointing to ’/responses/{id}’ or ’/responses/{id}/details’. The old endpoints with continue to work for the time being, and an email will be distributed to inform developers of their deprecation date.

June 22nd, 2016

Default Email Collector Message to HTML

Description of Changes: Previously, a plaintext version of the default email message was used if no value was passed for 'body_text’ or 'body_html’. This has been updated to default to an HTML version.

Endpoints Affected: /collectors/{id}/messages, /collectors/{id}/messages/{id}

Developer Actions Required: None

Make View Groups Available to Gold Plans

Description of Changes: To align correctly with the availabilty of team collaboration (groups) through the SurveyMonkey website, the groups endpoints are now available to Gold level plans.

Endpoints Affected: /groups, /groups/{id}, /groups/{id}/members, /groups/{id}/members/{id}

Developer Actions Required: Reauthorization of Gold users looking to make use of the affected endpoints.

June 30th, 2016

Allow Copying from an Existing Email Message

Description of Changes: POSTing to /collectors/{id}/messages with 'from_collector_id’ and 'from_message_id’ will copy an existing message with an option to include original set of recipients.

Endpoints Affected: /collectors/{id}/messages

Developer Actions Required: None

July 13th, 2016

Add Response Analyze URL

Description of Changes: Return response analyze URL, 'analyze_url’ for response resource. User needs to be logged in to visit the URL.

Endpoints Affected: /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}

Developer Actions Required: None

Improve OAuth Error Page

Description of Changes: Users confronted with a disabled app, or a private app they do not have access to will be provided with a improved error page describing the issue and an option to log in as a different user in the latter case.

Endpoints Affected: /oauth/authorize

Developer Actions Required: None

July 25th, 2016

Fix Forbidden Access 500s

Description of Changes: A number of endpoints listed below were returning a 500 is one or more of the resources did not belong to the user. This has been fixed to return 404s.

Endpoints Affected: /benchmark_bundles/{id}/analyze, /surveys/{id}/collectors, /collectors/{id}/messages, /surveys/{id}/pages, /surveys/{id}/pages/{id}, /surveys/{id}/pages/{id}/questions, /surveys/{id}/pages/{id}/questions/{id}, /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}, /collectors/{id}/recipients/{id}

Developer Actions Required: Remove any application dependencies that rely on the existing functionality.

Add Subject to Email Message List

Description of Changes: Return 'subject’ in collector email message resource list.

Endpoints Affected: /collectors/{id}/messages

Developer Actions Required: None

August 4th, 2016

Add Bulk Contact Fetch

Description of Changes: Add GET method to contact bulk endpoints to return complete contact information for large numbers of contacts.

Endpoints Affected: /contact_lists/{id}/contacts/bulk, /contacts/bulk

Developer Actions Required: None

August 18th, 2016

New Benchmark Questions Endpoints

Description of Changes: Allow fetching of question specific benchmarks for SurveyMonkey approved questions.

Endpoints Affected: /surveys/{id}/pages/{id}/questions/{id}, /surveys/{id}/pages/{id}/questions/{id}/benchmark

Developer Actions Required: None

October 6th, 2016

Change Custom Variables Plan Requirement

Description of Changes: Make survey custom variables accessible to Gold plan and above.

Endpoints Affected: /surveys, /surveys/{id}, /surveys/{id}/responses/bulk, /collectors/{id}/responses/bulk, /surveys/{id}/responses/{id}, /collectors/{id}/responses/{id}, /surveys/{id}/responses/{id}/details, /collectors/{id}/responses/{id}/details

Developer Actions Required: None

October 13th, 2016

Allow Copying of Collectors

Description of Changes: Copy collectors by passing the collector ID when creating one. Use 'from_collector_id’ when POSTing to /surveys/{id}/collectors.

Endpoints Affected: /surveys/{id}/collectors

Developer Actions Required: None

New Collector Recipients Endpoint

Description of Changes: Fetch all recipients for a given collector using /collectors/{id}/recipients.

Endpoints Affected: /collectors/{id}/recipients

Developer Actions Required: None

October 24th, 2016

Provide Support for Survey Nickname

Description of Changes: Allow setting of nickname, and provide nickname when fetching the survey resource list and individual resource.

Endpoints Affected: /surveys, /surveys/{id}

Developer Actions Required: None

November 17th, 2016

Added 6 new endpoints that extend analyze features

Description of changes: Allows those with view response details scope to call endpoints that return response counts per survey, page, or question and over a given time period.

Endpoints Affected: /surveys/{id}/rollups, /surveys/{id}/pages/{id}/rollups, /surveys/{id}/pages/{id}/questions/{id}/rollups, /surveys/{id}/trends, /surveys/{id}/pages/{id}/trends, /surveys/{id}/pages/{id}/quesions/{id}/trends

Developer Actions Required: None

January 12th, 2017

Include Resource IDs in Webhook Callback

Description of Changes: Webhook callback events now include the ids of resources involved in the event.

Developer Actions Required: None

Description of Changes: Footer field was added to survey resource. It can be set to be false to remove the SurveyMonkey footer in a POST, PUT, or PATCH to surveys

Endpoints Affected: /surveys, /surveys/{id}

Developer Actions Required: None

Filter Responses by Pages or Questions

Description of Changes: You can now request certain Pages or Questions to be included when calling Survey Responses endpoints, both in bulk and for individual responses.

Endpoints Affected: /surveys/{id}/response/{id}/details, /collectors/{id}/response{id}/details, /surveys/{id}/responses/bulk, /collectors/{id}/respones/bulk

Developer Actions Required: None

Request Additional Fields when Calling Recipient Lists

Description of Changes: When requesting recipient lists you can now include a variety of additional fields per recipient.

Endpoints Affected: /collectors/{id}/messages/{id}/recipients, /collectors/{id}/recipients

Developer Actions Required: None

Set Response Limit for Collectors

Description of Changes: You can now set or edit a response_limit for a collector. The collector will close after the limit is reached.

Endpoints Affected: /surveys/{id}/collectors, /collectors/{id}

Developer Actions Required: None

Set Survey End Page Behavior

Description of Changes: You can now set a collector redirect_type to set the survey end page behavior to either close or run in a loop (weblink only).

Endpoints Affected: /surveys/{id}/collectors, /collectors/{id}

Developer Actions Required: None

January 31st, 2017

Add 2 new endpoints that provide email invitation collector stats

Description of changes: Allows developers to call endpoints that return mail status and response stats for an email invitation collector or message

Endpoints Affected: /collectors/{id}/messages/{id}/stats, /collectors/{id}/stats

Developer Actions Required: None

August 11th, 2017

Support folders in API

Description of changes: Added two new endpoints /survey_folders and /survey_folders/{id} and added folder_id to the /surveys resource.

Endpoints Affected: /survey_folders, /survey_folders/{id}, /surveys, /surveys/{id}, and /surveys/{id}/details.

Developer Actions Required: None

September 6th, 2017

Support Multilingual Surveys in API

Description of changes: Added three new endpoints to support multilingual surveys: /survey_languages, /surveys/{survey_id}/languages, and /surveys/{survey_id}/languages/{language_code}.

Endpoints Affected: /survey_languages, /surveys/{survey_id}/languages, and /surveys/{survey_id}/languages/{language_code}.

Developer Actions Required: None

API Endpoints

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).

/users/me

Definition

GET https://api.surveymonkey.com/v3/users/me

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/users/me
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/users/me"
s.get(url)

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns the current user’s account details including their plan. Public App users need access to the View Users scope

User Resource

Example Response

{
  "username": "testuser",
  "scopes": {
    "available": [
      "users_read",
      "surveys_read",
      "collectors_read",
      "collectors_write",
      "contacts_read",
      "contacts_write",
      "surveys_write",
      "responses_read",
      "responses_read_detail",
      "responses_write",
      "groups_read",
      "webhooks_read",
      "webhooks_write",
      "library_read"
    ],
    "granted": [
      "collectors_read",
      "contacts_write",
      "contacts_read",
      "surveys_read",
      "collectors_write",
      "users_read"
    ]
  },
  "first_name": "Test",
  "last_name": "User",
  "account_type": "enterprise_platinum",
  "language": "en",
  "email": "user@surveymonkey.com",
  "href": "https://api.surveymonkey.com/v3/users/me",
  "date_last_login": "2017-04-28T03:49:24.333000+00:00",
  "date_created": "2015-12-03T01:23:00+00:00",
  "id": "1234"
}
Name Description Data Type
id User id String
username Username String
first_name User’s first name String
last_name User’s last name String
language ISO 639-1 code for the language set for the user’s account String-ENUM
email Email address for user’s account String
account_type SurveyMonkey plan the user has String-ENUM
date_created Date user’s account was created Date String
date_last_login Date user last logged in Date String in format YYYY-MM-DDTHH:MM:SS0000+HH:MM
scopes Contains two arrays: available, listing the scopes available to the user and granted, listing the scopes the user has approved during Oauth Object

/groups

Definition

GET https://api.surveymonkey.com/v3/groups

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" https://api.surveymonkey.com/v3/groups
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/groups
s.get(url)

Example Response

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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a team if the user account belongs to a team (users can only belong to one team). Public App users need access to the View Teams scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Groups List Resource

Name Description Data Type
data[_].id Group id String
data[_].name Group name String
data[_].href Resource API URL String

/groups/{id}

Definition

GET https://api.surveymonkey.com/v3/groups/{group_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" https://api.surveymonkey.com/v3/groups/1234
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/groups/%s" % (group_id)
s.get(url)

Example Response

{
  "id": "1234",
  "name": "Test Group",
  "member_count": 1,
  "max_invites": 100,
  "date_created": "2015-10-06T12:56:55+00:00"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a teams’s details including the teams’s owner and email address. Public App users need access to the View Teams scope

Group Resource if Account Owner or Admin

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

Group Resource if Member

Name Description Data Type
id Group id String
name Name of the group String
owner_email Group owner’s email address String

/groups/{id}/members

Definition

GET https://api.surveymonkey.com/v3/groups/{group_id}/members

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/groups/1234/members
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/groups/%s/members" % (group_id)
s.get(url)

Example Response

{
  "per_page": 1,
  "page": 1,
  "total": 1,
  "data": [{
    "id": "1234",
    "username": "test_user",
    "href": "http://api.surveymonkey.com/v3/members/1234"
  }],
  "links": {
    "self": "https://api.surveymonkey.com/v3/groups/12345/members?page=1&per_page=1"
  }
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of users who have been added as members of the specified group. Public App users need access to the View Teams scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Group Members List Resource

Name Description Data Type
data[_].id Member id String
data[_].username Member username String
data[_].href Resource API URL String

/groups/{id}/members/{id}

Definition

GET https://api.surveymonkey.com/v3/groups/{group_id}/members/{member_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/groups/1234/members/1234
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/groups/%s/members/%s" % (group_id, member_id)
s.get(url)

Example Response

{
  "id": "1234",
  "username": "test_user",
  "email": "test@surveymonkey.com",
  "type": "regular",
  "status": "active",
  "user_id": "1234",
  "date_created": "2015-10-06T12:56:55+00:00"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a group member’s details including their role and status. Public App users need access to the View Teams scope

Group Member Resource

Name Description Data Type
id Member id String
username Member username String
email User’s email address String
type Which type of role the member has: regular, account_owner, or admin String-ENUM
status A members status (if they have accepted an invitation into the group): active, pending String-ENUM
user_id User ID of the group member String
date_created Date and time when member was created DateString

Surveys, Pages, and Questions

The following endpoints let you create surveys, survey pages, and add questions to survey pages.

A POST to /surveys will create an empty survey to which you can add pages and questions (See formatting question types). This endpoint also accepts a survey or template ID as an arguement to create a pre-populated survey that can be used as is or modified by deleting, updating, or adding pages or questions.

A survey needs at least one page and question in order to record a survey response.

/surveys

Definition

POST https://api.surveymonkey.com/v3/surveys

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys -d '{"title":"My Survey"}'
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "title": "My Survey"
}
url = "https://api.surveymonkey.com/v3/surveys"
s.post(url, json=payload)

Example Response

{
  "title": "My Survey",
  "nickname": "",
  "category":"",
  "language": "en",
  "question_count": 10,
  "page_count": 10,
  "date_created": "2015-10-06T12:56:55",
  "date_modified": "2015-10-06T12:56:55",
  "id": "1234",
  "href": "https://api.surveymonkey.com/v3/surveys/1234",
  "buttons_text": {
    "done_button": "Done",
    "prev_button": "Prev",
    "exit_button": "Exit",
    "next_button": "Next"
  },
  "custom_variables": {
    "name": "label"
  },
  "footer": true,
  "folder_id":"1234",
  "preview": "https://www.surveymonkey.com/r/Preview/",
  "edit_url": "https://www.surveymonkey.com/create/",
  "collect_url": "https://www.surveymonkey.com/collect/list",
  "analyze_url": "https://www.surveymonkey.com/analyze/",
  "summary_url": "https://www.surveymonkey.com/summary/"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of surveys owned or shared with the authenticated user. Public App users need access to the View Surveys scope
  • POST: Creates a new empty survey or, if a template id or an existing survey id is specified, a survey prepopulated with pages and questions. Public App users need access to the Create/Modify Surveys scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
sort_by Field used to sort returned survey list: title, date_modified, or num_responses String-ENUM
sort_order Sort order: ASC or DESC String-ENUM
include 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 Comma Separated String-ENUM
title Search survey list by survey title String
start_modified_at Surveys must be last modified after this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
end_modified_at Surveys must be last modified before this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
folder_id Specify the id of a folder to only return surveys in it. String

Survey List Resource

Name Description Data Type
data[_].id Survey id String
data[_].title Survey title String
data[_].nickname Survey nickname String
data[_].href Resource API URL String

Request Body Arguments for POST (if copying from existing survey or template)

Name Required Description Data Type
title No (default=“New Survey”) Survey title String
from_template_id No (required if from_survey_id not provided) Survey template to copy from. See /survey_templates String
from_survey_id No (required if from_template_id not provided) Survey id to copy from String

Request Body Arguments for POST (if creating blank survey)

Name Required Description Type
title No (default=“New Survey”) Survey title String
nickname No (default=“”) Survey nickname String
language No (default=“en”) Survey language String
buttons_text No Survey Buttons text container Object
buttons_text.next_button No Button text String
buttons_text.prev_button No Button text String
buttons_text.exit_button No Button text. If set to an empty string, button will be ommitted from survey String
buttons_text.done_button No Button text String
custom_variables No Dictionary of survey variables Object
footer No (default=true) If false, SurveyMonkey’s footer is not displayed Boolean
folder_id No If specified, adds the survey to the folder with that id. String

Request Body Arguments for Bulk POST

Name Required Description Type
title No (default=“New Survey”) Survey title String
nickname No (default=“”) Survey nickname String
language No (default=“en”) Survey language String
buttons_text No Survey Buttons text container Objects
buttons_text.next_button No Button text String
buttons_text.prev_button No Button text String
buttons_text.exit_button No Button text. If set to an empty string, button will be ommitted from survey String
buttons_text.done_button No Button text String
pages Yes Pages to be created List of Page Objects
pages[_].questions Yes Questions to be created List of Question Objects
footer No (default=true) If false, SurveyMonkey’s footer is not displayed Boolean

/surveys/{id}

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/1234
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s" % (survey_id)
s.get(url)

Example Response

{
  "title": "My Survey",
  "nickname": "",
  "category": "",
  "language": "en",
  "question_count": 0,
  "page_count": 0,
  "date_created": "2015-10-06T12:56:55",
  "date_modified": "2015-10-06T12:56:55",
  "id": "1234",
  "href": "http://api.surveymonkey.com/v3/surveys/1234",
  "buttons_text": {
    "done_button": "Done",
    "prev_button": "Prev",
    "exit_button": "Exit",
    "next_button": "Next"
  },
  "custom_variables": {
    "name": "label"
  },
  "footer": true,
  "folder_id": "1234",
  "preview": "https://www.surveymonkey.com/r/Preview/",
  "edit_url": "https://www.surveymonkey.com/create/",
  "collect_url": "https://www.surveymonkey.com/collect/list",
  "analyze_url": "https://www.surveymonkey.com/analyze/",
  "summary_url": "https://www.surveymonkey.com/summary/",
  "response_count": 12
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a survey’s details. To get an expanded version showing all pages and questions use /surveys/{survey_id}/details. Requires View Surveys scope
  • PATCH: Modifies a survey’s title, nickname or language. Public App users need access to the Create/Modify Surveys scope
  • PUT: Replaces a survey. Request body arguments the same as POST /surveys. Public App users need access to the Create/Modify Surveys scope
  • DELETE: Deletes a survey. Public App users need access to the Create/Modify Surveys scope

Request Body Arguments for PATCH (See POST /surveys for PUT arguments)

Name Required Description Data Type
title No (PUT default=“New Survey”) Survey title String
nickname No (PUT default=“”) Survey nickname String
language No (PUT default=“en”) Survey language String
buttons_text No Survey Buttons text container Object
buttons_text.next_button No Button text String
buttons_text.prev_button No Button text String
buttons_text.exit_button No Button text. If set to an empty string, button will be ommitted from survey String
buttons_text.done_button No Button text String
custom_variables No Dictionary of survey variables Object
footer No (default=true) If false, SurveyMonkey’s footer is not displayed Boolean
folder_id No If specified, adds the survey to the folder with that id. String

Survey Resource

Name Description Type
id Survey id String
title Survey title String
nickname Survey nickname String
custom_variables Dictionary of survey variables Object
category Survey category chosen when creating the survey String
language ISO 639-1 code for survey language String-ENUM
question_count Number of questions in survey Integer
page_count Number of pages in survey Integer
date_created Date and time when survey was created Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
date_modified Date and time when survey was last modified Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
buttons_text.next_button Button text String
buttons_text.prev_button Button text String
buttons_text.exit_button Button text String
buttons_text.done_button Button text String
preview Survey preview URL String
folder_id If applicable, the id of the folder the survey is in String
edit_url Survey edit URL String
collect_url Survey collect URL String
analyze_url Survey analyze URL String
summary_url Survey summary URL String
href Resource API URL String
response_count Number of responses survey has received Integer
footer Whether or not SurveyMonkey’s footer is not displayed Boolean

/surveys/{id}/details

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/details

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/1234/details
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/details" % (survey_id)
s.get(url)

Example Response

{
  "title": "My Survey",
  "nickname": "",
  "custom_variables": {
    "name": "label"
  },
  "language": "en",
  "question_count": 10,
  "page_count": 10,
  "date_created": "2015-10-06T12:56:55+00:00",
  "date_modified": "2015-10-06T12:56:55+00:00",
  "id": "1234",
  "folder_id":"1234",
  "pages":[
    {
      //Page Object
      "questions": [
        {
          //Question Object
        }
      ]
    }
  ],
  "buttons_text": {
    "done_button": "Done",
    "prev_button": "Prev",
    "exit_button": "Exit",
    "next_button": "Next"
  },
  "footer": true,
  "preview": "https://www.surveymonkey.com/r/Preview/",
  "edit_url": "https://www.surveymonkey.com/create/",
  "collect_url": "https://www.surveymonkey.com/collect/list",
  "analyze_url": "https://www.surveymonkey.com/analyze/",
  "summary_url": "https://www.surveymonkey.com/summary/"
}

Available Methods

  • GET: Returns an expanded survey resource with a pages element containing a list of all page objects, each containing a list of questions objects. Public App users need access to the View Surveys scope

/survey_categories

Definition

GET https://api.surveymonkey.com/v3/survey_categories

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/survey_categories
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/survey_categories"
s.get(url)

Example Response

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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of survey categories that can be used to filter survey templates. Public App users need access to the View Library Assets scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
language ISO 639-1 code for language to filter by (default=en) String-ENUM

Survey Categories Resource

Name Description Data Type
data[_].id Resource id String
data[_].name Resource name String

/survey_templates

Definition

GET https://api.surveymonkey.com/v3/survey_templates

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/survey_templates?category=all
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "category": "community"
}
url = "https://api.surveymonkey.com/v3/survey_templates"
s.get(url, params=payload)

Example Response

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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of survey templates. Survey template ids can be used as an argument to POST a new survey. Public App users need access to the View Library Assets scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
language ISO 639-1 code for template language to filter by (default=en) String-ENUM
category Category to filter by, see /survey_categories for a list of available categories if not specified, all categories are returned String-ENUM

Survey Templates Resource

Name Description Type
data[_].id Resource id String
data[_].name Resource name String
data[_].title Survey title String
data[_].description Template description String
data[_].category Template category String
data[_].available Template is available to user Boolean
data[_].num_questions Number of questions in the template Integer
data[_].preview_link Template preview URL String

/survey_languages

Definition

GET https://api.surveymonkey.com/v3/survey_languages

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/survey_languages
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/survey_languages"
s.get(url)

Example Response

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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of survey languages that can be used to generate translations for multilingual surveys

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Survey Languages Resource

Name Description Data Type
data[_].id Language code String
data[_].name Name of language String
data[_].native_name Name of language in native language String

/surveys/{id}/pages

Definition

POST https://api.surveymonkey.com/v3/surveys/{survey_id}/pages

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/1234/pages -d '{"title":"Page Title"}'
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "title": "Page Title"
}
url = "https://api.surveymonkey.com/v3/surveys/%s/pages" % (survey_id)
s.post(url, json=payload)

Example Response

{
  "title": "Page Title",
  "description": "",
  "position": 1,
  "question_count": 0,
  "id": "1234",
  "href":"http://api.surveymonkey.com/v3/surveys/1234/pages/1234"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a page’s details. Public App users need access to the View Surveys scope
  • POST: Creates a new, empty page, see /surveys/{id}/pages/{id}/questions to add questions to pages. Public App users need access to the Create/Modify Surveys scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Page List Resource

Name Description Data Type
data[_].id Page ID String
data[_].title Page Title String
data[_].description Page Description String
data[_].href Resource API URL String
data[_].position Position of page in survey Integer

Request Body Arguments for POST

Name Required Description Type
title No (default=“”) Page title String
description No (default: “”) Page description String
position No (default=end) Position of page in survey Integer

/surveys/{id}/pages/{id}

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/1234/pages/1234
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/pages/%s" % (survey_id, page_id)
s.get(url)

Example Response

{
  "title": "Page Title",
  "description": "",
  "position": 1,
  "question_count": 0,
  "id": "1234",
  "href": "https://api.surveymonkey.com/v3/surveys/1234/pages/1234"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a page’s details. Public App users need access to the View Surveys scope
  • PATCH: Modifies a page (updates any fields accepted as arguments to POST /surveys{id}/pages). Public App users need access to the Create/Modify Surveys scope
  • PUT: Replaces a page (same arguments and requirements as POST /surveys{id}/pages). Public App users need access to the Create/Modify Surveys scope
  • DELETE: Deletes a page. Public App users need access to the Create/Modify Surveys scope

Request Body Arguments for PUT/PATCH

Name Required Description Data Type
title No (PUT default=“”) Page title String
description No (PUT default=“”) Page description String
position No (PUT default=end) Page position in survey String

Page Resource

Name Description Type
title Page title String
description Page description String
position Page position Integer
question_count Number of questions on page Integer
id Page id String

/surveys/{id}/pages/{id}/questions

Definition

POST https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}/questions

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}/questions -d '{"headings": [{"heading": "A question about primates.", "random_assignment": {"percent": 50, "position": 1}},{"heading": "A question about primates phrased slightly differently.", "random_assignment": {"percent": 50, "position": 2},}], "family": "open_ended", "subtype": "single", "position": 1, "sorting": {"type": "textasc","ignore_last": True}, "required": {"text": "This question is required!", "type": "at_least", "amount": "1"},"validation": {"type": "integer","text": "Validation has failed!","min": 20,"max": 30}, "forced_ranking": True, "answers": { #SEE ANSWERS SECTION }}'

import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "headings": [
    {
      "random_assignment": {
        "position": 1,
        "percent": 50
      },
      "heading": "Multiple Choice with Random Assignment v1"
    },
    {
      "random_assignment": {
        "position": 2,
        "percent": 50
      },
      "heading": "Multiple Choice with Random Assignment v2"
    }
  ],
  "family": "single_choice",
  "subtype": "vertical",
  "answers": {
    "choices": [
      {
        "text": "a",
        "visible": true,
        "position": 1
      },
      {
        "text": "b",
        "visible": true,
        "position": 2
      },
      {
        "text": "c",
        "visible": true,
        "position": 3
      }
    ]
  },
  "position": 3
}
url = "https://api.surveymonkey.com/v3/surveys/%s/pages/%s/questions" % (survey_id, page_id)
s.post(url, json=payload)

####Response
Same as request, but with two additional fields (id, href)

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of questions on a survey page. Public App users need access to the View Surveys scope
  • POST: Creates a new question on a survey page, see formatting question types. Public App users need access to the Create/Modify Surveys scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Question List Resource

Name Description Data Type
data[_].id Question id String
data[_].heading Question heading String
data[_].href Resource API URL String
data[_].position Position of question on page Integer

Request Body Arguments for POST

Name Required Description Data Type
headings Yes List of question headings objects Array
headings[_].heading Yes The title of the question, or empty string if random_assignment is defined String
headings[_].description No If random_assignment is defined, and family is presentation_image this is the title String
headings[_].image No Image data when question family is presentation_image Object or null
headings[_].image.url No URL of image when question family is presentation_image String
headings[_].random_assignment No Random assignment data Object or null
headings[_].random_assignment.percent Yes Percent chance of this random assignment showing up (must sum to 100) Integer
headings[_].random_assignment.position No Position of the random_assignment in survey creation page Integer
headings[_].random_assignment.variable_name No Internal use name for question tracking, can be "" String
position No (default=last) Position of question on page Integer
family Yes Question family determines the type of question, see formatting question types String
subtype Yes Question family’s subtype further specifies the type of question, see formatting question types String
sorting No Sorting details of answers Object
sorting.type Yes Sort answer choices by: default, textasc, textdesc, resp_count_asc, resp_count_desc, random, flip String-ENUM
sorting.ignore_last No If true, does not sort the last answer option (useful for “none of the above”, etc) Boolean
required No Whether an answer is required for this question Object
required.text Yes Text to display if a required question is not answered String
required.type Yes if question is matrix_single, matrix_ranking, and matrix menu Specifies how much of the question must be answered: all , at_least, at_most, exactly, or range String-ENUM
required.amount Yes if type is defined 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). String
validation No Whether the answer must pass certain validation parameters Object
validation.type Yes Type of validation to use: any, integer, decimal, date_us, date_intl, regex, email, or text_length String-ENUM
validation.text Yes Text to display if validation fails String
validation.min Yes Minimum value an answer can be to pass validation Date string, integer, or null depending on validation.type
validation.max Yes Maximum value an answer can be to pass validation Date string, integer, or null depending on validation.type
validation.sum No Only accepted is family=open_ended and subtype=numerical, the exact integer textboxes must sum to in order to pass validation Integer
validation.sum_text No Only accepted is family=open_ended and subtype=numerical, the message to display if textboxes do not sum to validation.sum String
forced_ranking No Required if type is matrix and subtype is rating or single, whether or not to force ranking Boolean
answers Yes for all question types except open_ended_single Answers object, refer to Formatting Question Types Object
display_options Yes for File Upload, Slider, & Emoji/Star Rating question types Display option object, refer to Formatting Question Types Object

Response Resource

Name Description Type
headings Question heading Array
headings[_].heading The title of the question, or empty string if random_assignment is defined String
headings[_].description If random_assignment is defined, and family is presentation_image this is the title String
headings[_].image Image data when question family is presentation_image Object or null
headings[_].image.url URL of image when question family is presentation_image String
headings[_].random_assignment Random assignment data Object or null
headings[_].random_assignment.percent Percent chance of this random assignment showing up (must sum to 100) Integer
headings[_].random_assignment.position Position of the random_assignment in survey creation page Integer
headings[_].random_assignment.variable_name Internal use name for question tracking, can be "" String
headings[_].random_assignment.id Internal use id for question tracking String
position Position of question on page Integer
visible Whether the question is visible (corresponds with being deleted in the UI) Boolean
family Question family, see formatting question types String
subtype Question family’s subtype, see formatting question types String
sorting Sorting details of answers Object
sorting.type Sort answer choices by: default, textasc, textdesc, resp_count_asc, resp_count_desc, random, flip String-ENUM
sorting.ignore_last If true, does not sort the last answer option (useful for “none of the above”, etc) Boolean
required Whether an answer is required for this question Object
required.text String to display if a required question is not answered String
required.type Required type for matrix questions: all , at_least, at_most, exactly, or range String-ENUM
required.amount 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). String
validation Whether the answer must pass certain validation parameters Object
validation.type Type of validation to use: any, integer, decimal, date_us, date_intl, regex, email, or text_length String-ENUM
validation.text Text to display if validation fails String
validation.min Minimum value an answer can be to pass validation Date string, integer, or null depending on validation.type
validation.max Maximum value an answer can be to pass validation Date string, integer, or null depending on validation.type
validation.sum Only accepted is family=open_ended and subtype=numerical, the exact integer textboxes must sum to in order to pass validation Integer
validation.sum_text Only accepted is family=open_ended and subtype=numerical, the message to display if textboxes do not sum to validation.sum String
forced_ranking If type is matrix and subtype is rating or single, whether or not to force ranking Boolean
answers Answers object, refer to Formatting Question Types Object
id Question id String

/surveys/{id}/pages/{id}/questions/{id}

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}/questions/{question_id}

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}/questions/{question_id}

import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/pages/%s/questions/%s" % (survey_id, page_id, question_id)
s.get(url)

####Response

Same as `POST` [/surveys/{id}/pages/questions](#surveys-id-pages-id-questions)

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a question. Requires View Surveys scope
  • PATCH: Updates a question (updates any fields accepted as arguments to POST /surveys/{id}/pages/questions. Public App users need access to the Create/Modify Surveys scope
  • PUT: Replaces a question (same arguments and requirements as POST /surveys/{id}/pages/questions. Public App users need access to the Create/Modify Surveys scope
  • DELETE: Deletes a question. Public App users need access to the Create/Modify Surveys scope

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’ NA 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’ NA 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

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

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.

/survey_folders

Definition

POST https://api.surveymonkey.com/v3/survey_folders

Example Request


curl -i -X POST -H "Authorization: bearer YOUR_ACCESS_TOKEN" -H "content-Type":"application/json" https://api.surveymonkey.com/v3/survey_folders -d "{"title":"My Team Folder"}"


import requests

s = request.session()
s.headers.update({
  "Authorization":"Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type":"application/json"
})

payload = {
  "title":"My Team's Folder"
}
url = "https://api.surveymonkey.com/v3/survey_folders"
s.post(url, json=payload)

Example Response

{
   "title":"My Team Folder",
   "href":"https:\\api.surveymonkey.com/v3/survey_folders/1605642",
   "id":"1605642",
   "num_surveys":0
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • POST: Creates
  • GET: Returns available folders

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page. Integer

Survey Folders List Resource

Name Description Data Type
per_page Integer
total Integer
data[_].href String
data[_].num_surveys Integer
data[_].id String
data[_].title String
page Integer
links[_].self String

Request Body Arguments for POST

Name Required Description Data Type
Title No Title for the folder String

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.

/surveys/{survey_id}/languages

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/languages

Example Request


curl -i -X GET -H "Authorization: bearer YOUR_ACCESS_TOKEN" -H "content-Type":"application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/languages


import requests

s = request.session()
s.headers.update({
  "Authorization":"Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type":"application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/languages" % (survey_id)
s.get(url)

Example Response

{
    "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\u00e7ais"
                "enabled": true,
                "id": "fr"
            }
        ],
    "page": 1,
    "links": {
    "self": "https://api.surveymonkey.com/v3/surveys/1234/languages/?page=1&per_page=50"
    }
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns all existing translations

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page. Integer

Translations List Resource

Name Description Data Type
data[_].stale_string_count Count of strings that have been updated in the source language since the translation was last updated Integer
data[_].translated_string_count Count strings that have translations Integer
data[_].href Resource URL String
data[_].inherited_string_count Count of strings that have empty translations but have a parent translation with an existing translation they can fall back to Integer
data[_].string_count Count of strings in the survey Integer
data[_].name The name of the language in English String
data[_].native_name The name of the language in the language itself String
data[_].enabled If True, translation is available for respondents to select Boolean
data[_].id Language code for the translation String

/surveys/{survey_id}/languages/{language_code}

Definition

POST https://api.surveymonkey.com/v3/surveys/{survey_id}/languages/{language_code}

Example Request


curl -i -X POST -H "Authorization: bearer YOUR_ACCESS_TOKEN" -H "content-Type":"application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/languages/fr -d '{"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"}], "enabled":true}


import requests

s = request.session()
s.headers.update({
  "Authorization":"Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type":"application/json"
})

payload = {

{
   "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":"Ê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"
      }
   ],
   "name":"French",
   "native_name":"fran\u00e7ais",
   "enabled":true,
   "id":"fr"
}


url = "https://api.surveymonkey.com/v3/surveys/%s/languages/fr" % (survey_id)
s.get(url, json=payload)

Example Response for GET. POST and PATCH return an empty body


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


Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns existing translations or the translation structure
  • POST: Creates a translation
  • PATCH: Updates a translation

Request Body Arguments for POST and PATCH

Name Required Description Data Type
enabled No If True, translation is available for respondents to select Boolean
translations 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. Array

Translation Object

Name |Description | Data Type —– ||—— | —– default| The text from the default language for the survey.|String translation|Translated text shown when a respondent chooses the survey in this language. Translate a survey by filling in all empty translations,|String context|Describes the string’s role in the survey|String id|Survey, question or answer option id related to the string|String

Contacts and Contact Lists

If your application is using email 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.

/contact_lists

Definition

POST https://api.surveymonkey.com/v3/contact_lists

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_lists -d '{"name": "My Contact List"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "name": "My Contact List"
}
url = "https://api.surveymonkey.com/v3/contact_lists"
s.post(url, json=payload)

Example Response

{
  "name": "My Contact List",
  "id": "1234",
  "href":"https://api.surveymonkey.com/v3/contact_lists/1234"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns all contact lists. Public App users need access to the View Contacts scope
  • POST: Creates a contact list, contacts can be sent survey invite messages using an email invite collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Contact List Resource

Name Description Data Type
data[_].id Contact list id String
data[_].name Contact list name String
data[_].href Resource API URL String

Request Body Arguments for POST

Name Required Description Data Type
name No (default=“New List”) Contact list name String

/contact_lists/{id}

Definition

GET https://api.surveymonkey.com/v3/contact_lists/{contact_list_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_lists/1234
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/contact_lists/%s" % (contact_list_id)
s.get(url)

Example Response

{
  "name": "My Contact List",
  "id": "1234",
  "href": "https://api.surveymonkey.com/v3/contact_lists/1234"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a contact list. Public App users need access to the View Contacts scope
  • PATCH: Modifies a contact list (updates any fields accepted as arguments to POST /contact_lists). Public App users need access to the Create/Modify Contacts scope
  • PUT: Replaces a contact list POST (same arguments and requirements as POST/contact_lists). Public App users need access to the Create/Modify Contacts scope
  • DELETE: Deletes a contact list. Public App users need access to the Create/Modify Contacts scope

Contact List Resource

Name Description Data Type
id Contact list id String
name Contact list name String

/contact_lists/{id}/copy

Definition

POST https://api.surveymonkey.com/v3/contact_lists/{contact_list_id}/copy

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_lists/1234/copy
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/contact_lists/%s/copy" % (contact_list_id)
s.post(url)

Example Response

{
  "name": "Copy of My Contact List",
  "id": "1234",
  "href":"https://api.surveymonkey.com/v3/contact_lists/1234"
}

Available Methods

  • POST: Creates a copy of an existing contact list. Requires Create/Modify Contacts scope

Contact List Resource

Name Description Data Type
id Contact list id String
name Contact list name String
href Resource API URL String

/contact_lists/{id}/merge

Definition

POST https://api.surveymonkey.com/v3/contact_lists/{contact_list_id}/merge

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_lists/1234/merge -d '{ "list_id": "4321" }'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "list_id": "4321"
}
url = "https://api.surveymonkey.com/v3/contact_lists/%s/merge" % (contact_list_id)
s.post(url)

Example Response

{
  "name": "My Contact List",
  "id": "1234",
  "href":"https://api.surveymonkey.com/v3/contact_lists/1234"
}

Available Methods

  • POST: Copies contacts in the list specified in the request body and adds to the list specified in the resource URL. Public App users need access to the Create/Modify Contacts scope

Request Body Arguments for POST

Name Required Description Data Type
list_id Yes List id to be merged over String

Contact List Resource

Name Description Data Type
id Contact list id String
name Contact list name String
href Resource API URL String

/contact_lists/{id}/contacts

Definition

POST https://api.surveymonkey.com/v3/contact_lists/{contact_list_id}/contacts

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_lists/1234/contacts -d '{ "first_name": "John", "last_name": "Doe", "email": "test@surveymonkey.com"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  }
}
url = "https://api.surveymonkey.com/v3/contact_lists/%s/contacts" % (contact_list_id)
s.post(url, json=payload)

Example Response

{
  "id": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  },
  "href": "https://api.surveymonkey.com/v3/contacts/1234"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns all contacts in a contact list. Public App users need access to the View Contacts scope
  • POST: Creates a new contact and adds them to a contact list, contacts can be sent survey invite messages using an email invite collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
status Filter by status (default=active): active, optout, bounced String-ENUM
sort_by Field used to sort returned contact list (default=email): email, first_name, last_name, 1, …, 6 String-ENUM
sort_order Sort order e.g. [‘ASC’, 'DESC’] String-ENUM
search_by Field used to search returned contact list: : email, first_name, last_name, 1, …, 6 String-ENUM
search Query used to search String

Contacts List Resource

Name Description Data Type
data[_].id Contact id String
data[_].first_name Contact first name String
data[_].last_name Contact last name String
data[_].email Contact email address String
data[_].href Resource API URL String

Request Body Arguments for POST

Name Required Description Data Type
first_name Yes Contact first name String
last_name Yes Contact last name String
email Yes Contact email address String
custom_fields No Contact custom fields Object

/contact_lists/{id}/contacts/bulk

Definition

POST https://api.surveymonkey.com/v3/contact_lists/{contact_list_id}/contacts/bulk

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_lists/1234/contacts/bulk -d '{ "contacts": [{ "first_name": "John", "last_name": "Doe", "email": "test@surveymonkey.com"}] }'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "contacts": [{
    "first_name": "John",
    "last_name": "Doe",
    "email": "test@surveymonkey.com",
    "custom_fields": {
      "1": "Mr",
      "2": "Company",
      "3": "Address",
      "4": "City",
      "5": "Country",
      "6": "Phone Number"
    }
  }]
}
url = "https://api.surveymonkey.com/v3/contact_lists/%s/contacts/bulk" % (contact_list_id)
s.post(url, json=payload)

Example Response

{
  "succeeded": [{
    "first_name": "John",
    "last_name": "Doe",
    "id": "1234",
    "email": "test@surveymonkey.com",
    "custom_fields": {
      "1": "Mr",
      "2": "Company",
      "3": "Address",
      "4": "City",
      "5": "Country",
      "6": "Phone Number"
    }
  }],
  "invalids": [{
  }],
  "existing": [{
  }]
}

Available Methods

  • GET: Returns a list of all contacts in the list with all available fields. Public App users need access to the View Contacts scope
  • POST: Creates multiple contacts and adds them to a list, contacts can be sent survey invite messages using an email invite collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope

Contacts List Resource

Name Description Data Type
data[_].id Contact id String
data[_].first_name Contact first name String
data[_].last_name Contact last name String
data[_].email Contact email address String
data[_].custom_fields Contact custom fields Object
data[_].href Resource API URL String

Request Body Arguments for POST

Name Required Description Data Type
data[_].first_name Yes Contact first name String
data[_].last_name Yes Contact last name String
data[_].email Yes Contact email String
data[_].custom_fields No Custom contact fields Object

/contacts

Definition

POST https://api.surveymonkey.com/v3/contacts

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contacts -d '{ "first_name": "John", "last_name": "Doe", "email": "test@surveymonkey.com" }'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  }
}
url = "https://api.surveymonkey.com/v3/contacts"
s.post(url, json=payload)

Example Response

{
  "id": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  },
  "href": "https://api.surveymonkey.com/v3/contacts/1234"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of all contacts. Public App users need access to the View Contacts scope
  • POST: Creates a new contact, contacts can be sent survey invite messages using an email invite collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope

Optional Query Strings for GET

Name Description Data Type
page Page number. Defaults to 1 Integer
per_page Number of contacts to return per page Integer
status Filter by status (default=active): ’active, optout, or bounced String-ENUM
sort_by Field used to sort returned contact list (default=email): email, first_name, last_name, 1, …, 6 String-ENUM
sort_order Sort order: ASC or DESC String-ENUM
search_by Field used to search returned contact list: email, first_name, last_name, 1, …, 6 String-ENUM
search Query used to search String

Contacts List Resource

Name Description Data Type
data[_].id Contact id String
data[_].first_name Contact first name String
data[_].last_name Contact last name String
data[_].email Contact email address String
data[_].href Resource API URL String

Request Body Arguments for POST

Name Required Description Data Type
first_name Yes Contact first name String
last_name Yes Contact last name String
email Yes Contact email address String
custom_fields No Contact custom field Object

/contacts/bulk

Definition

POST https://api.surveymonkey.com/v3/contacts/bulk

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contacts -d '{ "contacts": [{ "first_name": "John", "last_name": "Doe", "email": "test@surveymonkey.com" }'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "contacts": [{
    "first_name": "John",
    "last_name": "Doe",
    "email": "test@surveymonkey.com",
    "custom_fields": {
      "1": "Mr",
      "2": "Company",
      "3": "Address",
      "4": "City",
      "5": "Country",
      "6": "Phone Number"
    }
  }]
}
url = "https://api.surveymonkey.com/v3/contacts/bulk"
s.post(url, json=payload)

Example Response

{
  "succeeded": [{
    "first_name": "John",
    "last_name": "Doe",
    "id": "1234",
    "email": "test@surveymonkey.com",
    "custom_fields": {
      "1": "Mr",
      "2": "Company",
      "3": "Address",
      "4": "City",
      "5": "Country",
      "6": "Phone Number"
    }
  }],
  "invalids": [{
  }],
  "existing": [{
  }]
}

Available Methods

  • GET: Returns a list of all contacts with all available fields. Public App users need access to the View Contacts scope
  • POST: Creates multiple contacts, contacts can be sent survey invite messages using an email invite collector, see Collectors and Invite Messages. Public App users need access to the Create/Modify Contacts scope

Contacts List Resource

Name Description Data Type
data[_].id Contact id String
data[_].first_name Contact first name String
data[_].last_name Contact last name String
data[_].email Contact email address String
data[_].custom_fields Contact custom fields Object
data[_].href Resource API URL String

Request Body Arguments for POST

Name Required Description Data Type
data[_].first_name Yes Contact first name String
data[_].last_name Yes Contact last name String
data[_].email Yes Contact email String
data[_].custom_fields No Custom contact fields Object

/contacts/{id}

Definition

GET https://api.surveymonkey.com/v3/contacts/{contact_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contacts/1234
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/contacts/%s" % (contact_id)
s.get(url)

Example Response

{
  "id": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@surveymonkey.com",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  }
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a contact. Public App users need access to the View Contacts scope
  • PATCH: Modifies a contact (updates any fields accepted as arguments to POST /contacts. Public App users need access to the Create/Modify Contacts scope
  • PUT: Replaces a contact (same arguments and requirements as POST/contacts). Public App users need access to the Create/Modify Contacts scope
  • DELETE: Deletes a contact. Public App users need access to the Create/Modify Contacts scope

Contact Resource

Name Description Data Type
id Contact id String
first_name Contact first name String
last_name Contact last name String
email Contact email address String
custom_fields Contact custom fields Object

/contact_fields

Definition

GET https://api.surveymonkey.com/v3/contact_fields

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_fields
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/contact_fields"
s.get(url)

Example Response

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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of all custom contacts fields. Public App users need access to the View Contacts scope

Optional Query Strings for GET

Name Description Data Type
page Page number. Defaults to 1 Integer
per_page Number of contacts to return per page Integer

Contacts List Resource

Name Description Data Type
data[_].id Contact id String
data[_].label Contact Field Label String
data[_].href Resource API URL String

/contact_fields/{id}

Definition

PATCH https://api.surveymonkey.com/v3/contact_fields/{contact_field_id}

Example Request

curl -i -X PATCH -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/contact_fields/1 -d '{"label: "5"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "label" = "address"
}
url = "https://api.surveymonkey.com/v3/contact_fields/1"
s.patch(url)

Example Response

{
  "href": "https://api.surveymonkey.com/v3/contact_fields/1",
  "id": "1",
  "label": "address"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns the specified custom contact field. Public App users need access to the View Contacts scope
  • PATCH: Modifies a custom contact field’s label. Public App users need access to the Create/Modify Contacts scope

Request Body Arguments for PATCH

Name Required Description Data Type
label Yes Label assigned to the custom contact field String

Contact Field Resource

Name Description Data Type
id Contact field id String
label Contact field Label String

Collectors and Invite Messages

Collectors allow you to collect survey responses with a link to your survey. Two types of collectors are available through the API: weblink and email. Weblink collectors collectors give you a survey URL and email invitation collectors send survey invite messages with a survey URL via the /messages endpoints. 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.

/surveys/{id}/collectors

Definition

POST https://api.surveymonkey.com/v3/surveys/{survey_id}/collectors

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/1234/collectors -d '{"type":"weblink"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
 "type": "weblink"
}
url = "https://api.surveymonkey.com/v3/surveys/%s/collectors" % (survey_id)
s.post(url, json=payload)

Example Response

{
  "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.",
  "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"
}
  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of collectors for a given survey. Public App users need access to the View Collectors scope
  • POST: Creates a weblink or email collector for a given survey. Public App users need access to the Create/Modify Collectors scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
sort_by Field used to sort returned collector list e.g. [‘id’, 'date_modified’, 'type’, 'status’, 'name’] String-ENUM
sort_order Sort order e.g. ['ASC’, 'DESC’] String-ENUM
name Nickname of collector to search against String
start_date Collectors must be created after this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
end_date Collectors must be created before this date. Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
include Specify additional fields to return per collector: 'type’, 'status’, 'response_count’, 'date_created’, 'date_modified’, 'url’ Comma separated string-ENUMs

Collector List Resource

Name Description Data Type
data[_].id Collector id String
data[_].name Collector name String
data[_].href Resource URL String

Request Body Arguments for POST (if copying from existing collector)

Name Required Description Data Type
from_collector_id Yes Collector ID to copy collector from String

Request Body Arguments for POST

Name Required Description Data Type
type Yes Collector type: 'weblink’ or 'email’ String-ENUM
name No Collector name String
thank_you_message No (default=“Thank you for completing our survey!”“) Message for thank you page String
disqualification_message No (default="Thank you for completing our survey!) Message for disqualification page String
close_date No Close date of collector Date string
closed_page_message No (default="Thank you for completing our survey!”) Message shown when a survey is closed String
redirect_url No Redirect to this url upon survey completion String
display_survey_results No (default=False) Shows respondents survey instant results when they complete the survey Boolean
edit_response_type No (default='until_complete’) When respondents can edit their response: 'until_complete’, 'never’, or 'always’ String-ENUM
anonymous_type No (default='not_anonymous’) Turns off IP tracking. For email collectors, also removes respondent email address and name from response: 'not_anonymous’, 'partially_anonymous’, 'fully_anonymous’ String-ENUM
allow_multiple_responses No (default=False) Allows respondents to take a survey more than once from the same browser on the same computer. Not available for email collectors Boolean
password No Set a password to restrict access to your survey String
sender_email No Sender email for email collectors String
response_limit No Sets the collector to close after specified number of responses are collected Integer
redirect_type No 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) String-ENUM

/collectors/{id}

Definition

GET https://api.surveymonkey.com/v3/collectors/{collector_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/collectors/%s" % (collector_id)
s.get(url)

Example Response

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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a collector
  • PATCH: Modifies a collector (updates any fields accepted as arguments to POST /surveys/{survey_id}/collectors, with the addition of status and the removal of type). Public App users need access to the Create/Modify Collectors scope
  • PUT: Replaces a collector (same arguments and requirements as POST/surveys/{survey_id}/collectors, with the addition of status and the removal of type). Public App users need access to the Create/Modify Collectors scope
  • DELETE: Deletes a collector. Public App users need access to the Create/Modify Collectors scope

Collector Resource

Name Description Type
status Collector status: 'open’ or 'closed’ String-ENUM
id Collector id String
type Collector type: 'weblink’ or 'email’ String-ENUM
name Name of the collector String
thank_you_message Message for thank you page String
disqualification_message Message for disqualification page String
close_date Close date of collector Date string
closed_page_message Message shown when someone visits a closed survey String
redirect_url Redirects respondent to this url upon survey completion String
display_survey_results Shows respondents survey instant results when they complete the survey Boolean
edit_response_type When respondents can edit their response: 'until_complete’, 'never’, or 'always’ String-ENUM
anonymous_type Turns off IP tracking. For email collectors, also removes respondent email address and name from response: 'not_anonymous’, 'partially_anonymous’, 'fully_anonymous’ String-ENUM
allow_multiple_responses Allows respondents to take a survey more than once from the same browser on the same computer. Only available for weblink collectors. Boolean
date_modified Date collector was last modified Date string
url If collector is a Web Collector (type 'weblink’) then the url for the collector String
date_created Date collector was created Date string
password_enabled True if the collector is password protected Boolean
sender_email Sender email for email collectors. User’s email is used if null String
redirect_type 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) String-ENUM
href Resource API URL String

/collectors/{id}/messages

Definition

POST https://api.surveymonkey.com/v3/collectors/{collector_id}/messages

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/messages -d '{"type":"invite"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "type": "invite"
}
url = "https://api.surveymonkey.com/v3/collectors/%s/messages" % (collector_id)
s.post(url)

Example Response

{
   "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\">\u00a0<\/td> <\/tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td width=\"20\">\u00a0<\/td>\n                <td width=\"20\">\u00a0<\/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\">\u00a0<\/td>\n                <td width=\"20\">\u00a0<\/td> <\/tr>\n            <tr bgcolor=\"#A7BC38\">\n                <td colspan=\"5\" height=\"40\">\u00a0<\/td> <\/tr>\n            <tr>\n                <td height=\"10\" colspan=\"5\">\u00a0<\/td> <\/tr>\n            <tr>\n                <td>\u00a0<\/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>\u00a0<\/td> <\/tr> \n            <tr>\n                <td colspan=\"5\" height=\"30\">\u00a0<\/td> <\/tr>\n            <tr>\n                <td>\u00a0<\/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>\u00a0<\/td> <\/tr>\n            <tr>\n                <td colspan=\"5\" height=\"30\">\u00a0<\/td> <\/tr> \n            <tr valign=\"top\" style=\"color: #666666;font-size: 10px;\">\n                <td>\u00a0<\/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=\"[OptOutLink]\" target=\"_blank\" style=\"color: #333333; text-decoration: underline;\">Unsubscribe<\/a> from this list<\/p> <\/td>\n                <td>\u00a0<\/td> <\/tr>\n            <tr>\n                <td height=\"20\" colspan=\"5\">\u00a0<\/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\">\u00a0<\/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"
}

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Request Body Arguments for POST (if copying from existing message)

Name Required Description Data Type
from_collector_id Yes Collector ID to copy message from String
from_message_id Yes Message ID to copy from String
include_recipients No Include recipients attached to existing message Boolean

Request Body Arguments for POST (if not copying from existing message)

Name Required Description Data Type
type Yes Message type: 'invite’, 'reminder’, or 'thank_you’ String-ENUM
recipient_status 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’ Set of recipients to send to String-ENUM
subject No (default=“We want your opinion”) Subject of the email message to be sent to recipients String
body_text No The plain text body of the email message to be sent to recipients. Message must include [SurveyLink], [OptOutLink], and [FooterLink] and the opt out link must be clearly labeled. String
body_html No The html body of the email message to be sent to recipients. This overrides body_text. Message must include [SurveyLink], [OptOutLink], and [FooterLink] and the opt out link must be clearly labeled. String
is_branding_enabled No (default=True) Whether the email has SurveyMonkey branding Boolean

/collectors/{id}/messages/{id}

Definition

GET https://api.surveymonkey.com/v3/collectors/{collector_id}/messages/{message_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/messages/1234
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/collectors/%s/messages/%s" % (collector_id, message_id)
s.get(url)

Example Response

{
    "status": "not_sent",
    "is_scheduled": true,
    "subject": "Email subject",
    "body": "Email body",
    "is_branding_enabled": true,
    "date_created": "2015-10-06T12:56:55+00:00",
    "scheduled_date": "2015-10-07T12:56:55+00:00",
    "type": "invite",
    "recipient_status": null,
    "id": "1234",
    "href": "https://api.surveymonkey.com/v3/collectors/1234/messages/1234"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a message. Public App users need access to the View Collectors scope
  • PATCH: Modifies a message (only subject, body_text, body_html, is_branding, and recipient_status if 'reminder’ or 'thank_you’, can be modified). Public App users need access to the Create/Modify Collectors scope
  • PUT: Replaces a message (only subject, body_text, body_html, is_branding, and recipient_status if 'reminder’ or 'thank_you’, can be modified). Public App users need access to the Create/Modify Collectors scope
  • DELETE: Deletes a message. Public App users need access to the Create/Modify Collectors scope

Messages Resource

Name Description Data Type
status Whether the message is: 'sent’, 'not_sent’, or 'processing’ String-ENUM
is_scheduled If a message has been secheduled to send. See /collectors/{id}/messages/{id}/send Boolean
is_branding_enabled Whether the email has SurveyMonkey branding Boolean
date_created Date message was created Date string
scheduled_date Date message is scheduled to be sent. If Null, message has not been scheduled to send. Date string or Null
type Message type: 'invite’, 'reminder’, or 'thank_you’ String-ENUM
recipient_status Recipient filter: 'reminder’ or 'thank_you’ String-ENUM
id Message id String

/collectors/{id}/messages/{id}/send

Definition

POST https://api.surveymonkey.com/v3/collectors/{collector_id}/messages/{message_id}/send

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/messages/1234/send -d '{"scheduled_date":"2015-10-06T12:56:55+00:00"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "scheduled_date": "2015-10-06T12:56:55+00:00"
}
url = "https://api.surveymonkey.com/v3/collectors/%s/messages/%s/send" % (collector_id, message_id)
s.post(url, json=payload)

Example Request

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

Example Response

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

Available Methods

Request Body Arguments for POST

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

Message Resource

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

/collectors/{id}/messages/{id}/recipients

Definition

POST https://api.surveymonkey.com/v3/collectors/{collector_id}/messages/{message_id}/recipients

Example Request (with contact_id)

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients -d '{"contact_id:"1234"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "contact_id": 1234
}
url = "https://api.surveymonkey.com/v3/collectors/%s/messages/%s/recipients" % (collector_id, message_id)
s.post(url, json=payload)

Example Request (without contact_id)

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients-d '{"email":"test@surveymonkey.com"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "email": "test@surveymonkey.com",
  "first_name": "John",
  "last_name": "Doe",
  "custom_fields": {
    "1": "Mr",
    "2": "Company",
    "3": "Address",
    "4": "City",
    "5": "Country",
    "6": "Phone Number"
  },
  "extra_fields": {
      "favorite_color": "Red",
      "second_favorite_color": "Black",
      "third_favorite_color": "Green"
  }
}
url = "https://api.surveymonkey.com/v3/collectors/%s/messages/%s/recipients" % (collector_id, message_id)
s.post(url, json=payload)

Example Response

{
    "survey_response_status": "not_responded",
    "mail_status": "not_sent",
    "email": "test@surveymonkey.com",
    "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"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of recipients. Public App users need access to the View Collectors scope
  • POST: Creates a new recipient for the specified message. See /collectors/{id}/messages/{id}/send for sending. This method only available to messages of type invite if they have not already been sent. Public App users need access to the Create/Modify Collectors scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
include Specify additional fields to return per recipient: survey_response_status, mail_status, custom_fields, remove_link, extra_fields, survey_link Comma seperated string-ENUM

Recipient List Resource

Name Description Data Type
data[_].id Recipient id String
data[_].email Email of recipient added to collector String
data[_].href Resource API URL String
data[_].survey_response_status If the recipient has completed the survey: 'not_responded’, 'partially_responded’, 'completely_responded’. Only returned if requested String-ENUM
data[_].mail_status If an invite message to the recipient has been: 'sent’, 'not_sent’, or is 'processing’. Only returned if requested String-ENUM
data[_].custom_fields Custom fields included for the recipient contact. Only returned if requested Object
data[_].remove_link Unsubscribe link. Only returned if requested String
data[_].extra_fields Extra fields included for the message body. Only returned if requested Object
data[_].survey_link Link to the survey in the invite. Only returned if requested String

Requests Body Arguments for POST (if passing contact_id)

Name Required Description Data Type
contact_id Yes Contact id String

Requests Body Arguments for POST (if not passing contact_id)

Name Required Description Data Type
email Yes Email of the recipient String
first_name No First name of the recipient String
last_name No Last name the recipient String
custom_fields No Custom fields for the recipient contact Object
extra_fields No Extra fields needed for the message body Object

/collectors/{id}/messages/{id}/recipients/bulk

Definition

POST https://api.surveymonkey.com/v3/collectors/{collector_id}/messages/{message_id}/recipients/bulk

Example Request

curl -i -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/messages/1234/recipients/bulk -d '{"contact_ids":["1234", "5678"]}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "contact_ids": ["1234", "5678"],
  "contact_list_ids": ["1234567", "4567890"],
  "contacts" :[{
      "email":"test@surveymonkey.com",
      "first_name": "John",
      "last_name": "Doe",
      "custom_fields": {
        "1": "Mr",
        "2": "Company",
        "3": "Address",
        "4": "City",
        "5": "Country",
        "6": "Phone Number"
      },
      "extra_fields": {
        "favorite_color": "Red",
        "second_favorite_color": "Black"
      }
  }]
}
url = "https://api.surveymonkey.com/v3/collectors/%s/messages/%s/recipients" % (collector_id, message_id)
s.post(url, json=payload)

Example Response

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

Available Methods

  • POST: Creates multiple recipients. Public App users need access to the Create/Modify Collectors scope

Request Body Arguments for POST

Name Required Description Type
contact_ids No Contact ids Array
contact_list_ids No Contact list ids Array
contacts[_].email No Contact’s email address String
contacts[_].first_name No Contact’s first name String
contacts[_].last_name No Contact’s last name String
contacts[_].custom_fields No Custom fields for contact Object
contacts[_].extra_fields No Extra fields needed for the message body Object

Bulk Response

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

/collectors/{id}/recipients

Definition

GET https://api.surveymonkey.com/v3/collectors/{collector_id}/recipients

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/recipients
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/collectors/%s/recipients" % (collector_id)
s.get(url)

Example Response

{
  "per_page": 1,
  "total": 1,
  "data": [{
    "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"
  }
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of recipients. Public App users need access to the View Collectors scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
include Specify additional fields to return per recipient: survey_response_status, mail_status, custom_fields, remove_link, extra_fields, survey_link Comma seperated string-ENUM

Recipient List Resource

Name Description Data Type
data[_].id Recipient id String
data[_].email Email of recipient added to collector String
data[_].href Resource API URL String
data[_].survey_response_status If the recipient has completed the survey: 'not_responded’, 'partially_responded’, 'completely_responded’. Only returned if requested String-ENUM
data[_].mail_status If an invite message to the recipient has been: 'sent’, 'not_sent’, or is 'processing’. Only returned if requested String-ENUM
data[_].custom_fields Custom fields included for the recipient contact. Only returned if requested Object
data[_].remove_link Unsubscribe link. Only returned if requested String
data[_].extra_fields Extra fields included for the message body. Only returned if requested Object
data[_].survey_link Link to the survey in the invite. Only returned if requested String

/collectors/{id}/recipients/{id}

Definition

GET https://api.surveymonkey.com/v3/collectors/{collector_id}/recipients/{recipient_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/recipients/1234
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/collectors/%s/recipients/%s" % (collector_id, message_id, recipient_id)
s.get(url)

Example Response

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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a recipient. Public App users need access to the View Collectors scope
  • DELETE: Deletes a recipient. Public App users need access to the Create/Modify Collectors scope

Recipient Resource

Name Description Data Type
survey_response_status If the recipient has completed the survey: not_responded, partially_responded, completely_responded String-ENUM
mail_status If an invite message to the recipient has been: sent, not_sent, or is processing String-ENUM
custom_fields Contact details for recipient Object
id Recipient’s id String
remove_link Unsubscribe link String
extra_fields Extra fields Object
survey_link Link to the survey String

/collectors/{id}/stats

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

/collectors/{id}/messages/{id}/stats

Definition

GET https://api.surveymonkey.com/v3/collectors/{id}/messages/{id}/stats

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/collectors/1234/messages/1234/stats
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/collectors/%s/messages/%s/stats" % (collector_id, message_id)
s.get(url)

Example Response


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

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a stats for a collector’s message

Stats Resource

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

Survey Responses

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

/surveys/{id}/responses

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/responses

Example Request

curl -i -X POST -H "Content-Type: application/json" -H "Authorization:bearer YOUR_ACCESS_TOKEN" https://api.surveymonkey.com/v3/surveys/{survey_id}/responses

import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/responses/" % (survey_id)
s.get(url)

Example Response


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


Available Methods

  • GET: Returns a list of responses. Public App users need access to the View Responses scope

/collectors/{id}/responses

Definition

POST https://api.surveymonkey.com/v3/collectors/{collector_id}/responses

Example Request

curl -i -X POST -H "Content-Type: application/json" -H "Authorization:bearer YOUR_ACCESS_TOKEN" https://api.surveymonkey.com/v3/surveys/{survey_id}/responses -d '{"custom_variables":{"custvar_1": "one", "custvar_2": "two"},"response_status": "overquota","custom_value": "custom identifier for the response","date_created": "2015-10-06T12:56:55+00:00","ip_address": "127.0.0.1","recipient_id": "564728340", "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"}]}]}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "custom_variables": {
    "custvar_1": "one",
    "custvar_2": "two"
  },
  "response_status": "completed",
  "custom_value": "custom identifier for the response",
  "date_created": "2015-10-06T12:56:55+00:00",
  "ip_address": "127.0.0.1",
  "recipient_id": "564728340",
{
  "pages": [{
    "id": "12345678",
    "questions": [
    {  ##Single/Multiple Choice
        "answers": [{
            "choice_id": "12345678"
        }],
        "id": "12345678"
    },
    {  ##Matrix Single/Rating/Ranking, Emoji
        "answers": [{
            "row_id": "12345678",
            "choice_id": "12345678"
        }],
        "id": "12345678"
    },
    { ##Matrix Menu
        "answers": [{
            "row_id": "12345678",
            "col_id": "12345678",
            "choice_id": "12345678"
        }],
        "id": "12345678"
    },
    { ##Open Ended Single/Essay, Slider
        "answers": [{
            "text": "Sample Text Response"
        }],
        "id": "12345678"
    },
    { ##Open Ended Multi/Numerical, Demographic, Datetime
        "answers": [{
            "row_id": "12345678",
            "text": "Sample Text Response" ##(format depends on question type, "12/31/2015 11:59 PM" for datetime)
        }],
        "id": "12345678"
    }]
  }]
}
url = "https://api.surveymonkey.com/v3/surveys/%s/responses" % (survey_id)
s.post(url, json=payload)

Example Response to POST request

{
  "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" ##(format depends on question type, "12/31/2015 11:59 PM" for datetime)
        }],
        "id": "12345678"
    }]
  }],
  "collector_id": "50253690",
  "date_created": "2015-12-28T21:57:14+00:00",
  "survey_id": "105724755",
  "collection_mode": "default"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of responses. Public App users need access to the View Responses scope
  • POST: Creates a response. Public App users need access to the Create/Modify Responses scope

Optional Query Strings for GET

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

Response list resources returned from a GET

Name Description Data Type
data[_].id Response id String
data[_].href URL for the response resource String

Request Body Arguments for POST

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

/surveys/{id}/responses/bulk

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

/collectors/{id}/responses/bulk

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/responses/bulk
GET https://api.surveymonkey.com/v3/collectors/{collector_id}/responses/bulk

Example Request


curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/responses/bulk
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/responses/bulk" % (survey_id)
s.get(url, params=payload)

Example Response

{
  "per_page": 2,
  "total": 1,
  "data": [{
    "total_time": 0,
    "collection_mode": "default",
    "href": "https://api.surveymonkey.com/v3/responses/5007154325",
    "custom_variables": {
      "custvar_1": "one",
      "custvar_2": "two"
    },
    "custom_value": "custom identifier for the response",
    "edit_url": "https://www.surveymonkey.com/r/",
    "analyze_url": "https://www.surveymonkey.com/analyze/browse/",
    "ip_address": "",
    "pages": [{
      "id": "103332310",
      "questions": [{
          "answers": [{
              "choice_id": "3057839051"
          }],
          "id": "319352786"
      }]
    }],
    "date_modified": "1970-01-17T19:07:34+00:00",
    "response_status": "completed",
    "id": "5007154325",
    "collector_id": "50253586",
    "recipient_id": "0",
    "date_created": "1970-01-17T19:07:34+00:00",
    "survey_id": "105723396"
  }],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/surveys/123456/responses/bulk?page=1&per_page=2"
  }
}

Available Methods

  • GET: Retrieves a list of full expanded responses, including answers to all questions. Public App users need access to the View Response Details scope

Optional Query Strings for GET

Name Description Data Type
page Page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page. Max of 100 allowed per page. Integer
collector_ids Only include responses for this list of collector IDs Comma Separated Strings
start_created_at Responses started after this date DateString
end_created_at Responses started before this date DateString
start_modified_at Responses modified after this date DateString
end_modified_at Responses modified before this date DateString
status Status of the response: completed, partial, overquota, disqualified String-ENUM
email Email of the recipient String
first_name First Name of the recipient String
last_name Last Name of the recipient String
ip The IP the response was taken from String
custom The custom value associated with the response String
total_time_max The maximum amount of time spent on the response Integer
total_time_min The minimum amount of time spent on the response Integer
total_time_units Unit of time for total_time_min and total_time_max: second, minute, or hour String-ENUM
sort_order Sort order: ASC or DESC String-ENUM
sort_by Field used to sort returned responses: date_modified String-ENUM
page_ids List of survey pages to filter on. Returns all pages if not provided Commas Seperated Strings
question_ids List of survey questions to filter on. Returns all questions if not provided Commas Seperated Strings

Responses List Resource

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

/surveys/{id}/responses/{id}

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

/collectors/{id}/responses/{id}

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/responses/{response_id}
GET https://api.surveymonkey.com/v3/collectors/{collector_id}/responses/{response_id}

Example Request


curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/responses/{response_id}
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/responses/%s" % (survey_id, response_id)
s.get(url)

Example Response

{
  "total_time": 144,
  "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"
  },
  "custom_value": "custom identifier for the response",
  "edit_url": "https://www.surveymonkey.com/r/",
  "analyze_url": "https://www.surveymonkey.com/analyze/browse/",
  "page_path": [],
  "collector_id": "50253690",
  "date_created": "2015-12-28T21:57:14+00:00",
  "survey_id": "105724755",
  "collection_mode": "default"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a response. Public App users need access to the View Responses scope
  • PATCH: Modifies a response (updates any fields accepted as arguments to POST /surveys/{id}/responses). Public App users need access to the Create/Modify Responses scope
  • PUT: Replaces a response (same arguments and requirements as POST /surveys/{id}/responses). Public App users need access to the Create/Modify Responses scope
  • DELETE: Deletes a response. Public App users need access to the Create/Modify Responses scope

Response Resource

Name Description Type
survey_id ID of the survey the response was taken for String
collector_id ID of the collector the response was taken for String
recipient_id ID of the recipient (only for email collectors). See collector recipient String
total_time Total time in seconds spent on the survey Integer
custom_value Custom value associated with a response String
edit_url Weblink to the survey taking page to edit the response String
analyze_url Weblink to the analyze page to view the response String
ip_address IP Address the response was taken from String
custom_variables Values to any available custom variables in the survey Object
logic_path Logic path taken during the survey Object
metadata Other associated metadata or custom values Object
response_status Status of the response: completed, partial, overquota, or disqualified String-ENUM
page_path The order in which the pages were responded to. Array
collection_mode The collection mode of the response: default, preview, data_entry, survey_preview, or edit String-ENUM
date_created Date the response was created DateString
date_modified Date the response was last modified DateString

/surveys/{id}/responses/{id}/details

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

/collectors/{id}/responses/{id}/details

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/responses/{response_id}/details
GET https://api.surveymonkey.com/v3/collectors/{collector_id}/responses/{response_id}/details

Example Request


curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/responses/{response_id}/details
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/responses/%s/details" % (survey_id, response_id)
s.get(url)

Example Response

{
  "total_time": 144,
  "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"
  },
  "custom_value": "custom identifier for the response",
  "edit_url": "https://www.surveymonkey.com/r/",
  "analyze_url": "https://www.surveymonkey.com/analyze/browse/",
  "page_path": [],
  "pages": [{
    "id": "103332310",
    "questions": [{
        "answers": [{
            "choice_id": "3057839051"
        }],
        "id": "319352786"
    }]
  }],
  "collector_id": "50253690",
  "date_created": "2015-12-28T21:57:14+00:00",
  "survey_id": "105724755",
  "collection_mode": "default"
}

Available Methods

  • GET: Retrieve a full expanded response, including answers to all questions. Public App users need access to the View Response Details scope

Optional Query Strings for GET

Name Description Data Type
page_ids List of survey pages to filter on. Returns all pages if not provided Commas Seperated Strings
question_ids List of survey questions to filter on. Returns all questions if not provided Commas Seperated Strings

Response Resource

Name Description Type
survey_id ID of the survey the response was taken for String
collector_id ID of the collector the response was taken for String
recipient_id ID of the recipient (only for email collectors). See collector recipient String
total_time Total time in seconds spent on the survey Integer
custom_value Custom value associated with a response String
edit_url Weblink to the survey taking page to edit the response String
analyze_url Weblink to the analyze page to view the response String
ip_address IP Address the response was taken from String
custom_variables Values to any available custom variables in the survey Object
logic_path Logic path taken during the survey Object
metadata Other associated metadata or custom values Object
response_status Status of the response: completed, partial, overquota, or disqualified String-ENUM
current_page_id ID of the page the respondent is currently on, “0” if completed String
page_path The order in which the pages were responded to. Array
collection_mode The collection mode of the response: default, preview", data_entry, survey_preview, or edit String-ENUM
date_created Date the response was created DateString
date_modified Date the response was last modified DateString
pages Pages from the survey and their associated responses Array
pages[_].id The ID of the page with responses String
pages[_].questions The questions on that page with responses Array
pages[_].questions[_].id ID of the question with responses String
pages[_].questions[_].variable_id ID of the random assignment variable for the question String
pages[_].questions[_].answers The answers for the question with responses List
pages[_].questions[_].answers[_].choice_id The choice selected String
pages[_].questions[_].answers[_].row_id The row selected String
pages[_].questions[_].answers[_].col_id The column selected String
pages[_].questions[_].answers[_].other_id The other text choice selected String
pages[_].questions[_].answers[_].text Any open ended text String

The following endpoints let you view how many respondents answered a question a particular way and trends in how many respondents answered a question a particular way in a given time period, for example a week.

/surveys/{id}/rollups

Definition

GET https://api.surveymonkey.com/v3/surveys/{id}/rollups

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/1234/rollups
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/rollups" % (survey_id)
s.get(url)

Example Response


{
   "per_page":50,
   "total":2,
   "data":[
      {
         "subtype":"essay",
         "href":"https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions/1234/rollups",
         "id":"1234",
         "family":"essay",
         "summary":[
            {
               "answered":3,
               "skipped":1,
               "other_answered":0,
               "text":0
            }
         ]
      },
      {
         "subtype":"vertical",
         "href":"https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions/1234/rollups",
         "id":"1234",
         "family":"single_choice",
         "summary":[
            {
               "answered":0,
               "skipped":0,
               "stats":{
                  "std":0,
                  "max":0,
                  "min":0,
                  "median":0,
                  "mean":0
               },
               "other_answered":0,
               "choices":[
                  {
                     "count":0,
                     "id":"1234"
                  }
               ]
            }
         ]
      }
   ],
   "page":1,
   "links":{
      "self":"https:\/\/api.surveymonkey.com/v3/surveys/1234/rollups?page=1&per_page=50"
   }
}



Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns rollups for all questions in a survey. Public App users need access to the View Response Details scope

Optional Query Strings for GET

Name Description Data Type
collector_ids Limits responses to those from specified collector ids Comma separated strings
start_created_at Limits responses to those created after date specified Date string
end_created_at Limits responses to those created before date specified Date string
start_modified_at Limits responses to those last modified after date specified Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
end_modified_at Limits responses to those last modified before date specified Date string in format YYYY-MM-DDTHH:MM:SS (no offset)
status Limits responses to those of a certain status. Accepts: completed, partial, overquota, disqualified Comma separated string-ENUM
email Limits responses to those associated with specified email address. NOTE: Responses must come from an email collector. String
first_name Limits responses to those associated with specified first name. NOTE: Responses must come from an email collector. String
last_name Limits responses to those associated with specified last name. NOTE: Responses must come from an email collector. String
ip Limits responses to those associated with specified IP address String
custom Limits responses to those associated with specified value for custom field 1. NOTE: Responses must come from an email collector. String
total_time_max Limits responses to those that took respondents less time to complete than specified time String
total_time_min Limits responses to those that took respondents more time to complete than specified time String
total_time_units Determines which unit of time total_time_max and total_time_min use. Accepts: second, minute, hour String-ENUM

Rollups Resource

Name Description Type
data[_].subtype Question subtype. See question types String-ENUM
data[_].href Resource URL for a question’s rollup String
data[_].id Question identifier String
data[_].family Question family. See question types String-ENUM
data[_].summary.answered Returns the count of respondents who answered the question Integer
data[_].summary.skipped Returns the count of respondents who skipped the question Integer
data[_].summary.stats Returns basic statistics for close ended questions Object
data[_].summary.other_answered Returns the count of responses who answered the other choice, if available Integer
data[_].summary.choices Returns question’s choices with the id and count for each choice Object

/surveys/{id}/pages/{id}/rollups

Same as /surveys/{id}/rollups but returns rollups for only the survey page specified.

/surveys/{id}/pages/{id}/questions/{id}/rollups

Same as /surveys/{id}/rollups but returns rollups for only the survey question specified.

Definition

GET https://api.surveymonkey.com/v3/surveys/{id}/trends

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/1234/trends
import requests

s = requests.Session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/%s/trends" % (survey_id)
s.get(url)

Example Response


{
  "per_page": 50,
  "total": 1,
  "data": [
    {
      "subtype": "rating",
      "skipped": 0,
      "href": "https://api.surveymonkey.com/v3/surveys/1234/pages/1234/questions/1234/trends",
      "family": "matrix",
      "answered": 2,
      "trends": [
        {
          "start": "2016-11-01T00:00:00+00:00",
          "rows": [
            {
              "max": 1,
              "total": 2,
              "id": "1234",
              "choices": [
                {
                  "count": 0,
                  "id": "1234"
                },
                {
                  "count": 0,
                  "id": "1234"
                },
                {
                  "count": 1,
                  "id": "1234"
                },
                {
                  "count": 0,
                  "id": "1234"
                },
                {
                  "count": 1,
                  "id": "1234"
                }
              ]
            }
          ],
          "end": "2016-12-01T00:00:00+00:00"
        }
      ],
      "id": "1234",
      "trend_by": "month"
    }
  ],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/surveys/1234/trends?page=1&per_page=50"
  }
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns answer counts for a particular time periods. Public App users need access to the View Response Details scope

Optional Query Strings for GET (Accepts same as /rollups and the following additions)

Name Description Data Type
first_respondent Limits responses to those completed after the specified respondent id String
last_respondnet Limits responses to those completed before the specified respondent id String
trend_by Sets the period of time trends are broken into. Accepts: year, quarter, month, week, day, hour String-ENUM

Same as /surveys/{id}/trends but returns trends for only the survey page specified.

Same as /surveys/{id}/trends but returns trends for only the survey question specified.

Webhooks

Create webhooks that subscribe to various events in SurveyMonkey. You can create a webhook to POST a callback when:

  • A survey response is completed (‘response_completed’)
  • A survey response is disqualified ('response_disqualified’)
  • A survey response is updated ('response_updated’)
  • A respondent begins a survey ('response_created’)
  • A response is deleted ('response_deleted’)
  • A response is over a survey’s quota ('response_overquota’)
  • A collector is created ('collector_created’)
  • A collector is updated ('collector_updated’)
  • A collector is deleted ('collector_deleted’)

You can specify one or more survey ids to be included.

/webhooks

Definition

POST https://api.surveymonkey.com/v3/webhooks

Example Request

curl -X POST -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/webhooks -d \
  '{"name":"My Webhook", "event_type":"response completed", "object_type":"survey", "object_ids":["1234","5678"],"subscription_url":"https://surveymonkey.com/webhook_reciever"}'
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "name": "My Webhook",
  "event_type": "response_completed",
  "object_type": "survey",
  "object_ids": ["1234", "5678"],
  "subscription_url": "https://surveymonkey.com/webhook_reciever"
}
url = "https://api.surveymonkey.com/v3/webhooks"
s.post(url, json=payload)

Example Response

{
  "id": "1234",
  "name": "My Webhook",
  "event_type": "response_completed",
  "object_type": "survey",
  "object_ids": ["1234", "5678"],
  "subscription_url": "https://surveymonkey.com/webhook_reciever",
  "href": "https://api.surveymonkey.com/v3/webhooks/123"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of webhooks. Public App users need access to the View Webhooks scope
  • POST: Create a webhook, see below for callback format. Public App users need access to the Create/Modify Webhooks scope

Optional Query Strings for GET

Name Description Data Type
page Which page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Webooks List Resource

Name Description Data Type
data[_].id Webhook id String
data[_].name Webhook name String
data[_].href Resource API URL String

Request Body Arguments for POST

Name Required Description Data Type
name Yes Webhook name String
event_type Yes Event type that the webhook listens to: response_completed, response_updated, response_disqualified, response_created, response_deleted, response_overquota, collector_created, collector_updated, collector_deleted. String-ENUM
object_type Yes Object type to filter events by: survey or collector. NOTE: Setting object_type to collector and event_type to collector_created will result in a 400 error. String-ENUM
object_ids Yes Object ids to filter events by (for example, survey ids to listen for the response_completed event) Array
subscription_url Yes. Url must accept a HEAD request and return a 200. Subscription url that events are sent to String
authorization No Authorization header to pass when events are sent String

/webhooks/{id}

Definition

GET https://api.surveymonkey.com/v3/webhooks/{webhook_id}

Example Request

curl -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/webhooks/1234
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/webhooks/%s" % (webhook_id)
s.get(url)

Example Response

{
  "id": "1234",
  "name": "My Webhook",
  "event_type": "response_completed",
  "object_type": "survey",
  "object_ids": ["1234", "5678"],
  "subscription_url": "http://requestb.in/13qm6kg1",
  "href": "https://api.surveymonkey.com/v3/webhooks/123"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a webhook. Public App users need access to the View Webhooks scope
  • PATCH: Modifies a webhook (updates any fields accepted as arguments to POST /webhooks). Public App users need access to the Create/Modify Webhooks scope
  • PUT: Replaces a webhook (same arguments and requirements as POST /webhooks). Public App users need access to the Create/Modify Webhooks scope
  • DELETE: Deletes a webhook. Public App users need access to the Create/Modify Webhooks scope

Webhook Resource

Name Description Data Type
id Webhook id String
name Webhook name String
event_type Event type that the webhook listens to: response_completed, response_disqualified, or response_updated String-ENUM
object_type Object type to filter events by: survey or collector String-ENUM
object_ids Object ids to filter events by (for example, survey ids to listen for the response_completed event) Array
subscription_url Subscription url that callback events are sent to String
authorization Authorization header to pass when events are sent String
href Resource API URL String

Webhook Callbacks

Our webhook callbacks are sent as POST requests and include the following request headers that can be used to verify the request is coming from SurveyMonkey:

  • Sm-Apikey: Your Client ID or API key (if you’re using OLD Authentication)
  • Sm-Signature: # HMAC digest hashed with sha1

Verifying the request


import hashlib
import hmac
import base64

def generate_signature(payload, api_key, api_secret):

"""
:type payload: str The response body from the webhook exactly as you received it
:type api_key: str Your API Key for you app (if you have one) otherwise your Client ID
:type api_secret: str Your API Secret for your app
:return: str
"""

# ensure all strings passed in are ascii strings,
# as hmac does not work on unicode

api_key = api_key.encode("ascii")
api_secret = api_secret.encode("ascii")
payload = payload.encode("ascii")

signature = hmac.new(
key='%s&%s' % (api_key, api_secret),
msg=payload,
digestmod=hashlib.sha1)

signature_digest = signature.digest()

return base64.b64encode(signature_digest)

# Compare the signature generated from the request body against the one in the request headers
# Where "request" is the HTTP request received for the event, attributes to access body/headers may vary by framework
hmac.compare_digest(generate_signature(request.body, api_key, api_secret), request.headers['Sm-Signature'])


Example Collector Event Data

{
  "name": "My Webhook",
  "filter_type": "survey",
  "filter_id": "123456789",
  "event_type": "response_completed",
  "event_id": "123456789",
  "object_type": "response",
  "object_id": "123456",
  "event_datetime": "2016-01-01T21:56:31.182613+00:00",
  "resources": {
    "collector_id": "123456789",
    "survey_id": "123456789",
    "user_id": "123456789"
  }
}

Example Response Event Data

{
  "name": "My Webhook",
  "filter_type": "collector",
  "filter_id": "123456789",
  "event_type": "response_completed",
  "event_id": "123456789",
  "object_type": "response",
  "object_id": "123456",
  "event_datetime": "2016-01-01T21:56:31.182613+00:00",
  "resources": {
    "respondent_id": "123456789",
    "recipient_id": "123456789",
    "collector_id": "123456789",
    "survey_id": "123456789",
    "user_id": "123456789"
  }
}

Callback Event

Name Description Data Type
name Webhook name String
filter_type Which kind of object the webhook set to filter events by: survey or collector String-ENUM
filter_id The id of the object triggering the event String
event_type Event type that the webhook listens to: response_completed, response_disqualified, or response_updated String-ENUM
event_id Event id String
object_type Type of object that event occured for String
object_id id of object that event occured for String
event_datetime ISO 8601 string of date/time that the event occured String
resources Ids associated with th event. Depending on the webhook configuration can include: respondent_id, recipient_id, collector_id, survey_id, and user_id Object

Benchmarks

Benchmark data comes from SurveyMonkey customers who used Question Bank questions in their surveys. Organizations of all shapes and sizes use Question Bank, like local coffee shops, schools, and Fortune 500 companies. Benchmarks give context to your survey results by allowing you to compare your results to others who used the same Question Bank questions as you.

/benchmark_bundles

Definition

GET https://api.surveymonkey.com/v3/benchmark_bundles

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/benchmark_bundles
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/benchmark_bundles"
s.get(url)

Example Response

{
  "per_page": 5,
  "total": 5,
  "data": [
    {
      "href": "https://api.surveymonkey.com/v3/benchmark_bundles/nps_education",
      "id": "nps_education",
      "title": "All Education"
    },
    {
      "href": "https://api.surveymonkey.com/v3/benchmark_bundles/nps_higher_education",
      "id": "nps_higher_education",
      "title": "Higher Education"
    },
    {
      "href": "https://api.surveymonkey.com/v3/benchmark_bundles/nps_schools",
      "id": "nps_schools",
      "title": "K-12 Schools"
    },
    {
      "href": "https://api.surveymonkey.com/v3/benchmark_bundles/nps_sports_instruction",
      "id": "nps_sports_instruction",
      "title": "Sports Instruction"
    },
    {
      "href": "https://api.surveymonkey.com/v3/benchmark_bundles/nps_health_human_services",
      "id": "nps_health_human_services",
      "title": "Health and Human Services"
    }
  ],
  "page": 1,
  "links": {
    "self": "https://api.surveymonkey.com/v3/benchmark_bundles?page=1&per_page=5"
  }
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods
  • GET: Returns a list of benchmark bundles you have access to

Optional Query Strings for GET

Name Description Data Type
page Page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer
country Country to get the bundles for. Defaults to US String

Bundle List

Name Description Data Type
data[_].id Benchmark Bundle id String
data[_].title Benchmark Bundle name String
data[_].href Benchmark Bundle resource link String

/benchmark_bundles/{id}

Definition

GET https://api.surveymonkey.com/v3/benchmark_bundles/{bundle_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/benchmark_bundles/test_bundle
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/benchmark_bundles/%s" % (bundle_id)
s.get(url)

Example Response

{
  "title": "Consumer Goods and Services",
  "details": {
    "bullets": [
      "Includes retail companies, restaurants, and other consumer based industries",
      "2,600 responses per question (average)"
    ],
    "subtext": "Responses from 40+ organizations*"
  },
  "questions": [
    {
      "answer_order": "normal",
      "id": "25651",
      "answers": {
        "choices": [
          {
            "text": "Strongly Disagree"
          },
          {
            "text": "Disagree"
          },
          {
            "text": "Neutral/Neither agree nor disagree"
          },
          {
            "text": "Agree"
          },
          {
            "text": "Strongly Agree"
          }
        ]
      },
      "title": "My organization is dedicated to diversity and inclusiveness."
    },
  ],
  "id": "test_bundle"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns the questions and details included in a given bundle

Bundle Details

Name Description Data Type
id Benchmark Bundle id String
title Benchmark Bundle name String
details Benchmark Bundle description String
questions List of questions associated with the bundle Array
href Resource API URL String

/benchmark_bundles/{id}/analyze

Definition

GET https://api.surveymonkey.com/v3/benchmark_bundles/{bundle_id}/analyze

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" 'https://api.surveymonkey.com/v3/benchmark_bundles/test_bundle/analyze?question_ids=25651,25652'

import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

payload = {
  "question_ids": [123, 456],
  "percentile_start": 1,
  "percentile_end": 100
}
url = "https://api.surveymonkey.com/v3/benchmark_bundles/%s/analyze" % (bundle_id)
s.get(url, params=payload)

Example Response

{
  "date_end": "2015-12-31T00:00:00+00:00",
  "date_start": "2015-01-01T00:00:00+00:00",
  "id": "test_bundle",
  "benchmarks": [
    {
      "num_data_points": 50,
      "distribution_values": {
        "1": 0.0333333333,
        "3": 0.2222222222,
        "2": 0.0555555555,
        "5": 0.2222222222,
        "4": 0.4444444444
      },
      "question": {
        "answer_order": "normal",
        "id": "25651",
        "answers": {
          "choices": [
            {
              "text": "Strongly Disagree"
            },
            {
              "text": "Disagree"
            },
            {
              "text": "Neutral/Neither agree nor disagree"
            },
            {
              "text": "Agree"
            },
            {
              "text": "Strongly Agree"
            }
          ]
        },
        "title": "My organization is dedicated to diversity and inclusiveness."
      },
      "num_responses": 1000,
      "quartile_values": {
        "100": 5.4343,
        "0": 1.9,
        "75": 2.011,
        "50": 5.211,
        "25": 8.2
      }
    }
  ]
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns the benchmark for the given bundle

Query String for GET

Name Description Data Type
question_ids (required) List of question to recieve analytics for. Comma Separated Strings
percentile_start (optional) Starting percentile to filter by (default=0). Integer
percentile_end (optional) Ending percentile to filter by (default=100). Integer

Bundle Benchmark

Name Description Data Type
id Benchmark Bundle id String
date_start Start date for included responses in the benchmark String
date_end End date for included responses in the benchmark String
benchmarks List of benchmark results for each question in the bundle, with the question details Array

/surveys/{id}/pages/{id}/questions/{id}/benchmark

Definition

GET https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}/questions/{question_id}/benchmark

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}/questions/{question_id}/benchmark
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/surveys/{survey_id}/pages/{page_id}/questions/{question_id}/benchmark" % (survey_id, page_id, question_id)
s.get(url)

Example Response

{
  "date_end": "2015-12-31T00:00:00+00:00",
  "date_start": "2015-01-01T00:00:00+00:00",
  "benchmark": {
    "num_responses": 12921174,
    "num_data_points": 76147,
    "quartile_values": {
      "0": -100,
      "25": 2.8,
      "50": 40,
      "75": 67.6,
      "100": 100
    },
    "distribution_values": {
      "0": 0.2603693321,
      "100": 0.5344724075,
      "-100": 0.2051582605
    },
    "data_point_type_distribution": {
      "respondent_data_points": 0,
      "entity_data_points": 100
    }
  },
  "id": "327620251"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods
  • GET: Returns the benchmark for the given question

Query String for GET

Name Description Data Type
percentile_start (optional) Starting percentile to filter by (default=0). Integer
percentile_end (optional) Ending percentile to filter by (default=100). Integer

Question Benchmark

Name Description Type
id Benchmark question id String
date_start Start date for included responses in the benchmark String
date_end End date for included responses in the benchmark String
benchmark Benchmark result for the question Object

Errors

Get a list of errors or lookup an error by its id. See also error codes.

/errors

Definition

GET https://api.surveymonkey.com/v3/errors

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/errors
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/errors"
s.get(url)

Example Response

{
  "page": 1,
  "per_page": 1,
  "total": 1,
  "data": [{
    "id": "1234",
    "href": "https://api.surveymonkey.com/v3/errors/1234",
    "name": "Known Error"
  }],
  "links": {
    "self": "https://api.surveymonkey.com/v3/errors?page=1&per_page=1"
  }
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns a list of known errors

Optional Query Strings for GET

Name Description Data Type
page Page of resources to return. Defaults to 1 Integer
per_page Number of resources to return per page Integer

Errors list Resource

Name Description Data Type
data[_].id Error id String
data[_].href Resource API URL String
data[_].name Error name String

/errors/{id}

Definition

GET https://api.surveymonkey.com/v3/errors/{error_id}

Example Request

curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveymonkey.com/v3/errors/1234
import requests

s = requests.session()
s.headers.update({
  "Authorization": "Bearer %s" % YOUR_ACCESS_TOKEN,
  "Content-Type": "application/json"
})

url = "https://api.surveymonkey.com/v3/errors/%s" % (error_id)
s.get(url)

Example Response

{
  "id": "1234",
  "message": "This is an error.",
  "href": "https://api.surveymonkey.com/v3/errors/1234",
  "name": "Known Error",
  "docs": "https://developer.surveymonkey.com/api/v3/#error-codes"
}

Available Methods

  • HEAD: Checks if resource is available
  • OPTIONS: Returns available methods and options
  • GET: Returns the details of a known error

Error Resource

Name Description Data Type
id Error id String
message Error explanation String
href Resource API URL String
docs Error documentation page String
name Error name String

API Libraries & SDKs

Feedback SDKs for iOS and Android

Our mobile feedback SDKs let app developers:

  • Embed SurveyMonkey surveys in iOS or Android apps using a SDK collector
  • Schedule an intercept to prompt users to take a survey at a custom time interval
  • Bind to survey submissions and customize subsequent flows for a user based on their response
  • Use custom variables to record additional data in survey submissions

Get the SDK, sample projects, and full documentation on Github: