A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The SurveyMonkey API is how an app or AI agent works with a SurveyMonkey account: building a survey and its questions, sending it out through a collector, reading the responses that come back, and managing the contacts it goes to. Access is granted through an OAuth access token, and that token carries scopes that set which areas a call can read or write, like viewing surveys versus changing them. SurveyMonkey can also push an event to a registered endpoint when something happens, such as a response being completed.
How an app or AI agent connects to SurveyMonkey determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the access token behind it and the scopes that token carries.
The REST API takes JSON request bodies, returns JSON, and pages through lists with page and per_page, at https://api.surveymonkey.com/v3. A call authenticates with an OAuth access token sent as a Bearer token. Regional hosts exist for the EU and Canada (api.eu.surveymonkey.com, api.ca.surveymonkey.com) for accounts whose data is held in those regions.
SurveyMonkey POSTs a small notification to a registered HTTPS endpoint when a subscribed event occurs, such as a response being completed or a collector being created. The notification names the event type and the object that changed, but not its full data, so the receiver calls back to fetch the object. Webhooks are created and managed through the webhooks endpoints with the webhooks_write scope.
A public app sends a user through the authorization-code flow to grant the scopes the app requests, then exchanges the returned code for an access token tied to that user's account. Two scopes, create or modify surveys and create or modify responses, require SurveyMonkey to approve the app first, and some scopes require the account to be on a paid plan.
An app built for a single SurveyMonkey account can be issued an access token directly, without running the full authorization flow for every connection. It is sent the same way, as a Bearer token, and is limited to the same scopes.
The SurveyMonkey API is split into areas an agent can act on, like surveys, the pages and questions inside them, collectors that distribute a survey, the responses that come back, and the contacts a survey is sent to. Each area has its own methods, and a write can change a live survey, send invitations, or remove collected data.
Methods for listing, creating, updating, and deleting surveys.
Methods for the pages and questions that make up a survey's design.
Methods for the collectors that distribute a survey and the invite messages they send.
Methods for reading the responses collected by a survey or collector.
Methods for the contacts and contact lists a survey is sent to.
Methods for subscribing to and managing event notifications.
Methods for reading the authenticated user's account.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SurveysMethods for listing, creating, updating, and deleting surveys.7 | ||||||
| GET | /v3/surveys | List the surveys owned by or shared with the authenticated user. | read | surveys_read | Current | |
Scope label: View Surveys. Acts onsurvey Permission (capability) surveys_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/surveys | Create a new survey, either empty or prepopulated with pages and questions or from a template. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. This scope needs SurveyMonkey approval for a public app. Acts onsurvey Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/surveys/{id} | Retrieve a survey's details. | read | surveys_read | Current | |
Scope label: View Surveys. Acts onsurvey Permission (capability) surveys_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/surveys/{id}/details | Retrieve a survey expanded with its pages and questions in one call. | read | surveys_read | Current | |
Scope label: View Surveys. Acts onsurvey Permission (capability) surveys_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/surveys/{id} | Modify a survey's title, nickname, or language. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onsurvey Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/surveys/{id} | Replace an entire survey with a new definition. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onsurvey Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/surveys/{id} | Delete a survey. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Irreversible. Acts onsurvey Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Pages & QuestionsMethods for the pages and questions that make up a survey's design.8 | ||||||
| GET | /v3/surveys/{id}/pages | List the pages in a survey. | read | surveys_read | Current | |
Scope label: View Surveys. Acts onpage Permission (capability) surveys_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/surveys/{id}/pages | Create a new page in a survey. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onpage Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/surveys/{id}/pages/{page_id} | Modify a page in a survey. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onpage Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/surveys/{id}/pages/{page_id} | Delete a page from a survey. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onpage Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/surveys/{id}/pages/{page_id}/questions | List the questions on a survey page. | read | surveys_read | Current | |
Scope label: View Surveys. Acts onquestion Permission (capability) surveys_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/surveys/{id}/pages/{page_id}/questions | Create a new question on a survey page. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onquestion Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/surveys/{id}/pages/{page_id}/questions/{question_id} | Modify a question on a survey page. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onquestion Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/surveys/{id}/pages/{page_id}/questions/{question_id} | Delete a question from a survey page. | write | surveys_write | Current | |
Scope label: Create/Modify Surveys. Acts onquestion Permission (capability) surveys_writeVersionAvailable since the API’s base version Webhook event survey_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Collectors & MessagesMethods for the collectors that distribute a survey and the invite messages they send.6 | ||||||
| GET | /v3/surveys/{id}/collectors | List the collectors distributing a survey. | read | collectors_read | Current | |
Scope label: View Collectors. Acts oncollector Permission (capability) collectors_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/surveys/{id}/collectors | Create a weblink, email, SMS, or popup collector for a survey. | write | collectors_write | Current | |
Scope label: Create/Modify Collectors. Acts oncollector Permission (capability) collectors_writeVersionAvailable since the API’s base version Webhook event collector_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/collectors/{collector_id} | Retrieve a collector's details. | read | collectors_read | Current | |
Scope label: View Collectors. Acts oncollector Permission (capability) collectors_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/collectors/{collector_id}/messages | Create an invite, a reminder, a thanks, or an SMS message on an email or SMS collector. | write | collectors_write | Current | |
Scope label: Create/Modify Collectors. Acts onmessage Permission (capability) collectors_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/collectors/{collector_id}/messages/{message_id}/send | Send or schedule a collector message to the recipients on it. | write | collectors_write | Current | |
Scope label: Create/Modify Collectors. Sends real invitations to people. Acts onmessage Permission (capability) collectors_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/collectors/{collector_id}/messages/{message_id}/recipients/bulk | Add multiple recipients to a collector message at once. | write | collectors_write | Current | |
Scope label: Create/Modify Collectors. Acts onrecipient Permission (capability) collectors_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ResponsesMethods for reading the responses collected by a survey or collector.5 | ||||||
| GET | /v3/surveys/{id}/responses | List the responses to a survey, in summary form. | read | responses_read | Current | |
Scope label: View Responses. Acts onresponse Permission (capability) responses_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/surveys/{id}/responses/{response_id} | Retrieve a single response in summary form. | read | responses_read | Current | |
Scope label: View Responses. Acts onresponse Permission (capability) responses_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/surveys/{id}/responses/bulk | Retrieve many full responses with per-question answer data in one call. | read | responses_read_detail | Current | |
Scope label: View Response Details. Returns full respondent answers. Acts onresponse Permission (capability) responses_read_detailVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/surveys/{id}/responses/{response_id}/details | Retrieve a single response with its full per-question answer data. | read | responses_read_detail | Current | |
Scope label: View Response Details. Returns full respondent answers. Acts onresponse Permission (capability) responses_read_detailVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/collectors/{collector_id}/responses | List the responses gathered by a specific collector. | read | responses_read | Current | |
Scope label: View Responses. Acts onresponse Permission (capability) responses_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contacts & ListsMethods for the contacts and contact lists a survey is sent to.5 | ||||||
| GET | /v3/contact_lists | List the contact lists in the account. | read | contacts_read | Current | |
Scope label: View Contacts. Acts oncontact_list Permission (capability) contacts_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contact_lists | Create a contact list for sending survey invitations. | write | contacts_write | Current | |
Scope label: Create/Modify Contacts. Acts oncontact_list Permission (capability) contacts_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/contacts | List the contacts in the account. | read | contacts_read | Current | |
Scope label: View Contacts. Acts oncontact Permission (capability) contacts_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts | Create a new contact for survey messaging. | write | contacts_write | Current | |
Scope label: Create/Modify Contacts. Acts oncontact Permission (capability) contacts_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts/bulk | Create multiple contacts in one call. | write | contacts_write | Current | |
Scope label: Create/Modify Contacts. Acts oncontact Permission (capability) contacts_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for subscribing to and managing event notifications.4 | ||||||
| GET | /v3/webhooks | List the webhook subscriptions for the app. | read | webhooks_read | Current | |
Scope label: View Webhooks. Acts onwebhook Permission (capability) webhooks_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/webhooks | Create a webhook subscription for one or more event types. | write | webhooks_write | Current | |
Scope label: Create/Modify Webhooks. Acts onwebhook Permission (capability) webhooks_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/webhooks/{webhook_id} | Update a webhook subscription. | write | webhooks_write | Current | |
Scope label: Create/Modify Webhooks. Acts onwebhook Permission (capability) webhooks_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/webhooks/{webhook_id} | Delete a webhook subscription. | write | webhooks_write | Current | |
Scope label: Create/Modify Webhooks. Acts onwebhook Permission (capability) webhooks_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersMethods for reading the authenticated user's account.1 | ||||||
| GET | /v3/users/me | Retrieve the account details of the authenticated user. | read | users_read | Current | |
Scope label: View User Details. Acts onuser Permission (capability) users_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SurveyMonkey can notify an app when something happens in an account, like a response being completed or a collector being created. It sends an event naming the object that changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
response_completed | A respondent finished and submitted a survey. This is the common signal to fetch and process a new complete response. | /v3/surveys/{id}/collectors |
response_created | A respondent began a survey, before it is submitted. | /v3/surveys/{id}/collectors |
response_updated | An existing response's data changed. | /v3/surveys/{id}/collectors |
response_disqualified | A respondent was disqualified by the survey's logic or quota rules. | /v3/surveys/{id}/collectors |
response_deleted | A response was removed. | /v3/surveys/{id}/collectors |
survey_created | A new survey was created in the account. | /v3/surveys |
survey_updated | A survey's settings or structure changed. | /v3/surveys/{id}/v3/surveys/{id} |
survey_deleted | A survey was removed. | /v3/surveys/{id} |
collector_created | A new collector was created on a survey, distributing it by weblink, email, SMS, or popup. | /v3/surveys/{id}/collectors |
collector_updated | A collector's configuration changed. | /v3/surveys/{id}/collectors |
collector_deleted | A collector was removed. | /v3/surveys/{id}/collectors |
SurveyMonkey limits how often an app can call, with a per-minute ceiling and a separate daily ceiling that varies by plan, and returns the remaining allowance in response headers.
SurveyMonkey meters requests by count, not by a per-method cost. An app is allowed 120 requests per minute and a separate daily cap that starts at 500 on some plans and is higher on others. Every response includes X-Ratelimit-App-Global-Minute-Remaining, X-Ratelimit-App-Global-Day-Remaining, and matching reset headers, so an integration can read its remaining allowance rather than guess. The daily allowance resets at midnight GMT. Going over returns an error, and SurveyMonkey enforces against apps that repeatedly exceed 150 percent of a limit.
List endpoints are page-based. A request sets page (default 1) and per_page (default 50, up to 1000), and the response returns total, page, per_page, and a links object with self, first, prev, next, and last URLs to walk through the pages.
A list page returns up to 1000 items, the maximum value of per_page. On a Basic plan, a survey returns at most the 25 most recent responses, and asking for more returns an error pointing to the required upgrade.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | 1000-1017 (bad request) | The request was malformed or a parameter was invalid, like a missing required field or an unrecognized option. | Read the error name and message, fix the request, and resend. The call is not retryable as-is. |
| 401 | 1010-1018 (authentication) | The access token is missing, invalid, expired, or was revoked by the user. | Re-run the OAuth flow to obtain a fresh token, then retry. |
| 403 | 1020-1024 (permission) | The token lacks the scope for this call, or the account's plan does not permit it. | Request the needed scope when connecting, or confirm the account is on a plan that allows the action. |
| 404 | 1030-1032 (not found) | The requested survey, collector, response, or other resource does not exist or is not visible to this token. | Verify the id and that the token's account owns or was shared the resource. |
| 409 | 1050-1053 (conflict) | The request conflicts with the resource's current state, like a duplicate or an operation not allowed in that state. | Re-fetch the resource, reconcile the state, and retry. |
| 429 | 1040-1042 (rate limited) | The per-minute or per-day request limit was exceeded. | Read the X-Ratelimit-App-Global headers, wait for the reset, and retry with backoff. |
| 500 | 1060-1063 (server error) | An error on SurveyMonkey's side. It is rare. | Retry with backoff, and contact SurveyMonkey support if it persists. |
SurveyMonkey runs one current version of its API, identified in the path, and ships dated changes through its developer changelog rather than minting new version numbers.
SurveyMonkey runs one current major version, v3, identified in the request path. Rather than minting new version numbers, SurveyMonkey ships additive changes and notes them in its developer documentation and changelog. An integration tracks that changelog instead of pinning a dated version.
There is one current version; track the changelog for additive changes.
SurveyMonkey API changelog ↗Bollard AI sits between a team's AI agents and SurveyMonkey. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.