NationBuilder Lists API

openapi: 3.2.0
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:
  headers:
    Retry-After:
      description: Number of seconds to wait before retrying. Sent with 429 responses.
      schema:
        type: string
        examples:
        - '10'
      examples: {}
    RateLimit-Reset:
      description: Unix timestamp (in seconds) at which the current rate-limit window resets.
      schema:
        type: string
        examples:
        - '1719964810'
      examples: {}
    RateLimit-Remaining:
      description: Number of requests remaining for the current access token in the current rate-limit window.
      schema:
        type: string
        examples:
        - '249'
      examples: {}
    RateLimit-Limit:
      description: Maximum number of requests allowed for the current access token per rate-limit window (10 seconds).
      schema:
        type: string
        examples:
        - '250'
      examples: {}
  schemas:
    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.
    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_response_data:
      description: The JSON:API resource object representing a list.
      allOf:
      - $ref: '#/components/schemas/resource_identifier'
      - type: object
        properties:
          type:
            const: lists
            examples:
            - lists
          attributes:
            allOf:
            - $ref: '#/components/schemas/list_read_write_attributes'
            - $ref: '#/components/schemas/list_read_only_attributes'
    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.
    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'
    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
    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'
    list_read_only_attributes:
      description: The read-only attributes of a list.
      type: object
      properties:
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: When the list was created.
        signups_count:
          type:
          - integer
          - 'null'
          examples:
          - 372
          description: The number of signups on the list.
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: The last time the list was updated.
    signup_read_write_attributes:
      description: The attributes of a signup that can be both read and written.
      type: object
      properties:
        author_id:
          type:
          - string
          - 'null'
          examples:
          - '1'
          description: ID of the person interacting with the signup in the control panel.
        availability:
          type:
          - string
          - 'null'
          examples:
          - Saturday morning
          description: When can this signup be contacted?
        banned_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: When the signup was banned.
        born_at:
          type:
          - string
          - 'null'
          format: date
          examples:
          - '1990-08-06'
          description: The date the signup was born.
        capital_amount_in_cents:
          type:
          - integer
          - 'null'
          default: 0
          examples:
          - 500
          description: The amount of political capital this signup has accrued
        church:
          type:
          - string
          - 'null'
          examples:
          - Unity Church
          description: The name of the church the signup belongs to.
        city_district:
          type:
          - string
          - 'null'
          examples:
          - Trinity-Spadina (19)
          description: The city district code the signup belongs to.
        city_sub_district:
          type:
          - string
          - 'null'
          examples:
          - DOWNTOWN LOS ANGELES
          description: Political district.
        civicrm_id:
         

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