NationBuilder Lists API

openapi: 3.1.2
info:
  title: NationBuilder V2 Async Processes Lists 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: Lists
  x-tag-expanded: false
  description: 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).
paths:
  /api/v2/lists:
    parameters:
    - $ref: '#/components/parameters/list_index_include'
    - $ref: '#/components/parameters/list_sparse_fields'
    post:
      summary: Create a list
      tags:
      - Lists
      description: Creates a list from given data
      operationId: createList
      responses:
        '201':
          description: The newly created list.
          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/list_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/list_create_request_body'
    get:
      summary: List all lists in a nation
      tags:
      - Lists
      description: Lists all lists
      operationId: listLists
      parameters:
      - $ref: '#/components/parameters/pagination_number'
      - $ref: '#/components/parameters/pagination_size'
      responses:
        '200':
          description: A page of matching lists.
          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/list_index_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '429':
          $ref: '#/components/responses/rate_limited'
  /api/v2/lists/{id}:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/list_show_include'
    - $ref: '#/components/parameters/list_sparse_fields'
    get:
      summary: Show list with provided ID
      tags:
      - Lists
      description: Returns the list that matches the given ID.
      operationId: showList
      responses:
        '200':
          description: The requested list.
          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/list_show_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
    patch:
      summary: Update an existing list
      tags:
      - Lists
      description: Updates an existing list
      operationId: updateList
      responses:
        '200':
          description: The updated list.
          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/list_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/list_update_request_body'
    delete:
      summary: Delete list with provided ID
      tags:
      - Lists
      description: Permanently removes the list that matches the given ID.
      operationId: deleteList
      responses:
        '200':
          description: Confirmation that the list 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'
  /api/v2/lists/{id}/add_signups:
    parameters:
    - $ref: '#/components/parameters/id'
    patch:
      summary: Add signups
      tags:
      - Lists
      description: 'Add Signup IDs to list via an asynchronous process.

        Returns the token of an asynchronous process that can be queried using another endpoint.

        Accepts up to 10,000 signup IDs in a single payload.

        '
      operationId: addSignups
      responses:
        '202':
          description: A token for tracking the asynchronous add-signups process.
          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:
                type: object
                properties:
                  token:
                    type: string
                    examples:
                    - '1234'
        '400':
          description: The add-signups request exceeded the maximum of 10,000 signup IDs.
          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: A maximum of 10000 signup ids are allowed
              schema:
                $ref: '#/components/schemas/error_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
      requestBody:
        description: The signups to add to the list.
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list to add signups to.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    signup_ids:
                      type: array
                      description: IDs of the signups to add to custom list.
                      examples:
                      - - '1'
                        - '2'
                  required:
                  - id
                  - type
                  - signup_ids
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list to add signups to.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    signup_ids:
                      type: array
                      description: IDs of the signups to add to custom list.
                      examples:
                      - - '1'
                        - '2'
                  required:
                  - id
                  - type
                  - signup_ids
        required: true
  /api/v2/lists/{id}/remove_signups:
    parameters:
    - $ref: '#/components/parameters/id'
    patch:
      summary: Remove signups
      tags:
      - Lists
      description: 'Remove Signup IDs from a list via an asynchronous process.

        Returns the token of an asynchronous process that can be queried using another endpoint.

        Accepts up to 10,000 signup IDs in a single payload.

        '
      operationId: removeSignups
      responses:
        '202':
          description: A token for tracking the asynchronous remove-signups process.
          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:
                type: object
                properties:
                  token:
                    type: string
                    examples:
                    - '1234'
        '400':
          description: The remove-signups request exceeded the maximum of 10,000 signup IDs.
          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: A maximum of 10000 signup ids are allowed
              schema:
                $ref: '#/components/schemas/error_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
      requestBody:
        description: The signups to remove from the list.
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list to remove signups from.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    signup_ids:
                      type: array
                      description: IDs of the signups to remove from custom list
                      examples:
                      - - '1'
                        - '2'
                  required:
                  - id
                  - type
                  - signup_ids
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list to remove signups from.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    signup_ids:
                      type: array
                      description: IDs of the signups to remove from custom list
                      examples:
                      - - '1'
                        - '2'
                  required:
                  - id
                  - type
                  - signup_ids
        required: true
  /api/v2/lists/{id}/signups:
    parameters:
    - name: id
      in: path
      description: List id
      required: true
      schema:
        type: string
    - $ref: '#/components/parameters/signup_show_include'
    - $ref: '#/components/parameters/signup_sparse_fields'
    get:
      summary: List all signups on the list for provided ID
      tags:
      - Lists
      description: Lists all signups for a given list
      operationId: listSignupListings
      parameters:
      - $ref: '#/components/parameters/pagination_number'
      - $ref: '#/components/parameters/pagination_size'
      responses:
        '200':
          description: A page of matching signups on this list.
          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:
              schema:
                $ref: '#/components/schemas/signup_index_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
  /api/v2/lists/{id}/tag:
    parameters:
    - $ref: '#/components/parameters/id'
    patch:
      summary: Add a tag to signups
      tags:
      - Lists
      description: 'Tag signups in list via an asynchronous process. If the tag does not exist it is created.

        Returns the token of an asyncrhronously process that can be queried using another endpoint.

        '
      operationId: tagSignups
      responses:
        '202':
          description: A token for tracking the asynchronous tag-signups process.
          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:
                type: object
                properties:
                  token:
                    type: string
                    examples:
                    - '1234'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
      requestBody:
        description: The tags to apply to the list.
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list whose signups will be tagged.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    tag:
                      type: string
                      description: Tag name used to tag signups
                      examples:
                      - supporter
                  required:
                  - id
                  - type
                  - tag
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list whose signups will be tagged.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    tag:
                      type: string
                      description: Tag name used to tag signups
                      examples:
                      - supporter
                  required:
                  - id
                  - type
                  - tag
        required: true
  /api/v2/lists/{id}/untag:
    parameters:
    - $ref: '#/components/parameters/id'
    patch:
      summary: Remove a tag from signups
      tags:
      - Lists
      description: 'Remove tag from signups in list via an asynchronous process.

        Returns the token of an asyncrhronously process that can be queried using another endpoint.

        '
      operationId: untagSignups
      responses:
        '202':
          description: A token for tracking the asynchronous untag-signups process.
          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:
                type: object
                properties:
                  token:
                    type: string
                    examples:
                    - '1234'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
      requestBody:
        description: The tags to remove from the list.
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list whose signups will be untagged.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    tag:
                      type: string
                      description: Tag to remove from signups
                      examples:
                      - supporter
                  required:
                  - id
                  - type
                  - tag
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the list whose signups will be untagged.
                      examples:
                      - '1'
                    type:
                      type: string
                      const: lists
                      description: Resource type. Must always be lists.
                      examples:
                      - lists
                    tag:
                      type: string
                      description: Tag to remove from signups
                      examples:
                      - supporter
                  required:
                  - id
                  - type
                  - tag
        required: true
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.
    list_read_write_attributes:
      description: The attributes of a list that can be both read and written.
      type: object
      properties:
        author_id:
          type:
          - string
          - 'null'
          examples:
          - '1'
          description: The ID of the list's author.
        description:
          type:
          - string
          - 'null'
          examples:
          - All supporters that have been contacted by us
          description: Describes what the list is for.
        is_sharing_writable:
          type:
          - boolean
          - 'null'
          default: false
          examples:
          - false
          description: Gives edit permission to people who the list is shared.
        name:
          type:
          - string
          - 'null'
          examples:
          - Contacted Supporters
          description: The name of the custom list.
        parent_id:
          type:
          - string
          - 'null'
          examples:
          - '1'
          description: The id of the original list this was split off from.
        signup_id:
          type:
          - string
          - 'null'
          examples:
          - '1'
          description: The person who this list is assigned to, not the author.
        slug:
          type:
          - string
          - 'null'
          examples:
          - contacted_supporters
          description: A unique identifier for the list. Not required for groups.
    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.
    signup_response_data:
      description: The JSON:API resource object representing a signup.
      allOf:
      - $ref: '#/components/schemas/resource_identifier'
      - type: object
        properties:
          type:
            const: signups
            examples:
            - signups
          attributes:
            allOf:
            - $ref: '#/components/schemas/signup_read_write_attributes'
            - $ref: '#/components/schemas/signup_read_only_attributes'
    signup_sideload_values:
      description: Relationship names that can be sideloaded with the include query parameter on signup endpoints.
      type: string
      enum:
      - author
      - last_contacted_by
      - memberships
      - page
      - parent
      - path_journeys
      - petition_signatures
      - precinct
      - recruiter
      - signup_profile
      - signup_tags
      - taggings
      - voter
    signup_read_only_attributes:
      description: The read-only attributes of a signup.
      type: object
      properties:
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
        email1_is_bouncing:
          type:
          - boolean
          - 'null'
          examples:
          - false
          description: Whether email address 1 is marked as bounced.
        email2_is_bouncing:
          type:
          - boolean
          - 'null'
          examples:
          - false
          description: Whether email address 2 is marked as bounced.
        email3_is_bouncing:
          type:
          - boolean
          - 'null'
          examples:
          - false
          description: Whether email address 3 is marked as bounced.
        email4_is_bouncing:
          type:
          - boolean
          - 'null'
          examples:
          - false
          description: Whether email address 4 is marked as bounced.
        full_name:
          type:
          - string
          - 'null'
          examples:
          - Lucy Octavia Butler
          description: Signup's full name.
        is_cpu:
          type:
          - boolean
          - 'null'
          examples:
          - false
          description: Is the signup a control panel user
        is_donor:
          type:
          - boolean
          - 'null'
          examples:
          - false
          description: The signup is a donor.
        note_updated_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: Last time the note was updated.
        priority_level_changed_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: The last time the priority level changed.
        profile_content_html:
          type:
          - string
          - 'null'
          examples:
          - <h1>My Profile</h1>
          description: HTML formatted version of the signup's profile contents.
        support_level_changed_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: When the signups support level changed.
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
    list_create_request:
      description: The request body for creating a new list.
      allOf:
      - $ref: '#/components/schemas/create_request_document'
      - type: object
        properties:
          data:
            type: object
            properties:
              type:
                const: lists
                examples:
                - lists
              attributes:
                $ref: '#/components/schemas/list_read_write_attributes'
    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
    list_field_values:
      description: Readable list attribute names selectable with sparse fieldsets (fields[lists]).
      type: string
      enum:
      - author_id
      - created_at
      - description
      - is_sharing_writable
      - name
      - parent_id
      - signup_id
      - signups_count
      - slug
     

# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nationbuilder/refs/heads/main/openapi/nationbuilder-lists-api-openapi.yml