Polls API endpoints

The latest documentation for endpoint is always on the DevPortal: https://partner.socios.com/devportal/apis/d93ca9b9-6e1f-4ec7-813e-a4e8c3c1d658/test

Endpoint to get a list of polls using search filters

get

Authorizations

Query parameters

searchstring

Filter by poll question text, accepts parts of question text as well

partnerIds[]string · uuid[]

Filter by partner ids that polls have been created for

ids[]string · uuid[]

Filter by poll ids

quorumReachedboolean

Filter polls by voting quorum achievement. * e.g. true = required percentage of votes for the poll is achieved

boundboolean

Filter by poll binding, should the poll outcome be respected

types[]string · enum[]

Filter by types of a poll, defaults to engagement and integrity

statuses[]string · enum[]

Filter by poll statuses

disclosedAt[from]string · date-time

Filter by date and time when poll results were disclosed [from specific date]

Example: 2022-03-29T12:30:33

disclosedAt[to]string · date-time

Filter by date and time when poll results were disclosed [up to specific date]

Example: 2022-03-29T14:30:33

publicationDate[from]string · date-time

Filter by date and time when poll was published [from specific date]

publicationDate[to]string · date-time

Filter by date and time when poll was published [up to specific date]

openAt[from]string · date-time

Filter by date and time when poll opened [from specific date]

openAt[to]string · date-time

Filter by date and time when poll opened [up to specific date]

closeAt[from]string · date-time

Filter by date and time when poll got closed [from specific date]

closeAt[to]string · date-time

Filter by date and time when poll got closed [up to specific date]

orderBy[]string · enum[]

Order results by date column

pageinteger · integer

limitinteger · integer

orderBystring

cursorstring

directionstring · enum

Options: asc, ASC, DESC, desc

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api-public.socios.com/polls/1.0.8/polls'

200

200

{
  "data": {
    "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerId": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerName": "Example name",
    "partnerImages": [
      {
        "url": "https://url.com/partner/d66eb9d2-56c6-4b1b-8f56-31f8aa319abe/partner_logo/38aca876-86a8-4a10-a0e8-b0859614c8b3.png?version=1653577420",
        "type": "png",
        "format": "desktop",
        "width": "500",
        "height": "500"
      }
    ],
    "question": "What skins should Team Vitality play game 2 of MSI?",
    "openAt": "text",
    "publicationDate": "text",
    "closeAt": "text",
    "disclosedAt": "text",
    "type": "engagement",
    "isBound": true,
    "isQuorumReached": true,
    "quorum": "0.2",
    "currentQuorumPercentage": "0.2",
    "usedTokenCount": 4,
    "tokenLimit": 3000,
    "status": "cancelled",
    "information": "Lorem ipsum",
    "answers": [
      {
        "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
        "answer": "We should go west!",
        "votePercentage": "15.7",
        "totalVoteTokensUsed": 15,
        "statistics": {
          "uniqueAnswerVoteCount": 2
        }
      }
    ],
    "statistics": {
      "uniqueVoteCount": 2
    },
    "blockchainAddress": "0x000000000000000"
  }
}

Search for polls succeeded for GET /poll/polls

REMOVED WITH NO ALTERNATIVE AVAILABLE

Endpoint to get a single poll by id

get

Authorizations

Path parameters

pollIdstringrequired

Poll Id to be retrieved

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api-public.socios.com/polls/1.0.8/poll/{pollId}'

200

200

{
  "data": {
    "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerId": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerName": "Example name",
    "partnerImages": [
      {
        "url": "https://url.com/partner/d66eb9d2-56c6-4b1b-8f56-31f8aa319abe/partner_logo/38aca876-86a8-4a10-a0e8-b0859614c8b3.png?version=1653577420",
        "type": "png",
        "format": "desktop",
        "width": "500",
        "height": "500"
      }
    ],
    "question": "What skins should Team Vitality play game 2 of MSI?",
    "openAt": "text",
    "publicationDate": "text",
    "closeAt": "text",
    "disclosedAt": "text",
    "type": "engagement",
    "isBound": true,
    "isQuorumReached": true,
    "quorum": "0.2",
    "currentQuorumPercentage": "0.2",
    "usedTokenCount": 4,
    "tokenLimit": 3000,
    "status": "cancelled",
    "information": "Lorem ipsum",
    "answers": [
      {
        "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
        "answer": "We should go west!",
        "votePercentage": "15.7",
        "totalVoteTokensUsed": 15,
        "statistics": {
          "uniqueAnswerVoteCount": 2
        }
      }
    ],
    "statistics": {
      "uniqueVoteCount": 2
    },
    "blockchainAddress": "0x000000000000000"
  }
}

Success response

DEPRECATED - Vote on a poll

post

Deprecated

Authorizations

Path parameters

