NationBuilder Petitions API

openapi: 3.2.0
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:
    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'
    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.
    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.
    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.
    petition_response_data:
      description: The JSON:API resource object representing a petition.
      allOf:
      - $ref: '#/components/schemas/resource_identifier'
      - type: object
        properties:
          type:
            const: petitions
            examples:
            - petitions
          attributes:
            $ref: '#/components/schemas/petition_read_write_attributes'
    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'
    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
    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_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
    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'
    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.
    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.
    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_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
    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.
    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.
    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.
    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.
    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
    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_sideload_values:
      description: Relationship names that can be sideloaded with the include query paramete

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