CSV Documentation

Getting Started

If you’re a state or local election official reading this, first, thank you for your work and your interest in the project. The data required to participate in this project is typically found in absentee voter roster files, voter registration databases, or voter history files. Sometimes all three…and maybe others. The standard looks to capture Uniformed and Overseas Citizen Absentee Voting Act (UOCAVA) transactions, such as:

  • when a voter requests a ballot;
  • when the application is processed;
  • to what country the ballot is sent and when;
  • why an application/ballot is rejected; and,
  • whether a voter is military or overseas citizen.

To make the process of collecting data easier, this project borrows lessons from the Voting Information Project’s (VIP’s) approach to data collection: use a flat file format for data collection and push any transformations downstream.

Naming Convention

Due to the many issues around elections data collection and cleanliness, much of the data still requires some form of human oversight. Therefore, having a relatively accessible file naming convention is beneficial. While this is not a hard-and-fast rule, anyone producing data in this standard should use the following naming convention, which borrows from a yet-unreleased version of the Voting Information Project’s documentation.

esbdata-${ELECTION_DATE}-${STATE}[-${LOCAL}].{csv|zip}

An explanation of each of the segments of the file naming convention above are as follows:

  • ${ELECTION_DATE} - The date of the election in ISO 8601 format.
  • ${STATE} - The full state name (e.g. Alaska, Arkansas, etc…) and not the abbreviation. If there are spaces in the state name, they should be substituted with underscores (e.g. New York -> New_York).
  • ${LOCAL} (optional) - This additional identifier should be used if the file contains data from a specific jurisdiction. As with ${STATE} above, all spaces should be substituted with underscores. For example, if the data contained in the file only covers Maricopa County, AZ for the November 6, 2012 election, the file name would be esbdata-2012-11-06-Arizona-Maricopa_County.csv.
  • {csv|zip} - If the file is an uncompressed CSV document, the extension should be .csv. If the file is zipped, the file extension should end with .zip.

For a final example, esbdata-2012-11-06-Iowa.zip denotes Iowa’s data for the Nov 6, 2012 election that has been compressed.

Data Fields

The following fields are possible data points for each transaction that the standard hopes to collect.

Id

Data Type: string

This field is required and must be unique.

Unique identifier for the transaction (i.e. not the voter). Ids should remain consistent, regardless of when an export is created.

VoterId

Data Type: string

This field is required.

Identifier that uniquely identifies a voter but is not required to be unique within the dataset. This number must be obfuscated from the original voter identifier in the jurisdiction’s registration database. This field helps analyze how effective each type of transaction is for an individual voter.

RequestMethod

Data Type: string

This field is required.

Specifies the method by which the request was triggered. Possible values are email; fax; in-person, which means the request was triggered by a person; mail; online, which means the request was submitted via online form or system — through the elections office or other registration agency; phone, which means the request was placed via phone call; untracked, which signifies that this variable is not tracked in the system; and, other, which is a catch-all for any values that fall outside of the other values.

The value of RequestMethod must be one of the following:

  • email
  • fax
  • in-person
  • mail
  • online
  • phone
  • untracked
  • other

RequestOtherMethod

Data Type: string

If RequestMethod fails to cover all of the possible request methods for a particular voter transaction, this field specifies an alternate method by which the request was received.

RequestDate

Data Type: date

Specifies the date the request was processed by the local or state election official.

RequestStatusType

Data Type: string

This field is required.

Specifies the current status of the request. Possible values are accepted, which denotes that the request was successfully processed; cancelled, which signifies that the request has been cancelled by a voter’s direct or indirect action; pending, which signifies that request is still being processed; rejected, which means the request was not successfully processed.

The value of RequestStatusType must be one of the following:

  • accepted
  • cancelled
  • pending
  • rejected

RequestStatusReasonType

Data Type: array

This field is required.

