API Documentation

Build amazing integrations with our REST API

v1.0.0 RESTful
Base URL
/api/v1/
Format
JSON
Auth Method
Token / OAuth2
Rate Limit
1000/day

Introduction

The Survey App API allows you to programmatically access and manage your surveys, questions, responses, and analytics. Our API follows RESTful principles and returns JSON responses.

API Status: All endpoints are currently Live and ready for production use.

Base URL

https://api.surveyapp.com/api/v1/

Quick Start

# Get your API key
curl -X POST https://api.surveyapp.com/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "your-email", "password": "your-password"}'

Authentication

All API requests require authentication using either Token Authentication or OAuth2.

Token Authentication

Include your token in the Authorization header:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

To get a token:

curl -X POST https://api.surveyapp.com/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "password123"}'
OAuth2 Authentication

For OAuth2, use the standard Authorization Code flow:

Authorization: Bearer <access_token>

Available OAuth2 endpoints:

  • /o/authorize/ - Authorization endpoint
  • /o/token/ - Token endpoint
  • /o/revoke_token/ - Revoke token
Security Note: Never expose your API tokens in client-side code. Keep them secure on your server.

Rate Limiting

To ensure fair usage, we implement rate limiting on all API endpoints.

Plan Requests/Day Requests/Minute Burst Limit
Free 1,000 60 10
Pro 10,000 300 50
Business 100,000 1,000 200
Enterprise Unlimited 5,000 1,000

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1631234567

Error Handling

Our API uses conventional HTTP response codes to indicate success or failure.

Code Description
200 OK - Request successful
201 Created - Resource created successfully
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": {
      "field_name": ["This field is required."]
    }
  }
}

Surveys Endpoints

List Surveys
GET

Retrieve a list of your surveys with pagination.

Endpoint
GET /surveys/
Query Parameters
Parameter Type Description
page integer Page number (default: 1)
page_size integer Items per page (default: 20)
status string Filter by status (active, draft, closed)
search string Search in survey titles
Response Example
{
  "count": 42,
  "next": "https://api.surveyapp.com/api/v1/surveys/?page=2",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Customer Satisfaction Survey",
      "description": "Feedback about our products",
      "status": "active",
      "created_at": "2023-10-01T12:00:00Z",
      "updated_at": "2023-10-05T14:30:00Z",
      "response_count": 156
    }
  ]
}
Create Survey
POST

Create a new survey.

Endpoint
POST /surveys/
Request Body
{
  "title": "Employee Feedback",
  "description": "Quarterly employee satisfaction survey",
  "status": "draft",
  "settings": {
    "require_login": false,
    "limit_responses": 1000,
    "start_date": "2023-11-01T00:00:00Z",
    "end_date": "2023-11-30T23:59:59Z"
  }
}
Get Survey
GET

Retrieve details of a specific survey.

Endpoint
GET /surveys/{id}/
Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Customer Satisfaction Survey",
  "description": "Feedback about our products",
  "status": "active",
  "created_at": "2023-10-01T12:00:00Z",
  "updated_at": "2023-10-05T14:30:00Z",
  "response_count": 156,
  "settings": {
    "require_login": false,
    "limit_responses": 1000,
    "start_date": "2023-10-01T00:00:00Z",
    "end_date": "2023-12-31T23:59:59Z",
    "allow_anonymous": true,
    "show_progress": true
  },
  "questions": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "text": "How satisfied are you with our product?",
      "type": "rating",
      "required": true,
      "order": 1
    }
  ]
}

Questions Endpoints

List Questions
GET

Retrieve questions for a specific survey.

Endpoint
GET /surveys/{survey_id}/questions/
Response Example
[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "survey": "550e8400-e29b-41d4-a716-446655440000",
    "text": "How satisfied are you with our product?",
    "type": "rating",
    "required": true,
    "order": 1,
    "options": [
      {"id": 1, "text": "Very Unsatisfied"},
      {"id": 2, "text": "Unsatisfied"},
      {"id": 3, "text": "Neutral"},
      {"id": 4, "text": "Satisfied"},
      {"id": 5, "text": "Very Satisfied"}
    ]
  }
]

Responses Endpoints

Submit Response
POST

Submit a response to a survey.

Endpoint
POST /surveys/{survey_id}/responses/
Request Body
{
  "respondent_email": "user@example.com",
  "answers": [
    {
      "question_id": "660e8400-e29b-41d4-a716-446655440001",
      "value": 5
    },
    {
      "question_id": "660e8400-e29b-41d4-a716-446655440002",
      "value": "The product is excellent!"
    }
  ]
}

Analytics Endpoints

Get Survey Analytics
GET

Retrieve analytics for a specific survey.

Endpoint
GET /surveys/{survey_id}/analytics/
Response Example
{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_responses": 156,
  "completion_rate": 89.5,
  "average_time": "4m 32s",
  "responses_by_date": {
    "2023-10-01": 12,
    "2023-10-02": 18,
    "2023-10-03": 15
  },
  "question_analytics": [
    {
      "question_id": "660e8400-e29b-41d4-a716-446655440001",
      "question_text": "How satisfied are you with our product?",
      "type": "rating",
      "average_rating": 4.2,
      "response_count": 150,
      "distribution": {
        "1": 5,
        "2": 12,
        "3": 28,
        "4": 65,
        "5": 40
      }
    }
  ]
}

cURL Examples

Get Authentication Token
curl -X POST https://api.surveyapp.com/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "yourpassword"}'
Create a Survey
curl -X POST https://api.surveyapp.com/api/v1/surveys/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Test Survey",
    "description": "Created via API",
    "status": "draft"
  }'
Get Survey Responses
curl -X GET https://api.surveyapp.com/api/v1/surveys/SURVEY_ID/responses/ \
  -H "Authorization: Token YOUR_API_TOKEN"

Frequently Asked Questions

You can generate an API key from your Profile Settings page. Navigate to the "API Access" section and click "Generate New Token".

Free accounts have a limit of 1,000 requests per day. Pro accounts get 10,000, Business accounts get 100,000, and Enterprise accounts have no limit.

Yes! Webhooks are available for Pro and higher plans. You can configure webhooks to receive notifications for new survey responses, survey completion, and other events.

Support

API Status

Check our status page for real-time API health and uptime information.

Contact Support

For API-related issues, contact api@surveyapp.com.