Alloy API (1.0.0)

Download OpenAPI specification:Download

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 10 requests per second. 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.

Authentication

basicAuth

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, birth_date, address, city, state, and zip fields are required. phone_num is optional, as are middle_name and suffix.

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 will not be returned through the Get Voters query endpoint.

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.

Authorizations:
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

200

Returns the full information on the voter (including registration status and registration date) queried by the authenticated organization. created_date and updated_date represent the dates when the API user inputted and updated the voter. registration_changed_date reflects the date of any more recent changes to a voter's registration status.

400

Missing required parameters, including first name, last name, birth date, or ZIP

401

Auth token not included or wrong credentials

429

API key rate limit hit

get /verify
https://api.alloy.us/v1/verify

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "api_version": "v1",
  • "data":
    {
    }
}

Submit Voters

This endpoint can be used to keep track of voters' registration statuses as they change over time. Interested in learning more? This feature is currently in Beta, and you can reach out to our partnerships team at partnerships@alloy.us to learn more! Submits new voter records to be tracked by the registration monitoring API. When submitting new voter records to the API, the first_name, last_name, birth_date, address, city, state, and zip fields are required. middle_name, suffix, and phone_num are optional. 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). It is an error to submit records which are missing the required fields or have values defined for appended fields. Users may submit no more than 1000 records per request.

This is endpoint is used for looking up voter registration statuses for many people. To check the voter registration status, that may be queried by the corresponding GET endpoint.

Authorizations:
Request Body schema: application/json
Array
id
string (Uuid)
first_name
string
middle_name
string
last_name
string
suffix
string
address
string
city
string
state
string
zip
string
birth_date
string

Must be in YYYY-MM-DD format.

phone_num
string
submitted_registration_date
string

An optional external date reflecting when an attempt was made to register the voter. Must be in YYYY-MM-DD format.

Responses

200

Returns the voter submitted for tracking, along with the UUID used to identify the individual voter

400

Missing required parameters, including first name, last name, birth date, or ZIP

401

Auth token not included or wrong credentials

413

Payload too large. User may not submit more than 1000 records at a time.

429

API key rate limit hit

post /voters
https://api.alloy.us/v1/voters

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "api_version": "v1",
  • "data":
    {
    }
}

Get Voters

Returns the full information on the voters tracked by the authenticated organization. Tracked voters can only be queried after they have been submitted via the Submit Voters POST request.

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.

We limit responses to 1000 records per request, sorted by updated_date. To paginate through the list of all voter records, you may include page_size and offset query parameters.

Authorizations:
query Parameters
offset
integer

The number of items to skip before starting to collect the result set.

page_size
integer

The numbers of items to return. If this is not provided, the default is 1000 records. The max is also 1000 records.

Responses

200

Returns the full information on the voters (including registration status and registration date) tracked by the authenticated organization. created_date and updated_date represent the dates when the API user inputted and updated the voter. registration_changed_date reflects the date of any more recent changes to a voter's registration status.

401

Auth token not included or wrong credentials

429

API key rate limit hit

get /voters
https://api.alloy.us/v1/voters

Request samples

Copy
curl -u testKey:testSecret https://api.alloy.us/v1/voters

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "api_version": "v1",
  • "data":
    {
    }
}

Get Single Voter

Use this endpoint to get the full information on the voters tracked by the authenticated organization. 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.

Authorizations:
path Parameters
voterId
required
string (Uuid)
Example: 00000000-0000-0000-0000-000000000000

UUID of the tracked voter to get

Responses

200

Returns the full information on the individual voter (including registration status and registration date) tracked by the authenticated organization.

401

Auth token not included or wrong credentials

404

UUID not found

429

API key rate limit hit

get /voters/{voterId}
https://api.alloy.us/v1/voters/{voterId}

Request samples

Copy
curl -u testKey:testSecret -X GET https://api.alloy.us/v1/voters/0000000-0000-0000-0000-000000000000

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "api_version": "v1",
  • "data":
    {
    }
}

Update Single Voter

Use this endpoint to add or replace individual fields of an existing voter record.

Authorizations:
path Parameters
voterId
required
string (Uuid)
Example: 00000000-0000-0000-0000-000000000000

UUID of the tracked voter to update

Request Body schema: application/json

A JSON object containing updated voter information

id
string (Uuid)
first_name
string
middle_name
string
last_name
string
suffix
string
address
string
city
string
state
string
zip
string
birth_date
string

Must be in YYYY-MM-DD format.

phone_num
string
submitted_registration_date
string

An optional external date reflecting when an attempt was made to register the voter. Must be in YYYY-MM-DD format.

Responses

200

The voter was updated successfully

401

Auth token not included or wrong credentials

404

UUID not found

429

API key rate limit hit

post /voters/{voterId}
https://api.alloy.us/v1/voters/{voterId}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "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"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "api_version": "v1",
  • "data": { },
  • "error":
    {
    }
}

Delete Single Voter

Use this endpoint to remove an incorrect existing voter record.

Authorizations:
path Parameters
voterId
required
string (Uuid)
Example: 00000000-0000-0000-0000-000000000000

UUID of the tracked voter to delete

Responses

204

The voter was successfully deleted

401

Auth token not included or wrong credentials

429

API key rate limit hit

delete /voters/{voterId}
https://api.alloy.us/v1/voters/{voterId}

Request samples

Copy
curl -u testKey:testSecret -X DELETE https://api.alloy.us/v1/voters/0000000-0000-0000-0000-000000000000

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "api_version": "v1",
  • "data": { },
  • "error":
    {
    }
}