REST API Documentation

Home  »  Integrations

Authentication

The API uses Basic Authentication over TLS combined with an API token. Each client application will need to request a username and password from Skypunch Technology which is to be passed in the header of each request to the API. Additionally, each client application will need to submit a parameter named key with a value equal to the API token associated with their account through the header of each request. Clients may retrieve their API token by:

  1. Logging into My Account.
  2. Click the My Info tab on the welcome screen.
  3. Click My account profile link.
  4. Find the API token at the top of the profile.

Tips for Developers

Popular documentation tools (for example, Swagger) are not well suited for the Skypunch Technology API because unlike many APIs, these services—or at least the three ballot services—are not primarily intended to permit CRUD (Create, Read, Update and Delete) operations on data. Rather, the API’s ballot resource—and its three sub-resources (step_one, step_two, step_three) support actual application logic and user flow through the process of:

  1. viewing a ballot.
  2. confirming the selections made by a voter on that ballot.
  3. inserting the ballot into the system.

For this reason, the step_one and step_two representations of the ballot resource return HTML as the response. This HTML is ready for output in a web browser and may be styled to blend in with a consuming site’s look and feel as explained under the section Styling the Ballot.

Special Note for ColdFusion Websites

The Skypunch Technology API is built in ColdFusion. That means that for the three ballot services (step_one, step_two and step_three) any website also built using ColdFusion may simply submit a voter’s ballot selections (in other words, the FORM scope after clicking a Submit button on the ballot) to the web service as a native ColdFusion structure and bypass parsing over that FORM scope to create an XML object containing a voter’s selections (Examples of creating this XML are included below where appropriate). See the ColdFusion API documentation for more information and code samples.

Styling the Ballot

When consuming a ballot into your own website by using the Get Ballot step one, and Get Ballot step two methods detailed below, it will not, by default have any styling applied and subsequently not look very nice. To change that and apply the same styles used when the ballot is hosted on the Skypunch Technology site, follow these steps:

  1. Log into My account.
  2. Click the Preview ballot button associated with your election. (If that button does not display, you may also click the Submit a paper ballot link.)
  3. Once the ballot displays, view the source code for that page.
  4. Copy the style sheet from the HEAD section on this page and paste it into each of your ballot pages.

By copying the style sheet from a current ballot on the Skypunch Technology site, you are ensured of having the most up-to-date styles in use with the ballot at any given time. Once the style sheet has been copied into your own ballot pages, you may leave it as-is, or make any changes you wish to those styles in order to make the ballot blend in perfectly with your own site’s look and feel.

Avoiding style conflicts

Some of the styles may conflict with existing styles already in use on your site. However, because the output from the step one and step two methods must be nested into a <FORM> tag anyway, it is recommended to include the id attribute for that FORM tag giving the value something such as ballot. An example would look like:

<form method="post" id="ballot">

You then prepend any CSS rules where there is a conflict with #ballot. An example would look like:

#ballot header > div > img:first-child {width:570px; height:95px; vertical-align:text-bottom;}

This makes the selector for that rule a descendant selector, and ensures the rule is only applied to the ballot and nothing else.

The API Methods

  • Values in curly brackets are variables provided by the consuming application.
  • Election ID is the election ID generated by Skypunch Technology for each election. This value is displayed in your Skypunch Technology account associated with each election, or you may get it programmatically from the /elections endpoint.
  • The documentation references the three models for conducting an election, 1. fully hosted, 2. passed authentication, and 3. fully integrated. Those models are represented at the Election Model Flowcharts.

Get elections

Description: Gets general data about elections useful for displaying an announcement about an upcoming election, or the deadline to vote in a currently-running election. Also contains election IDs useful for creating endpoints to other resources.

HTTP Method: GET

Endpoint
https://www.electionsonline.com/rest/v3/elections
Notes
Append ?startdate=yyyy/mm/dd to the endpoint to select only elections beginning after the specified date.
Sample request
GET /rest/v3/elections
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Sample response
[
	{
		"ID": 1549,
		"UUID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
		"PUBLISHRESULTS": 1,
		"ELECTIONNAME": "Sample Election",
		"STARTDATE": "June, 06 2016 00:00:00",
		"ENDDATE": "June, 13 2016 23:59:00",
		"BIODEADLINE": "June, 03 2016 23:59:00"
	},
	{
		"ID": 1562,
		"UUID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
		"PUBLISHRESULTS": 0,
		"ELECTIONNAME": "Demonstration Election",
		"STARTDATE": "June, 29 2016 00:00:00",
		"ENDDATE": "June, 29 2016 00:00:00",
		"BIODEADLINE": "June, 29 2016 00:00:00"
	}
]

