openapi: 3.0.3
info:
  title: Fundraise Up REST API
  description: >-
    The Fundraise Up REST API gives programmatic access to fundraising data for a
    nonprofit's Fundraise Up account. It is resource-oriented, uses predictable
    URLs, accepts JSON-encoded request bodies with a Content-Type of
    application/json, and returns JSON responses. The API lets you work with
    Donations, Recurring Plans, Supporters (donors), and Events (an audit log),
    and generate Donor Portal access links. Donations and recurring plans can be
    created and updated, but updates are only allowed within 24 hours of creation;
    supporters and events are read-only. List endpoints use cursor-based
    pagination via the limit, starting_after, and ending_before query parameters.
    All requests authenticate with an API key (created in the dashboard under
    Settings > API keys) passed as an HTTP Bearer token. Fundraise Up does not
    expose a WebSocket API; event-based syncing is done by polling the Events
    resource. Field-level request and response schemas are intentionally left open
    here and should be reconciled against the hosted reference at
    https://api.fundraiseup.com/v1/docs/.
  version: '1.0'
  contact:
    name: Fundraise Up
    url: https://fundraiseup.com
  license:
    name: Proprietary
    url: https://fundraiseup.com/terms/
servers:
  - url: https://api.fundraiseup.com/v1
    description: Fundraise Up REST API
security:
  - bearerAuth: []
tags:
  - name: Donations
    description: One-time and recurring donations, including offline and ACH donations.
  - name: Recurring Plans
    description: Recurring donation plans modeling a supporter's ongoing giving.
  - name: Supporters
    description: Donor records (Fundraise Up calls donors "supporters").
  - name: Events
    description: Audit-log events across donations, recurring plans, tributes, and supporters.
  - name: Donor Portal
    description: Secure access-link generation for the self-service Donor Portal.
paths:
  /donations:
    get:
      operationId: listDonations
      tags:
        - Donations
      summary: List donations
      description: Retrieves donations with cursor-based pagination.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
      responses:
        '200':
          description: A paginated list of donations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DonationList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createDonation
      tags:
        - Donations
      summary: Create a donation
      description: >-
        Creates a one-time or recurring donation, including donations collected
        outside the website and ACH US Direct Debit donations (which require a
        Stripe Payment Method ID created in Stripe beforehand).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Donation'
      responses:
        '200':
          description: The created donation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /donations/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getDonation
      tags:
        - Donations
      summary: Retrieve a donation
      description: Retrieves the details of a specific donation by ID.
      responses:
        '200':
          description: The requested donation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateDonation
      tags:
        - Donations
      summary: Update a donation
      description: >-
        Updates a donation. Updates are only permitted within 24 hours of the
        donation's creation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Donation'
      responses:
        '200':
          description: The updated donation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /recurring_plans:
    get:
      operationId: listRecurringPlans
      tags:
        - Recurring Plans
      summary: List recurring plans
      description: Retrieves recurring donation plans with cursor-based pagination.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
      responses:
        '200':
          description: A paginated list of recurring plans.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringPlanList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createRecurringPlan
      tags:
        - Recurring Plans
      summary: Create a recurring plan
      description: Creates a recurring donation plan.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringPlan'
      responses:
        '200':
          description: The created recurring plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /recurring_plans/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getRecurringPlan
      tags:
        - Recurring Plans
      summary: Retrieve a recurring plan
      description: Retrieves the details of a specific recurring plan by ID.
      responses:
        '200':
          description: The requested recurring plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateRecurringPlan
      tags:
        - Recurring Plans
      summary: Update a recurring plan
      description: >-
        Updates a recurring plan. Updates are only permitted within 24 hours of
        the plan's creation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringPlan'
      responses:
        '200':
          description: The updated recurring plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /supporters:
    get:
      operationId: listSupporters
      tags:
        - Supporters
      summary: List supporters
      description: Retrieves supporters (donor records) with cursor-based pagination.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
      responses:
        '200':
          description: A paginated list of supporters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupporterList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /supporters/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getSupporter
      tags:
        - Supporters
      summary: Retrieve a supporter
      description: Retrieves the details of a specific supporter by ID.
      responses:
        '200':
          description: The requested supporter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Supporter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /events:
    get:
      operationId: listEvents
      tags:
        - Events
      summary: List events
      description: >-
        Retrieves audit-log events across donations, transaction attempts,
        recurring plans, tributes, and supporters, with cursor-based pagination.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
      responses:
        '200':
          description: A paginated list of events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /events/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getEvent
      tags:
        - Events
      summary: Retrieve an event
      description: Retrieves the details of a specific event by ID.
      responses:
        '200':
          description: The requested event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /donor_portal/access_links/supporters/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      operationId: createSupporterAccessLink
      tags:
        - Donor Portal
      summary: Create a supporter Donor Portal access link
      description: >-
        Generates a secure link that lets a supporter open their Donor Portal
        without logging in.
      responses:
        '200':
          description: The generated access link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /donor_portal/access_links/recurring_plans/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      operationId: createRecurringPlanAccessLink
      tags:
        - Donor Portal
      summary: Create a recurring-plan Donor Portal access link
      description: >-
        Generates a secure link that lets a supporter access a specific recurring
        plan in the Donor Portal without logging in.
      responses:
        '200':
          description: The generated access link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key created in the dashboard under Settings > API keys, sent as a Bearer token.
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Number of records to return, from 1 to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    StartingAfter:
      name: starting_after
      in: query
      required: false
      description: A cursor (object ID) to fetch the page of records after it.
      schema:
        type: string
    EndingBefore:
      name: ending_before
      in: query
      required: false
      description: A cursor (object ID) to fetch the page of records before it.
      schema:
        type: string
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
    NotFound:
      description: The requested resource does not exist.
    TooManyRequests:
      description: Rate limit exceeded (8 requests/second or 128 requests/minute).
  schemas:
    Pagination:
      type: object
      properties:
        has_more:
          type: boolean
          description: Whether more records are available beyond this page.
    Donation:
      type: object
      description: A one-time or recurring donation. Field schema to be reconciled against the hosted reference.
      properties:
        id:
          type: string
        object:
          type: string
          example: donation
      additionalProperties: true
    DonationList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Donation'
    RecurringPlan:
      type: object
      description: A recurring donation plan. Field schema to be reconciled against the hosted reference.
      properties:
        id:
          type: string
        object:
          type: string
          example: recurring_plan
      additionalProperties: true
    RecurringPlanList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/RecurringPlan'
    Supporter:
      type: object
      description: A supporter (donor) record. Field schema to be reconciled against the hosted reference.
      properties:
        id:
          type: string
        object:
          type: string
          example: supporter
      additionalProperties: true
    SupporterList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Supporter'
    Event:
      type: object
      description: An audit-log event. Field schema to be reconciled against the hosted reference.
      properties:
        id:
          type: string
        object:
          type: string
          example: event
        type:
          type: string
          description: The event type, for example donation.success or recurring_plan.activated.
      additionalProperties: true
    EventList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Event'
    AccessLink:
      type: object
      description: A secure Donor Portal access link.
      properties:
        url:
          type: string
          format: uri
      additionalProperties: true