NationBuilder Imports API

openapi: 3.2.0
info:
  title: NationBuilder V2 Imports 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.'
servers:
- url: https://{subdomain}.nationbuilder.com
  variables:
    subdomain:
      default: yournation
      description: Your NationBuilder nation slug
security:
- BearerAuth: []
tags:
- name: Imports
  x-tag-expanded: false
  description: All kinds of data can be imported into a nation, when this happens we create an import resource as a record of the imported data. Each import has a type attribute defining the kind of data being imported. Find more information on imports and import types here. This version of the imports API does not currently support creating or archiving imports. Please use the v1 Imports API for this functionality here.
paths:
  /api/v2/imports:
    parameters:
    - $ref: '#/components/parameters/import_index_include'
    - $ref: '#/components/parameters/import_sparse_fields'
    get:
      summary: List all imports in a nation
      tags:
      - Imports
      description: List all imports
      operationId: listImports
      responses:
        '200':
          description: A page of matching imports.
          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/import_index_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '429':
          $ref: '#/components/responses/rate_limited'
  /api/v2/imports/{id}:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/import_show_include'
    - $ref: '#/components/parameters/import_sparse_fields'
    get:
      summary: Show import with provided ID
      tags:
      - Imports
      description: Returns the import that matches the given ID.
      operationId: showImport
      responses:
        '200':
          description: The requested import.
          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/import_show_response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limited'
components:
  schemas:
    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.
    import_read_only_attributes:
      description: The read-only attributes of a import.
      type: object
      properties:
        content_head:
          type:
          - string
          - 'null'
          examples:
          - id, first_name, last_name, amount, amount_in_cents\r\n, Joe, Bloggs, 100, 10000
          description: Comma separated list containing attribute names for the import.
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
        error_lines:
          type:
          - string
          - 'null'
          examples:
          - 'error: Joe Bloggs,Amount must be at least $0.01'
          description: Errors created during the import.
        file_name:
          type:
          - string
          - 'null'
          examples:
          - DonationsImport.csv
          description: File name of the import.
        finished_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: When the import finished.
        is_overwritable:
          type:
          - boolean
          - 'null'
          default: false
          examples:
          - false
          description: Flag used to determine whether non-empty fields are overwritten. Defaults to false.
        lines_count:
          type:
          - integer
          - 'null'
          examples:
          - 1
          description: Number of lines in the import.
        rows_successful:
          type:
          - integer
          - 'null'
          examples:
          - 1
          description: Number of successfully imported rows.
        rows_unsuccessful:
          type:
          - integer
          - 'null'
          examples:
          - 1
          description: Number of unsuccessfully imported rows.
        rows_updated:
          type:
          - integer
          - 'null'
          examples:
          - 1
          description: Number of updated rows.
        started_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
          description: When the import started.
        status:
          type:
          - string
          - 'null'
          enum:
          - finished
          - unprocessable
          - queueing
          - in_progress
          - null
          examples:
          - in_progress
          description: The status of the import.
        tag_list:
          type:
          - string
          - 'null'
          examples:
          - donations-last-week
          description: Assign these tags to the imported signups.
        type:
          type:
          - string
          - 'null'
          examples:
          - People
          description: The import type.
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2019-10-26T10:00:00-04:00'
    import_sideload_values:
      description: Relationship names that can be sideloaded with the include query parameter on import endpoints.
      type: string
      enum:
      - author
      - point_person
      - signups
      - terminator
    import_response_data:
      description: The JSON:API resource object representing a import.
      allOf:
      - $ref: '#/components/schemas/resource_identifier'
      - type: object
        properties:
          type:
            const: imports
            examples:
            - imports
          attributes:
            $ref: '#/components/schemas/import_read_only_attributes'
    resource_identifier:
      description: A JSON:API resource identifier object, the type/id pair that uniquely identifies a single resource.
      type: object
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: Unique identifier of the resource.
          examples:
          - '1'
        type:
          type: string
          description: The JSON:API resource type.
    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
    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
    import_show_response:
      description: A JSON:API response containing a single import.
      allOf:
      - $ref: '#/components/schemas/show_document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/import_response_data'
    rate_limited_response:
      description: The body returned by the rate limiter when an access token exceeds its request quota.
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable explanation of the rate limit.
          examples:
          - You have made too many requests. Please try again later.
    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'
    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.
    resource:
      description: A generic JSON:API resource object. Resources sideloaded in a document's included member use this shape; their attributes are those of the resource type named in the type member.
      allOf:
      - $ref: '#/components/schemas/resource_identifier'
      - type: object
        properties:
          attributes:
            type: object
            description: The attributes of the resource, as documented for its resource type.
          relationships:
            type: object
            description: References from this resource to other resources in the document.
    import_field_values:
      description: Readable import attribute names selectable with sparse fieldsets (fields[imports]).
      type: string
      enum:
      - content_head
      - created_at
      - error_lines
      - file_name
      - finished_at
      - is_overwritable
      - lines_count
      - rows_successful
      - rows_unsuccessful
      - rows_updated
      - started_at
      - status
      - tag_list
      - type
      - updated_at
    import_index_response:
      description: A paginated JSON:API response containing a list of imports.
      allOf:
      - $ref: '#/components/schemas/index_document'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/import_response_data'
  headers:
    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: {}
    Retry-After:
      description: Number of seconds to wait before retrying. Sent with 429 responses.
      schema:
        type: string
        examples:
        - '10'
      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: {}
  responses:
    not_found:
      description: No resource exists with the provided ID.
      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: not_found
            message: Record not found
          schema:
            $ref: '#/components/schemas/error_response'
    unauthorized:
      description: The access token is missing, expired, or not authorized to access this resource.
      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: unauthorized
            message: You are not authorized to access this content. Your access token may be missing. The resource owner also may not have a permission level sufficient to grant access.
          schema:
            $ref: '#/components/schemas/error_response'
    rate_limited:
      description: The access token has exceeded its request quota for the current rate-limit window.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          example:
            message: You have made too many requests. Please try again later.
          schema:
            $ref: '#/components/schemas/rate_limited_response'
  parameters:
    id:
      name: id
      in: path
      description: id
      required: true
      schema:
        type: string
    import_show_include:
      name: include
      in: query
      description: 'Comma-delimited list of sideloaded resources to include as part of the import response.

        See guidance [here](https://support.nationbuilder.com/en/articles/9899245-api-v2-walkthrough#h_2d5333adab) about

        sideloading large numbers of resources and pagination.

        '
      schema:
        type: array
        default: []
        uniqueItems: true
        items:
          $ref: '#/components/schemas/import_sideload_values'
      required: false
      style: form
      explode: false
    import_sparse_fields:
      name: fields[imports]
      in: query
      required: false
      description: Comma-delimited list of import attributes to only return in the response
      schema:
        type: array
        default: []
        uniqueItems: true
        items:
          $ref: '#/components/schemas/import_field_values'
      style: form
      explode: false
    import_index_include:
      name: include
      in: query
      description: 'Comma-delimited list of sideloaded resources to include as part of the import index response.

        See guidance [here](https://support.nationbuilder.com/en/articles/9899245-api-v2-walkthrough#h_2d5333adab) about

        sideloading large numbers of resources and pagination.

        '
      schema:
        type: array
        default: []
        uniqueItems: true
        items:
          $ref: '#/components/schemas/import_sideload_values'
      required: false
      style: form
      explode: false
  securitySchemes:
    BearerAuth:
      description: Authentication using a bearer token (JWT) issued via OAuth.
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Get started with the NationBuilder API
  url: https://nationbuilder.com/api_quickstart