openapi: 3.0.3
info:
  title: Bloomerang REST API v2 Constituents Reference Data API
  description: The Bloomerang REST API v2 is a private-key, server-to-server API for reading and writing data in a Bloomerang donor management CRM account - constituents, transactions (donations, pledges, recurring donations), interactions, notes, relationships, and webhook subscriptions. Requests are authenticated with either a private API key sent in the X-Api-Key header (generated by an Administrator user under User Settings) or an OAuth 2.0 access token for third-party applications. Bloomerang does not offer a sandbox environment - all requests operate against production data. Endpoints for Constituents, Transactions, and Interactions are directly confirmed in Bloomerang's public documentation and third-party integration guides; endpoints for Households, Notes, Relationships, Custom Fields, Webhooks, Users, Funds, Campaigns, and Appeals are modeled from Bloomerang's REST API v1 resource parity, community client libraries, and CRM feature documentation, since Bloomerang does not publish a complete, versioned OpenAPI/Swagger document for v2. See review.yml in this repository for the endpointsConfirmed vs endpointsModeled breakdown.
  version: '2.0'
  contact:
    name: Bloomerang
    url: https://bloomerang.com/api/rest-api
servers:
- url: https://api.bloomerang.co/v2
  description: Bloomerang REST API v2 (production - no sandbox is offered)
security:
- apiKeyAuth: []
- oauth2Bearer: []
tags:
- name: Reference Data
  description: Users, funds, campaigns, and appeals used as designations and attribution.
paths:
  /users:
    get:
      operationId: listUsers
      tags:
      - Reference Data
      summary: List CRM users
      description: Lists the CRM users on the account, for attributing interactions and tasks. Endpoint modeled from Bloomerang REST API v1 User resource parity - see review.yml.
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funds:
    get:
      operationId: listFunds
      tags:
      - Reference Data
      summary: List funds
      description: Lists the funds available as transaction designations. Endpoint modeled from Bloomerang REST API v1 Fund resource parity - see review.yml.
      responses:
        '200':
          description: A list of funds.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Fund'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /campaigns:
    get:
      operationId: listCampaigns
      tags:
      - Reference Data
      summary: List campaigns
      description: Lists fundraising campaigns. Endpoint modeled from Bloomerang REST API v1 Campaign resource parity - see review.yml.
      responses:
        '200':
          description: A list of campaigns.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appeals:
    get:
      operationId: listAppeals
      tags:
      - Reference Data
      summary: List appeals
      description: Lists fundraising appeals. Endpoint modeled from Bloomerang REST API v1 Appeal resource parity - see review.yml.
      responses:
        '200':
          description: A list of appeals.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Appeal'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Fund:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
        IsActive:
          type: boolean
    Campaign:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
        StartDate:
          type: string
          format: date
        EndDate:
          type: string
          format: date
        GoalAmount:
          type: number
          format: double
    User:
      type: object
      properties:
        Id:
          type: integer
        FirstName:
          type: string
        LastName:
          type: string
        EmailAddress:
          type: string
          format: email
        IsActive:
          type: boolean
    Error:
      type: object
      properties:
        Message:
          type: string
        Errors:
          type: array
          items:
            type: string
    Appeal:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
        IsActive:
          type: boolean
  responses:
    Unauthorized:
      description: Missing or invalid API key / access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Private API key generated by an Administrator user in Bloomerang under User Settings > Edit My User. Grants full read/write access - keep it secret.
    oauth2Bearer:
      type: oauth2
      description: 'OAuth 2.0 access token for third-party applications, presented as `Authorization: Bearer {access_token}`.'
      flows:
        authorizationCode:
          authorizationUrl: https://crm.bloomerang.co/oauth/authorize
          tokenUrl: https://api.bloomerang.co/v2/oauth/token
          scopes:
            api: Full read/write access to account data.