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

HTTPcURLJavaScriptPython

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

REMOVED WITH NO ALTERNATIVE AVAILABLE

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

HTTPcURLJavaScriptPython

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

400

Bad Request

application/json

post

HTTPcURLJavaScriptPython

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

⬇️ 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

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

HTTPcURLJavaScriptPython

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

⬇️ 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

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

HTTPcURLJavaScriptPython

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

REMOVED WITH NO ALTERNATIVE AVAILABLE

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

HTTPcURLJavaScriptPython

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

REMOVED WITH NO ALTERNATIVE AVAILABLE