# Polls API Documentation

PollsAPI is a simple API providing you with the ability to integrate Polls in your applications

## Pre-requisites

The first step before you can start using the PollsAPI is signing up and creating an account by going to the [registration page](https://pollsapi.com/login) or logging into the [dashboard](https://pollsapi.com/app) if you already have an account.

Once you're in, your API key should be visible on the dashboard where you can simply copy and paste it to your requests. It is a string of random numbers and letters that looks something like this:

**Example API Key:** `NT6BT3HZYD4BT8IOW3NEBB5DFK1R`

## Getting Started

PollsAPI can be consumed with any programming language, and has been optimized to provide the best performance. Once you have your **API Key** you are ready to start using our APIs.

Our APIs are accessible on the base hostname 

#### **`https://api.pollsapi.com/v1`**

All of our APIs require you to pass the **`api_key`** header and the response is in JSON format.

{% hint style="info" %}
If you plan on using our APIs from backend, you might need to update your firewalls to allow outbound calls to our server. Please contact [**hello@pollsapi.com**](mailto:hello@pollsapi.com) if you face any issues.
{% endhint %}

Now, let's jump into the API functions we have.


# API Introduction

Polls API provides API functions to cover all the scenarios that you may have for integration Polls in your Application.

Here is the list of methods in our API.

* [**Create Poll**](/api/create-poll)
* [**Get Poll by Id**](/api/get-poll-by-id)
* [**Get all Polls**](/api/get-all-polls)
* [**Get all Polls with Identifier**](/api/get-polls-by-identifer)
* [**Remove Poll**](/api/remove-poll)
* [**Add Vote**](/api/add-vote)
* [**Get Vote by Id**](/api/get-vote-by-id)
* [**Get all votes on Poll**](/api/get-all-votes-on-a-poll)
* [**Get all votes by identifier**](/api/get-all-votes-with-identifier)
* [**Delete Vote**](/api/remove-vote)

All of the endpoints require the header **api-key** containing your account's api-key.


# Create poll

API to create a poll

## Fields Information

### **Poll**

| Key                     | Type     | Description                                                         |
| ----------------------- | -------- | ------------------------------------------------------------------- |
| **question** `required` | `string` | The question/title of the Poll                                      |
| **identifier**          | `string` | Can be used to pass in custom identifier, eg - user id, email, etc. |
| **data**                | `object` | A flexible data field to store any meta data with each option       |

### **Option**

**Minimum 2 Options are required in a poll** (Just making the obvious known :sweat\_smile: )

| Key                 | Type     | Description                                                   |
| ------------------- | -------- | ------------------------------------------------------------- |
| **text** `required` | `string` | String to store the option's text                             |
| **data**            | `object` | A flexible data field to store any meta data with each option |

## Creating a Poll

<mark style="color:green;">`POST`</mark> `https://api.pollsapi.com/v1/create/poll`

This endpoint allows you to get free cakes.

#### Headers

| Name         | Type   | Description              |
| ------------ | ------ | ------------------------ |
| Content-Type | string | application/json         |
| api-key      | string | API Key for your account |

#### Request Body

| Name       | Type   | Description                                                                                  |
| ---------- | ------ | -------------------------------------------------------------------------------------------- |
| identifier | string | Can be used to store a custom identifier                                                     |
| data       | object | A flexible data field to store custom metadata                                               |
| question   | string | The question/title of the poll you are creating                                              |
| options    | array  | List of options the poll should have(Min. 2). Please check below for the structure of Option |

{% tabs %}
{% tab title="200 Poll Created" %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "identifier": null,
    "question": "Do you like polls?",
    "data": {},
    "created_at": "2020-10-24T02:28:46.391Z",
    "updated_at": "2020-10-24T02:28:46.391Z",
    "id": "5f93915e7e044c74074f072e",
    "entity": "Poll",
    "options": [
      {
        "text": "Yes",
        "votes_count": 0,
        "data": {},
        "poll_id": "5f93915e7e044c74074f072e",
        "created_at": "2020-10-24T02:28:46.422Z",
        "updated_at": "2020-10-24T02:28:46.422Z",
        "id": "5f93915e7e044c74074f072f",
        "entity": "Option"
      },
      {
        "text": "No",
        "votes_count": 0,
        "data": {},
        "poll_id": "5f93915e7e044c74074f072e",
        "created_at": "2020-10-24T02:28:46.422Z",
        "updated_at": "2020-10-24T02:28:46.422Z",
        "id": "5f93915e7e044c74074f0730",
        "entity": "Option"
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

### Example cURL request

```bash
curl -X POST \
  'https://api.pollsapi.com/v1/create/poll' \
  -H 'content-type: application/json' \
  -H "api-key: $API_KEY" \
  -d '
{
  "question": "Do you like polls?",
  "options": [
    {
      "text": "Yes"
    },
    {
      "text": "No"
    }
  ]
}
'
```

## Request Body

```javascript
{
    "question": "Does this doc help?",
    "identifier": "custom_identifier",
    "data": {
        "custom": "Poll Data"
    }
    "options": [
        {
            "text": "Option Text",
            "data": {
                "custom": "data"
            }
        },
        {
            "text": "Option Text2",
            "data": {
                "custom": "data"
            }
        }
    ]
}
```

##


# Get poll by Id

Endpoint to fetch a Poll by Id

You have a poll created, but how do you fetch it?

Well, this is the reason this endpoint exists:wink:. Just pass in the poll id that you want to retrieve and let the magic happen.

## Get Poll by Id

<mark style="color:blue;">`GET`</mark> `https://api.pollsapi.com/v1/get/poll/{poll_id}`

This endpoint allows you to fetch your poll by ID

#### Path Parameters

| Name     | Type   | Description             |
| -------- | ------ | ----------------------- |
| poll\_id | string | ID of the Poll to fetch |

#### Headers

| Name    | Type   | Description              |
| ------- | ------ | ------------------------ |
| api-key | string | API KEY for your account |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "identifier": null,
    "question": "Do you like polls?",
    "data": {},
    "created_at": "2020-10-24T02:28:46.391Z",
    "updated_at": "2020-10-24T02:28:46.391Z",
    "id": "5f93915e7e044c74074f072e",
    "entity": "Poll",
    "options": [
      {
        "text": "Yes",
        "votes_count": 0,
        "data": {},
        "poll_id": "5f93915e7e044c74074f072e",
        "created_at": "2020-10-24T02:28:46.422Z",
        "updated_at": "2020-10-24T02:28:46.422Z",
        "id": "5f93915e7e044c74074f072f",
        "entity": "Option"
      },
      {
        "text": "No",
        "votes_count": 0,
        "data": {},
        "poll_id": "5f93915e7e044c74074f072e",
        "created_at": "2020-10-24T02:28:46.422Z",
        "updated_at": "2020-10-24T02:28:46.422Z",
        "id": "5f93915e7e044c74074f0730",
        "entity": "Option"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{ 
    "status": "error", 
    "statusCode": 404, 
    "message": "Poll not found" 
}

```

{% endtab %}
{% endtabs %}

### Example cURL Request

```bash
curl https://api.pollsapi.com/v1/get/poll/5f9f7b186477891e5bc646a1 \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY"
```


# Get all polls

Responds with a paginated response of all the polls

You might have a case where you would need to fetch all the Polls and maybe show it as a Feed or maybe for your own Dashboard. You can easily do this with our *get all polls* API. Check it out below on how to use it.

> We love our servers, like everyone else, which is why this API sends our paginated response. You can pass in **offset & limit** to fetch polls in bulk as pages.&#x20;
>
> There is a max limit of 100, so even if you pass *`?limit=150`  it will only send at max 100.*

## Get all polls

<mark style="color:blue;">`GET`</mark> `https://api.pollsapi.com/v1/get/polls?offset=0&limit=25`

This endpoint allows you to get all polls as a paginated response.

#### Query Parameters

| Name   | Type   | Description                              |
| ------ | ------ | ---------------------------------------- |
| offset | number | Number of items to be skipped            |
| limit  | number | Number of items to be fetched (Max: 100) |

#### Headers

| Name    | Type   | Description              |
| ------- | ------ | ------------------------ |
| api-key | string | API Key for your account |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "docs": [
      {
        "data": "null",
        "identifier": null,
        "question": "Do you like polls?",
        "created_at": "2020-11-02T03:20:56.842Z",
        "updated_at": "2020-11-02T03:20:56.842Z",
        "id": "5f9f7b186477891e5bc646a1",
        "entity": "Poll",
        "options": [
          {
            "data": "null",
            "text": "Yes",
            "votes_count": 0,
            "poll_id": "5f9f7b186477891e5bc646a1",
            "created_at": "2020-11-02T03:20:56.872Z",
            "updated_at": "2020-11-02T03:20:56.872Z",
            "id": "5f9f7b186477891e5bc646a2",
            "entity": "Option"
          },
          {
            "data": "null",
            "text": "No",
            "votes_count": 0,
            "poll_id": "5f9f7b186477891e5bc646a1",
            "created_at": "2020-11-02T03:20:56.872Z",
            "updated_at": "2020-11-02T03:20:56.872Z",
            "id": "5f9f7b186477891e5bc646a3",
            "entity": "Option"
          }
        ]
      }
    ],
    "totalDocs": 1,
    "offset": 0,
    "limit": 10,
    "totalPages": 1,
    "page": 1,
    "pagingCounter": 1,
    "hasPrevPage": false,
    "hasNextPage": false,
    "prevPage": null,
    "nextPage": null
  }
}

```

{% endtab %}
{% endtabs %}

### Example cURL Request

```bash
curl https://api.pollsapi.com/v1/get/polls?offset=0&limit=10 \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY"
```


# Get polls by identifer

The custom identifier which is used in poll creation can also be used to retrieve the polls.

The max limit that can be used is 100, anything above it would be disregarded.

> We love our servers, like everyone else, which is why this API sends our paginated response. You can pass in **offset & limit** to fetch polls in bulk as pages.&#x20;
>
> There is a max limit of 100, so even if you pass *`?limit=150`  it will only send at max 100.*

## Get polls by identifier

<mark style="color:blue;">`GET`</mark> `https://api.pollsapi.com/v1/get/polls-with-identifier/{identifier}?offset=0&limit=25`

Fetch all the polls by the custom identifier property

#### Path Parameters

| Name       | Type   | Description                                       |
| ---------- | ------ | ------------------------------------------------- |
| identifier | string | Identifier for which all polls need to be fetched |

#### Query Parameters

| Name   | Type   | Description                                             |
| ------ | ------ | ------------------------------------------------------- |
| offset | number | Number of items to be skipped                           |
| limit  | number | Number of items to be fetched, default is 25 (Max: 100) |

#### Headers

| Name    | Type   | Description              |
| ------- | ------ | ------------------------ |
| api-key | string | API Key for your account |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "docs": [],
    "totalDocs": 0,
    "offset": 0,
    "limit": 25,
    "totalPages": 1,
    "page": 1,
    "pagingCounter": 1,
    "hasPrevPage": false,
    "hasNextPage": false,
    "prevPage": null,
    "nextPage": null
  }
}

```

{% endtab %}
{% endtabs %}

### Example cURL Request

```bash
curl https://api.pollsapi.com/v1/get/polls-with-identifier \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY"
```


# Create Vote

Add a vote to an option

Now that you have a Poll with some options, let's go ahead and add vote to it.

## Add vote to an option in a poll

<mark style="color:green;">`POST`</mark> `https://api.pollsapi.com/v1/create/vote`

This endpoint helps you add a vote to an option

#### Headers

| Name         | Type   | Description              |
| ------------ | ------ | ------------------------ |
| Content-Type | string | application/json         |
| api-key      | string | API Key for your account |

#### Request Body

| Name       | Type   | Description                                            |
| ---------- | ------ | ------------------------------------------------------ |
| poll\_id   | string | ID of the Poll on which the vote will be added         |
| option\_id | string | ID of the Option the vote will be on                   |
| identifier | string | Custom field that can be used to store some identifier |

{% tabs %}
{% tab title="200 Poll Created" %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "identifier": "user_12",
    "poll_id": "5f9f7b186477891e5bc646a1",
    "option_id": "5f9f7b186477891e5bc646a2",
    "created_at": "2020-11-02T06:24:24.760Z",
    "updated_at": "2020-11-02T06:24:24.760Z",
    "id": "5f9fa6186477891e5bc646a5",
    "entity": "Vote"
  }
}



```

{% endtab %}
{% endtabs %}

### Example cURL Request

```bash
curl -X POST https://api.pollsapi.com/v1/create/vote \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY" \
  -d '
  {
      "poll_id": "5f9f7b186477891e5bc646a1",
      "option_id": "5f9f7b186477891e5bc646a2",
      "identifier": "user_12"
  }
  '
```

### Request Body

```javascript
{
    "poll_id": "5f9f7b186477891e5bc646a1",
    "option_id": "5f9f7b186477891e5bc646a2",
    "identifier": "user_12"
}
```


# Get Vote by Id

With this API you can retrieve a particular vote by it's Id

## Get Vote by Id

<mark style="color:blue;">`GET`</mark> `https://api.pollsapi.com/v1/get/vote/{vote_id}`

This endpoint allows you to fetch your vote by ID

#### Path Parameters

| Name     | Type   | Description             |
| -------- | ------ | ----------------------- |
| vote\_id | string | ID of the Poll to fetch |

#### Headers

| Name    | Type   | Description              |
| ------- | ------ | ------------------------ |
| api-key | string | API KEY for your account |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "identifier": "user_12",
    "poll_id": "5f9f7b186477891e5bc646a1",
    "option_id": "5f9f7b186477891e5bc646a2",
    "created_at": "2020-11-02T06:24:24.760Z",
    "updated_at": "2020-11-02T06:24:24.760Z",
    "id": "5f9fa6186477891e5bc646a5",
    "entity": "Vote"
  }
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{ 
    "status": "error", 
    "statusCode": 404, 
    "message": "Vote not found" 
}

