NAV
ruby python php

Introduction

Welcome to the API documentation for ElectionBuddy. If you are looking for our Voting Integrations (i.e. "voter SSO") documentation, please head to integrations.electionbuddy.com.
ElectionBuddy provides application programming interface following the REST architecture. Through this interface, it is possible to communicate with the ElectionBuddy system.

Versioning

Currently, two API versions are supported. The endpoint for Version 1 ("V1") is https://electionbuddy.com/api/v1 and the endpoint for Version 2 ("V2") is https://secure.electionbuddy.com/api/v2.

Authentication

You authenticate to our APIs using an API key. This key identifies yourself and your organization and grants permission on behalf of your organization.
You must send the API key on every request. The API key must be sent as an HTTP (Request) Authorization header.
The API key is listed on your organization's Edit page under Integrations tab > Organization Authorization Key.

Responses

All responses are properly structured JSON.

Version 1

Organizations

Identifier

identifier is listed on your organization's Edit page under Integrations tab > Organization id and must be included in the URL.
For example, for the create_user endpoint, replace YOUR_ID_HERE with your ID in the following:
https://electionbuddy.com/api/v1/organizations/YOUR_ID_HERE/create_user.
This ID tells the system which organization the request pertains to.

Create user

  require 'uri'
  require 'net/http'
  require 'json'

  url = URI("https://electionbuddy.com/api/v1/organizations/3/create_user")

  http = Net::HTTP.new(url.host, url.port)

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP'
  request["content-type"] = 'application/json'
  request.body = {
    first_name: "Aria",
    last_name: "Stark",
    email: "aria.stark@wolf.com",
    password: "123456",
    job_title: "Director",
    role: "member"
  }.to_json

  response = http.request(request)

import http.client

conn = http.client.HTTPConnection("electionbuddy.com")

params = {
  "first_name": "Aria",
  "last_name": "Stark",
  "email": "aria.stark@wolf.com",
  "password": "123456",
  "job_title": "Director",
  "role": "member"
}

payload = json.dumps(params)

headers = {'authorization': "krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP"}

conn.request("POST", "/api/v1/organizations/3/create_user", payload, headers)

$request = new HttpRequest();
$request->setUrl('https://electionbuddy.com/api/v1/organizations/3/create_user');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP'
));

$request->setBody('{
  "first_name": "Aria",
  "last_name": "Stark",
  "email": "aria.stark@wolf.com",
  "password": "123456",
  "job_title": "Director",
  "role": "member"
}');

try {
  $response = $request->send();
} catch (HttpException $ex) {
  echo $ex;
}

Successful request (200 OK)

{
  "organization": {
    "id": 3,
    "name": "Organization",
    "users": [
      {
        "id": 1,
        "email": "aria.stark@wolf.com",
        "first_name": "Aria",
        "last_name": "Stark",
        "job_title": "Director"
      }
    ]
  }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "errors": [
    {
      "message": "password must be filled"
    }
  ]
}

This endpoint creates a brand new user and associates it with the organization (as per the identifier in the URL).

HTTP Request

POST https://electionbuddy.com/api/v1/organizations/:id/create_user

Body Parameters

Parameter Required Description
first_name true User first name.
last_name true User last name.
email true User email. This must be unique throughout the system.
password true User password. This needs to be at least 6 characters long.
job_title false Job title for the user.
role true Role that the user plays in the organization. Possible values are "member" and "administrator".

Add user

  require 'uri'
  require 'net/http'
  require 'json'

  url = URI("https://electionbuddy.com/api/v1/organizations/3/add_user")

  http = Net::HTTP.new(url.host, url.port)

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP'
  request["content-type"] = 'application/json'
  request.body = {
    email: "aria.stark@wolf.com",
    role: "member"
  }.to_json

  response = http.request(request)

import http.client

conn = http.client.HTTPConnection("electionbuddy.com")

params = {
  "email": "aria.stark@wolf.com",
  "role": "member"
}

payload = json.dumps(params)

headers = {'authorization': "krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP"}

conn.request("POST", "/api/v1/organizations/3/add_user", payload, headers)

$request = new HttpRequest();
$request->setUrl('https://electionbuddy.com/api/v1/organizations/3/add_user');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP'
));

$request->setBody('{
  "email": "aria.stark@wolf.com",
  "role": "member"
}');

try {
  $response = $request->send();
} catch (HttpException $ex) {
  echo $ex;
}

Successful request (200 OK)

{
  "organization": {
    "id": 3,
    "name": "Organization",
    "users": [
      {
        "id": 1,
        "email": "aria.stark@wolf.com",
        "first_name": "Aria",
        "last_name": "Stark",
        "job_title": "Director"
      }
    ]
  }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "errors": [
    {
      "message": "email is in invalid format"
    }
  ]
}

This endpoint adds an existing user to the organization.

HTTP Request

POST https://electionbuddy.com/api/v1/organizations/:id/add_user

Body Parameters

Parameter Required Description
email true User email. The user with this email must exist and must not belong to the organization already.
role true Role that the user plays in the organization. Possible values are "member" and "administrator".

