Rest Api

WB Polls provides a REST API for managing standalone polls programmatically. Use these endpoints to create, list, manage, and retrieve results for polls from external applications or custom integrations.

Base URL

All endpoints are under the following namespace:

https://yoursite.com/wp-json/wbpoll/v1/

Authentication

The API uses WordPress REST API authentication. Protected endpoints require one of these methods:

• Cookie Authentication works automatically for logged-in users
• Application Passwords suit external applications connecting to WordPress
• OAuth or JWT can be added via third-party plugins

Include the X-WP-Nonce header with a valid WordPress REST nonce for authenticated requests.

Endpoints

List All Polls

Retrieve all published polls.

GET /wp-json/wbpoll/v1/listpoll

Authentication: Public (returns published polls only)

Response Example:

[
  {
    "id": 140,
    "title": "What is your favorite programming language?",
    "content": "Help us understand which languages are most popular.",
    "date": "2026-01-02 09:58:12",
    "options": [
      { "label": "JavaScript" },
      { "label": "Python" },
      { "label": "PHP" }
    ],
    "start_time": "2026-01-02 09:58:12",
    "end_date": "2026-01-09 09:58:12",
    "never_expire": "no",
    "multivote": "no"
  }
]

Get Poll by ID

Retrieve a specific poll.

POST /wp-json/wbpoll/v1/listpoll/id

Authentication: Public for published polls, owner or admin for drafts and pending polls

Request Body:

{
  "pollid": 140
}

Get User Polls

Retrieve all polls created by a specific user.

POST /wp-json/wbpoll/v1/listpoll/user/id

Authentication: Required (returns own polls unless admin)

Request Body:

Parameter	Type	Description
id	integer	User ID (must match logged-in user unless admin)
status	string	Filter by status: any, publish, draft, pending

Create or Update a Poll

Create a new poll or update an existing one.

POST /wp-json/wbpoll/v1/postpoll

Authentication: Required (must have poll creation permission)

Request Body:

Parameter	Type	Required	Description
title	string	Yes	Poll title or question
content	string	No	Poll description
poll_type	string	No	Type: default, image, video, audio, html
poll_id	integer	No	Poll ID for updates (omit to create new)
_wbpoll_answer	array	Yes	Array of answer option texts
_wbpoll_answer_extra	array	No	Array of answer type metadata
_wbpoll_start_date	string	No	Start date in Y-m-d H:i:s format
_wbpoll_end_date	string	No	End date in Y-m-d H:i:s format
_wbpoll_never_expire	string	No	Set to yes to disable expiration
_wbpoll_multivote	string	No	Set to yes for multi-select
_wbpoll_show_result_before_expire	string	No	Set to yes to show results before voting

Media Fields by Poll Type:

Poll Type	Additional Field	Value
image	_wbpoll_full_size_image_answer	Array of image URLs
video	_wbpoll_video_answer_url	Array of video URLs
audio	_wbpoll_audio_answer_url	Array of audio URLs
html	_wbpoll_html_answer	Array of HTML strings

Text Poll Example:

{
  "title": "What is your favorite color?",
  "content": "Help us pick the theme color.",
  "poll_type": "default",
  "_wbpoll_answer": ["Red", "Blue", "Green"],
  "_wbpoll_never_expire": "yes"
}

Image Poll Example:

{
  "title": "Choose your workspace",
  "poll_type": "image",
  "_wbpoll_answer": ["Minimalist", "Cozy", "Standing Desk"],
  "_wbpoll_answer_extra": ["image", "image", "image"],
  "_wbpoll_full_size_image_answer": [
    "https://example.com/minimalist.jpg",
    "https://example.com/cozy.jpg",
    "https://example.com/standing.jpg"
  ]
}

Success Response:

{
  "success": true,
  "message": "Your poll is published.",
  "post_id": 145,
  "url": "https://yoursite.com/poll/your-poll-slug/"
}

Pause a Poll

Temporarily stop a poll from accepting votes.

POST /wp-json/wbpoll/v1/listpoll/pause/poll

Authentication: Owner or admin

Request Body:

{
  "pollid": 140,
  "_wbpoll_pause_poll": "yes"
}

Set _wbpoll_pause_poll to "no" or omit it to resume the poll.

Delete a Poll

Permanently delete a poll.

POST /wp-json/wbpoll/v1/listpoll/delete/poll

Authentication: Owner or admin

Request Body:

{
  "pollid": 140
}

Unpublish a Poll

Change a poll’s status from published to draft.

POST /wp-json/wbpoll/v1/listpoll/unpublish/poll

Authentication: Owner or admin

Request Body:

{
  "pollid": 140
}

Publish a Poll

Change a poll’s status from draft to published.

POST /wp-json/wbpoll/v1/listpoll/publish/poll

Authentication: Owner or admin

Request Body:

{
  "pollid": 140
}

Get Poll Results

Retrieve detailed voting results for a poll.

POST /wp-json/wbpoll/v1/listpoll/result/poll

Authentication: Owner or admin

Request Body:

{
  "pollid": 140
}

Error Responses

All endpoints return errors in the standard WordPress REST API format:

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

Common Error Codes

Code	Status	Description
rest_not_logged_in	401	User must be logged in
rest_forbidden	403	User lacks permission
rest_invalid_poll	400	Invalid poll ID provided
rest_poll_not_found	404	Poll does not exist
poll_type_disabled	403	Poll type is disabled in settings
poll_create_failed	500	Server error creating poll
poll_delete_failed	400	Failed to delete poll

Code Examples

JavaScript: Fetch All Polls

fetch('/wp-json/wbpoll/v1/listpoll')
  .then(response => response.json())
  .then(polls => console.log(polls));

JavaScript: Create a Poll

fetch('/wp-json/wbpoll/v1/postpoll', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-WP-Nonce': wpApiSettings.nonce
  },
  body: JSON.stringify({
    title: 'My New Poll',
    content: 'Description here',
    poll_type: 'default',
    '_wbpoll_answer': ['Option 1', 'Option 2', 'Option 3'],
    '_wbpoll_never_expire': 'yes'
  })
})
.then(response => response.json())
.then(result => console.log(result));

PHP: Create a Poll

$response = wp_remote_post(
    rest_url( 'wbpoll/v1/postpoll' ),
    array(
        'headers' => array(
            'X-WP-Nonce' => wp_create_nonce( 'wp_rest' )
        ),
        'body' => array(
            'title'          => 'New Poll Question',
            'content'        => 'Poll description',
            '_wbpoll_answer' => array( 'Option 1', 'Option 2', 'Option 3' )
        )
    )
);

$data = json_decode( wp_remote_retrieve_body( $response ), true );

Rate Limiting

The API does not implement rate limiting by default. For production sites with high traffic, consider adding rate limiting through a caching plugin, a security plugin like Wordfence, or server-level configuration with nginx or Cloudflare.