API Documentation

Access SurveyMethods functionality programmatically through our comprehensive REST API.

Overview

The SurveyMethods API allows you to:

Create and manage surveys
Retrieve responses and results
Manage contacts and lists
Send email invitations
Generate reports
Automate workflows

Getting Started

API Access

API access is available on Professional plans and above.

Go to Account > API Settings
Click Generate API Key
Copy your API key securely
Set up authentication

Base URL

All API requests use:

https://api.surveymethods.com/v1

Authentication

Use API key authentication in the header:

Authorization: Bearer YOUR_API_KEY

Example request:

curl -X GET "https://api.surveymethods.com/v1/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Core Endpoints

Surveys

List all surveys:

GET /surveys

Get survey details:

GET /surveys/{surveyId}

Create a survey:

POST /surveys

Update a survey:

PUT /surveys/{surveyId}

Delete a survey:

DELETE /surveys/{surveyId}

Responses

Get all responses:

GET /surveys/{surveyId}/responses

Get single response:

GET /surveys/{surveyId}/responses/{responseId}

Export responses:

GET /surveys/{surveyId}/responses/export

Collectors

List collectors:

GET /surveys/{surveyId}/collectors

Create collector:

POST /surveys/{surveyId}/collectors

Update collector:

PUT /surveys/{surveyId}/collectors/{collectorId}

Contacts

List contacts:

GET /contacts

Create contact:

POST /contacts

Update contact:

PUT /contacts/{contactId}

Delete contact:

DELETE /contacts/{contactId}

Contact Groups

List groups:

GET /contact-groups

Get group contacts:

GET /contact-groups/{groupId}/contacts

Add contacts to group:

POST /contact-groups/{groupId}/contacts

Request & Response Format

Request Headers

Required headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Response Format

All responses return JSON:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "perPage": 50,
    "total": 150
  }
}

Error Responses

Errors return appropriate HTTP status codes:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Survey ID is required",
    "details": { ... }
  }
}

Common status codes:

200 - Success
201 - Created
400 - Bad request
401 - Unauthorized
403 - Forbidden
404 - Not found
429 - Rate limited
500 - Server error

Pagination

List endpoints support pagination:

GET /surveys?page=2&perPage=25

Parameters:

page - Page number (default: 1)
perPage - Items per page (default: 50, max: 100)

Response includes:

{
  "meta": {
    "page": 2,
    "perPage": 25,
    "total": 150,
    "totalPages": 6
  }
}

Filtering & Sorting

Filtering

Filter results using query parameters:

GET /surveys?status=active&createdAfter=2024-01-01

Sorting

Sort results:

GET /surveys?sortBy=createdAt&sortOrder=desc

Rate Limiting

API requests are rate limited:

Standard: 100 requests/minute
Enterprise: 500 requests/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

When exceeded, receive 429 Too Many Requests.

Common Use Cases

Create Survey and Collect Responses

// 1. Create survey
const survey = await fetch('/v1/surveys', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: JSON.stringify({
    title: 'Customer Feedback',
    pages: [...]
  })
});

// 2. Create web link collector
const collector = await fetch(`/v1/surveys/${survey.id}/collectors`, {
  method: 'POST',
  body: JSON.stringify({
    type: 'weblink',
    name: 'Main Collection'
  })
});

// 3. Get responses later
const responses = await fetch(
  `/v1/surveys/${survey.id}/responses`
);

Send Email Invitations

// 1. Create email collector
const collector = await createCollector(surveyId, {
  type: 'email',
  name: 'Q1 Campaign'
});

// 2. Add recipients
await fetch(`/v1/collectors/${collector.id}/recipients`, {
  method: 'POST',
  body: JSON.stringify({
    contacts: [contactId1, contactId2]
  })
});

// 3. Send invitations
await fetch(`/v1/collectors/${collector.id}/send`, {
  method: 'POST',
  body: JSON.stringify({
    subject: 'Your feedback matters',
    body: 'Please take our survey...'
  })
});

Export Response Data

// Get all responses with answers
const responses = await fetch(
  `/v1/surveys/${surveyId}/responses?` +
  `include=answers&format=expanded`
);

// Or export as CSV
const csv = await fetch(
  `/v1/surveys/${surveyId}/responses/export?format=csv`
);

SDKs & Libraries

Official SDKs available:

JavaScript/Node.js: npm install surveymethods
Python: pip install surveymethods
PHP: composer require surveymethods/sdk
Ruby: gem install surveymethods

Node.js Example

const SurveyMethods = require('surveymethods');

const client = new SurveyMethods({
  apiKey: 'YOUR_API_KEY'
});

// List surveys
const surveys = await client.surveys.list();

// Get responses
const responses = await client.surveys.responses(surveyId);

Webhooks Integration

Receive real-time notifications via webhooks. See the Webhooks documentation for details.

Best Practices

Security

Store API keys securely (use environment variables)
Rotate keys periodically
Use HTTPS only
Implement proper error handling

Performance

Cache responses when appropriate
Use pagination for large datasets
Implement retry logic with exponential backoff
Batch operations when possible

Error Handling

try {
  const response = await fetch('/v1/surveys');
  if (!response.ok) {
    const error = await response.json();
    // Handle specific error codes
    if (response.status === 429) {
      // Wait and retry
    }
  }
} catch (error) {
  // Handle network errors
}

API Changelog

v1.5 (Latest)

Added bulk operations
Improved filtering options
New report endpoints

v1.4

Webhook support
Contact custom fields
Response metadata

v1.3

Email collector API
Reminder scheduling
Enhanced pagination

Support

API Status: status.surveymethods.com
Developer Portal: developers.surveymethods.com
Support Email: api-support@surveymethods.com

Related articles: