openapi: 3.0.3
info:
  title: Bloomerang REST API v2 Constituents Households 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: Households
  description: Family-unit grouping of individual constituents.
paths:
  /households:
    post:
      operationId: createHousehold
      tags:
      - Households
      summary: Create a household
      description: Creates a household constituent grouping one or more individual constituent members. Endpoint modeled from Bloomerang REST API v1 household resource parity; not independently confirmed for v2 - see review.yml.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HouseholdInput'
      responses:
        '200':
          description: The created household.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Household'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /households/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the household constituent.
      schema:
        type: integer
    get:
      operationId: getHousehold
      tags:
      - Households
      summary: Retrieve a household
      description: Retrieves a household by ID. Endpoint modeled from Bloomerang REST API v1 household resource parity - see review.yml.
      responses:
        '200':
          description: The requested household.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Household'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateHousehold
      tags:
      - Households
      summary: Update a household
      description: Updates household membership or details. Endpoint modeled from Bloomerang REST API v1 household resource parity - see review.yml.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HouseholdInput'
      responses:
        '200':
          description: The updated household.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Household'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Household:
      allOf:
      - $ref: '#/components/schemas/HouseholdInput'
      - type: object
        properties:
          Id:
            type: integer
    HouseholdInput:
      type: object
      required:
      - Name
      properties:
        Name:
          type: string
        MemberIds:
          type: array
          description: Constituent IDs of the individuals belonging to this household.
          items:
            type: integer
        Address:
          type: object
          properties:
            Street:
              type: string
            City:
              type: string
            State:
              type: string
            PostalCode:
              type: string
            Country:
              type: string
    Error:
      type: object
      properties:
        Message:
          type: string
        Errors:
          type: array
          items:
            type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key / access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      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.