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. In addition, if there are questions about a particular voter’s transactions, an organization could provide this identifier back to the jurisdiction to glean more information about the voter’s experience.

ApplicationRequestMethod

Data Type: string

This field is required.

Specifies the method by which the application request was received. Possible values are email, which signifies the application was received via email; fax, which denotes the application was received by fax; in-person, which means the application was delivered by a person (NB: this does not necessarily signify the voter themselves delivered the application); mail, which signifies the application was received via mail; online, which means the application was submitted via online form or system; 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 ApplicationRequestMethod must be one of the following:

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

ApplicationRequestOtherMethod

Data Type: string

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

ApplicationRequestPostmarkDate

Data Type: date

Specifies the date the request was postmarked. If there is any confusion as to the whether the date the application was recorded was the date on the postmark or the date the application was physically received by the election administration entity, assume postmark and use this field rather than ApplicationRequestReceivedDate.

ApplicationRequestProcessedDate

Data Type: date

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

ApplicationRequestReceivedDate

Data Type: date

Specifies the date the application request was received by the local or state election official. In mail-only states, this date is the most recent date the voter became an active UOCAVA voter.

ApplicationRequestRejectionType

Data Type: array

This field is required.

If ApplicationRequestStatusType is rejected or cured, then specifies the reason the application 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, 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 ApplicationRequestRejectionType must be one of the following:

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

ApplicationRequestRejectionOtherType

Data Type: string

If ApplicationRequestRejectionType fails to cover all possible types of Application Rejection reasons, this field will list an alternate type.

ApplicationRequestStatusType

Data Type: string

This field is required.

Specifies the current status of the application. Possible values are accepted, which denotes that the application was successfully processed; cured which means the application was supplemented with additional information to make it valid; pending, which signifies that application is still being processed; rejected which means the application was not successfully processed.

The value of ApplicationRequestStatusType must be one of the following:

  • accepted
  • cured
  • pending
  • rejected

ApplicationRequestType

Data Type: string

This field is required.

Specifies the type of ballot application request. 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 used for ballot requests; and untracked, which means the type of application is not tracked.

The value of ApplicationRequestType 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 of the possible ways a ballot may be rejected, this field specifies an alternate reason why the reason the ballot was rejected.

BallotReturnDate

Data Type: date

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

BallotReturnType

Data Type: string

Specifies the method by which the voter returned the ballot to 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 BallotReturnType must be one of the following:

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

BallotReturnOtherType

Data Type: string

If BallotReturnType 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.

BallotTransmissionType

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 BallotTransmissionType must be one of the following:

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

BallotTransmissionOtherType

Data Type: string

If BallotTransmissionType 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 local, which dictates the jurisdiction created the identifier, fips, which means the identifier follows the Federal Information Processing Standard (FIPS) code, 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:

  • ocd-id
  • fips
  • local

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, if the domestic or overseas designation is unknown, simply whether the voter is military), overseas citizen, or other.

The value of VoterType must be one of the following:

  • domestic-military
  • military
  • overseas-citizen
  • overseas-military
  • other

WasApplicationRejected

Data Type: boolean

Deprecated. Specifies whether the application request was accepted or rejected.