```

{% endtab %}
{% endtabs %}

### Example cURL Request

```bash
curl https://api.pollsapi.com/v1/get/vote/5f9fa6186477891e5bc646a5 \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY"
```


# Get all votes on a poll

Fetch all the votes on a poll as a paginated response

Having all the information is great, with Polls API you can get all the Votes on the polls easily.

> We love our servers, like everyone else, which is why this API sends our paginated response. You can pass in **offset & limit** to fetch votes in bulk as pages.&#x20;
>
> There is a max limit of 100, so even if you pass *`?limit=150`  it will only send at max 100.*

## Get all votes

<mark style="color:blue;">`GET`</mark> `https://api.pollsapi.com/v1/get/votes/{poll_id}?offset=0&limit=25`

This endpoint allows you to fetch paginated response for all the Votes on a poll.

#### Path Parameters

| Name     | Type   | Description    |
| -------- | ------ | -------------- |
| poll\_id | string | ID of the Poll |

#### Query Parameters

| Name   | Type   | Description                              |
| ------ | ------ | ---------------------------------------- |
| offset | number | Number of items to be skipped            |
| limit  | number | Number of items to be fetched (Max: 100) |

#### Headers

| Name    | Type   | Description              |
| ------- | ------ | ------------------------ |
| api-key | string | API Key for your account |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "docs": [
      {
        "identifier": "user_12",
        "poll_id": "5f9f7b186477891e5bc646a1",
        "option_id": "5f9f7b186477891e5bc646a2",
        "created_at": "2020-11-02T06:24:24.760Z",
        "updated_at": "2020-11-02T06:24:24.760Z",
        "id": "5f9fa6186477891e5bc646a5",
        "entity": "Vote"
      }
    ],
    "totalDocs": 1,
    "offset": 0,
    "limit": 10,
    "totalPages": 1,
    "page": 1,
    "pagingCounter": 1,
    "hasPrevPage": false,
    "hasNextPage": false,
    "prevPage": null,
    "nextPage": null
  }
}