Remove user

  require 'uri'
  require 'net/http'
  require 'json'

  url = URI("https://electionbuddy.com/api/v1/organizations/3/remove_user")

  http = Net::HTTP.new(url.host, url.port)

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP'
  request["content-type"] = 'application/json'
  request.body = {
    email: "aria.stark@wolf.com"
  }.to_json

  response = http.request(request)

import http.client

conn = http.client.HTTPConnection("electionbuddy.com")

params = {
  "email": "aria.stark@wolf.com"
}

payload = json.dumps(params)

headers = {'authorization': "krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP"}

conn.request("POST", "/api/v1/organizations/3/remove_user", payload, headers)

$request = new HttpRequest();
$request->setUrl('https://electionbuddy.com/api/v1/organizations/3/remove_user');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'authorization' => 'krguLcynqwCGDucHmrBgcHCq8D9HgRoUHUhNfKvP'
));

$request->setBody('{
  "email": "aria.stark@wolf.com"
}');

try {
  $response = $request->send();
} catch (HttpException $ex) {
  echo $ex;
}

Successful request (200 OK)

{
  "organization": {
    "id": 3,
    "name": "Organization",
    "users": [
      {
        "id": 1,
        "email": "aria.stark@wolf.com",
        "first_name": "Aria",
        "last_name": "Stark",
        "job_title": "Director"
      }
    ]
  }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "errors": [
    {
      "message": "email not found"
    }
  ]
}

This endpoint removes a user from the organization. The user is not deleted from the system, it just gets disassociated from the organization.

HTTP Request

POST https://electionbuddy.com/api/v1/organizations/:id/remove_user

Body Parameters

Parameter Required Description
email true User email. The user with this email must exist and must belong to the organization.

Version 2

Get Vote Ballot Design

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

vote_id = '58508'

url = "https://secure.electionbuddy.com/api/v2/votes/ballot_designs/#{vote_id}"

headers = { authorization: 'tGs_pFLsxJ58yTRBRjDqhxKWDAsMj9zXLoFs4HGN' }

response = Faraday.get(url, {}, headers)

puts response.body

import requests

vote_id = "58508"

url = f"https://secure.electionbuddy.com/api/v2/votes/ballot_designs/{vote_id}"

headers = { 'Authorization': 'tGs_pFLsxJ58yTRBRjDqhxKWDAsMj9zXLoFs4HGN' }

response = requests.get(url= url, headers= headers)

print(response.json())

<?php
$curl = curl_init();

$vote_id = '58508';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://secure.electionbuddy.com/api/v2/votes/ballot_designs/{$vote_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: tGs_pFLsxJ58yTRBRjDqhxKWDAsMj9zXLoFs4HGN'
  ),
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;

Successful request (200 OK)

{
    "vote": {
        "instructions_text": "<p>Foo</p>",
        "custom_verification_instructions": "",
        "default_verification_instructions": "Finalize your choices by selecting <strong>Submit</strong>. To make changes, select <strong>Edit</strong>",
        "custom_confirm_response": null,
        "default_confirm_response": "",
        "admin_email": "For questions, contact Foo Bar at foo.bar@example.com",
        "logo": "//foo.example.com",
        "number_of_questions": 2,
        "questions": [
            {
                "id": 154343,
                "title": "Vice-Chair"
            },
            {
                "id": 154331,
                "title": "New Position/Question 1"
            }
        ]
    }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
    "id": [
        "must be greater than 0"
    ]
}

This endpoint retrieves the ballot design for a given vote.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/ballot_designs/:vote_id

Query Parameters

Parameter Required Description
vote_id true The vote ID.

Get Vote Ballot Question Details

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

vote_id = '1'
question_id = '1'
url = "https://secure.electionbuddy.com/api/v2/votes/#{vote_id}/questions/#{question_id}"

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.get(url, {}, headers)

puts response.body


import requests

vote_id = '1'
question_id = '1'
url = f"https://secure.electionbuddy.com/api/v2/votes/{vote_id}/questions/{question_id}"

