Establishing a Connection
SurveyMonkey uses the OAuth 2 authentication standard. The account whose surveys will be read must have a paid plan subscription, given that SurveyMonkey requires this to read survey responses.
There are two authentication methods available for connecting to SurveyMonkey:
- Using the Personal Access Token, when you are registering a private oauth application.
- Using OAuth, when you are registering a public oauth application.
Using the Personal Access Token
Use the personal token to test and to access your own data.
- OAuthAccessToken: Set this to the AccessToken generated in your app settings.
- InitiateOAuth: Set this to OFF.
When to Use a Custom OAuth App
Desktop Authentication with a Custom OAuth AppFollow the steps below to authenticate with the credentials for a custom OAuth app.
Get and Refresh the OAuth Access Token
After setting the following connection properties, you are ready to connect:
- OAuthClientId: Set this to the client Id in your app settings.
- OAuthClientSecret: Set this to the secret in your app settings.
- CallbackURL: Set this to the OAuth Redirect URL that you specified to use your own OAuth app.
- InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property.
- IsPrivateApp: Set this to false.
- Extracts the access token from the callback URL and authenticates requests.
- Refreshes the access token when it expires.
- Saves OAuth values in OAuthSettingsLocation to be persisted across connections.
Authenticate to SurveyMonkey from a Web Application
When connecting via a Web application, or if the provider is not authorized to open a browser window, use stored procedures and set InitiateOAuth to manage the temporary OAuth tokens.
Get an Access TokenTo obtain the access token, set the following connection properties:
- OAuthClientId: Set this to the ClientId that you received.
- OAuthClientSecret: Set this to the ClientSecret that you received.
Refresh the Token
You can set InitiateOAuth to REFRESH to automatically refresh the OAuth access token when it expires.
To connect to data and automatically refresh the OAuthAccessToken, set the following on the first data connection:
On subsequent data connections, set the following:
Creating a Custom OAuth App
Register an OAuth Application with SurveyMonkey
Follow the procedure below to obtain the OAuth client credentials, the OAuthClientId, OAuthClientSecret and OAuthAccessToken:
- Click My Apps on https://developer.surveymonkey.com/
- Log in to your SurveyMonkey account.
- Click Create an App, specify an app nickname, and select a private or public app. Click Settings. The Client Id, Secret and Access Token are displayed.
If you are making a desktop application, set the Callback URL to http://localhost:33333 or a different port number of your choice.
If you are making a Web application, set the Callback URL to a page on your Web app you would like the user to be returned to after they have authorized your application.
- Select the scopes required by your application. The provider requires the following scopes: (1) View Users, (2) View Surveys, (3) View Responses, (4) View Response Details, (5) View Contacts, and (6) View Collectors.
Note: An Advantage-level plan is required for public application use and a Premier-level plan is required for private application use.
Connecting Through a Firewall or Proxy
To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.
In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.
Set the following properties:
- To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
- To tunnel the connection, set FirewallType to TUNNEL.
- To authenticate, specify FirewallUser and FirewallPassword.
- To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.
Troubleshooting the Connection
To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.
- Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
- Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.