Get specific election

Description: Gets general data about a specific election.

HTTP Method: GET

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}
Sample request
GET /rest/v3/elections/{electionID}
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Sample response
[
	{
		"ID": 1549,
		"UUID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
		"PUBLISHRESULTS": 1,
		"ELECTIONNAME": "Sample Election",
		"STARTDATE": "June, 06 2016 00:00:00",
		"ENDDATE": "June, 13 2016 23:59:00",
		"BIODEADLINE": "June, 03 2016 23:59:00"
	}
]

Get ballot step one

Description: Display the ballot in an external website and style the look and feel to match that external site. Once a voter makes selections on this representation of the ballot, they proceed to the step_two representation to confirm their selections. If service is consumed using ColdFusion, see the supplemental CF documentation for this service.

HTTP Method: POST

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/ballot/step_one
Notes
The body of the request is a collection of key-value pairs most easily created by treating the parameters listed below as form fields.
  • VoterID is a unique numeric identifier for each voter.
  • Voted is a boolean value denoting the voting status of voters. False for those who have not voted, true for those who have.
  • VoterGroup should be an empty string when voter groups are not associated with an election. When in use however, this parameter should match the appropriate voter group code defined in the election setup for voters who are in a given voter group.
  • SIGs, like voterGroup should be an empty string when not in use. When used, this parameter should match the SIG code associated with any positions when the voter should have those positions included on the ballot.
  • Weight should default to 1, but may be any integer value to reflect the weight of a voter’s ballot in cases where some voters’ ballots carry more weight than others.
  • js is a boolean parameter. True for browsers that support javascript, false for those that don’t. This impacts the behavior of the candidate biographies.
Sample request
POST /rest/v3/elections/{electionID}/ballot/step_one
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

voterID=10&voted=false&voterGroup=&sigs=&weight=1&js=true
Response
The response will be a string of HTML. Simply output the string to the desired location on the web page and apply styles as described in the above section Styling the Ballot.

Get ballot step two

Description: Display the confirmation page showing the selections made by the voter on the previous page (step_one). From this page, a voter proceeds to the step_three representation of the ballot where their selections are saved into the system. If service is consumed using ColdFusion, see the supplemental CF documentation for this service.

HTTP Method: POST

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/ballot/step_two
Notes
The body of the request is a collection of key-value pairs most easily created by treating the parameters listed below as form fields.
  • Ballot is distinct in that it is a snippet of XML you create based on the selections made by the voter on the previous page. The following sample demonstrates the format of XML you must end up with. For demonstration purposes, this sample assumes:
    1. The ballot contains the positions President (id = 8812) and Treasurer (id = 8813).
    2. The voter selected Robert Harrison for President and Terry McAllister for Treasurer.
    3. The voter either provided no comments, or comments are not enabled for either position
    To create this XML, you must parse through the FORM scope created when the ballot is submitted by the voter on step_one. Look for the FORM scope variable, positions. This comma-delimited list of the positions on the ballot may be looped over and the various XML nodes created during each loop iteration. 
    ‹positions›
   ‹position›
      ‹positionID›pos8812‹/positionID›
      ‹candidates›Robert Harrison‹/candidates›
      ‹comments›‹/comments›
   ‹/position›
      ‹position›
      ‹positionID›pos8813‹/positionID›
      ‹candidates›Terry McAllister‹/candidates›
      ‹comments›‹/comments›
   ‹/position›
‹/positions›
  • VoterID is a unique numeric identifier for each voter.
  • Weight should default to 1, but may be any integer value to reflect the weight of a voter’s ballot in cases where some voters’ ballots carry more weight than others.
  • Languages is a comma-delimited string of the languages codes support by the system (en for English, es for Spanish, de for German, fr for French, it for Italian, ch for Chinese, br and Portuguese).
Sample request
POST /rest/v3/elections/{electionID}/ballot/step_two
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

ballot=‹positions›‹position›‹positionID›pos8812‹/positionID›‹candidates›Robert Harrison‹/candidates›‹comments›‹/comments›‹/position›
‹position›‹positionID›pos8813‹/positionID›‹candidates›Terry McAllister
‹/candidates›‹comments›‹/comments›‹/position›‹/positions›&voterID=123&weight=1&languages=en
Response
The response will be a string of HTML. Simply output the string to the desired location on the web page and apply styles as described in the above section Styling the Ballot.

