openapi: 3.1.2
info:
title: NationBuilder V2 Async Processes Petitions 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. It layers a few
conventions on top of the JSON:API standard, described below. For a broader
introduction, see the
[NationBuilder v2 API core concepts](https://support.nationbuilder.com/en/articles/9757369-nationbuilder-v2-api-core-concepts)
guide.
### Request and response format
Requests and responses follow the [JSON:API](https://jsonapi.org/) document
structure: single resources are returned under a top-level `data` member, and
collections are paginated arrays of resource objects with `links` for the
current, previous, and next pages. Related resources can be sideloaded into a
top-level `included` array with the `include` query parameter, and responses
can be trimmed to specific attributes with `fields[resource_type]` sparse
fieldsets (plus opt-in `extra_fields[resource_type]` attributes where noted).
Responses are served as `application/vnd.api+json`; request bodies may be
sent as `application/vnd.api+json` or `application/json`.
Filtering uses an operator syntax: `filter[attribute]=value` for
equality (comma-separated values act as OR), and
`filter[attribute][operator]=value` for other comparisons. String attributes
support `eq`, `not_eq`, `eql`, `not_eql`, `prefix`, `not_prefix`, `suffix`,
`not_suffix`, `match`, and `not_match`; numeric and date attributes support
`eq`, `not_eq`, `gt`, `gte`, `lt`, and `lte`. Note that JSON:API relationship
routes (`/resource/{id}/relationships/other`) are not provided; related
resources are reachable through the filtered index URLs given in each
resource''s `relationships` links.
### Errors
Error responses use a flat JSON body with a machine-readable `code` and a
human-readable `message`. Some errors carry additional detail members (for
example `validation_errors`). The exception is 422 validation failures,
which return a JSON:API `errors` array locating each invalid field via
`source.pointer`.
### Rate limiting
Requests are limited per access token (250 requests per 10-second window).
Every response includes `RateLimit-Limit`, `RateLimit-Remaining`, and
`RateLimit-Reset` headers; exceeding the limit returns a 429 with a
`Retry-After` header.
'
servers:
- url: https://{subdomain}.nationbuilder.com
variables:
subdomain:
default: yournation
description: Your NationBuilder nation slug
security:
- BearerAuth: []
tags:
- name: Petitions
x-tag-expanded: false
description: Petitions are pages on your site that can be signed and shared by your supporters. Learn more about them [here](https://support.nationbuilder.com/en/articles/2327303-create-a-petition).
paths:
/api/v2/petitions:
parameters:
- $ref: '#/components/parameters/petition_index_include'
- $ref: '#/components/parameters/petition_sparse_fields'
post:
summary: Create a petition
tags:
- Petitions
description: Creates a petition from given data
operationId: createPetition
responses:
'201':
description: The newly created petition.
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/petition_show_response_with_required_sidepost'
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'422':
$ref: '#/components/responses/unprocessable'
'429':
$ref: '#/components/responses/rate_limited'
requestBody:
description: The petition to create.
content:
application/vnd.api+json:
example:
data:
type: petitions
attributes:
intro: Petition intro
content: Petition content
goal: 5
additional_signatures_count: 10
signature_name: endorsement
is_auto_response: false
page_id: '1'
auto_response_broadcaster_id: '1'
auto_response_subject: Auto response subject
auto_response_content: Auto response content
gather_volunteers: false
petition_form_address: required
petition_form_phone: optional
relationships:
page:
data:
type: pages
temp-id: new-id
method: create
included:
- type: pages
temp-id: new-id
attributes:
site_id: '1'
parent_id: '1'
author_id: '1'
external_id: abc
slug: your-slug
status: unlisted
name: Page Name
headline: Page headline
title: Page Title
excerpt: Page excerpt...
page_type_name: Petition
permission_level: anyone
schema:
$ref: '#/components/schemas/petition_create_request'
application/json:
example:
data:
type: petitions
attributes:
intro: Petition intro
content: Petition content
goal: 5
additional_signatures_count: 10
signature_name: endorsement
is_auto_response: false
page_id: '1'
auto_response_broadcaster_id: '1'
auto_response_subject: Auto response subject
auto_response_content: Auto response content
gather_volunteers: false
petition_form_address: required
petition_form_phone: optional
relationships:
page:
data:
type: pages
temp-id: new-id
method: create
included:
- type: pages
temp-id: new-id
attributes:
site_id: '1'
parent_id: '1'
author_id: '1'
external_id: abc
slug: your-slug
status: unlisted
name: Page Name
headline: Page headline
title: Page Title
excerpt: Page excerpt...
page_type_name: Petition
permission_level: anyone
schema:
$ref: '#/components/schemas/petition_create_request'
get:
summary: List all petitions in a nation
tags:
- Petitions
description: Lists all petitions
operationId: listPetitions
parameters:
- $ref: '#/components/parameters/pagination_number'
- $ref: '#/components/parameters/pagination_size'
responses:
'200':
description: A page of matching petitions.
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/petition_index_response'
'401':
$ref: '#/components/responses/unauthorized'
'429':
$ref: '#/components/responses/rate_limited'
/api/v2/petitions/{id}:
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/petition_show_include'
- $ref: '#/components/parameters/petition_sparse_fields'
get:
summary: Show petition with provided ID
tags:
- Petitions
description: Returns the JSON:API resource object for a single petition.
operationId: showPetition
responses:
'200':
description: The requested petition.
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/petition_show_response'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/rate_limited'
patch:
summary: Update an existing petition
tags:
- Petitions
description: Updates an existing petition
operationId: updatePetition
responses:
'200':
description: The updated petition.
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/petition_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/petition_update_request_body'
delete:
summary: Delete petition with provided ID
tags:
- Petitions
description: Permanently removes the petition that matches the given ID.
operationId: deletePetition
responses:
'200':
description: Confirmation that the petition 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:
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
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.
petition_index_response:
description: A paginated JSON:API response containing a list of petitions.
allOf:
- $ref: '#/components/schemas/index_document'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/petition_response_data'
petition_field_values:
description: Readable petition attribute names selectable with sparse fieldsets (fields[petitions]).
type: string
enum:
- additional_signatures_count
- auto_response_broadcaster_id
- auto_response_content
- auto_response_subject
- content
- gather_volunteers
- goal
- intro
- is_auto_response
- page_id
- petition_form_address
- petition_form_phone
- signature_name
sidepost_relationship_data:
description: Identifies a related resource written in the same request (a sidepost), an extension to JSON:API. For method create, the temp-id links this relationship entry to the matching object in the request's top-level included array; the other methods identify an existing related resource by id. Omitting method associates an existing resource without modifying it.
type: object
required:
- type
properties:
type:
type: string
description: The JSON:API type of the related resource.
id:
type: string
description: The ID of an existing related resource; used with every method except create.
temp-id:
type: string
description: Client-generated temporary ID tying this relationship to an entry in the included array when creating the related resource.
examples:
- new-id
method:
type: string
description: The sidepost operation to perform on the related resource.
enum:
- create
- update
- destroy
- disassociate
examples:
- create
page_sidepost_attributes:
description: Writable page attributes for sideposting; excludes page_type_name which the parent resource sets.
type: object
properties:
author_id:
type:
- string
- 'null'
examples:
- '1'
description: The author of the page.
excerpt:
type:
- string
- 'null'
examples:
- Page excerpt...
description: Longer page description used for search engine optimization.
external_id:
type:
- string
- 'null'
examples:
- abc
description: Optional reference for pages imported from an external service.
headline:
type:
- string
- 'null'
examples:
- Page headline
description: This is a header rendered above the page content.
name:
type: string
examples:
- Page Name
description: The name of the page.
parent_id:
type:
- string
- 'null'
examples:
- '1'
description: The parent page ID (null for top-level pages).
permission_level:
type: string
enum:
- anyone
- logged_in
- members
- control_panel_users
- admins
examples:
- anyone
description: 'The permission level required to view this page. Options: "anyone" (public access), "logged_in" (any authenticated user), "members" (site members only), "control_panel_users" (users with control panel access), "admins" (site administrators only).'
site_id:
type: string
examples:
- '1'
description: The site this page belongs to.
slug:
type: string
examples:
- your-slug
description: A unique identifier that also makes up the url of the page. www.yoursite.com/[slug]
status:
type: string
enum:
- archived
- deleted
- expired
- hidden
- published
- rule_violated
- unlisted
examples:
- unlisted
description: The page status - describing the visibility of the page.
title:
type: string
examples:
- Page Title
description: Brief page description seen on search engines.
petition_update_request:
description: The request body for updating an existing petition.
allOf:
- $ref: '#/components/schemas/update_request_document'
- type: object
properties:
data:
type: object
properties:
id:
type: string
examples:
- '1'
type:
const: petitions
examples:
- petitions
attributes:
$ref: '#/components/schemas/petition_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.
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
petition_show_response_with_required_sidepost:
description: A JSON:API response containing a single petition, with the related page always sideloaded (included).
allOf:
- $ref: '#/components/schemas/show_document'
- type: object
properties:
data:
$ref: '#/components/schemas/petition_response_data'
included:
examples:
- - type: pages
id: '1'
attributes:
site_id: '1'
parent_id: '1'
author_id: '1'
external_id: abc
slug: your-slug
status: unlisted
name: Page Name
headline: Page headline
title: Page Title
excerpt: Page excerpt...
page_type_name: Petition
permission_level: anyone
parent_slug: blog
url_path: /your-slug
published_at: '2019-10-26T10:00:00-04:00'
ancestors_permission_level: members
effective_permission_level: control_panel_users
temp-id: new-id
type: array
items:
type: object
properties:
type:
type: string
const: pages
examples:
- pages
id:
type: string
examples:
- '1'
attributes:
allOf:
- $ref: '#/components/schemas/page_sidepost_attributes'
- $ref: '#/components/schemas/page_read_only_attributes'
- type: object
properties:
page_type_name:
type: string
examples:
- Petition
description: Must be 'Petition' since this is the page associated with the petition.
enum:
- Petition
temp-id:
type: string
examples:
- new-id
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.
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.
petition_read_write_attributes:
description: The attributes of a petition that can be both read and written.
type: object
properties:
additional_signatures_count:
type:
- integer
- 'null'
default: 0
examples:
- 10
description: Number of offline signatures to add to the signature count total.
auto_response_broadcaster_id:
type:
- string
- 'null'
examples:
- '1'
description: The broadcaster that sends the autoresponse.
auto_response_content:
type:
- string
- 'null'
examples:
- Auto response content
description: The content of the autoresponse email.
auto_response_subject:
type:
- string
- 'null'
examples:
- Auto response subject
description: The subject in the autoresponse email.
content:
type:
- string
- 'null'
examples:
- Petition content
description: The content is rendered on the petition page.
gather_volunteers:
type:
- boolean
- 'null'
examples:
- false
description: Ask for signers to volunteer.
goal:
type:
- integer
- 'null'
default: 0
examples:
- 5
description: The number of signatures you want this petition to receive.
intro:
type:
- string
- 'null'
examples:
- Petition intro
description: The intro is rendered on the petition page above the content.
is_auto_response:
type:
- boolean
- 'null'
default: true
examples:
- false
description: Sends an autoresponse to a signup after signing the petition.
page_id:
type:
- string
- 'null'
examples:
- '1'
description: ID of the page associated with the petition
petition_form_address:
type:
- string
- 'null'
enum:
- required
- optional
- hidden
- null
examples:
- required
description: Require or ask signers to include their address in the signature.
petition_form_phone:
type:
- string
- 'null'
enum:
- required
- optional
- hidden
- null
examples:
- optional
description: Require or ask signers to include their phone number in the signature.
signature_name:
type:
- string
- 'null'
examples:
- endorsement
description: What you call a signature.
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: {}
petition_show_response:
description: A JSON:API response containing a single petition.
allOf:
- $ref: '#/components/schemas/show_document'
- type: object
properties:
data:
$ref: '#/components/schemas/petition_response_data'
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.
petition_sideload_values:
description: Relationship names that can be sideloaded with the include query parameter on petition endpoints.
type: string
enum:
- page
- petition_signatures
page_read_only_attributes:
description: The read-only attributes of a page.
type: object
properties:
ancestors_permission_level:
type:
- string
- 'null'
examples:
- members
description: The most restrictive permission level inherited from parent pages in the hierarchy. Returns null if the page has no parent.
effective_permission_level:
type: string
examples:
- control_panel_users
description: The actual permission level that will be enforced for this page. This is the most restrictive level between the page itself and its ancestors, ensuring users need the highest required access level to view the page.
parent_slug:
type:
- string
- 'null'
examples:
- blog
description: The parent page slug (null for top-level pages).
published_at:
type:
- string
- 'null'
format: date-time
examples:
- '2019-10-26T10:00:00-04:00'
description: When this page was published.
url_path:
type: string
examples:
- /your-slug
description: URL to the page.
petition_create_request:
description: The request body for creating a new petition.
allOf:
- $ref: '#/components/schemas/create_request_document'
- type: object
properties:
data:
type: object
properties:
type:
const: petitions
examples:
- petitions
attributes:
$ref: '#/components/schemas/petition_read_write_attributes'
relationships:
type: object
properties:
page:
type: object
properties:
data:
allOf:
- $ref: '#/components/schemas/sidepost_relationship_data'
- type: object
properties:
type:
const: pages
examples:
- pages
included:
examples:
- - type: pages
temp-id: new-id
attributes:
site_id: '1'
parent_id: '1'
author_id: '1'
external_id: abc
slug: your-slug
status: unlisted
name: Page Name
headline: Page headline
title: Page Title
excerpt: Page excerpt...
page_type_name: Petition
permission_level: anyone
type: array
items:
type: object
properties:
type:
type: string
const: pages
examples:
- pages
temp-id:
type: string
examples:
- new-id
attributes:
allOf:
- $ref: '#/components/schemas/page_sidepost_attributes'
- type: object
properties:
page_type_name:
type: string
examples:
- Petition
description: Must be 'Petition' since this page is being created for the petition.
enum:
- Petition
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'
petition_response_data:
description: The JSON:API resource object representing a petition.
allOf:
- $ref: '#/components/schemas/resource_identifier'
-
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nationbuilder/refs/heads/main/openapi/nationbuilder-petitions-api-openapi.yml