Agor API : The Swiss Army Knife of Voting Systems


We are very excited to present you our latest creation: Agor API, a solution to integrate votes and polls on your website or in your software.

What is an API?

An API (Application Programming Interface) is a set of functions that developers create so that other developers can simply use complex tools, methods and algorithms.

The goal is to provide a gateway to a feature by hiding the details of its implementation. The API is therefore a “toolbox” interface that provides services to other softwares. You can use all the functions we have designed, by a simple call to AgorAPI.

Why this product?

API - Slack logo

For the past 2 years, you have been making votes, surveys and polls with our Slack application. With nearly 60,000 users and 35,000 polls, we’ve heard your growing need for quick and simple voting tools. We are fully convinced of the interest that alternative voting systems represent. That is why we have worked tirelessly during the last months to offer you AgorAPI (Agora Polling Interface).

We see endless applications to AgorAPI, but here are a few use cases that we have identified:

This list is obviously not exhaustive, your imagination is the only limit and we look forward to seeing what you will achieve with AgorAPI!

It is available for early access starting today. You are all invited to test it, to see if it fits your needs, and to tell us if anything is missing in the guide or the reference. Early access is expected to last until late summer and we will improve our service throughout this transitional period.

We count on you: the more feedback you will give us, the better AgorAPI will be for its official launch!

The Swiss Army Knife of voting systems


When designing AgorAPI, we kept in mind our goal of creating a complete and flexible tool. As a consequence, AgorAPI allows you to use the most suitable voting system for your poll: the usual majority rule (the choice with the most votes wins) or the Condorcet method (ranked voting leading to a consensual result).

Below is a summary of the main functions offered by AgorAPI:


To ensure security and confidentiality, all requests to the API are identified, by means of a token, allowing full access to your data. So make sure your tokens remain secret!

Creation of a poll

By sending a request containing the title and the different choices of the poll, you generate identifiers (PXXX for the poll, CXXX for the choices that are attached to it). These identifiers will allow you to manage all interactions with the poll (voting, adding choices, closing …).


You have to send a request with the PXXX identifier of the poll and the CXXX’s of the selected choice. It is possible to vote for several choices at the same or at a different preference level (ranked vote), sending the list of desired choices and their respective preference ranks (example: C003 at rank 1, C006 at rank 2, C002 at rank 3)

Displaying results

The results contain the list of choices, sorted by decreasing order of their scores. You can also generate result charts to get crystal clear illustrations of the outcome of the poll.

User management

If the application that uses AgorAPI has users, the API allows you to associate each vote with a user and to ensure that each user has voted only once.

Many additional options are available; from insertion / modification of the choices during poll to anonymization of the votes, we have implemented every function which we could think of to customize your poll. Please read the User Guide and the exhaustive reference to learn how to harness the power of AgorAPI in your projects.

And it’s not over! We will soon enlarge the range of available voting systems so that each of your polls is carried out using the most appropriate method.

Use Case example: website Poll Integration

If you’re still here at this point, I have no doubt you’re going to be interested in this example.
This 10 minutes tutorial will show you how to quickly set up a Condorcet voting interface on your website.


  • PHP 5.4 CLI or newer version installed on your machine
  • Registration to AgorAPI and creation of an API key on your personal space

Open a shell console and start by setting up the API_TOKEN shell variable to your API key value:

[code langage="bash"]

You can check on the validity of your key by sending this simple request:

[code language="bash"]
curl -i -H "Accept: application/json" -H "Content-type: application/json" \
     -X GET "$API_TOKEN"

This should show you the key description that you set up earlier and your used and remaining credits.

You can now create your poll: send the request below after replacing My poll title with your question, and first choice, second choice and third choice with the answers you want to suggest (you can add some others).

[code langage="bash"]
curl -i -H "Accept: application/json" -H "Content-type: application/json" \
     -X POST "$API_TOKEN" \
     -d '{"title": "My poll title", "choices": [{"label": "first choice"}, {"label": "second choice"}, {"label": "third choice"}]}'

This request will send you back a JSON content with a P-starting “id” value on the first line:

[code langage="json"]

Write down this value, you will use it to access the poll you just created in your browser.
You are now ready to integrate the poll in your website.

You have to download and unzip these files:

Then, edit api.ini in the OA folder, and replace <MyApiKey> with your API key value.

[code langage="bash"]
base_url =
token =&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;MyApiKey&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;

Save api.ini and upload all the files in the folder or server of your choice (keep api.ini and CurlClient.php in the OA folder).
If you want to test locally, just launch a PHP server from your console (you must be in the root folder of the files):

[code langage="bash"]
php -S localhost:8888

And here we are ! You can access the vote_index.php via your browser. You have to pass the Poll_id you wrote down earlier in parameter of the

either http://your.domain.url/vote_index.php?id=Poll_id if it is on your online server or localhost:8888/vote_index.php?id=Poll_id if you are running it locally. People who access this page will be able to vote without restriction and to see the current state of the votes.


About Open Agora

Nuanced and targeted consultations

Open Agora solutions allow you to collect rich opinions and easily reach consensus

Leave a comment

Your email address will not be published.