Get ballot step three

Description: Inserts the ballot into the system right after the voter confirms their selections on the step_two representation of the ballot resource. If service is consumed using ColdFusion, see the supplemental CF documentation for this service. All parameters are required except the four custom parameters.

HTTP Method: POST

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/ballot/step_three
Notes
The body of the request is a collection of key-value pairs most easily created by treating the parameters listed below as form fields.
  • Ballot 
    ‹positions›
   ‹position›
      ‹positionID›pos8812‹/positionID›
      ‹candidates›Robert Harrison‹/candidates›
      ‹comments›‹/comments›
   ‹/position›
      ‹position›
      ‹positionID›pos8813‹/positionID›
      ‹candidates›Terry McAllister‹/candidates›
      ‹comments›‹/comments›
   ‹/position›
‹/positions›
  • VoterID is a unique numeric identifier for each voter.
  • Weight should default to 1, but may be any integer value to reflect the weight of a voter’s ballot in cases where some voters’ ballots carry more weight than others.
  • VoterGroup is the same variable used in the step_one ballot representation.
  • SIGs, is the same variable used in the step_one ballot representation.
  • custom1 is an optional parameter used for passing voter-specific demographic data.
  • custom2 is an optional parameter used for passing voter-specific demographic data.
  • custom3 is an optional parameter used for passing voter-specific demographic data.
  • custom4 is an optional parameter used for passing voter-specific demographic data.
  • Languages is a comma-delimited string of the languages codes support by the system (en for English, es for Spanish, de for German, fr for French, it for Italian, ch for Chinese, br and Portuguese).
Sample request

POST /rest/v3/elections/{electionID}/ballot/step_three
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

ballot=‹positions›‹position›‹positionID›pos8812‹/positionID›‹candidates›Robert Harrison‹/candidates›‹comments›‹/comments›‹/position›‹position›‹positionID›pos8813‹/positionID›‹candidates›Terry McAllister‹/candidates›‹comments›‹/comments›‹ /position›‹/positions›&voterID=123&weight=1&voterGroup=&sigs=&custom1=&custom2=&custom3=&custom4=&languages=en

Sample response
{
    "heading": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPkJhbGxvdCBhY2NlcHRlZDwvc3Bhbj4=",
    "message": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPlRoYW5rIHlvdS4gWW91ciBiYWxsb3Q
    	gaGFzIGJlZW4gYWNjZXB0ZWQuPC9zcGFuPg==",
    "status": "1",
    "ballot_id": "DSSYjuoBdDkJi2fjq3C1WL",
    "verify_heading": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPkJhbGxvdCB2ZXJpZmljYXRpb
    	248L3NwYW4+",
    "verify_message": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPihPcHRpb25hbCkgVmVyaWZ5a
    	W5nIHRoaXMgYmFsbG90IGxhdGVyIHJlcXVpcmVzIHNhdmluZyBkYXRhIGFib3V0IGl0IHJpZ
        2h0IG5vdy48L3NwYW4+",
    "verify_button": "PHNwYW4gY2xhc3M9Imxhbmd1YWdlXzEiPkdldCB2ZXJpZmljYXRpb24g
    	ZGF0YTwvc3Bhbj4="
}

Get ballot count

Description: Gets a count of all ballots cast for an election. Useful for driving increased voter participation as described at Social Proof to Increase Voter Turnout.

HTTP Method: GET

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/ballot/count
Notes
Notice in the sample request that it is not necessary to send a key parameter through the request header as it is with other services.
Sample request
GET /rest/v3/elections/2206/ballot/count
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Cache-Control: no-cache
Response
The response will contain nothing but an integer.

Get voters

Description: Gets all voters for fully-hosted elections. For passed-authentication or fully-integrated elections, where a voter roster is never loaded into the Skypunch Technology system, this is not applicable. One use of this service would be to determine who has voted and send email reminders only to those who have not for clients who choose to send email reminder using their own email service.

