Surveys

Retrieve a paginated list of surveys for your organization.

Query Parameters

Example Request

curl -X GET "https://surventrics.ai/api/v1/surveys?status=live" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Customer Satisfaction Survey",
      "description": "Help us improve our service",
      "slug": "customer-satisfaction-2024",
      "status": "live",
      "questionCount": 10,
      "responseCount": 142,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "hasMore": false
  }
}

Create a new survey. The survey will be created in draft status.

Request Body

Example Request

curl -X POST "https://surventrics.ai/api/v1/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Feedback Survey",
    "description": "Tell us what you think about our product",
    "welcomeMessage": "Thanks for taking the time to share your thoughts!",
    "thankYouMessage": "Your feedback has been recorded."
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "title": "Product Feedback Survey",
  "description": "Tell us what you think about our product",
  "slug": "product-feedback-survey",
  "status": "draft",
  "questionCount": 0,
  "responseCount": 0,
  "createdAt": "2024-01-21T09:00:00Z",
  "updatedAt": "2024-01-21T09:00:00Z"
}

Retrieve a single survey by ID. If your API key has the questions:read scope, questions will be included in the response.

Path Parameters

Example Request

curl -X GET "https://surventrics.ai/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update an existing survey. You can change the title, description, messages, and status.

Request Body

Example: Launch Survey

curl -X PUT "https://surventrics.ai/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "live"}'

Delete a survey. Live surveys cannot be deleted - pause or close them first.

Example Request

curl -X DELETE "https://surventrics.ai/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.