payload = ""
headers = {
  'Authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.json())

<?php

$curl = curl_init();

$vote_id = '1';
$question_id = '1';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://secure.electionbuddy.com/api/v2/votes/{$vote_id}/questions/{$question_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK)

{
  "question": {
    "title": "New Position/Question 1",
      "voting_system": "plurality",
      "details_text": null,
      "choice_text": "candidate",
      "number_of_vacancies": 1,
      "writeins": false,
      "minimum_choice_required": 1,
      "maximum_choice_required": 1,
      "abstain": true,
      "random_order": false,
      "comments": false,
      "standard_instructions": "Select ONE choice. If you don't want to vote, select abstain.",
      "custom_instructions_text": null,
      "disable_standard_instructions": false,
      "number_of_choices": 2,
      "choices": [
        {
          "id": 823695,
          "name": "No",
          "order": 2,
          "info": null
        },
        {
          "id": 823694,
          "name": "Yes",
          "order": 1,
          "info": null
        }
      ]
  }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "id": [
    "question must belong to election"
  ]
}

This endpoint retrieves the details of a question under a given vote.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/:vote_id/questions/:question_id

Query Parameters

Parameter Required Description
vote_id true The vote ID.
question_id true The question ID.

Get Vote Details

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

vote_id = 1

url = "https://secure.electionbuddy.com/api/v2/votes/#{vote_id}"

headers = { authorization: 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw' }

response = Faraday.get(url, {}, headers)

puts response.body

import requests

vote_id = '1'

url = f"https://secure.electionbuddy.com/api/v2/votes/{vote_id}"

headers = { 'Authorization': 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw' }

response = requests.request("GET", url, headers=headers, data="")

print(response.json())


<?php

$curl = curl_init();

$vote_id = '1';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://secure.electionbuddy.com/api/v2/votes/{$vote_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK)

{
  "vote": {
      "admin_access_to_results": "after",
      "allow_integrations": false,
      "anonymity": "hidden",
      "end_date": "2022-01-20T19:00:00Z",
      "id": 1,
      "integrity_level": "high",
      "number_of_access_keys": {
          "assigned": 5,
          "unassigned": 0
      },
      "organization_id": 34816,
      "primary_contact_email": "donnaa@electionbuddy.com",
      "primary_contact_user_id": 33591,
      "primary_language": "english",
      "run_type": "test",
      "start_date": "2022-01-18T17:25:00Z",
      "state": "completed",
      "timezone": "Pacific Time (US & Canada)",
      "title": "Audit Logs",
      "vote_key": "J0MoOQHzle",
      "vote_type": "election",
      "voter_access_to_results": "after",
      "voting_location": "remote"
  }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "error": "Vote Not Found"
}

This endpoint retrieves the vote details.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/:vote_id

Query Parameters

Parameter Required Description
vote_id true The vote ID.

Get Vote Notice Details

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

vote_id = '1'
url = "https://secure.electionbuddy.com/api/v2/votes/#{vote_id}/notice_detail"

headers = { authorization: 'TnKsCN8J6acyZQjR39T-XBPHJBFdXPJTyFNELUqh' }

response = Faraday.get(url, {}, headers)

puts response.body

import requests

vote_id = '1'
url = f"https://secure.electionbuddy.com/api/v2/votes/{vote_id}/notice_detail"

headers = {
  'Authorization': 'TnKsCN8J6acyZQjR39T-XBPHJBFdXPJTyFNELUqh'
}

response = requests.get(url, headers=headers)

print(response.json())


<?php

$curl = curl_init();

$vote_id = '1';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://secure.electionbuddy.com/api/v2/votes/{$vote_id}/notice_detail",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: TnKsCN8J6acyZQjR39T-XBPHJBFdXPJTyFNELUqh'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK)

{
    "vote": {
        "email": true,
        "email_confirmation": false,
        "organization_as_email_sender": false,
        "email_proxy_text": false,
        "email_personalized_text": "",
        "email_custom_text": "<div id='ballot-notice-email-template-component'>\n  <p>You are invited to vote in the {{organization_name}} - {{election_name}}.</p><p>The voting deadline is {{election_end_date}} {{election_time_zone}}.</p><p>We are using an online election system to tabulate our votes. You have been assigned a unique access key which can only be used to vote once and your voting choices will remain anonymous. Do not forward this email. Do not reply to this email to vote, as your vote will not be registered.</p><p></p><p>If you have election questions, feedback or want to be removed from future ballot lists, please email {{user_full_name}} at {{user_email}}.</p><br><strong>To vote, visit:</strong><br> {{ballot_link}} <br><p>Or copy and paste the link into your web browser.</p>You can also visit {{access_link}} and enter <strong>\" {{access_key}} \"</strong>\n</div>",
        "sms": false,
        "default_country_code": "US",
        "organization_acronym": "",
        "sms_custom_text": "",
        "postal": false,
        "postal_qr_code": false,
        "delivery_delay": 0,
        "postal_return_address": {},
        "postal_personalized_text": "",
        "postal_custom_text": "",
        "postal_paper_ballot": false,
        "postal_papaer_ballot_tear_off": false,
        "printed_notice": false,
        "printed_notice_personalize_text": "",
        "printed_custom_text": "",
        "create_notice_yourself": false,
        "number_of_reminders_reserved": 0
    }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
    "error": "not found"
}

This endpoint retrieves the details of the notices used for the given vote.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/:vote_id/notice_detail

Query Parameters

Parameter Required Description
vote_id true The vote ID.

Get Vote Results

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

vote_id = '1'

url = "https://secure.electionbuddy.com/api/v2/votes/#{vote_id}/results"

headers = { authorization: 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw' }

response = Faraday.get(url, {}, headers)

puts response.body

import requests

vote_id = '1'

url = f"https://secure.electionbuddy.com/api/v2/votes/{vote_id}/results"

headers = {
  'Authorization': 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw'
}

response = requests.get(url, headers=headers)

print(response.json())


<?php

$curl = curl_init();

$vote_id = '1';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://secure.electionbuddy.com/api/v2/votes/{$vote_id}/results",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK)

{
  "id": 1,
  "title": "Election 2022",
  "questions": [
      {
        "id": 154349,
        "title": "Leader",
        "total_eligible_voters": 10,
        "ballots_not_received": 1,
        "abstentions": {
            "by_choice": 3,
            "total": 4
        },
        "choices": [
          {
            "name": "Betty Green",
            "data": 4.0,
            "weighted_data": null
          },
          {
            "name": "Lisa Morgan",
            "data": 2.0,
            "weighted_data": null
          }
      ]
    },
    {
        "id": 154350,
        "title": "Chair",
        "total_eligible_voters": 10,
        "ballots_not_received": 1,
        "abstentions": {
            "by_choice": 2,
            "total": 3
        },
        "choices": [
          {
            "name": "Elizabeth Taylor",
            "data": 4.0,
            "weighted_data": null
          },
          {
            "name": "Margaret Brown",
            "data": 3.0,
            "weighted_data": null
          }
      ]
    }
  ]
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "errors": {
    "vote": "not found"
  }
}

This endpoint retrieves the results of a given vote.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/:vote_id/results

Query Parameters

Parameter Required Description
vote_id true The vote ID.

Get Vote Voter Options

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

id = '1'
url = "https://secure.electionbuddy.com/api/v2/votes/#{id}/voter_options"

headers = { authorization: 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw' }

response = Faraday.get(url, {}, headers)

puts response.body

import requests

id = '1'
url = f"https://secure.electionbuddy.com/api/v2/votes/{id}/voter_options"

headers = {
  'Authorization': 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw'
}

response = requests.get(url = url, headers= headers)

print(response.json())

<?php

$curl = curl_init();

$id = '1';

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://secure.electionbuddy.com/api/v2/votes/${id}/voter_options",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw'
  ),
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;

Successful request (200 OK)

{
  "voter_options": {
    "additional_voters": 1,
    "allow_voting_integrations_enabled": false,
    "label_enabled": false,
    "reporting_groups": {
      "enabled": false,
      "groups": [

      ]
    },
    "required_fields": [
      "identifier"
    ],
    "two_factor_authentication": {
      "enabled": false,
      "type": "password"
    },
    "unique_id_type": "identifier",
    "voting_groups_enabled": false,
    "weighted_ballots_enabled": false
  }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "error": "Vote Not Found"
}

This endpoint retrieves the voter options.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/:vote_id/voter_options

Query Parameters

Parameter Required Description
vote_id true The vote ID.

Get Voter Access Key and Access URL

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

vote_id =  '1'
param = { identifier: 'user@email.com' }
url = "https://secure.electionbuddy.com/api/v2/votes/#{vote_id}/voters/access_keys"

headers = { authorization: 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw' }

response = Faraday.get(url, param, headers)

puts response.body

import requests

vote_id = '1'
param = { 'identifier': 'user@email.com' }
url = f"https://secure.electionbuddy.com/api/v2/votes/{vote_id}/voters/access_keys"

headers = {
  'Authorization': 'f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw'
}

response = requests.get(url = url, params = param, headers= headers)

print(response.json())


<?php

$curl = curl_init();

$vote_id = '1';
$identifier = 'user@email.com';
$query = http_build_query(['identifier' => $identifier]);
$url = "https://secure.electionbuddy.com/api/v2/votes/{$vote_id}/voters/access_keys";

curl_setopt_array($curl, array(
  CURLOPT_URL => ($url . "?" . $query),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: f8MXwEEeTyvNxz1kPrb-RGVQsr-PVAwFK8sbS6Qw'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK)

{
  "access_key": {
    "key": "29K2-TWHK-SV89-8JY8",
    "url": "https://electionbuddy.com/ballot/29K2-TWHK-SV89-8JY8",
    "status": "completed",
    "updated_at": "2022-01-20T18:07:30.530Z",
    "vote": {
        "id": 1,
        "name": "Election 2022"
    },
    "organization": {
        "name": "ABC"
    }
  }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "errors": {
    "identifier": [
        "can't be blank"
    ]
  }
}

This endpoint retrieves the voter's access key and the access URL.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/:vote_id/voters/access_keys?identifier=:identifier

Query Parameters

Parameter Required Description
vote_id true The vote ID.
identifier true The aspect that identifies the voter in the voter list. This can be a custom ID, an email, an SMS number, or the voter's name in the postal address.

Get Votes

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/votes"

params = {
  title: 'election',
  run_type: 'live',
  start_date: 'December 20, 2021 1:15 PM',
  start_date_max: 'March 20, 2022, 10:30 AM',
  types: ['election'],
  statuses: %w[created completed],
  page: 2,
  per_page: 3
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.get(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/votes"

params = {
  'title': 'election',
  'run_type': 'live',
  'start_date': 'December 20, 2021 1:15 PM',
  'start_date_max': 'March 20, 2022, 10:30 AM',
  'types': ['election'],
  'statuses': ['created', 'completed'],
  'page': 2,
  'per_page': 3
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.get(url = url, params = params, headers= headers)

print(response.json())

<?php

$curl = curl_init();

$url = 'https://secure.electionbuddy.com/api/v2/votes';

$data = [
  'title' => 'election',
  'run_type' => 'live',
  'start_date' => 'December 20, 2021 1:15 PM',
  'start_date_max' =>  'March 20, 2022, 10:30 AM',
  'types' =>  ['election'],
  'statuses' => ['created', 'completed'],
  'page' => 2,
  'per_page' => 3
];

$query = http_build_query($data);

curl_setopt_array($curl, array(
  CURLOPT_URL => ($url . "?" . $query),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK)

{
  "votes": [
    {
      "id": 2,
      "title": "Board of Directors 2022",
      "status": "created",
      "type": "election",
      "run_type": "live",
      "start_date": "2021-12-21T15:00:00Z",
      "end_date": "2021-12-22T15:00:00Z",
      "timezone": "Mountain Time (US & Canada)"
    },
    {
      "id": 4,
      "title": "Budget Approval",
      "status": "completed",
      "type": "election",
      "run_type": "live",
      "start_date": "2022-01-16T15:00:00Z",
      "end_date": "2022-02-19T15:00:00Z",
      "timezone": "Brasilia"
    },
    {
      "id": 17,
      "title": "Membership Poll",
      "status": "created",
      "type": "election",
      "run_type": "live",
      "start_date": "2022-02-11T17:00:00Z",
      "end_date": "2022-03-19T13:00:00Z",
      "timezone": "Buenos Aires"
    }
  ],
  "meta": { "total": 6 }
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "title": ["is too short (minimum is 2 characters)"],
  "start_date": ["can't be blank"],
  "run_type": ["not allowed"],
  "types": ["not allowed"],
  "statuses":["not allowed"]
}

This endpoint retrieves a list of votes for an organization. The list can be filtered by the parameters combination.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes

Query Parameters

Parameter Required Description
title false Vote title.
run_type false Whether the vote is a test or not. The possible values are "test" or "live".
start_date false The vote start date.
start_date_max false Vote maximum start date. It must be used with start_date if a date range is desired.
types false The vote types list: 'election', 'meeting_vote' and 'announcement'.
statuses false The vote statuses list: 'created', 'cancelled', 'running', and 'completed'.
page false The current resultset page. The default value is 1.
per_page false The number of records returned in a page. The default value is 25.

Import Voter List

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/votes/voters/importations"

params = {
  "vote_id": 58812,
  "voters": [
    {
      "identifier": "1000",
      "label": "Label1",
      "email": "buddy@electionbuddy.com",
      "sms": "+17801231230",
      "name": "Election Buddy",
      "address_line1": "9650 20 Ave NW",
      "address_line2": "",
      "city": "Edmonton",
      "state": "AB",
      "zip": "T6N 1G1",
      "country": "CA",
      "group": "Student",
      "weight": "1.00",
      "authentication_token": "password1",
      "MyReportingGroupTitle": "SD20",
      "AnotherReportinGroupTitle": "School1"
    }
  ],
  "append_mode": "false"
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.post(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/votes/voters/importations"

params = {
  'vote_id': 58812,
  'voters': [
    {
      'identifier': '1000',
      'label': 'Label1',
      'email': 'buddy@electionbuddy.com',
      'sms': '+17801231230',
      'name': 'Election Buddy',
      'address_line1': '9650 20 Ave NW',
      'address_line2': '',
      'city': 'Edmonton',
      'state': 'AB',
      'zip': 'T6N 1G1',
      'country': 'CA',
      'group': 'Student',
      'weight': '1.00',
      'authentication_token': 'password1',
      'MyReportingGroupTitle': 'SD20',
      'AnotherReportinGroupTitle': 'School1'
    }
  ],
  'append_mode': 'false'
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.post(url = url, json = params, headers = headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/votes/voters/importations');

$data = [
  'vote_id' => 58812,
  'voters' => [
    [
      'identifier' => '1000',
      'label' => 'Label1',
      'email' => 'buddy@electionbuddy.com',
      'sms' => '+17801231230',
      'name' => 'Election Buddy',
      'address_line1' => '9650 20 Ave NW',
      'address_line2' => '',
      'city' => 'Edmonton',
      'state' => 'AB',
      'zip' => 'T6N 1G1',
      'country' => 'CA',
      'group' => 'Student',
      'weight' => '1.00',
      'authentication_token' => 'password1',
      'MyReportingGroupTitle' => 'SD20',
      'AnotherReportinGroupTitle' => 'School1'
    ]
  ],
  'append_mode' => 'false'
];


$payload = json_encode($data);

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK)

{
  "importation_identifier": "35e9ad9e-b219-46e6-b7fd-7906791a2b28"
}

Example of unsuccessful request (400 Bad Request)

{
  "vote_id": [
      "can't be blank",
      "is not a number"
  ],
  "voters": [
      "must have at least one voter"
  ],
  "all_blank": [
      "must not have all blank values"
  ]
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "error": {
      "vote": "not found"
  }
}

This endpoint accepts a list of voters that will be imported into a given vote.

HTTP Request

POST https://secure.electionbuddy.com/api/v2/votes/voters/importations

Query Parameters

Parameter Required Description
vote_id true The vote ID.
voters true A list of voters with key/value pairs representing data about the voters as per the vote's voter data requirements below.
append_mode false If set to true, subsequent calls to the API for the given vote_id will append the voters into the existing voter list. Otherwise, the voter list will be fully replaced with the submitted voters.

Voter Data Requirements

Below is a list of subparameters (key/value pairs) based on a vote's voter list requirements

When using Key Required Description
Ballot ID identifier true Unique identifier of a voter when the Ballot ID voter option is enabled. For more info, see Voter Options: Ballot IDs.
Email Notices email true Unique email address of a voter. If the Ballot ID voter option is enabled, this field doesn't need to be unique. For more info, see Voter Options: Ballot IDs.
SMS Notices sms true Unique SMS phone number of a voter. If the Ballot ID voter option is enabled, this field doesn't need to be unique. SMS numbers follow the E.164 format. For more info about this format, see E.164 from wikipedia.
Postal Notices name true Unique name to use for postal purposes (e.g. Voter's first and last name). If the Ballot ID voter option is enabled, this field doesn't need to be unique. For more info, see Voter Options: Ballot IDs.
address_line1 true Suite/House number of the voter's address.
address_line2 false Additional information for voter's address.
city true City of the voter's address.
state true Province or State of the voter's address.
zip true Zip or Postal code of the voter's address.
country true Country of the voter's address.
Voter Labels label false Label to identify a voter. For more info, see Voter Options: Voter Labels.
Weighted Ballots weight false Vote weighting assigned to a voter. For more info, see Weighted Voting.
Voting Groups group true Used to assign a voter into a group. For more info, see Voter Options: Voting Groups.
2FA > Password authentication_token true A password assigned to a voter. For more info, see Two-Factor Authentication.
2FA > Phone Verification sms true The SMS number that will receive the authentication code. For more info, see Two-Factor Authentication.
Reporting Groups the group title true Use the Group Title that was entered in the voter setup. For more info, see Voter Options: Reporting Groups

Caveats

Validate imported Voter List

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/votes/voters/validations"

params = {
  "vote_id": 58812
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.post(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/votes/voters/validations"

params = {
  'vote_id': 58812
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.post(url = url, json = params, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/votes/voters/validations');

$data = [
  'vote_id' => 58812
];


$payload = json_encode($data);

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (201 Created)

{
  "validation_identifier": "ae0a1724-9791-4bb2-8331-6d4e55a9b7c8"
}

Example of unsuccessful request (422 Unprocessable Entity)

{
  "error": {
      "vote": "not found"
  }
}

This endpoint triggers a validation against a given vote's voter list.
To get the validation results, see Get Voter List Validation Results endpoint

HTTP Request

POST https://secure.electionbuddy.com/api/v2/votes/voters/validations

Query Parameters

Parameter Required Description
vote_id true The vote ID.

Get Voter List Validation Results

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/votes/voters/validations"

params = {
  "identifier": '90dd086d-d4a3-4f02-9de4-221880355052'
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.get(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/votes/voters/validations"

params = {
  'identifier': '90dd086d-d4a3-4f02-9de4-221880355052'
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.get(url = url, json = params, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/votes/voters/validations');

$data = [
  'identifier' => '90dd086d-d4a3-4f02-9de4-221880355052'
];

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK) without any errors

{
  "results": {
      "vote_id": 58812,
      "validation_id": 929,
      "identifier": "90dd086d-d4a3-4f02-9de4-221880355052",
      "voter_list_validations": {
          "voter_list_errors": {},
          "meta": {
              "total": 0
          }
      },
      "voter_lines_validation": {
          "voter_line_errors": [],
          "meta": {
              "total": 0,
              "page": 1,
              "per_page": 10
          }
      }
  }
}

Example of successful request (200 OK) with voter list errors

{
    "results": {
        "vote_id": 58777,
        "validation_id": 935,
        "identifier": "ba1716d5-a5f4-4b8f-ad0b-5f6e868caf51",
        "voter_list_validations": {
            "voter_list_errors": {
                "voter_list_overflow": [
                    "Test elections cannot have more than 5 voters. You have a list of 10 voter(s) and 0 manual key(s) reserved."
                ]
            },
            "meta": {
                "total": 1
            }
        },
        "voter_lines_validation": {
            "voter_line_errors": [],
            "meta": {
                "total": 0,
                "page": 1,
                "per_page": 10
            }
        }
    }
}

Example successful request (200 OK) with voter-specific errors

{
  "results": {
      "vote_id": 58787,
      "validation_id": 937,
      "identifier": "dfe4c244-5b92-4158-85a8-696025480d30",
      "voter_list_validations": {
          "voter_list_errors": {},
          "meta": {
              "total": 0
          }
      },
      "voter_lines_validation": {
          "voter_line_errors": [
              {
                  "voter_information_line_id": 17346137,
                  "errors": {
                      "email": [
                          "Email has the wrong format"
                      ]
                  }
              },
              {
                  "voter_information_line_id": 17346135,
                  "errors": {
                      "email": [
                          "Email has the wrong format"
                      ]
                  }
              }
          ],
          "meta": {
              "total": 2,
              "page": 1,
              "per_page": 10
          }
      }
  }
}

Example of unsuccessful request (400 Bad Request)

{
    "identifier": [
        "can't be blank",
        "is not a valid identifier"
    ]
}

This endpoint retrieves the validation results for a voter list.

HTTP Request

GET https://secure.electionbuddy.com/api/v2/votes/voters/validations

Query Parameters

Parameter Required Description
identifier true UUID identifier returned by the Validate imported Voter List endpoint
page false The current resultset page. The default value is 1.
per_page false The number of records returned in a page. The default value is 10

Validation Results Explained

Organizations

Create

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/organizations"

params = {
  name: 'New Organization',
  owner_id: 1,
  location: 'Edmonton, AB, Canada',
  organization_type_id: 1,
  organization_type_other: 'Other Organization Type',
  membership_tier: '1-20',
  logo: ''
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.post(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/organizations"

params = {
  name: 'New Organization',
  owner_id: 1,
  location: 'Edmonton, AB, Canada',
  organization_type_id: 1,
  organization_type_other: 'Other Organization Type',
  membership_tier: '1-20',
  logo: ''
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.post(url = url, json = params, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/organizations');

$data = [
  'name' => 'New Organization',
  'owner_id' => 1,
  'location' => 'Edmonton, AB, Canada',
  'organization_type_id' => 1,
  'organization_type_other' => 'Other Organization Type',
  'membership_tier' => '1-20',
  'logo' => ''
];

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK) without any errors

{
  "id": 10,
  "name": "New Organization",
  "owners": [
    {
      "id": 1,
      "email": "owner@email.com"
    }
  ],
  "billing_account": {
    "id": 1,
    "name": "Pay Per Election"
  },
  "location": "Edmonton, AB, Canada",
  "organization_type": "Student Government",
  "organization_type_other": "Other Organization Type",
  "membership_tier": "1-20",
  "logo": null,
  "created_at": "2024-07-09T23:59:54.744Z",
  "updated_at": "2024-07-09T23:59:54.744Z"
}

Example of unsuccessful request (400 Bad Request)

{
    "name": [
        "can't be blank"
    ]
}

This endpoint creates a new organization.

HTTP Request

POST https://secure.electionbuddy.com/api/v2/organizations

Query Parameters

Parameter Required Description
name true The Organization's name
owner_id false The ID of the user that will be the organization's owner. If none is give, the API Key owner will be the new organization's owner
location false Organization's location. Should be sent in the format 'City, Estate, Country'. If none is given, the API Key organization location will be used
organization_type_id false Organization's type. If none is given, the API Key organization type will be used
organization_type_other false If none is given, the API Key organization type other will be used
membership_tier false Organization's membership tier. If none is given, the API Key membership tier will be used
logo false Organization's logo. Should be a base64 format, less than 5MB and JPEG of PNG format. If none is given, the API Key logo will be used

Update

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/organizations/me"

params = {
  name: 'New Name',
  location: 'Edmonton, AB, Canada',
  organization_type_id: 1,
  organization_type_other: 'Other Organization Type',
  membership_tier: '1-20',
  logo: ''
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.post(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/organizations/me"

params = {
  name: 'New Name',
  location: 'Edmonton, AB, Canada',
  organization_type_id: 1,
  organization_type_other: 'Other Organization Type',
  membership_tier: '1-20',
  logo: ''
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.post(url = url, json = params, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/organizations/me');

$data = [
  'name' => 'New Name',
  'location' => 'Edmonton, AB, Canada',
  'organization_type_id' => 1,
  'organization_type_other' => 'Other Organization Type',
  'membership_tier' => '1-20',
  'logo' => ''
];

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK) without any errors

{
  "id": 10,
  "name": "New Name",
  "owners": [
    {
      "id": 1,
      "email": "owner@email.com"
    }
  ],
  "billing_account": {
    "id": 1,
    "name": "Pay Per Election"
  },
  "location": "Edmonton, AB, Canada",
  "organization_type": "Student Government",
  "organization_type_other": "Other Organization Type",
  "membership_tier": "1-20",
  "logo": null,
  "created_at": "2024-07-09T23:59:54.744Z",
  "updated_at": "2024-07-09T23:59:54.744Z"
}

Example of unsuccessful request (400 Bad Request)

{
    "name": [
        "can't be blank"
    ]
}

This endpoint updates the API Key Organization.

HTTP Request

POST https://secure.electionbuddy.com/api/v2/organizations/me

Query Parameters

Parameter Required Description
name false The Organization's name
location false Organization's location. Should be sent in the format 'City, Estate, Country'
organization_type_id false Organization's type
organization_type_other false Other organization type
membership_tier false Organization's membership tier
logo false Organization's logo. Should be a base64 format, less than 5MB and JPEG of PNG format

Add User

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/organizations/me/members"

params = {
  user_email: 'user@email.com',
  role: 'administrator'
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.post(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/organizations/me/members"

params = {
  user_email: 'user@email.com',
  role: 'administrator'
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.post(url = url, json = params, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/organizations/me/members');

$data = [
  "user_email" => "user@email.com",
  "role" => "administrator"
];

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK) without any errors

{
  "status": "invited",
  "user": {
    "email": "email@user.com"
  },
  "role": "administrator"
}

Example of unsuccessful request (400 Bad Request)

{
    "email": [
        "Could not find an user with given email"
    ]
}

This endpoint adds an User to an Organization

HTTP Request

POST https://secure.electionbuddy.com/api/v2/organizations/me/members

Query Parameters

Parameter Required Description
user_email true The email of the user to be added to the organization
role true The new member's role. The only accepted roles are "member", "administrator" and "vote_monitor"

Remove User

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/organizations/me/members"

params = {
  user_email: 'user@email.com'
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.delete(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/organizations/me/members"

params = {
  user_email: 'user@email.com'
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.delete(url = url, json = params, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/organizations/me/members');

$data = [
  "user_email" => "user@email.com"
];

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK) without any errors

{
  "status": "removed",
  "user": {
    "email": "email@user.com"
  }
}

Example of unsuccessful request (400 Bad Request)

{
    "email": [
        "Could not find an user with given email"
    ]
}

This endpoint removes an User from the Organization

HTTP Request

DELETE https://secure.electionbuddy.com/api/v2/organizations/me/members

Query Parameters

Parameter Required Description
user_email true The email of the user to be removed to the organization

Update Voting Integrations

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations"

params = {
  provider: 'azure',
  azure: {
    tenant_identifier: 'tenant_identifier',
    client_identifier: 'client_identifier',
    client_secret: 'client_secret'
  },
  vantaca: {
    login: '',
    password: '',
    company_id: '',
    association_code: ''
  }
}

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.post(url, params, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations"

params = {
  provider: 'azure',
  azure: {
    tenant_identifier: 'tenant_identifier',
    client_identifier: 'client_identifier',
    client_secret: 'client_secret'
  },
  vantaca: {
    login: '',
    password: '',
    company_id: '',
    association_code: ''
  }
}

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.post(url = url, json = params, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations');

$data = [
  "provider" => "azure",
  "azure" => {
    "tenant_identifier" => "tenant_identifier",
    "client_identifier" => "client_identifier",
    "client_secret" => "client_secret"
  },
  "vantaca" => {
    "login" => "",
    "password" => "",
    "company_id" => "",
    "association_code" => ""
  }
];

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK) without any errors

{
  "id": 1,
  "provider": "azure",
  "organization": {
    "id": 1,
    "name": "Organization"
  },
  "azure": {
    "tenant_identifier": "tenant_identifier",
    "client_identifier": "client_identifier",
    "client_secret": "client_secret"
  },
  "vantaca": {
    "login": null,
    "password": null,
    "company_id": null,
    "association_code": null
  },
  "created_at": "2024-07-09T23:59:54.744Z",
  "updated_at": "2024-07-09T23:59:54.744Z"
}

Example of unsuccessful request (400 Bad Request)

{
    "provider": [
        "Invalid provider"
    ]
}

This endpoint updates the Organization's Voting Integrations

HTTP Request

POST https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations

Query Parameters

Parameter Required Description
provider false The provider of the Voting Integrations. It can be "electionbuddy", "azure" or "vantaca"
azure[tenant_identifier] false The tenant identifier from Azure
azure[client_identifier] false The client identifier from Azure
azure[client_secret] false The client secret from Azure
vantaca[login] false Login from Vantaca
vantaca[password] false Password from Vantaca
vantaca[company_id] false Company_id from Vantaca
vantaca[association_code] false Association code from Vantaca

Show Voting Integrations

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'faraday'
end

url = "https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations"

headers = { authorization: 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = Faraday.get(url, {}, headers)

puts response.body

import requests

url = "https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations"

headers = { 'authorization': 'i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt' }

response = requests.get(url = url, headers= headers)

print(response.json())

<?php

$curl = curl_init('https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations');

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: i89V-AH5V2Qyk7zaYNHt8fyZNRNwPQAZDUVzozRt'
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Successful request (200 OK) without any errors

{
  "id": 1,
  "provider": "azure",
  "organization": {
    "id": 1,
    "name": "Organization"
  },
  "azure": {
    "tenant_identifier": "tenant_identifier",
    "client_identifier": "client_identifier",
    "client_secret": "client_secret"
  },
  "vantaca": {
    "login": null,
    "password": null,
    "company_id": null,
    "association_code": null
  },
  "created_at": "2024-07-09T23:59:54.744Z",
  "updated_at": "2024-07-09T23:59:54.744Z"
}

This endpoint shows the Organization's Voting Integrations

HTTP Request

GET https://secure.electionbuddy.com/api/v2/organizations/me/voting_integrations

Errors

The ElectionBuddy API returns the following error codes:

Error code Meaning
401 Unauthorized -- Your API key is incorrect.
403 Forbidden -- You don't have permission to access the requested resource.
404 Not Found -- The specified object does not exist or you don't have permission to access it.
422 Unprocessable Entity -- Your request is valid but we were unable to process it. This is probably due to validation errors caused by the parameters sent.
500 Internal Server Error -- We had an unexpected problem processing your request.
ruby python php