HTTP Method: GET

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/voters
Notes
The default behavior is to get all voters, but the response may be filtered to only those voters who have voted, or those who have not. To filter, simply append ?filter=voted or ?filter=notvoted to the URI.
Sample request
GET /rest/v3/elections/{electionID}/voters
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Cache-Control: no-cache
Sample response
[
    {
        "ID": 2891481,
        "FIRSTNAME": "Pete",
        "LASTNAME": "Lopez",
        "EMAIL": "lopez@phony-domain.net",
        "WEIGHT": 1.0000,
        "VOTERGROUP": null,
        "SIGS": null,
        "ROLES": "voter",
        "VOTED": 1,
        "CUSTOM1": null,
        "CUSTOM2": null,
        "CUSTOM3": null,
        "CUSTOM4": null,
        "LANGUAGE": null,
        "OTP_TYPE": "s",
        "STATIC_OTP": 109379
    },
    {
        "ID": 2891486,
        "FIRSTNAME": "Jimmy",
        "LASTNAME": "Roberts",
        "EMAIL": "jimmy@phony-domain.tech",
        "WEIGHT": 1.0000,
        "VOTERGROUP": null,
        "SIGS": null,
        "ROLES": "voter",
        "VOTED": 0,
        "CUSTOM1": null,
        "CUSTOM2": null,
        "CUSTOM3": null,
        "CUSTOM4": null,
        "LANGUAGE": null,
        "OTP_TYPE": null,
        "STATIC_OTP": null
    }
]

Add a voter

Description: Add a single voter to an existing voter roster.

HTTP Method: POST

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/voters
Notes
otp_type is optional in the request and should only be included for public sector elections. Set the value to d for dynamic one-time password voters and s for static one-time password voters.
Sample request
POST /rest/v3/elections/{electionID}/voters
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/json
Cache-Control: no-cache
{
    "first_name":"Terry",
    "last_name":"McMurray",
    "email":"terry@phony-domain.net",
    "weight":1,
    "voter_group":"student",
    "sigs":"",
    "custom1":"",
    "custom2":"",
    "custom3":"", 
    "custom4":"",
    "otp_type":""
}
Sample response
{
    "sigs": null,
    "email": "terry@phony-domain.net",
    "voted": 0,
    "weight": 1.0000,
    "custom1": null,
    "custom2": null,
    "custom3": null,
    "custom4": null,
    "language": null,
    "otp_type": null,
    "voter_id": 2891501,
    "last_name": "McMurray",
    "first_name": "Terry",
    "voter_group": "student"
}

Get voter IDs for passed authentication voters

Description: In a passed authentication election, voters log in at an external website, then are passed over to Skypunch Technology to vote. In the process, their distinct ID in the originating website is stored at Skypunch Technology. Use this service to retrieve those IDs and update your own database flagging the voters as voted so they may be filtered out of receiving further email reminders, and just to maintain record of who voted.

HTTP Method: GET

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/voters/passed
Sample request
GET /rest/v3/elections/{electionID}/voters/passed
Host: www.electionsonline.com
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
Cache-Control: no-cache
Sample response
6103,4982,1085,10876,2374,1984

Get token for passed authentication

Description: Get an authentication token for a voter who logs in at an external site, then is passed over to the Skypunch Technology site for viewing and casting the ballot.

HTTP Method: POST

Endpoint
https://www.electionsonline.com/rest/v3/elections/{electionID}/token
Notes

The response is a JSON object (see Sample response below) containing three keys. The values associated with those keys depend on the response from this endpoint. When this endpoint issues a token, the token_issued key will equal yes and the token key will equal the token that you may use to authenticaticate the voter and direct them to the ballot. Do that by redirecting the request to the following URL providing the token in the response as the value of the token parameter. For example:

https://www.electionsonline.com/vote/login.cfm?token=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx.

In other cases, for example if the voter has already voted, a message to that effect will appear in the message key and token will be blank.

In the sample request below, the four custom fields at the end of the string of name/value pairs are all optional. Include them if you wish to pass custom voter demographic data into the system. Otherwise, they may be omitted.

Sample request
POST /rest/v3/elections/{electionID}/token
Host: www.electionsonline.com
Authorization: Basic ACH2aWRzaW1twesORNdAcHJhMCHvcmlhbg==
key: 08BF6D9D-YC16-72F4-385AD9AF30CCF877
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

firstname=Robert&lastname=Royal&email=royal@phony-domain.tech&voterID=1268&weight=1&votergroup=0&sigs=0&custom1=51&custom2=22213&custom3=Male&custom4=Volunteer
Sample response
{
        "Token": "f3de9ee1-c143-11ee-8cac-74867a213c83",
        "Message": "",
        "token_issued": "yes"
}