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
searchstringOptional

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

partnerIds[]string · uuid[]Optional

Filter by partner ids that polls have been created for

ids[]string · uuid[]Optional

Filter by poll ids

quorumReachedbooleanOptional

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

boundbooleanOptional

Filter by poll binding, should the poll outcome be respected

disclosedAt[from]string · date-timeOptional

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

Example: 2022-03-29T12:30:33
disclosedAt[to]string · date-timeOptional

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

Example: 2022-03-29T14:30:33
publicationDate[from]string · date-timeOptional

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

publicationDate[to]string · date-timeOptional

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

openAt[from]string · date-timeOptional

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

openAt[to]string · date-timeOptional

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

closeAt[from]string · date-timeOptional

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

closeAt[to]string · date-timeOptional

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

pageinteger · integerOptional
limitinteger · integerOptional
orderBystringOptional
cursorstringOptional
directionstring · enumOptionalPossible values:
Responses
200
Search for polls succeeded for GET /poll/polls
application/json
get
GET /polls/1.0.8/polls HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200

Search for polls succeeded for GET /poll/polls

{
  "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"
  }
}

Endpoint to get a single poll by id

get
Authorizations
Path parameters
pollIdstringRequired

Poll Id to be retrieved

Responses
200
Success response
application/json
get
GET /polls/1.0.8/poll/{pollId} HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200

Success response

{
  "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"
  }
}
Deprecated

DEPRECATED - Vote on a poll

post
Authorizations
Path parameters
pollIdstringRequired

Poll Id to vote for

Body
answerIdstring · uuidRequiredExample: 35de3eda-fc2f-4f15-be0a-17cbdef6630f
Responses
201
AnswerVote Created successfully on POST /poll/{pollId}/vote
post
POST /polls/1.0.8/user/poll/{pollId}/vote HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "answerId": "35de3eda-fc2f-4f15-be0a-17cbdef6630f"
}

No content

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

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

get
Authorizations
Path parameters
pollIdstringRequired

Poll Id to be retrieved

Responses
200
Success response
application/json
get
GET /polls/1.0.8/user/poll/{pollId} HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200

Success response

{
  "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"
  }
}
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

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

get
Authorizations
Query parameters
searchstringOptional

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

partnerIds[]string · uuid[]Optional

Filter by partner ids that polls have been created for

ids[]string · uuid[]Optional

Filter by poll ids

quorumReachedbooleanOptional

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

boundbooleanOptional

Filter by poll binding, should the poll outcome be respected

userVotedbooleanOptional

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.

disclosedAt[from]string · date-timeOptional

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

Example: 2022-03-29T12:30:33
disclosedAt[to]string · date-timeOptional

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

Example: 2022-03-29T14:30:33
publicationDate[from]string · date-timeOptional

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

publicationDate[to]string · date-timeOptional

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

openAt[from]string · date-timeOptional

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

openAt[to]string · date-timeOptional

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

closeAt[from]string · date-timeOptional

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

closeAt[to]string · date-timeOptional

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

pageinteger · integerOptional
limitinteger · integerOptional
orderBystringOptional
cursorstringOptional
directionstring · enumOptionalPossible values:
Responses
200
Search for user polls succeeded for GET /user/polls
application/json
get
GET /polls/1.0.8/user/polls HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200

Search for user polls succeeded for GET /user/polls

{
  "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"
  }
}

Deprecated

DEPRECATED - Endpoint to get a list of user polls history

get
Authorizations
Query parameters
searchstringOptional

Search by poll question text

pageinteger · integerOptional
limitinteger · integerOptional
orderBystringOptional
cursorstringOptional
directionstring · enumOptionalPossible values:
Responses
200
Search for user polls succeeded for GET /user/polls/history
application/json
get
GET /polls/1.0.8/user/polls/history HTTP/1.1
Host: api-public.socios.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
200

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

{
  "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"
  }
}

Last updated