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, 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).

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.

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, address, 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":
    {
    }
}

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

Responses

200

Returns the updated date of data by state code of monitored voters.

400

No monitored voters submitted via POST endpoint.

401

Auth token not included or wrong credentials

get/voter-metadata
https://api.alloy.us/v1/voter-metadata

Request samples

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

Response samples

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

Submit Voters

This endpoint submits new voter records in bulk and adds them to your tracked voters list. When submitting new voter records to the API, the first_name, last_name, address, city, state, and zip fields are required. birth_date, 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 a single 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, address, 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 or the Verify GET 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.

We include the ability to filter your voters by query parameters related to status, zipcode, and registration update dates:

  • registration_status: Use the registration_status query parameter to filter voters whose registration status matches a certain status. Statuses include:

    • Active
    • Challenged
    • Not Eligible
    • Denied
    • Inactive
    • Pending
    • Confirmation
    • Removed
    • Preregistered
    • Rejected
    • Unregistered
    • Verify
    • Cancelled
    • Incomplete
    • Purged
  • zip: Use the zipcode query parameter to filter by your population's zipcode. For example, to find Purged voters who reside in the zipcode 22121, you can use the query params ?registration_status=Purged&zip=22121.

  • exceeding_days: Use the exceeding_days query parameter to filter voters whose registration status has not changed in over the specified number of days. For example, to find voters who reside in 22121, were Pending over 30 days ago, and their status still has not changed, you can use the query params ?registration_status=Pending&zip=22121&exceeding_days=30.

  • within_days: Use the within_days query parameter to filter voters whose registration status has changed within the specified number of days. For example, to find a population of voters who have been Purged within 30 days, you can use the query params ?registration_status=Purged&zip=22121&within_days=30.

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.

registration_status
string

The registration status to filter on.

zip
string

The zip code to filter on.

exceeding_days
integer

Filters on voters whose registration status has not changed in over X days, where X is the value of the query parameter provided.

within_days
integer

Filters on voters whose registration status has changed within X days, where X is the value of the query parameter provided.

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":
    {
    }
}