Documentation Powered by ReDoc

Alloy API (1.0.0)

Download OpenAPI specification:Download

Alloy: info@alloy.us URL: https://alloy.us Terms of Service

This document describes Alloy's Voter Registration Application Programming Interface (API). To use this interface, you will need to:

  • Obtain API credentials from Alloy
  • Transform your voter contact list into a JSON format
  • Submit all or portion of your JSON voter records to the API
  • Query the API to obtain the submitted voter records with voter registration status appended to it.

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.

Sandbox

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.

  • Once you request access, someone from our team will reach out and issue you a sandbox key and secret.
  • The url for the sandbox is the same as production.
  • When querying this data, you'll only be able to match and see voter registration statuses for a set of fake voters. If you want access to production data, you'll need to work with a member of our team to sign a service agreement. Contact partnerships@alloy.us for more information.

Getting Started

Download

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!

First Request

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.

Verify a Voter

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.

Explore voter data

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 2003-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

Authentication

basicAuth

HTTP Basic Authentication. The username is the api key and the password is the api secret.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Verify Voter Registration Status

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.

Authorizations:
basicAuth
query Parameters
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
zip
string
Example: zip=22121
birth_date
string
Example: birth_date=1732-02-22
phone_num
string
Example: phone_num=555-555-5555

Responses

Request samples 

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'

Response samples

Content type
application/json
{
  • "api_version": "v1",
  • "data":
    {
    }
}

Verify Permanent Absentee Ballot Status

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.

Authorizations:
basicAuth
query Parameters
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
zip
string
Example: zip=22121
birth_date
string
Example: birth_date=1732-02-22
phone_num
string
Example: phone_num=555-555-5555

Responses

Request samples 

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'

Response samples

Content type
application/json
{
  • "api_version": "v1",
  • "data":
    {
    }
}

Get Last Updated Date by State for Your Voters

Once you've checked the status of a voter or group of voters through the Submit Voters POST endpoint, Verify Absentee endpoint, or the Verify endpoint, you can use this endpoint to see if there have been updates to Alloy's data that may have impacted a voter's status. This endpoint returns all state codes found in your population of voters 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/

Authorizations:
basicAuth

Responses

Request samples 

curl -u testKey:testSecret -X GET https://api.alloy.us/v1/voter-metadata

Response samples

Content type
application/json
{
  • "api_version": "v1",
  • "data":
    {