Civitech Verify API

Civitech Verify API (1.0.0)

Civitech: support@civitech.io | URL: civitech.io

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

  • Obtain API credentials from Civitech
  • 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 in the form of an API key and a secret from Civitech 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:

Table of Contents

Sandbox

Authentication

GET Verify Voter Registration Status

GET Verify Permanent Absentee Ballot Status

GET Get Last Updated Date by State

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 support@civitech.io for more information.
curl --request GET --url https://regverify.campaignos.app/v1/voters --user API_KEY:API_SECRET<br>

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://regverify.campaignos.app/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 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

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 Civitech'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
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

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.

RESPONSE SCHEMA: application/json
api_version
string (ApiVersion)
data
object (RegisteredPerson)
id
string (Uuid)
Randomly generated id that changes over time.
first_name
string
middle_name
string
last_name
string
suffix
string
address
string
city
string
state
string
zip
string
birth_date
string
phone_num
string
registration_status
string
registration_date
string
The date the voter was first seen on the SOS file.
submitted_registration_date
string
An optional external date reflecting when an attempt was made to register the voter.
created_date
string
The date a voter was added to your tracked voters list.
updated_date
string
The date a voter was updated in your tracked voter list.
registration_changed_date
string
The date a voter's registration changed from their most recent status to their current status (for ex, the day they went from Inactive to Active).
last_updated_date
string
The date a voter was last seen in our database (this corresponds to the most recent voter file where the voter was seen).
sos_voter_id
integer
A unique identification number given by a state. This identifier is generated by Civitech when this is not provided. 
is_new_registrant
boolean
This field indicates whether a person appeared on a Secretary of State file as an Active registrant after August 1, 2020. The date will change in future election cycles to ensure we are capturing people who register in the final months before an election.
400  Missing required parameters, including first name, last name, address, or ZIP
RESPONSE SCHEMA: application/json
api_version
string
data
object Nullable
error
object (ApiError)
message string
code integer
401  Auth token not included or wrong credentials
RESPONSE SCHEMA: application/json
api_version
string
data
object Nullable
error
object (ApiError)
message string
code integer
429  API key rate limit hit
RESPONSE SCHEMA: application/json
api_version
string
data
object Nullable
error
object (ApiError)
message string
code integer

Request Samples

Shell

curl -u testKey:testSecret 'https://regverify.campaignos.app/v1/verify?first_name=George&last_name=Washington&address=3200%20Mount%20Vernon&city=Mount%20Vernon&state=VA&zip=22121&birth_date=1732-02-22'

Python

import requests
KEY = "testKey"
SECRET = "testSecret"
res = requests.get("https://regverify.campaignos.app/v1/verify?first_name=George&last_name=Washington&address=3200%20Mount%20Vernon&city=Mount%20Vernon&state=VA&zip=22121&birth_date=1732-02-22", auth=(KEY, SECRET))
print(res.content)

Response Samples

200

{
  "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",
    "sos_id": 1234512345,
    "is_new_registrant": true
  }
}

400401429

{
  "api_version": "v1",
  "data": {},
  "error": {
    "message": "This is an error message",
    "code": 0
  }
}

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

Responses

200 

Returns the vote by mail information on the voter queried by the authenticated organization. created_date and updated_date represent the dates when the API user inputted and updated the voter.

RESPONSE SCHEMA: application/json
api_version
string (ApiVersion)
data
object (RegisteredPerson)
id
string (Uuid)
Randomly generated id that changes over time.
first_name
string
middle_name
string
last_name
string
suffix
string
address
string
city
string
state
string
zip
string
birth_date
string
phone_num
string
submitted_registration_date
string
An optional external date reflecting when an attempt was made to register the voter.
created_date
string
The date a voter was added to your tracked voters list.
updated_date
string
The date a voter was updated in your tracked voter list.
permanent_absentee boolean
sos_voter_id
integer
A unique identification number provided by a state. This identifier is generated by Civitech when this is not provided.
400  Missing required parameters, including first name, last name, address, or ZIP
RESPONSE SCHEMA: application/json
api_version
string
data
object Nullable
error
object (ApiError)
message string
code integer
401  Auth token not included or wrong credentials
RESPONSE SCHEMA: application/json
api_version
string
data
object Nullable
error
object (ApiError)
message string
code integer
429  API key rate limit hit
RESPONSE SCHEMA: application/json
api_version
string
data
object Nullable
error
object (ApiError)
message string
code integer

Request Samples

Shell

curl -u testKey:testSecret 'https://regverify.campaignos.app/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'

Python

import requests
KEY = "testKey"
SECRET = "testSecret"
res = requests.get("https://regverify.campaignos.app/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", auth=(KEY, SECRET))
print(res.content)

Response Samples

200

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

400401429

{
  "api_version": "v1",
  "data": {},
  "error": {
    "message": "This is an error message",
    "code": 0
  }
}

Get Last Updated Date by State

This endpoint returns all state codes with the date the corresponding state was last updated in Civitech's database. You can learn more about how often we are committed to updating state-level voter data on our website.

AUTHORIZATIONS:  basicAuth

Responses

200 

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

RESPONSE SCHEMA: application/json
api_version
string (ApiVersion)
data
object (DataFreshness)
data_freshness object
property name* string         
401  Auth token not included or wrong credentials
RESPONSE SCHEMA: application/json
api_version
string
data
object Nullable
error
object (ApiError)
message string
code integer

Request Samples

Shell

curl -u testKey:testSecret -X GET https://regverify.campaignos.app/v1/voter-metadata

Python

import requests
KEY = "testKey"
SECRET = "testSecret"
res = requests.get("https://regverify.campaignos.app/v1/voter-metadata", auth=(KEY, SECRET))
print(res.content)

Response Samples

200

{
  "api_version": "v1",
  "data": {
    "data_freshness": {
      "VA": "1732-02-22"
    }
  }
}

401

{
"api_version": "v1",
"data": { },
"error": {
"message": "This is an error message",
"code": 0
}
}

Still need help? Contact Us Contact Us