POST Polls

Create or Update Poll

Use this method to create a new poll.

POST /api/v3/{appid}/poll/poll/create

Use this method to create a new poll. If you create a poll with a customID, you can call this method again to update the poll, passing in the same customID. However, if you provide a customID and that is in use already by another poll, you will get an error response.

When creating a poll, provide the desired values. When updating an existing poll, only provide the values to overwrite. To delete a value, pass an empty string.

METADATA

ownerid: (required) The userid of the owner of the poll

DISPLAY PROPERTIES

title: (required) The title of the poll. Required on create. Optional on update.
description: (optional) The description of the poll
pictureurl: (optional) The URL for a picture for the room
embedcontenttop: (optional) Content to be displayed at the top of the poll
embedcontentbottom: (optional) Content to be displayed at the bottom of the poll
displayresults: (optional) [default="aftervote"/always/pollclosed] Use "aftervote" to display results after a vote is over. Set to "always" to return current standings. Set to "pollclosed" to only allow poll results to be disclosed when the poll is closed.
sortchoices: (optional, "random" or "asconfigured", default = "asconfigured") When retrieving the list of response choices they can be displayed in the order you specified or in random order.

BEHAVIOR SETTINGS

allowanonymouspolling: (optional, default=false), if true, allows users to submit responses without a userid value.
allowmultiplechoicesperuser: ("true" or default = "false") If true, the user may submit answers for more than one choice.
maxtotalresponsesperuser: (default = 1). This is the number of times that a user can respond to the poll, the total of all responses regardless of which choice was selected.
maxresponsesperchoiceperuser: (default = 1). The maximum time a user may submit a response per choice. For example you can make it so the user can respond 3 times but must select a different choice with each response, or you could allow the user to vote as many times as desired per choice with all their available responses.

AUTO PUBLISH SETTINGS

whenpollpublish: (optional) [default=now] An ISO-8601 date time. Now by default. If specified, poll is hidden until the specified date and time.
whenpollexpires: (optional) [default=null] An ISO-8601 date time. If specified, the poll transitions to the expired state at this time and is no longer returned by the API (It only exists as archived data).
whenpollopens: (optional) [default=now] An ISO-8601 date time. Now by default. If specified, poll is not open until this time and no one can respond until then.
whenpollcloses: (optional) [default=null] An ISO-8601 date time. Null by default. If specified, poll transitions to closed state at this time and doesn't accept responses.

LEAD CAPTURE

leadcaptureenabled: (optional, default=false) If true, enables lead capture for the poll.
leadcapturerequired: (optional, default=false) If true, makes lead capture required for the poll.
leadcapturename: (optional) If true, captures the name of the lead.
leadcapturetitle: (optional) The title for the lead capture form.
leadcapturedescription: (optional) The description for the lead capture form.
leadcaptureprompt: (optional) The prompt for the lead capture form.

SOCIAL SHARE

socialshareenable: (optional, default=false) If true, enables social sharing for the poll.
socialhandlefacebook: (optional) The Facebook handle for social sharing.
socialhandlex: (optional) The X (formerly Twitter) handle for social sharing.
socialhandletiktok: (optional) The TikTok handle for social sharing.
socialhandlewhatsapp: (optional) The WhatsApp handle for social sharing.
socialcardtitle: (optional) The title for the social card.
socialcardimageurl: (optional) The image URL for the social card.
socialcardurl: (optional) The URL for the social card.

CUSTOM FIELDS

customid: (optional) A customid for the room. Can be unused, or a unique key. If provided, and a poll with that customid is already created this call will update the existing poll.
customtype : (optional) Custom type string.
custompayload : (optional) Custom payload string.
customfield1 : (optional) User custom field 1. Store any string value you want here, limit 1024 bytes.
customfield2 : (optional) User custom field 2. Store any string value you want here, limit 1024 bytes.
customtags : (optional) A comma delimited list of tags

Request

Parameters

Values in the path and query string.

appid path

string TalkLabs ID required

The TalkLabs application ID assigned to your account.

Example: your-app-id

Request

JSON body

Send as application/json.

ownerUserId

string customer-defined

title

string

subtitle

string

description

string

pictureUrl

string

embedContentTop

string

embedContentBottom

string

videoId

string

displayResults

integer · int32

sortChoices

integer · int32

maxTotalResponsesPerUser

integer · int32

The maximum number of votes an individual can cast

allowMultipleChoicesPerUser

boolean

Should users be allowed to vote for more than one response choice

maxResponsesPerChoicePerUser

integer · int32

The maximum number of times a user can vote for a single choice

whenPollPublish

string · date-time

whenPollOpens

string · date-time

whenPollCloses

string · date-time

whenPollExpires

string · date-time

allowAnonymousPolling

boolean

leadCaptureEnabled

boolean

leadCaptureRequired

boolean

leadCaptureName

boolean

leadCaptureTitle

string

leadCaptureDescription

string

leadCapturePrompt

string

socialShareEnable

boolean

socialHandleFacebook

string

socialHandleX

string

socialHandleTikTok

string

socialHandleWhatsApp

string

socialCardTitle

string

socialCardImageUrl

string

socialCardUrl

string

customType

string

customId

string customer-defined

A customer defined ID chosen by your application. TalkLabs stores it so you can retrieve the resource without keeping its TalkLabs ID.

customPayload

string

customField1

string

customField2

string

customTags

string[]

Request example

{
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}

Response

Status codes

Every JSON response uses the API result envelope.

200 OK ApiResult

400 Bad Request ApiResult

403 Forbidden ApiResult

500 Internal Server Error ApiResult

Example response · 200

{
  "message": "Success",
  "errors": {},
  "data": {
    "kind": "poll.poll",
    "id": "662da20fe45ad80a7f2bd950",
    "appid": "662bb49bf10e9a26a7e8ed92",
    "ownerid": "u-8842",
    "title": "Sample Poll 1: Vote for your favorite color",
    "description": "Vote for your favorite color",
    "posterurl": "",
    "embedcontenttop": "",
    "embedcontentbotton": "",
    "whenpollpublish": "2024-04-28T01:10:39.5358368Z",
    "whenpollopens": "2024-04-27T21:10:39.5358872-04:00",
    "whenpollcloses": null,
    "whenpollexpires": null,
    "displayresults": 1,
    "sortanswers": 0,
    "customtype": "",
    "customid": "sample-poll-1-vote",
    "custompayload": "",
    "customtags": [],
    "customfield1": "",
    "customfield2": ""
  }
}

curl --request POST \
  --url "https://api.sportstalk247.com/api/v3/${APP_ID}/poll/poll/create" \
  --header "Accept: application/json" \
  --header "x-api-token: ${TALKLABS_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}'

const appId = process.env.TALKLABS_APP_ID;


const response = await fetch(
  `https://api.sportstalk247.com/api/v3/${appId}/poll/poll/create`,
{
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'x-api-token': process.env.TALKLABS_API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}),
});

const result = await response.json();

import json
import os
import requests

app_id = os.environ["TALKLABS_APP_ID"]


response = requests.post(
    f"https://api.sportstalk247.com/api/v3/{app_id}/poll/poll/create",
    headers={
        "Accept": "application/json",
        "x-api-token": os.environ["TALKLABS_API_TOKEN"],
    },
    json=json.loads(r'''{
  "title": "What is your favorite color?",
  "description": "Vote for your favorite color"
}'''),
)
response.raise_for_status()
result = response.json()

Environment variables TALKLABS_APP_ID TALKLABS_API_TOKEN

Response