```

{% endtab %}
{% endtabs %}

### Example cURL Request

```bash
curl https://api.pollsapi.com/v1/get/votes/5f93915e7e044c74074f072e?offset=0&limit=10 \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY"
```


# Get all votes with identifier

Retrieve all the votes by using the custom identifier property

> We love our servers, like everyone else, which is why this API sends our paginated response. You can pass in **offset & limit** to fetch votes in bulk as pages.&#x20;
>
> There is a max limit of 100, so even if you pass *`?limit=150`  it will only send at max 100.*

## Get all votes

<mark style="color:blue;">`GET`</mark> `https://api.pollsapi.com/v1/get/votes-with-identifier/{identifier}?offset=0&limit=25`

This endpoint allows you to fetch paginated response for all the Votes on a poll.

#### Path Parameters

| Name       | Type   | Description                               |
| ---------- | ------ | ----------------------------------------- |
| identifier | string | Custom identifier used to create the vote |

#### Query Parameters

| Name   | Type   | Description                              |
| ------ | ------ | ---------------------------------------- |
| offset | number | Number of items to be skipped            |
| limit  | number | Number of items to be fetched (Max: 100) |

#### Headers

| Name         | Type   | Description              |
| ------------ | ------ | ------------------------ |
| Content-Type | string | application/json         |
| api-key      | string | API Key for your account |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "status": "success",
  "statusCode": 200,
  "data": {
    "docs": [
      {
        "identifier": "user_12",
        "poll_id": "5f9f7b186477891e5bc646a1",
        "option_id": "5f9f7b186477891e5bc646a2",
        "created_at": "2020-11-02T06:24:24.760Z",
        "updated_at": "2020-11-02T06:24:24.760Z",
        "id": "5f9fa6186477891e5bc646a5",
        "entity": "Vote"
      }
    ],
    "totalDocs": 1,
    "offset": 0,
    "limit": 10,
    "totalPages": 1,
    "page": 1,
    "pagingCounter": 1,
    "hasPrevPage": false,
    "hasNextPage": false,
    "prevPage": null,
    "nextPage": null
  }
}

