Voter Registration API

The Voter Registration API allows users to create applications that include voter registration functionality without being concerned with the details of creating PDFs, following up with voters, or the rules associated with registering in various states.

We hope that by releasing this API people with innovative online voter registration ideas will be able to build them without the effort that would have otherwise been required.

Authentication

Using any DNC API requires the use of an API key. By default all API key users are rate limited – if your application requires a higher volume key, please get in touch.

In addition to signing up for an API key, you must sign up as a Raise Your Vote partner to use the API key with the voter registration API. You must also associate your API key with your Raise Your Vote partnership in the partner dashboard settings. This will allow registrations submitted via API to appear in your partner dashboard, alongside any registrations collected by partner widget.

Registration Fields

Registration fields are the fields that are required to complete a registration form. These fields vary by state and include the following information for each field.

  • name The name of the field.
  • required A boolean that indicates whether the field is required.
  • help_text Help text that can be displayed to the end user.
  • label Human readable label for the field
  • options For fields that are constrained to a set, the set of possible options
  • validations Validations that can be applied to the field. These will also be enforced by the API when registrations are submitted.

These registration fields are returned as a collection of fields that define the fields for that state. They can be retrieved by performing an HTTP GET of the registration fields resource for that state:

https://www.raiseyourvote.com/api/registration/fields/MA.json?lang=en&key=YOUR_API_KEY

There are some states and territories where registering via the API is not permitted. In those cases, the API will return an appropriate error condition. https://www.raiseyourvote.com/api/registration/fields/WY.json?lang=en&key=YOUR_API_KEY

Registrations

Registrations are created by performing an HTTP POST to the https://www.raiseyourvote.com/api/registrations.json resource. The post must include the following elements as URL encoded key/value pairs on the query string.  The post should have an empty body.

Required Fields

  • key The API key to use for this registration.
  • registration[address_state] The state that the registration is taking place in.
  • registration fields for state The registration fields that the fields API indicate are required for a particular state. The key for each field should be registration[name] where name is the field name supplied by the registration fields API.

Possible Fields
The following fields should be included in the registration if the Registration Fields API indicates that the field is required for a particular state, or if it is necessary to complete a name change or change of address form.

  • registration[ethnicity]
  • registration[temp_id_number]
  • registration[name_title]
  • registration[name_first]
  • registration[name_last]
  • registration[name_middle]
  • registration[name_suffix]
  • registration[address_city_town]
  • registration[address_street]
  • registration[address_county]
  • registration[address_zipcode]
  • registration[birthdate]
  • registration[change_current_registration]
  • registration[email]
  • registration[phone_number]
  • registration[gender]
  • registration[email_optin]
  • registration[sms_optin]
  • registration[i18n]
  • registration[citizen]

If the user has an optional mailing address:

  • registration[mailing_address_city_town]
  • registration[mailing_address_state]
  • registration[mailing_address_street]
  • registration[mailing_address_zipcode]

If the user is changing their address:

  • registration[previous_address_city_town]
  • registration[previous_address_street]
  • registration[previous_address_zipcode]
  • registration[previous_address_state]

If the user is changing their name:

  • registration[previous_name_first]
  • registration[previous_name_last]
  • registration[previous_name_middle]
  • registration[previous_name_suffix]

Additional Optional Fields
The following fields are also allowed for all registrations, but are not required.

  • registration[referer] The HTTP Referrer of the end user.
  • registration[ip] The IP address of the end user.
  • registration[source] A source code that is persisted with the registration. Can be used for analytics purposes.

Successful registration creation requests will return a url for the PDF that corresponds to the registration that was submitted. In addition, the system will add the registration to the partner dashboard associated with the API key, and send an email to the voter with a link to the PDF for their records.

If the registration is unsuccessful a collection of validation errors will be returned to the API consumer. These should be displayed to the user so they have the opportunity to correct the problem.

Client Libraries

An example client library in Ruby is available for the Voter Registration API.  Examples for PHP and cURL are also available.

Usage

Most uses of the API will follow this pattern:

  1. A request is made for the registration fields for the state in which the end users it attempting to register to vote
  2. The registration fields are rendered by the consuming application, and the user completes them.
  3. A completed registration is collected by the consuming application and submitted to the registrations API.
  4. The system responds with a URL for a completed registration form, which the end user is redirected to.
  5. The registration is available to administrators in the partner dashboard.

Help

If you have problems or questions, please send a message to the Open.Dems mailing list