Download OpenAPI specification:Download
This document describes Alloy's Voter Registration Application Programming Interface (API). To use this interface, you will need to:
All requests to the API require authorization. You will need to obtain credentials the form of an API key and a secret from Alloy before you can use the API. These credentials are akin to a user name and password, and you should not share them with anyone who you do not want to have access to your data.
API keys have a rate limit of 200 request per second for the Verify
GET endpoint and 10 requests per second for all other endpoints. If you need a higher rate limit, please reach out to us!
You will need to provide your credentials with each request. If you are using cURL, a simple way to do this is to store your credentials in a configuration file.
Want to learn more about some of the use cases for Verify? Check out the following How-To Docs:
Our sandbox environment is the first step to getting started with Verify. It uses sample data to simulate what it's like to integrate and use the Verify API, and it's quick and easy (and free) to test out! If you haven't already, start by requesting access to the sandbox here.
Download the sandbox key/secret sent to you by Alloy. This key will only be available to download for 7 days. Please reach out to our team if you need another key sent your way!
Make your first request to the API to validate the issued credentials work as expected. Do not forget to replace API_KEY:API_SECRET with your credentials.
curl --request GET --url https://api.alloy.us/v1/voters --user API_KEY:API_SECRET
You should expect to see a small amount of json returned, with no error indicated.
The sandbox is loaded with fake voter data. Make a call to verify the status for one of these voters. Do not forget to replace API_KEY:API_SECRET with your credentials.
curl --request GET --url 'https://api.alloy.us/v1/verify?first_name=Ron&last_name=Tsosie&address=1299%20Taylor%20St&city=Montgomery&state=AL&zip=36109&birth_date=1963-09-28' --user API_KEY:API_SECRET
Ron should report as being an Active voter.
Now that you have successfully checked the status for a voter, you can explore the other sample voters in the sandbox environment!
first_name | last_name | address | city | zip | state | registration_status | birth_date | permanent_absentee |
---|---|---|---|---|---|---|---|---|
Ron | Tsosie | 1299 Taylor St | Montgomery | 36109 | AL | Active | 1963-09-28 | |
Brandie | Nguyen | 9015 Fairview St | Wasilla | 99654 | AK | 1946-12-11 | ||
Peggy | Lee | 5737 Homestead Rd | Tucson | 85718 | AZ | Cancelled | 1993-11-26 | |
Russell | Kim | 5079 E Pecan St | Little Rock | 72209 | AK | Suspense | 1989-10-17 | |
Louella | Williams | 568 Forest Ln | Santa Monica | 90403 | CA | Active | 1955-01-20 | |
Irene | Johnson | 8027 Hillcrest Rd | Pueblo | 81001 | CO | Active | 1957-11-05 | true |
Rebecca | Jones | 8135 Woodland St | Vernon Rockville | 06066 | CT | Purged | 1946-12-22 | |
Terrence | Brown | 2969 Pecan Acres Ln | Washington | 20020 | DC | Active | 1963-05-05 | |
Mia | Jackson | 1067 Oak Lawn Ave | Bear | 19701 | DE | Inactive | 1996-12-21 | |
Isaac | Davis | 997 Hamilton Ave | Port Orange | 32127 | FL | Inactive | 1947-06-27 | |
Marcus | Thomas | 5712 White Oak Dr | Augusta | 30906 | GA | Active | 1953-06-09 | |
Ken | Garcia | 4473 Hickory Creek Dr | Captain Cook | 96704 | HI | 1961-11-29 | ||
Isaiah | Hernandez | 5406 W Campbell Ave | Pocatello | 83204 | ID | Active | 1993-11-25 | |
Theodore | Sanchez | 9394 Blossom Hill Rd | Lake Zurich | 60047 | IL | 1962-09-30 | ||
Catherine | Medina | 7438 W Sherman Dr | Brownsburg | 46112 | IN | Not Reported | 1977-03-01 | |
Cecil | Flores | 1343 Smokey Ln | Ankeny | 50023 | IA | Pending | 1979-10-13 | |
Janna | Rivera | 4958 Karen Dr | Derby | 67037 | KS | Active | 1949-12-18 | |
Angel | Ramos | 3591 Saddle Dr | Henderson | 42420 | KY | Not Reported | 1946-08-25 | |
Ashley | Vargas | 5231 Dogwood Ave | Baton Rouge | 70806 | LA | Active | 1958-11-26 | |
Stacey | Nunez | 580 Mcclellan Rd | Bangor | 04401 | ME | 1989-09-06 | ||
Edward | Shaw | 7838 Woodland St | Bowie | 20715 | MD | Active | 1978-09-18 | |
Roy | Silva | 1135 Pecan Acres Ln | Watertown | 02472 | MA | 1994-07-15 | ||
Jackson | James | 9474 Karen Dr | Davidson | 48423 | MI | Rejected | 1977-07-13 | false |
Leon | Reyes | 7996 Lakeshore Rd | Brainerd | 56401 | MN | Active | 1998-06-08 | |
Jar | Dunn | 2683 Photinia Ave | Ocean Springs | 39564 | MS | Purged | 1954-01-22 | |
Abigail | Jacobs | 3429 Country Club Rd | Saint Louis | 63109 | MO | Active | 1971-12-19 | |
Rhonda | Jordan | 4498 Northaven Rd | Butte | 59701 | MT | Provisional | 1992-11-15 | |
Letitia | Howard | 4699 Green Rd | Grand Island | 68801 | NE | Active | 1994-05-08 | |
Gertrude | Ruiz | 6235 Oak Lawn Ave | Reno | 89523 | NV | Inactive | 1945-08-24 | |
Susan | Andrews | 2088 W Sherman Dr | Nashua | 03060 | NH | 1956-04-10 | ||
Willie | Watkins | 2568 Adams St | Parsippany | 07054 | NJ | Pending | 1945-09-05 | |
Shannon | Ward | 3229 Plum St | Albuquerque | 87106 | NM | Active | 1978-11-07 | |
Guy | Graves | 5851 W Belt Line Rd | Massapequa Park | 11762 | NY | Preregistered | 2002-06-01 | |
George | Woods | 1101 Karen Dr | Elizabeth City | 27909 | NC | Removed | 1990-07-30 | |
Daisy | Allen | 8766 Dane St | Bismarck | 58501 | ND | Active | 1994-08-09 | |
Warren | Marshall | 4057 Prospect Rd | Hamilton | 45011 | OH | Active | 1945-08-31 | |
Jayden | Ross | 3998 Marsh Ln | Ada | 74820 | OK | Active | 1958-03-27 | |
Maurice | Long | 213 Bollinger Rd | Tualatin | 97062 | OR | Active | 1976-03-25 | true |
Claudine | Fields | 929 W Pecan St | Irwin | 15642 | PA | Inactive | 1978-05-28 | |
Marilyn | Gardner | 1868 Lakeview St | Johnston | 02919 | RI | Pending | 1987-09-11 | |
Darryl | Jensen | 5994 Hunters Creek Dr | Hartsville | 29550 | SC | Active | 1947-09-18 | |
David | Bates | 4697 Miller Ave | Rapid City | 57701 | SD | Inactive | 1980-06-30 | |
Hallie | Hunt | 5656 W Sherman Dr | Oak Ridge | 37830 | TN | Active | 1951-01-18 | |
Nicholas | Turner | 9481 N Stelling Rd | Desoto | 75115 | TX | Cancelled | 1949-02-13 | |
Elsie | Barnett | 9573 Rolling Green Rd | Bountiful | 84010 | UT | Active | 1984-09-20 | true |
Diana | Washington | 6117 Paddock Way | Ascutney | 05030 | VT | Challenged | 1970-08-24 | |
Victor | Evans | 8447 Eason Rd | Fredericksburg | 22405 | VA | 1961-02-05 | ||
Marie | Campbell | 4720 Lovers Ln | Wenatchee | 98801 | WA | Cancelled | 1945-03-31 | false |
Pauline | Lynch | 8727 Pecan Acres Ln | Clarksburg | 26301 | WV | Active | 1962-02-19 | |
Toni | Walters | 8433 Fairview St | Janesville | 53546 | WI | Active | 1996-02-26 | true |
Marion | Weaver | 7059 Marsh Ln | Cheyenne | 82002 | WY | Pending | 1952-08-30 |
Immediately returns the registration information on the voter queried by the authenticated organization.
When submitting new voter records to the API, the first_name
, last_name
, address
, city
, state
, and zip
fields are required. birth_date
is optional, as are middle_name
, suffix
and phone_num
. submitted_registration_date
is optional and reflects the date a person was registered to vote by a voter registration organization (for example, the day their form was mailed in or the day they submitted an online form).
Optional fields are used to narrow in on the voter record that best matches your query parameters. If birth_date is included in your query and does not match the birth date found on the SOS voter record, a null response will be returned. For all other optional fields, if that data is not part of the SOS voter record, it won't impact the match.
In addition to given inputs, the API will return back registration status and registration date. If both registration status and registration date are null, then the person is not found on the voter files and is therefore likely not registered. If registration status is null but there is a non-null registration date, then the person is found on the voter files, but a voter status was not provided by the Secretary of State.
Voters queried through this endpoint can be returned through the Get Voters
query endpoint. An HTTP request to this endpoint will return an id
, which can be used to track the voter through our other endpoints described below.
This endpoint is useful for immediately looking up a single person's current voter registration status at one point in time. To re-check a person's voter registration status and see if anything has changed, you'll need to re-call the API, or you'll need to use the Get Voters
endpoint.
For more information on the voter registration statuses returned for each state, check out Alloy's Voter Status Data Dictionary.
The rate limit for this endpoint is 200 requests/second.
Was this section helpful? Let us know here!
first_name | string Example: first_name=George |
middle_name | string Example: middle_name=G |
last_name | string Example: last_name=Washington |
suffix | string Example: suffix=Jr |
address | string Example: address=3200%20Mount%20Vernon |
city | string Example: city=Mt%20Vernon |
state | string Example: state=VA The capitalized postal code abbreviation for a given state. |
zip | string Example: zip=22121 The Zip code, in either five or nine digit formats (12345 or 12345-6789). |
birth_date | string Example: birth_date=1732-02-22 |
phone_num | string Example: phone_num=555-555-5555 |
curl -u testKey:testSecret 'https://api.alloy.us/v1/verify?first_name=George&last_name=Washington&address=3200%20Mount%20Vernon&city=Mount%20Vernon&state=VA&zip=22121&birth_date=1732-02-22'
{- "api_version": "v1",
- "data": {
- "id": "00000000-0000-0000-0000-000000000000",
- "first_name": "GEORGE",
- "middle_name": "",
- "last_name": "WASHINGTON",
- "suffix": "",
- "address": "3200 MOUNT VERNON",
- "city": "MT VERNON",
- "state": "VA",
- "zip": "22121",
- "birth_date": "1732-02-22",
- "phone_num": "555-555-5555",
- "registration_status": "Active",
- "registration_date": "1732-02-22",
- "submitted_registration_date": "1732-02-22",
- "created_date": "1732-02-22",
- "updated_date": "1732-02-22",
- "registration_changed_date": "1732-02-22",
- "last_updated_date": "1732-02-22",
- "alloy_person_id": 1234512345,
- "is_new_registrant": true
}
}
In some states, voters may request to be placed on a "permanent absentee ballot" list. This list is often maintained alongside the raw voter file data and denotes whether or not a voter meets that state's requirements to be considered permanent absentee for the upcoming election. You can see state specifications for permanent absentee below:
State | List | Specifications |
---|---|---|
Arizona | Permanent Early Voting List | The county will automatically mail the voter an early ballot for every election they’re eligible to vote in. |
Michigan | Permanent Absentee Voter List | Once a voter is on this list, they will automatically receive an absentee voter application before every election. The voter will need to return the application to their local clerk with a valid reason for applying absentee before they’re registered absentee for that election. |
Wisconsin | Permanent Absentee Voter | In order to apply for permanent absentee, a voter must certify that they are indefinitely confined. Once a voter is on the list, they stay on the list until they are no longer confined or until they fail to return a ballot. The definition of indefinitely confined is shifting for 2020 due to COVID-19. Learn more here. |
Some states use an exclusively vote-by-mail system. Voters verified in these states will return ‘true’ for their permanent absentee status. These states include: Colorado, Oregon, Utah, and Washington.
first_name | string Example: first_name=George |
middle_name | string Example: middle_name=G |
last_name | string Example: last_name=Washington |
suffix | string Example: suffix=Jr |
address | string Example: address=3200%20Mount%20Vernon |
city | string Example: city=Mt%20Vernon |
state | string Example: state=VA The capitalized postal code abbreviation for a given state. |
zip | string Example: zip=22121 The Zip code, in either five or nine digit formats (12345 or 12345-6789). |
birth_date | string Example: birth_date=1732-02-22 |
phone_num | string Example: phone_num=555-555-5555 |
curl -u testKey:testSecret 'https://api.alloy.us/v2/vbm/verify?first_name=George&last_name=Washington&address=3200%20Mount%20Vernon&city=Mount%20Vernon&state=VA&zip=22121&birth_date=1732-02-22'
{- "api_version": "v1",
- "data": {
- "id": "00000000-0000-0000-0000-000000000000",
- "first_name": "GEORGE",
- "middle_name": "",
- "last_name": "WASHINGTON",
- "suffix": "",
- "address": "3200 MOUNT VERNON",
- "city": "MT VERNON",
- "state": "VA",
- "zip": "22121",
- "birth_date": "1732-02-22",
- "phone_num": "555-555-5555",
- "submitted_registration_date": "1732-02-22",
- "created_date": "1732-02-22",
- "updated_date": "1732-02-22",
- "permanent_absentee": true,
- "alloy_person_id": 1234512345
}
}
This endpoint returns all state codes with the date the corresponding state was last updated in Alloy's database. You can learn more about how often we are committed to updating state-level voter data on our website: https://alloy.us/verify/details/
Was this section helpful? Let us know here!
curl -u testKey:testSecret -X GET https://api.alloy.us/v1/voter-metadata
{- "api_version": "v1",
- "data": {
- "data_freshness": {
- "VA": "1732-02-22"
}
}
}
This endpoint can be used to check the voter status of many voters at once using a CSV.
The Verify API makes it easy to get the voter registration status for any voter: the Verify GET request can immediately return a voter status for a voter, and the Submit Voters POST request can help you track changing voter statuses over time. However, there may also be cases when you need to check the voter registration status for a large batch of voters one-off to support your voter registration efforts.
You can either implement this endpoint as needed to batch check statuses, or you can submit your CSV of voters through our website and have the results of your query emailed to you, typically within 1-2 days. The link for downloading your results expires one week after it is sent. You’ll only be able to use this form once you have an API key and secret assigned. Please reach out to our Partnerships team at partnerships@alloy.us to request API access if you haven’t already!
Note that when uploading your CSV, the columns should match the query parameters of the /v1/verify endpoint. Any misformatted rows will be removed from the output of voters you receive.
Want to learn more about how to bulk upload voters through Verify? Check out our how-to doc here!
Example:
first_name,middle_name,last_name,suffix,birth_date,zip,address,city,state,phone_num,submitted_registration_date
George,,Washington,,,22121,3200 Mount Vernon,Mt Vernon,VA,,
string <email> | |
file | string <binary> |