Survey REST API Reference

REST API endpoints for BuddyPress Polls surveys. Base URL: /wp-json/wbsurvey/v1/

Authentication

• Public endpoints: No authentication required
• Admin endpoints: Require can_manage_surveys capability (edit_posts)
• Authentication: WordPress REST API nonce or application passwords

Public Survey Flow

List Surveys

Get published surveys.

GET /wp-json/wbsurvey/v1/surveys

Parameters:

Parameter	Type	Default	Description
per_page	int	10	Surveys per page
page	int	1	Page number
status	string	publish	Survey status filter

Example Request:

curl https://example.com/wp-json/wbsurvey/v1/surveys?per_page=5

Example Response:

[
  {
    "id": 123,
    "title": "Customer Satisfaction Survey",
    "description": "Help us improve our service",
    "status": "publish",
    "created_date": "2026-02-01 10:00:00"
  }
]

Get Single Survey

Retrieve survey details with questions.

GET /wp-json/wbsurvey/v1/surveys/{id}

Example Request:

curl https://example.com/wp-json/wbsurvey/v1/surveys/123

Example Response:

{
  "id": 123,
  "title": "Customer Satisfaction Survey",
  "description": "Help us improve our service",
  "questions": [
    {
      "poll_id": 456,
      "question": "How satisfied are you?",
      "type": "radio",
      "options": ["Very Satisfied", "Satisfied", "Neutral", "Dissatisfied"]
    }
  ],
  "settings": {
    "require_email": false,
    "access_level": "public",
    "show_results": true,
    "thankyou_title": "Thank You!",
    "thankyou_message": "Your feedback matters.",
    "gdpr_text": "We respect your privacy."
  }
}

Start Survey Response

Initialize a new survey response.

POST /wp-json/wbsurvey/v1/surveys/{id}/start

Parameters:

Parameter	Type	Required	Description
email	string	No	Respondent email (if required by survey)

Example Request:

curl -X POST https://example.com/wp-json/wbsurvey/v1/surveys/123/start \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

Example Response:

{
  "response_id": 789,
  "survey_id": 123,
  "started_at": "2026-02-14 14:30:00"
}

Submit Answer

Submit answer for a survey question.

POST /wp-json/wbsurvey/v1/responses/{response_id}/answer

Parameters:

Parameter	Type	Required	Description
poll_id	int	Yes	Question/poll ID
answer	mixed	Yes	Answer value (string for radio/text, array for checkbox)

Example Request:

curl -X POST https://example.com/wp-json/wbsurvey/v1/responses/789/answer \
  -H "Content-Type: application/json" \
  -d '{"poll_id":456,"answer":"Very Satisfied"}'

Example Response:

{
  "success": true,
  "message": "Answer recorded"
}

Complete Survey Response

Mark response as complete.

POST /wp-json/wbsurvey/v1/responses/{response_id}/complete

Example Request:

curl -X POST https://example.com/wp-json/wbsurvey/v1/responses/789/complete

Example Response:

{
  "success": true,
  "completed_at": "2026-02-14 14:35:00",
  "redirect_url": "https://example.com/thank-you"
}

Admin Management

Create Survey

Create new survey.

POST /wp-json/wbsurvey/v1/surveys

Required: can_manage_surveys capability

Parameters:

Parameter	Type	Required	Description
title	string	Yes	Survey title
description	string	No	Survey description
status	string	No	publish/draft/private
settings	object	No	Survey settings

Settings Object:

• require_email (bool): Require email from respondents
• access_level (string): public/authenticated/roles/password
• show_results (bool): Display results after completion
• thankyou_title (string): Thank you page title
• thankyou_message (string): Thank you message
• thankyou_redirect (string): Redirect URL after completion
• gdpr_text (string): GDPR/privacy notice

Example Request:

curl -X POST https://example.com/wp-json/wbsurvey/v1/surveys \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -d '{
    "title": "Q1 Feedback Survey",
    "description": "Quarterly customer feedback",
    "status": "draft",
    "settings": {
      "require_email": true,
      "access_level": "public",
      "show_results": false,
      "thankyou_title": "Thank You!"
    }
  }'

