Voter records store the ballot history of a single signup.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nationbuilder-voters-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: NationBuilder V2 Voters API
version: '2.0'
description: 'The NationBuilder V2 API is a JSON:API-compliant API for managing NationBuilder
resources such as people, donations, events, and lists.'
servers:
- url: https://{subdomain}.nationbuilder.com
variables:
subdomain:
default: yournation
description: Your NationBuilder nation slug
security:
- BearerAuth: []
tags:
- name: Voters
x-tag-expanded: false
description: Voter records store the ballot history of a single signup.
paths:
/api/v2/voters:
parameters:
- $ref: '#/components/parameters/voter_index_include'
- $ref: '#/components/parameters/voter_sparse_fields'
post:
summary: Create a voter
tags:
- Voters
description: Creates a voter from given data
operationId: createVoter
responses:
'201':
description: The newly created voter.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/voter_show_response'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'422':
$ref: '#/components/responses/unprocessable'
'429':
$ref: '#/components/responses/rate_limited'
requestBody:
$ref: '#/components/requestBodies/voter_create_request_body'
get:
summary: List all voters in a nation
tags:
- Voters
description: Lists all voters
operationId: listVoters
parameters:
- $ref: '#/components/parameters/pagination_number'
- $ref: '#/components/parameters/pagination_size'
responses:
'200':
description: A page of matching voters.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/voter_index_response'
'401':
$ref: '#/components/responses/unauthorized'
'429':
$ref: '#/components/responses/rate_limited'
/api/v2/voters/{id}:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/voter_show_include'
- $ref: '#/components/parameters/voter_sparse_fields'
get:
summary: Show voter with provided ID
tags:
- Voters
description: Returns the JSON:API resource object for a single voter.
operationId: showVoter
responses:
'200':
description: The requested voter.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/voter_show_response'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/rate_limited'
patch:
summary: Update an existing voter
tags:
- Voters
description: Updates an existing voter
operationId: updateVoter
responses:
'200':
description: The updated voter.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/voter_show_response'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/unprocessable'
'429':
$ref: '#/components/responses/rate_limited'
requestBody:
$ref: '#/components/requestBodies/voter_update_request_body'
delete:
summary: Delete voter with provided ID
tags:
- Voters
description: Permanently removes the voter that matches the given ID.
operationId: deleteVoter
responses:
'200':
description: Confirmation that the voter was deleted.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/delete_document'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/rate_limited'
components:
schemas:
index_document:
description: The JSON:API top-level document shape for paginated collection responses, with resource objects under data and pagination links.
type: object
required:
- data
properties:
data:
type: array
description: The page of resource objects for this collection; each resource binds its concrete item schema here via allOf composition.
links:
$ref: '#/components/schemas/pagination_links'
included:
$ref: '#/components/schemas/included'
meta:
type: object
description: Non-standard information about the document, such as requested statistics. Empty unless the endpoint has metadata to convey.
voter_index_response:
description: A paginated JSON:API response containing a list of voters.
allOf:
- $ref: '#/components/schemas/index_document'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/voter_response_data'
validation_error_document:
description: The JSON:API errors document returned with status 422 when model validations fail on create or update. Unlike this API's flat 4xx error bodies, validation failures follow the JSON:API errors format.
type: object
required:
- errors
properties:
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/validation_error'
voter_field_values:
description: Readable voter attribute names selectable with sparse fieldsets (fields[voters]).
type: string
enum:
- is_absentee_voter
- is_active_voter
- is_dropped_from_file
- is_early_voter
- is_permanent_absentee_voter
- signup_id
voter_create_request:
description: The request body for creating a new voter.
allOf:
- $ref: '#/components/schemas/create_request_document'
- type: object
properties:
data:
type: object
properties:
type:
const: voters
examples:
- voters
attributes:
$ref: '#/components/schemas/voter_read_write_attributes'
resource_identifier:
description: A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource.
type: object
required:
- type
- id
properties:
id:
type: string
description: Unique identifier of the resource.
examples:
- '1'
type:
type: string
description: The JSON:API resource type.
delete_document:
examples:
- meta: {}
description: The successful destroy response, an empty JSON:API meta-only document returned with status 200 (rather than JSON:API's commonly used 204 No Content).
type: object
required:
- meta
additionalProperties: false
properties:
meta:
examples:
- {}
type: object
properties: {}
error_response:
description: The error body returned for 4xx and 5xx responses, with a machine-readable code and a human-readable message. Some errors include additional detail members alongside these two. The exception is 422 validation failures, which are returned as JSON:API errors documents instead.
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code identifying the failure.
examples:
- not_found
message:
type: string
description: Human-readable explanation of the failure.
examples:
- Record not found
pagination_links:
description: JSON:API pagination links for the pages of a collection. A key whose page is unavailable, or that the server's pagination strategy does not provide, is omitted or null.
type: object
properties:
self:
type: string
description: Link to the current page.
examples:
- /articles?page[number]=2
first:
type:
- string
- 'null'
description: Link to the first page.
examples:
- /articles?page[number]=1
last:
type:
- string
- 'null'
description: Link to the last page.
examples:
- /articles?page[number]=5
prev:
type:
- string
- 'null'
description: Link to the previous page.
examples:
- /articles?page[number]=1
next:
type:
- string
- 'null'
description: Link to the next page.
examples:
- /articles?page[number]=3
rate_limited_response:
description: The body returned by the rate limiter when an access token exceeds its request quota.
type: object
required:
- message
properties:
message:
type: string
description: Human-readable explanation of the rate limit.
examples:
- You have made too many requests. Please try again later.
update_request_document:
description: The JSON:API top-level document shape for update requests, whose data member identifies the resource by type and id and carries the changed attributes.
type: object
required:
- data
properties:
data:
type: object
required:
- type
- id
properties:
id:
type: string
description: The ID of the resource being updated.
type:
type: string
description: The JSON:API resource type of the resource being updated.
included:
description: Sideloaded resources requested via the include query parameter. Each entry is a full resource object whose shape is documented under its own resource type.
type: array
items:
$ref: '#/components/schemas/resource'
voter_read_write_attributes:
description: The attributes of a voter that can be both read and written.
type: object
properties:
is_absentee_voter:
type: boolean
default: false
examples:
- false
description: The voter voted via absentee ballot.
is_active_voter:
type: boolean
default: false
examples:
- false
description: The voter actively votes.
is_dropped_from_file:
type: boolean
default: false
examples:
- false
description: When true this indicates the voter was in the file during the last refresh.
is_early_voter:
type: boolean
default: false
examples:
- false
description: Voter votes before the election date.
is_permanent_absentee_voter:
type: boolean
default: false
examples:
- false
description: Voter permanently votes via absentee ballot.
signup_id:
type: string
examples:
- '1'
description: The voter resource's associated Signup ID
show_document:
description: The JSON:API top-level document shape for responses returning a single resource under the data member.
type: object
required:
- data
properties:
data:
type: object
description: The primary resource object; each resource binds its concrete schema here via allOf composition.
included:
$ref: '#/components/schemas/included'
meta:
type: object
description: Non-standard information about the document. Empty unless the endpoint has metadata to convey.
voter_sideload_values:
description: Relationship names that can be sideloaded with the include query parameter on voter endpoints.
type: string
enum:
- ballots
- signup
voter_show_response:
description: A JSON:API response containing a single voter.
allOf:
- $ref: '#/components/schemas/show_document'
- type: object
properties:
data:
$ref: '#/components/schemas/voter_response_data'
voter_response_data:
description: The JSON:API resource object representing a voter.
allOf:
- $ref: '#/components/schemas/resource_identifier'
- type: object
properties:
type:
const: voters
examples:
- voters
attributes:
$ref: '#/components/schemas/voter_read_write_attributes'
resource:
description: A generic JSON:API resource object. Resources sideloaded in a document's included member use this shape; their attributes are those of the resource type named in the type member.
allOf:
- $ref: '#/components/schemas/resource_identifier'
- type: object
properties:
attributes:
type: object
description: The attributes of the resource, as documented for its resource type.
relationships:
type: object
description: References from this resource to other resources in the document.
create_request_document:
description: The JSON:API top-level document shape for create requests, whose data member carries the new resource's type and attributes.
type: object
required:
- data
properties:
data:
type: object
required:
- type
properties:
type:
type: string
description: The JSON:API resource type of the resource being created.
validation_error:
description: A single JSON:API error object describing a validation failure, locating the invalid field via source.pointer and carrying the model-level attribute, message, and code under meta.
type: object
properties:
code:
type: string
description: Machine-readable error code.
examples:
- unprocessable_entity
status:
type: string
description: The HTTP status code, as a string.
examples:
- '422'
title:
type: string
description: Short human-readable summary of the error type.
examples:
- Validation Error
detail:
type: string
description: Human-readable explanation specific to this failure.
examples:
- Email 'not-an-email' should look like an email address
source:
type: object
properties:
pointer:
type: string
description: JSON Pointer to the request document member the error relates to.
examples:
- /data/attributes/email
meta:
type: object
description: The underlying model validation error, including the attribute name, message, and code. Errors on sideposted resources nest these members under a relationship key.
properties:
attribute:
type: string
description: The attribute that failed validation.
message:
type: string
description: The validation failure message.
code:
type: string
description: The validation failure code.
voter_update_request:
description: The request body for updating an existing voter.
allOf:
- $ref: '#/components/schemas/update_request_document'
- type: object
properties:
data:
type: object
properties:
id:
type: string
examples:
- '1'
type:
const: voters
examples:
- voters
attributes:
$ref: '#/components/schemas/voter_read_write_attributes'
headers:
RateLimit-Reset:
description: Unix timestamp (in seconds) at which the current rate-limit window resets.
schema:
type: string
examples:
- '1719964810'
examples: {}
RateLimit-Limit:
description: Maximum number of requests allowed for the current access token per rate-limit window (10 seconds).
schema:
type: string
examples:
- '250'
examples: {}
RateLimit-Remaining:
description: Number of requests remaining for the current access token in the current rate-limit window.
schema:
type: string
examples:
- '249'
examples: {}
Retry-After:
description: Number of seconds to wait before retrying. Sent with 429 responses.
schema:
type: string
examples:
- '10'
examples: {}
responses:
not_found:
description: No resource exists with the provided ID.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/json:
example:
code: not_found
message: Record not found
schema:
$ref: '#/components/schemas/error_response'
unauthorized:
description: The access token is missing, expired, or not authorized to access this resource.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/json:
example:
code: unauthorized
message: You are not authorized to access this content. Your access token may be missing. The resource owner also may not have a permission level sufficient to grant access.
schema:
$ref: '#/components/schemas/error_response'
rate_limited:
description: The access token has exceeded its request quota for the current rate-limit window.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
example:
message: You have made too many requests. Please try again later.
schema:
$ref: '#/components/schemas/rate_limited_response'
bad_request:
description: The request body or query parameters are invalid, such as an unknown attribute, filter, filter operator, sort field, or sideload.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/json:
example:
code: bad_request
message: Tried to filter on attribute :bogus, but could not find an attribute with that name.
schema:
$ref: '#/components/schemas/error_response'
unprocessable:
description: Model validations failed for the resource being created or updated. Unlike this API's other errors, validation failures are returned as a JSON:API errors document locating each invalid field.
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
content:
application/vnd.api+json:
example:
errors:
- code: unprocessable_entity
status: '422'
title: Validation Error
detail: Email 'not-an-email' should look like an email address
source:
pointer: /data/attributes/email
meta:
attribute: email
message: '''not-an-email'' should look like an email address'
schema:
$ref: '#/components/schemas/validation_error_document'
parameters:
voter_show_include:
name: include
in: query
description: 'Comma-delimited list of sideloaded resources to include as part of the voter response.
See guidance [here](https://support.nationbuilder.com/en/articles/9899245-api-v2-walkthrough#h_2d5333adab) about
sideloading large numbers of resources and pagination.
'
schema:
type: array
default: []
uniqueItems: true
items:
$ref: '#/components/schemas/voter_sideload_values'
required: false
style: form
explode: false
voter_sparse_fields:
name: fields[voters]
in: query
required: false
description: Comma-delimited list of voter attributes to only return in the response
schema:
type: array
default: []
uniqueItems: true
items:
$ref: '#/components/schemas/voter_field_values'
style: form
explode: false
voter_index_include:
name: include
in: query
description: 'Comma-delimited list of sideloaded resources to include as part of the voter index response.
See guidance [here](https://support.nationbuilder.com/en/articles/9899245-api-v2-walkthrough#h_2d5333adab) about
sideloading large numbers of resources and pagination.
'
schema:
type: array
default: []
uniqueItems: true
items:
$ref: '#/components/schemas/voter_sideload_values'
required: false
style: form
explode: false
pagination_number:
name: page[number]
description: Page number to list (starting at 1)
in: query
required: false
schema:
type: string
default: '1'
pagination_size:
name: page[size]
description: 'Number of results to display per page (default: 20, max: 100, min: 1)'
in: query
required: false
schema:
type: string
default: '20'
id:
name: id
in: path
description: id
required: true
schema:
type: string
requestBodies:
voter_update_request_body:
description: The attributes to update on the existing voter.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/voter_update_request'
application/json:
schema:
$ref: '#/components/schemas/voter_update_request'
voter_create_request_body:
description: The voter to create.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/voter_create_request'
application/json:
schema:
$ref: '#/components/schemas/voter_create_request'
securitySchemes:
BearerAuth:
description: Authentication using a bearer token (JWT) issued via OAuth.
type: http
scheme: bearer
bearerFormat: JWT
externalDocs:
description: Get started with the NationBuilder API
url: https://nationbuilder.com/api_quickstart