New Integration: SurveyMonkey

Description

Add SurveyMonkey integration to sync surveys, responses, collectors, and respondent data into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/hubspot/ - Similar customer data platform with OAuth
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference on OAuth flow

Required Files Structure

integrations/surveymonkey/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # SurveyMonkey API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

SurveyMonkey API Integration

OAuth Setup

• Use OAuth 2.0
• Developer Portal (US): https://developer.surveymonkey.com/
• Developer Portal (EU): https://developer.eu.surveymonkey.com/
• Required scopes: surveys_read, responses_read, collectors_read, users_read, contacts_read
• Base URL: https://api.surveymonkey.com/v3

Key Endpoints

• GET /v3/surveys - List all surveys
• GET /v3/surveys/{id} - Get survey details
• GET /v3/surveys/{id}/details - Get full survey with questions
• GET /v3/surveys/{id}/responses/bulk - Get all responses for a survey
• GET /v3/surveys/{id}/responses/{response_id} - Get a specific response
• GET /v3/surveys/{id}/collectors - List collectors for a survey
• GET /v3/collectors/{id} - Get collector details
• GET /v3/users/me - Get current user info
• GET /v3/groups - List groups
• GET /v3/contact_lists - List contact lists

Events to Track

1. Surveys - Created, modified, deployed surveys
2. Responses - New survey responses, completed responses
3. Collectors - Collector creation, status changes (open/closed)
4. Contacts - Contact list updates, new respondents

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create API utilities in utils.ts with SurveyMonkey v3 API client
• Implement sync logic in schedule.ts for surveys, responses, collectors
• Convert SurveyMonkey data to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• REST API v3 with JSON responses
• OAuth 2.0 authentication
• Pagination via page and per_page parameters (configurable page size)
• Separate US and EU data centers with different base URLs
• Rate limits apply per OAuth token
• Bulk response endpoint is most efficient for syncing all responses
• Supports webhooks for real-time response notifications
• Survey details endpoint returns full question structure needed to interpret responses

Resources

• SurveyMonkey API v3 Documentation
• SurveyMonkey Developer Portal
• SurveyMonkey API Help
• SurveyMonkey API Postman Collection
• SurveyMonkey Public API Docs (GitHub)

Labels

enhancement, integration, new-feature