Example Response:

{
  "id": 124,
  "title": "Q1 Feedback Survey",
  "status": "draft",
  "created_date": "2026-02-14 15:00:00"
}

Update Survey

Update existing survey.

PUT /wp-json/wbsurvey/v1/surveys/{id}
PATCH /wp-json/wbsurvey/v1/surveys/{id}

Required: can_manage_surveys capability

Example Request:

curl -X PATCH https://example.com/wp-json/wbsurvey/v1/surveys/124 \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -d '{"status":"publish"}'

Delete Survey

Delete survey.

DELETE /wp-json/wbsurvey/v1/surveys/{id}

Required: can_manage_surveys capability

Parameters:

Parameter	Type	Default	Description
force	bool	false	Bypass trash and delete permanently

Example Request:

curl -X DELETE https://example.com/wp-json/wbsurvey/v1/surveys/124?force=true \
  -H "X-WP-Nonce: YOUR_NONCE"

Get Survey Results

Retrieve survey analytics and results.

GET /wp-json/wbsurvey/v1/surveys/{id}/results

Required: can_manage_surveys capability

Example Response:

{
  "survey_id": 123,
  "total_responses": 150,
  "completed_responses": 142,
  "questions": [
    {
      "poll_id": 456,
      "question": "How satisfied are you?",
      "responses": {
        "Very Satisfied": 85,
        "Satisfied": 42,
        "Neutral": 10,
        "Dissatisfied": 5
      }
    }
  ]
}

Response Management

List Survey Responses

Get responses for a specific survey.

GET /wp-json/wbsurvey/v1/surveys/{id}/responses

Required: can_manage_surveys capability

Parameters:

Parameter	Type	Default	Description
per_page	int	10	Responses per page
page	int	1	Page number
status	string	all	completed/incomplete/all

List All Responses

Get responses across all surveys.

GET /wp-json/wbsurvey/v1/responses

Required: can_manage_surveys capability

Parameters:

Parameter	Type	Description
per_page	int	Responses per page
page	int	Page number
status	string	completed/incomplete/all
survey_id	int	Filter by survey
email	string	Filter by respondent email
date_after	string	ISO 8601 date (2026-02-01T00:00:00)
date_before	string	ISO 8601 date

Example Request:

curl https://example.com/wp-json/wbsurvey/v1/responses?survey_id=123&status=completed \
  -H "X-WP-Nonce: YOUR_NONCE"

Get Single Response

Retrieve response details.

GET /wp-json/wbsurvey/v1/responses/{response_id}

Required: can_manage_surveys capability

Example Response:

{
  "id": 789,
  "survey_id": 123,
  "email": "user@example.com",
  "status": "completed",
  "started_at": "2026-02-14 14:30:00",
  "completed_at": "2026-02-14 14:35:00",
  "answers": [
    {
      "poll_id": 456,
      "question": "How satisfied are you?",
      "answer": "Very Satisfied"
    }
  ]
}

Delete Response

Delete survey response.

DELETE /wp-json/wbsurvey/v1/responses/{response_id}

Required: can_manage_surveys capability

Export Responses

Export survey responses as CSV.

GET /wp-json/wbsurvey/v1/responses/export/{survey_id}

Required: can_manage_surveys capability

Parameters:

Parameter	Type	Default	Description
status	string	all	completed/incomplete/all

Example Request:

curl https://example.com/wp-json/wbsurvey/v1/responses/export/123?status=completed \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -o survey-responses.csv

Error Responses

All endpoints return standard WordPress REST API error format:

{
  "code": "rest_forbidden",
  "message": "You do not have permission to manage surveys.",
  "data": {
    "status": 403
  }
}

Common error codes:

• rest_forbidden (403): Missing required capability
• rest_invalid_param (400): Invalid parameter value
• rest_post_invalid_id (404): Survey/response not found
• rest_cannot_create (500): Creation failed