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)
wbpollanswer	array	Yes	Array of answer option texts
wbpollanswer_extra	array	No	Array of answer type metadata
wbpollstart_date	string	No	Start date in Y-m-d H:i:s format
wbpollend_date	string	No	End date in Y-m-d H:i:s format
wbpollnever_expire	string	No	Set to yes to disable expiration
wbpollmultivote	string	No	Set to yes for multi-select
wbpollshowresultbefore_expire	string	No	Set to yes to show results before voting

Media Fields by Poll Type:

Poll Type	Additional Field	Value
image	wbpollfullsizeimage_answer	Array of image URLs
video	wbpollvideoanswerurl	Array of video URLs
audio	wbpollaudioanswerurl	Array of audio URLs
html	wbpollhtml_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 wbpollpause_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
restnotlogged_in	401	User must be logged in
rest_forbidden	403	User lacks permission
restinvalidpoll	400	Invalid poll ID provided
restpollnot_found	404	Poll does not exist
polltypedisabled	403	Poll type is disabled in settings
pollcreatefailed	500	Server error creating poll
polldeletefailed	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.