pollIdstringrequired

Poll Id to vote for

Body

answerIdstring · uuidrequired

Example: 35de3eda-fc2f-4f15-be0a-17cbdef6630f

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api-public.socios.com/polls/1.0.8/user/poll/{pollId}/vote' \
  --header 'Content-Type: application/json' \
  --data '{
    "answerId": "35de3eda-fc2f-4f15-be0a-17cbdef6630f"
  }'

201

400

201

No body

AnswerVote Created successfully on POST /poll/{pollId}/vote

⬇️ ALTERNATIVE: Allow a user to vote on a specific poll ⬇️

import { createWalletClient, privateKeyToAccount } from 'viem';

const privateKey = '0xSenderPrivateKey'; // Replace with the sender's private key
const account = privateKeyToAccount(privateKey);

const walletClient = createWalletClient({
  account,
  transport: http('https://rpc.ankr.com/chiliz'),
});

async function vote(id, weight) {
  const txHash = await walletClient.writeContract({
    address: '0xPollAddress', // Replace with the poll contract address
    abi: survey3ABI, // Poll contract ABI
    functionName: 'vote', // Function to cast the vote
    args: [id, BigInt(weight)], // Replace 'id' with answer id and 'weight' with the amount of tokens that should be used to cast the vote
  });
  return txHash;
}

// Example usage
vote('dab3d446-959f-47e7-8789-f618d969de1e', 1).then(console.log);

DEPRECATED - Endpoint to get a single poll by id & userId

get

Deprecated

Authorizations

Path parameters

pollIdstringrequired

Poll Id to be retrieved

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api-public.socios.com/polls/1.0.8/user/poll/{pollId}'

200

200

{
  "data": {
    "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerId": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerName": "Example name",
    "partnerImages": [
      {
        "url": "https://url.com/partner/d66eb9d2-56c6-4b1b-8f56-31f8aa319abe/partner_logo/38aca876-86a8-4a10-a0e8-b0859614c8b3.png?version=1653577420",
        "type": "png",
        "format": "desktop",
        "width": "500",
        "height": "500"
      }
    ],
    "question": "What skins should Team Vitality play game 2 of MSI?",
    "openAt": "text",
    "closeAt": "text",
    "publicationDate": "text",
    "disclosedAt": "text",
    "isBound": true,
    "isQuorumReached": true,
    "quorum": "0.2",
    "currentQuorumPercentage": "0.2",
    "usedTokenCount": 4,
    "tokenLimit": 3000,
    "status": "cancelled",
    "information": "Lorem ipsum",
    "answers": [
      {
        "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
        "answer": "We should go west!",
        "votePercentage": "15.7",
        "totalVoteTokensUsed": 15,
        "statistics": {
          "uniqueAnswerVoteCount": 2
        },
        "voteStatus": "rejected"
      }
    ],
    "statistics": {
      "uniqueVoteCount": 2
    },
    "userVote": true,
    "blockchainAddress": "0x000000000000000"
  }
}

Success response

⬇️ ALTERNATIVE: Retrieve user vote on a specific poll ⬇️

import { createPublicClient, http, keccak256 } from 'viem';
import { abi as survey3ABI } from './Survey3ABI.json';

const client = createPublicClient({
  transport: http('https://rpc.ankr.com/chiliz'),
});

const pollAddress = '0xPollAddress'; // Replace with the actual poll contract address
const userAddress = '0xUserAddress'; // Replace with the user's wallet address

// Returns hashes of answerIds that the user voted on
async function getUserVoteHashes() {
  const votes = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getUserAnswers', // Function to retrieve the answers that the user voted on
    args: [userAddress], // User's address whose votes you want to fetch
  });
  return votes;
}

// Returns votes in plain text
async function getUserVotesPlainText() {
  // fetch all answers
  const answers = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getAnswers', // Function to retrieve the answers
    args: [], // User's address whose votes you want to fetch
  });

  // fetch user's votes
  const votes = await client.readContract({
    address: pollAddress, // Poll contract address
    abi: survey3ABI, // Poll conttract ABI
    functionName: 'getUserAnswers', // Function to retrieve the answers that the user voted on
    args: [userAddress], // User's address whose votes you want to fetch
  });

  // filter answers, return the ones that the user voted on
  const plainTextVotes = answers.filter(a => votes.includes(keccak256(a.id)));

  return plainTextVotes;
}

// Example usage
getUserVotesPlainText().then(console.log);
getUserVoteHashes().then(console.log);

DEPRECATED - Endpoint to get a list of polls using search filters

get

Deprecated

Authorizations

Query parameters

searchstring

Filter by poll question text, accepts parts of question text as well

partnerIds[]string · uuid[]

Filter by partner ids that polls have been created for

ids[]string · uuid[]

Filter by poll ids

quorumReachedboolean