If RequestStatusType is rejected, cancelled, or pending, then RequestStatusReasonType specifies the reason the activity was rejected. Possible values are duplicate, which denotes that the election official already received an application for the voter; invalid, which means the application was invalid; mismatch-voter-signature, which means the application signature did not match the voter signature on file; missing-identification, which means that an unspecified identifier was required and missing from the application; missing-ssn, denoting that the Social Security Number was missing from the application; missing-state-id-number, which means the state identifier was required and missing from the application; missing-voter-signature, meaning the voter did not sign the application; untracked, which means the reason for rejection is not tracked; and other, which is a catch-all for any values that fall outside of the other values. Multiple values are possible for this field.

The value of RequestStatusReasonType must be one of the following:

  • duplicate
  • invalid
  • mismatch-voter-signature
  • missing-identification
  • missing-ssn
  • missing-state-id-number
  • missing-voter-signature
  • untracked
  • other

RequestReasonOtherType

Data Type: string

If RequestStatusReasonType fails to cover all possible types of request reasons, this field will list an alternate type.

RequestType

Data Type: string

This field is required.

Specifies the type of request that triggered the change. Possible values are fpca, which means a voter submitted a Federal Postcard Application; fwab, which denotes a voter returned a Federal Write-In Absentee Ballot prior to receiving or requesting a ballot through other means; informal-request, which signifies a voter requested a ballot through a less formal process, such as a letter or phone call; nvra, which means a voter used a National Voter Registration (Act) form; state-application, which denotes a state form triggered the activity; and untracked, which means the type of application is not tracked.

The value of RequestType must be one of the following:

  • fpca
  • fwab
  • informal-request
  • nvra
  • state-application
  • untracked

BallotRejectionType

Data Type: array

Specifies the reason why the ballot was rejected. Possible values are mismatch-voter-signature, which denotes the signature on file did not match the signature on the returned envelope or document; missing-voter-signature, which signifies that the voter signature is missing on the returned documents; not-timely, which means the ballot was received after the required deadline; postmark, which signifies the ballot was postmarked after the required date; rejected, which signifies the ballot was rejected for an unspecified reason; undeliverable, which denotes the ballot was returned as undeliverable to the address where it was sent; untracked, which signifies that this variable is not tracked in the system; voided-spoiled, which means the ballot had to be voided or spoiled either by the administration or the voter; voter-died, which signifies the voter died thereby impacting the ability to count the ballot (NB: this is largely dependent on state law); voter-moved, which signifies the voter moved from their registered address; voter-unregistered, which means the voter is not registered to vote; and, other, which is a catch-all for any values that fall outside of the other values.

The value of BallotRejectionType must be one of the following:

  • mismatch-voter-signature
  • missing-voter-signature
  • not-timely
  • postmark
  • rejected
  • undeliverable
  • untracked
  • voided-spoiled
  • voter-died
  • voter-moved
  • voter-unregistered
  • other

BallotRejectionOtherType

Data Type: string

If BallotRejectionType fails to cover all the possible ways a ballot may be rejected, this field specifies an alternate reason why the reason the ballot was rejected.

BallotReceivedDate

Data Type: date

Specifies the date the ballot was received by the local or state election official.

BallotReceivedMethod

Data Type: string

Specifies the method by which the ballot was received by the local or state election official. Possible values are email, which signifies the ballot was received via email; fax, which denotes the ballot was received by fax; in-person, which means the ballot was delivered by a person (NB: this does not necessarily signify the voter themselves delivered the ballot); mail, which signifies the ballot was received via mail; online, which means the ballot was submitted via online form or system; untracked, which signifies that this variable is not tracked in the system; and, other, which is a catch-all for any values that fall outside of the other values.

The value of BallotReceivedMethod must be one of the following:

  • email
  • fax
  • in-person
  • mail
  • online
  • untracked
  • other

BallotReceivedOtherMethod

Data Type: string

If BallotReceivedMethod fails to cover all of the possible return types for a particular voter transaction, this field specifies an alternate method by which the voter returned the ballot to the local or state election official.

BallotTransmissionDate

Data Type: date

Specifies the date the local or state election official sent the ballot to the voter.

BallotTransmissionMethod

Data Type: string