```

{% endtab %}
{% endtabs %}

### Example cURL Request

```bash
curl "https://api.pollsapi.com/v1/get/votes-with-identifier/user_12" \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY"
```


# Remove vote

Delete a vote from an option on a poll

Delete the vote by the ID

## Delete Vote

<mark style="color:green;">`POST`</mark> `https://api.pollsapi.com/v1/remove/vote`

#### Headers

| Name         | Type   | Description              |
| ------------ | ------ | ------------------------ |
| Content-Type | string | application/json         |
| api-key      | string | API Key for your account |

#### Request Body

| Name     | Type   | Description                  |
| -------- | ------ | ---------------------------- |
| vote\_id | string | ID of the poll to be deleted |

{% tabs %}
{% tab title="200 " %}

```javascript
{ 
    "status": "success", 
    "statusCode": 200, 
    "data": true 
}

```

{% endtab %}
{% endtabs %}

```bash
curl -X POST https://api.pollsapi.com/v1/remove/vote \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY" \
  -d '
  {
      "vote_id": "5f9fa6186477891e5bc646a5"
  }
'
```

### Request Body

```bash
{
    "vote_id": "5f9fa6186477891e5bc646a5"
}
```


# Remove Poll

Delete the poll

Deleting a Poll will remove all the data for the Poll including the Options and Votes.

## Delete Poll

<mark style="color:green;">`POST`</mark> `https://api.pollsapi.com/v1/remove/poll`

#### Headers

| Name         | Type   | Description              |
| ------------ | ------ | ------------------------ |
| Content-Type | string | application/json         |
| api-key      | string | API Key for your account |

#### Request Body

| Name     | Type   | Description                  |
| -------- | ------ | ---------------------------- |
| poll\_id | string | ID of the poll to be deleted |

{% tabs %}
{% tab title="200 " %}

```javascript
{ 
    "status": "success", 
    "statusCode": 200, 
    "data": true 
}

```

{% endtab %}
{% endtabs %}

```bash
curl -X POST https://api.pollsapi.com/v1/remove/poll \
  -H "content-type: application/json" \
  -H "api-key: $API_KEY" \
  -d '
  {
      "poll_id": "5f9f7b186477891e5bc646a1"
  }
'
```

### Request Body

```bash
{
    "poll_id": "5f9f7b186477891e5bc646a1"
}
```