Filter polls by voting quorum achievement. * e.g. true = required percentage of votes for the poll is achieved

boundboolean

Filter by poll binding, should the poll outcome be respected

userVotedboolean

Only list polls where the user has voted (only used when listing polls for a user). * Providing value false will give the same response as value true.

voteStatuses[]string · enum[]

Filter polls by statuses of voting answers

types[]string · enum[]

Filter by types of a poll, defaults to engagement and integrity

statuses[]string · enum[]

Filter by poll statuses

disclosedAt[from]string · date-time

Filter by date and time when poll results were disclosed [from specific date]

Example: 2022-03-29T12:30:33

disclosedAt[to]string · date-time

Filter by date and time when poll results were disclosed [up to specific date]

Example: 2022-03-29T14:30:33

publicationDate[from]string · date-time

Filter by date and time when poll was published [from specific date]

publicationDate[to]string · date-time

Filter by date and time when poll was published [up to specific date]

openAt[from]string · date-time

Filter by date and time when poll opened [from specific date]

openAt[to]string · date-time

Filter by date and time when poll opened [up to specific date]

closeAt[from]string · date-time

Filter by date and time when poll got closed [from specific date]

closeAt[to]string · date-time

Filter by date and time when poll got closed [up to specific date]

orderBy[]string · enum[]

Order results by date column

pageinteger · integer

limitinteger · integer

orderBystring

cursorstring

directionstring · enum

Options: asc, ASC, DESC, desc

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api-public.socios.com/polls/1.0.8/user/polls'

200

200

{
  "data": {
    "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerId": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerName": "Example name",
    "partnerImages": [
      {
        "url": "https://url.com/partner/d66eb9d2-56c6-4b1b-8f56-31f8aa319abe/partner_logo/38aca876-86a8-4a10-a0e8-b0859614c8b3.png?version=1653577420",
        "type": "png",
        "format": "desktop",
        "width": "500",
        "height": "500"
      }
    ],
    "question": "What skins should Team Vitality play game 2 of MSI?",
    "openAt": "text",
    "closeAt": "text",
    "publicationDate": "text",
    "disclosedAt": "text",
    "isBound": true,
    "isQuorumReached": true,
    "quorum": "0.2",
    "currentQuorumPercentage": "0.2",
    "usedTokenCount": 4,
    "tokenLimit": 3000,
    "status": "cancelled",
    "information": "Lorem ipsum",
    "answers": [
      {
        "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
        "answer": "We should go west!",
        "votePercentage": "15.7",
        "totalVoteTokensUsed": 15,
        "statistics": {
          "uniqueAnswerVoteCount": 2
        },
        "voteStatus": "rejected"
      }
    ],
    "statistics": {
      "uniqueVoteCount": 2
    },
    "userVote": true,
    "blockchainAddress": "0x000000000000000"
  }
}

Search for user polls succeeded for GET /user/polls

REMOVED WITH NO ALTERNATIVE AVAILABLE

DEPRECATED - Endpoint to get a list of user polls history

get

Deprecated

Authorizations

Query parameters

searchstring

Search by poll question text

pageinteger · integer

limitinteger · integer

orderBystring

cursorstring

directionstring · enum

Options: asc, ASC, DESC, desc

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api-public.socios.com/polls/1.0.8/user/polls/history'

200

200

{
  "data": {
    "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerId": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
    "partnerName": "Example name",
    "partnerImages": [
      {
        "url": "https://url.com/partner/d66eb9d2-56c6-4b1b-8f56-31f8aa319abe/partner_logo/38aca876-86a8-4a10-a0e8-b0859614c8b3.png?version=1653577420",
        "type": "png",
        "format": "desktop",
        "width": "500",
        "height": "500"
      }
    ],
    "question": "What skins should Team Vitality play game 2 of MSI?",
    "openAt": "text",
    "closeAt": "text",
    "publicationDate": "text",
    "disclosedAt": "text",
    "isBound": true,
    "isQuorumReached": true,
    "quorum": "0.2",
    "currentQuorumPercentage": "0.2",
    "usedTokenCount": 4,
    "tokenLimit": 3000,
    "status": "cancelled",
    "information": "Lorem ipsum",
    "answers": [
      {
        "id": "35de3eda-fc2f-4f15-be0a-17cbdef6630f",
        "answer": "We should go west!",
        "votePercentage": "15.7",
        "totalVoteTokensUsed": 15,
        "statistics": {
          "uniqueAnswerVoteCount": 2
        },
        "voteStatus": "rejected"
      }
    ],
    "statistics": {
      "uniqueVoteCount": 2
    },
    "userVote": true,
    "blockchainAddress": "0x000000000000000"
  }
}

Search for user polls succeeded for GET /user/polls/history

REMOVED WITH NO ALTERNATIVE AVAILABLE