Lists are collections of signups. Often created from filters they are useful for grouping signups together by common attributes. They can be used to perform batch updates on signups or as a list of recipients for a mailing blast. Read more on what you can do with lists [here](https://support.nationbuilder.com/en/articles/2305947-create-a-list).
NationBuilder Lists API is one of 41 APIs that NationBuilder publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Lists. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and a getting-started guide.
This API exposes
10 operations
across 7 paths,
and defines 28 schemas.
It is described by OpenAPI 3.1.2, at version 2.0.
Requests are made against a single base URL, https://{subdomain}.nationbuilder.com.
10 operations7 paths28 schemas1 DELETE3 GET5 PATCH1 POST
Metadata
The identity and technical contract details declared by the specification.
Specification
OpenAPI 3.1.2
API Version
2.0
Base URL
https://{nation-slug}.nationbuilder.com/api/v2
Authentication
HTTP Bearer
Resource Areas
1
Authentication & Security 1
NationBuilder Lists API declares
1 security scheme
for authenticating requests.
It accepts HTTP bearer tokens (JWT) (BearerAuth).
By default, every request must be authenticated.
BearerAuth — Authentication using a bearer token (JWT) issued via OAuth.
Paths & Operations 10
Across 7 paths, the API surfaces 10 operations — 1 DELETE, 3 GET, 5 PATCH, 1 POST. Each is listed below with its method, path, parameters, and response codes.
Lists 10
Lists are collections of signups. Often created from filters they are useful for grouping signups together by common attributes. They can be used to perform batch updates on signu…
POST
/api/v2/lists
Create a list
createList2 paramsbody→ 201400401422429
GET
/api/v2/lists
List all lists in a nation
listLists4 params→ 200401429
GET
/api/v2/lists/{id}
Show list with provided ID
showList3 params→ 200401404429
PATCH
/api/v2/lists/{id}
Update an existing list
updateList3 paramsbody→ 200400401404422429
DELETE
/api/v2/lists/{id}
Delete list with provided ID
deleteList3 params→ 200401404429
PATCH
/api/v2/lists/{id}/add_signups
Add signups
addSignups1 parambody→ 202400401404429
PATCH
/api/v2/lists/{id}/remove_signups
Remove signups
removeSignups1 parambody→ 202400401404429
GET
/api/v2/lists/{id}/signups
List all signups on the list for provided ID
listSignupListings5 params→ 200401404429
PATCH
/api/v2/lists/{id}/tag
Add a tag to signups
tagSignups1 parambody→ 202400401404429
PATCH
/api/v2/lists/{id}/untag
Remove a tag from signups
untagSignups1 parambody→ 202400401404429
Schemas 28
The contract defines 28 schemas that model the data the API accepts and returns. The most detailed are signup_read_write_attributes (128 properties), signup_read_only_attributes (13 properties), list_read_write_attributes (7 properties), validation_error (6 properties). Each schema is shown below with its type and property counts.
error_response
object
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 alo…
2 properties2 required
show_document
object
The JSON:API top-level document shape for responses returning a single resource under the data member.
3 properties1 required
list_read_write_attributes
object
The attributes of a list that can be both read and written.
7 properties
resource_identifier
object
A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource.
2 properties2 required
signup_response_data
The JSON:API resource object representing a signup.
signup_sideload_values
string
Relationship names that can be sideloaded with the include query parameter on signup endpoints.
signup_read_only_attributes
object
The read-only attributes of a signup.
13 properties
list_create_request
The request body for creating a new list.
pagination_links
object
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…
5 properties
list_field_values
string
Readable list attribute names selectable with sparse fieldsets (fields[lists]).
signup_read_write_attributes
object
The attributes of a signup that can be both read and written.
128 properties
signup_index_response
A paginated JSON:API response containing a list of signups.
list_response_data
The JSON:API resource object representing a list.
index_document
object
The JSON:API top-level document shape for paginated collection responses, with resource objects under data and pagination links.
4 properties1 required
validation_error
object
A single JSON:API error object describing a validation failure, locating the invalid field via source.pointer and carrying the model-level attribute, message,…
6 properties
list_update_request
The request body for updating an existing list.
list_index_response
A paginated JSON:API response containing a list of lists.
list_sideload_values
string
Relationship names that can be sideloaded with the include query parameter on list endpoints.
delete_document
object
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).
1 property1 required
list_show_response
A JSON:API response containing a single list.
rate_limited_response
object
The body returned by the rate limiter when an access token exceeds its request quota.
1 property1 required
list_read_only_attributes
object
The read-only attributes of a list.
3 properties
validation_error_document
object
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 fail…
1 property1 required
update_request_document
object
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.
1 property1 required
create_request_document
object
The JSON:API top-level document shape for create requests, whose data member carries the new resource's type and attributes.
1 property1 required
resource
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…
signup_field_values
string
Readable signup attribute names selectable with sparse fieldsets (fields[signups]).
included
array
Sideloaded resources requested via the include query parameter. Each entry is a full resource object whose shape is documented under its own resource type.
Specification
The full machine-readable OpenAPI contract behind this narrative.