Specifies the method in which the ballot was sent to the voter. Possible values are email, which signifies the ballot was transmitted via email; fax, which denotes the ballot was transmitted by fax; in-person, which means the ballot given to a person; mail, which signifies the ballot was transmitted via mail; online, which means the ballot was transmitted via online form or system; untracked, which signifies that this variable is not tracked in the system; and, other, which is a catch-all for any values that fall outside of the other values.

The value of BallotTransmissionMethod must be one of the following:

  • email
  • fax
  • in-person
  • mail
  • online
  • untracked
  • other

BallotTransmissionOtherMethod

Data Type: string

If BallotTransmissionMethod fails to cover all of the possible transmission types for a particular transaction, this field specifies an alternate method in which the local or state election official sent the ballot to the voter.

BallotType

Data Type: string

Specifies the type of ballot transferred to the voter. Possible values are absentee, which is a general catch-all for any type of absentee ballot, federal, which denotes the voter only received a ballot that allows voting on federal contests, full, which denotes a ballot with all possible contests in the voter’s assigned precinct; fwab, which specifies a Federal Write-In Absentee Ballot, and provisional, which denotes a provisional ballot; and, untracked, which signifies that this variable is not tracked in the system.

The value of BallotType must be one of the following:

  • absentee
  • federal
  • full
  • fwab
  • provisional
  • untracked

ElectionDate

Data Type: date

This field is required.

Specifies the date the election took place.

ElectionName

Data Type: string

This field is required.

Specifies the name of the election.

JurisdictionId

Data Type: string

This field is required.

Specifies a unique identifier for the jurisdiction.

JurisdictionIdType

Data Type: string

This field is required.

Specifies the type of identifier used to identify the jurisdiction in JurisdictionId. Possible values are fips, which means the identifier follows the Federal Information Processing Standard (FIPS) code, local, which dictates the jurisdiction created the identifier, or ocd-id, which means the identifier follows the Open Civic Data Division Identifier (OCDID) standard.

The value of JurisdictionIdType must be one of the following:

  • fips
  • local
  • ocd-id

JurisdictionName

Data Type: string

This field is required.

Specifies the name of the jurisdiction in which the voter is registered.

StateName

Data Type: string

This field is required.

Specifies the name of the state in which the voter is registered.

The value of StateName must be one of the following:

  • Alabama
  • Alaska
  • American Samoa
  • Arizona
  • Arkansas
  • California
  • Colorado
  • Connecticut
  • Delaware
  • District of Columbia
  • Federated States of Micronesia
  • Florida
  • Georgia
  • Guam
  • Hawaii
  • Idaho
  • Illinois
  • Indiana
  • Iowa
  • Kansas
  • Kentucky
  • Louisiana
  • Maine
  • Marshall Islands
  • Maryland
  • Massachusetts
  • Michigan
  • Minnesota
  • Mississippi
  • Missouri
  • Montana
  • Nebraska
  • Nevada
  • New Hampshire
  • New Jersey
  • New Mexico
  • New York
  • North Carolina
  • North Dakota
  • Northern Mariana Islands
  • Ohio
  • Oklahoma
  • Oregon
  • Palau
  • Pennsylvania
  • Puerto Rico
  • Rhode Island
  • South Carolina
  • South Dakota
  • Tennessee
  • Texas
  • Utah
  • Vermont
  • Virgin Islands
  • Virginia
  • Washington
  • West Virginia
  • Wisconsin
  • Wyoming

VoterMailingCountry

Data Type: string

Specifies what country to which the ballot was mailed. The country should be a recognized country name according to ISO 3166.

VoterType

Data Type: string

Specifies whether the voter is domestic or overseas military (or simply military if the designation is unknown), a spouse or dependent of a member of the military, or other if the type of voter falls outside the previous designations.

The value of VoterType must be one of the following:

  • domestic-military
  • domestic-military-spouse-dependent
  • military
  • military-spouse-dependent
  • overseas-citizen
  • overseas-military
  • overseas-military-spouse-dependent
  • other