> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List fundraising portfolio relationships

> Lists ready projected donors, households or relationship groups with attributed giving, retention, contact risk and optional planning summaries. Defaults to configured household grouping. Planning filters apply only with the plan feature enabled. Requires permission: one of donors_view.



## OpenAPI

````yaml get /admin/fundraising/portfolio
openapi: 3.0.0
info:
  title: Gratona API
  description: >-
    REST API for the Gratona fundraising platform, including donor, donation,
    sponsorship, program, event, and integration workflows. Endpoints are
    organized by tag. Most endpoints require either a Passport bearer token or
    an issued API key — see the Security Schemes section.
  contact:
    name: Gratona Engineering
    url: https://gratona.com
    email: devs@gratona.com
  version: 1.0.0
servers:
  - url: https://api.gratona.com/v1
    description: Server Version 1.0.0
security: []
tags:
  - name: Auth
    description: >-
      Login, signup, logout, password reset, and email verification for admin
      users and donors.
  - name: Donors
    description: >-
      Donor records: CRUD, profile fields, household linkage, search, filters,
      merge, and duplicate detection.
  - name: Donations
    description: >-
      Individual donation records, recurring commitments, soft credits, refunds,
      designations, and exports.
  - name: Sponsorships
    description: >-
      Donor-to-entity commitment relationships, lifecycle transitions, and
      commitment-specific filters.
  - name: Entities
    description: >-
      Recipient records (children, families, projects, animals, etc.), their
      status, and entity-level fields.
  - name: Programs
    description: >-
      Program / campaign configuration: hierarchy, settings, and program-level
      metadata.
  - name: Forms
    description: >-
      Custom form builder (HysForm), form fields, standardized donor fields, and
      field migrations.
  - name: Trips
    description: >-
      Mission-trip management: trips, participants, budgets, tasks,
      e-signatures, fundraising milestones, and background checks.
  - name: Communications
    description: >-
      Email templates, SMS, newsletters, donor email manager, and per-donor
      notes.
  - name: Payments
    description: >-
      Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks).
      Excludes inbound webhooks — see the Webhooks tag.
  - name: Reports
    description: Dashboards, analytics, scheduled reports, and exports.
  - name: Admin
    description: >-
      Client-account administration: users, groups/permissions, settings,
      integrations, and account lifecycle.
  - name: Donor Portal
    description: >-
      Endpoints consumed by the donor-facing portal (donor login, dashboard,
      donation history, messages).
  - name: Recipient Portal
    description: Endpoints consumed by the recipient-facing portal.
  - name: Public
    description: >-
      Unauthenticated public endpoints: donor signup, public trip pages,
      peer-to-peer campaigns, public checkout.
  - name: Webhooks
    description: >-
      Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr,
      DropboxSign). Annotated minimally for reference; payload shapes are owned
      by the upstream provider.
  - name: Events
    description: >-
      Event setup, invitations, registration, ticketing, attendance and event
      reporting.
  - name: Journeys
    description: >-
      Journey graphs, activation, enrollment, message templates and event
      follow-up automations.
  - name: Tasks
    description: Workspace tasks, assignments, saved task views and record collaboration.
  - name: Fundraising
    description: >-
      Fundraising portfolios, stewardship plans, giving anniversaries and
      personal donor follow-up.
  - name: Impact Stories
    description: Story intake, review, assets, consent and publication workflows.
  - name: Integrations
    description: Workspace integration connections, mappings, synchronization and recovery.
  - name: Email Calendar
    description: Connected email/calendar accounts and donor interactions.
  - name: Spaces
    description: Workspace Spaces and collaborative Pages.
  - name: Library
    description: Workspace documents, source connections, files and analysis.
  - name: Intelligence
    description: Donor intelligence and Tali workspace workflows.
  - name: Automation
    description: >-
      V3 automation primitive discovery, input validation, invocation and Zapier
      contracts.
  - name: Schema
    description: V3 model, enum, capability and scope discovery.
  - name: Zapier
    description: Zapier automation connections, polling feeds and actions.
  - name: Files
    description: Files
  - name: Client
    description: Client
  - name: Payment Gateways
    description: Payment Gateways
  - name: Email Settings
    description: Email Settings
  - name: Admin Dashboard
    description: Admin Dashboard
  - name: Recipients
    description: Recipients
  - name: Historical Archived Updates
    description: Historical Archived Updates
  - name: Team & access
    description: Team & access
  - name: Settings
    description: Settings
  - name: Notifications
    description: Notifications
  - name: Participation
    description: Participation
  - name: Users
    description: Users
  - name: Wrapped
    description: Wrapped
  - name: Donor SignUp
    description: Donor SignUp
  - name: Frontend
    description: Frontend
  - name: User
    description: User
  - name: Workspace
    description: Workspace
paths:
  /admin/fundraising/portfolio:
    get:
      tags:
        - Fundraising
      summary: List fundraising portfolio relationships
      description: >-
        Lists ready projected donors, households or relationship groups with
        attributed giving, retention, contact risk and optional planning
        summaries. Defaults to configured household grouping. Planning filters
        apply only with the plan feature enabled. Requires permission: one of
        donors_view.
      operationId: fundraisingHubPortfolio
      parameters:
        - name: acknowledgement_work_scope
          in: query
          description: >-
            Acknowledgement work scope. Validation: nullable; allowed values:
            active, historical, all.
          required: false
          schema:
            type: string
            enum:
              - active
              - historical
              - all
              - null
            nullable: true
          example: active
        - name: fundraiser_user_id
          in: query
          description: >-
            Relationship-manager id, all or unassigned; scoped by donor
            visibility.
          required: false
          schema:
            type: string
            maxLength: 64
            nullable: true
          example: all
        - name: group_by_household
          in: query
          description: >-
            Boolean-like query input; true/false and numeric forms are
            normalized by this workflow.
          required: false
          schema:
            type: boolean
            nullable: true
          example: false
        - name: search
          in: query
          description: 'Search. Validation: nullable, string, max:255.'
          required: false
          schema:
            type: string
            maxLength: 255
            nullable: true
          example: education
        - name: date_from
          in: query
          description: 'Date from. Validation: nullable, date.'
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
          example: '2026-10-20T12:00:00Z'
        - name: date_to
          in: query
          description: 'Date to. Validation: nullable, date.'
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
          example: '2026-10-20T12:00:00Z'
        - name: state
          in: query
          description: 'State. Validation: nullable, string, max:64.'
          required: false
          schema:
            type: string
            maxLength: 64
            nullable: true
          example: State
        - name: comparison_mode
          in: query
          description: 'Comparison mode. Validation: nullable, string, max:64.'
          required: false
          schema:
            type: string
            maxLength: 64
            nullable: true
          example: Comparison Mode
        - name: current_start
          in: query
          description: 'Current start. Validation: nullable, date.'
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
          example: '2026-10-20T12:00:00Z'
        - name: current_end
          in: query
          description: 'Current end. Validation: nullable, date.'
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
          example: '2026-10-20T12:00:00Z'
        - name: comparison_start
          in: query
          description: 'Comparison start. Validation: nullable, date.'
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
          example: '2026-10-20T12:00:00Z'
        - name: comparison_end
          in: query
          description: 'Comparison end. Validation: nullable, date.'
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
          example: '2026-10-20T12:00:00Z'
        - name: refresh
          in: query
          description: >-
            Boolean-like query input; true/false and numeric forms are
            normalized by this workflow.
          required: false
          schema:
            type: boolean
            nullable: true
          example: false
        - name: page
          in: query
          description: 'Page. Validation: nullable, integer, min:1.'
          required: false
          schema:
            type: integer
            minimum: 1
            nullable: true
          example: 1
        - name: per_page
          in: query
          description: 'Per page. Validation: nullable, integer, min:10, max:100.'
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 10
            nullable: true
          example: 10
        - name: segment
          in: query
          description: 'Segment. Validation: nullable, string, max:64.'
          required: false
          schema:
            type: string
            maxLength: 64
            nullable: true
          example: Segment
        - name: status
          in: query
          description: 'Status. Validation: nullable, string, max:64.'
          required: false
          schema:
            type: string
            maxLength: 64
            nullable: true
          example: all
        - name: portfolio_view
          in: query
          description: >-
            Portfolio view. Validation: nullable; allowed values: managed,
            qualifying, all.
          required: false
          schema:
            type: string
            enum:
              - managed
              - qualifying
              - all
              - null
            nullable: true
          example: managed
        - name: plan_period
          in: query
          description: >-
            Plan period. Validation: nullable, string,
            regex:/^\d{4}-\d{2}-\d{2},\d{4}-\d{2}-\d{2}$/.
          required: false
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2},\d{4}-\d{2}-\d{2}$
            nullable: true
          example: 2026-01-01,2026-12-31
        - name: plan_currency
          in: query
          description: 'Plan currency. Validation: nullable, string, max:3.'
          required: false
          schema:
            type: string
            maxLength: 3
            nullable: true
          example: Plan Currency
        - name: tier
          in: query
          description: 'Tier. Validation: nullable; allowed values: all, A, B, C, unset.'
          required: false
          schema:
            type: string
            enum:
              - all
              - A
              - B
              - C
              - unset
              - null
            nullable: true
          example: all
        - name: plan_health
          in: query
          description: >-
            Plan health. Validation: nullable; allowed values: all, on_track,
            needs_attention, at_risk, draft, paused, complete, no_plan.
          required: false
          schema:
            type: string
            enum:
              - all
              - on_track
              - needs_attention
              - at_risk
              - draft
              - paused
              - complete
              - no_plan
              - null
            nullable: true
          example: all
        - name: next_move
          in: query
          description: >-
            Next move. Validation: nullable; allowed values: all, overdue, none,
            scheduled.
          required: false
          schema:
            type: string
            enum:
              - all
              - overdue
              - none
              - scheduled
              - null
            nullable: true
          example: all
        - name: sort_field
          in: query
          description: >-
            Sort field. Validation: nullable, string; allowed values:
            donor_name, lifetime_total, last_gift_date, days_since_contact,
            giving_trend, ytd_giving.
          required: false
          schema:
            type: string
            enum:
              - donor_name
              - lifetime_total
              - last_gift_date
              - days_since_contact
              - giving_trend
              - ytd_giving
              - null
            nullable: true
          example: donor_name
        - name: sort_direction
          in: query
          description: 'Sort direction. Validation: nullable; allowed values: asc, desc.'
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
              - null
            nullable: true
          example: asc
      responses:
        '200':
          description: Operation result.
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/FundraisingHubCaseload'
                type: object
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '403':
          description: >-
            The authenticated user lacks access to this workflow or its related
            records.
        '422':
          description: >-
            Request, policy, source relationship, lifecycle or selection
            validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestRejection'
        '503':
          description: The portfolio projection is initializing or temporarily unavailable.
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  error_code:
                    type: string
                    example: FUNDRAISING_PORTFOLIO_PROJECTION_INITIALIZING
                  message:
                    type: string
                  projection:
                    $ref: '#/components/schemas/FundraisingHubProjection'
                type: object
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    FundraisingHubCaseload:
      description: >-
        Page of ready portfolio facts. Planning summary/currencies appear only
        with the stewardship-plan feature. Search reports whether candidate
        matching was truncated.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FundraisingHubPortfolioRow'
        pagination:
          $ref: '#/components/schemas/FundraisingHubPagination'
        summary:
          properties:
            total:
              description: Count.
              type: integer
              example: 2
              nullable: false
            at_risk:
              description: Count.
              type: integer
              example: 2
              nullable: false
            lapsed:
              description: Count.
              type: integer
              example: 2
              nullable: false
            upgrade_potential:
              description: Count.
              type: integer
              example: 2
              nullable: false
            needs_contact:
              description: Count.
              type: integer
              example: 2
              nullable: false
            unassigned:
              description: Count.
              type: integer
              example: 2
              nullable: false
            lifetime_total:
              description: Amount or percentage.
              type: number
              example: 25
              nullable: false
            ytd_giving:
              description: Amount or percentage.
              type: number
              example: 25
              nullable: false
          type: object
          additionalProperties:
            description: Count.
            type: integer
            example: 2
            nullable: false
        projection:
          $ref: '#/components/schemas/FundraisingHubProjection'
        trend_context:
          properties:
            basis:
              description: Serialized value.
              type: string
              example: Example
              nullable: true
            mode:
              description: Serialized value.
              type: string
              example: Example
              nullable: true
            follows_selected_comparison:
              description: Workflow state.
              type: boolean
              example: true
            formula:
              description: Serialized value.
              type: string
              example: Example
              nullable: true
            current:
              properties:
                start:
                  description: Organization-local calendar date.
                  type: string
                  format: date
                  example: '2026-10-20'
                  nullable: true
                end:
                  description: Organization-local calendar date.
                  type: string
                  format: date
                  example: '2026-10-20'
                  nullable: true
                label:
                  description: Serialized value.
                  type: string
                  example: Example
                  nullable: false
              type: object
            comparison:
              properties:
                start:
                  description: Organization-local calendar date.
                  type: string
                  format: date
                  example: '2026-10-20'
                  nullable: true
                end:
                  description: Organization-local calendar date.
                  type: string
                  format: date
                  example: '2026-10-20'
                  nullable: true
                label:
                  description: Serialized value.
                  type: string
                  example: Example
                  nullable: false
              type: object
          type: object
        search:
          properties:
            candidate_count:
              description: Count.
              type: integer
              example: 2
              nullable: false
            estimated_hits:
              description: Count.
              type: integer
              example: 2
              nullable: false
            truncated:
              description: Workflow state.
              type: boolean
              example: true
            fallback:
              description: Serialized value.
              type: string
              example: Example
              nullable: true
          type: object
        planning_summary:
          properties:
            managed_count:
              description: Count.
              type: integer
              example: 2
              nullable: false
            qualifying_count:
              description: Count.
              type: integer
              example: 2
              nullable: false
            no_next_move_count:
              description: Count.
              type: integer
              example: 2
              nullable: false
            overdue_move_count:
              description: Count.
              type: integer
              example: 2
              nullable: false
            currencies:
              type: array
              items:
                properties:
                  currency:
                    description: Serialized value.
                    type: string
                    example: Example
                    nullable: true
                  goal_amount:
                    description: Amount or percentage.
                    type: number
                    example: 25
                    nullable: false
                  attributed_actual:
                    description: Amount or percentage.
                    type: number
                    example: 25
                    nullable: false
                  remaining_amount:
                    description: Amount or percentage.
                    type: number
                    example: 25
                    nullable: false
                  currency_mismatch_plan_count:
                    description: Count.
                    type: integer
                    example: 2
                    nullable: false
                type: object
          type: object
        plan_currencies:
          type: array
          items:
            type: string
            example: USD
      type: object
    UnauthorizedResponse:
      title: UnauthorizedResponse
      description: >-
        Returned with HTTP 401 when the request lacks a valid Passport bearer
        token, a valid `X-HYS-API-Key`, or a valid session. The body is the
        simple `{message, status}` envelope emitted by `AuthenticateApiOrKey`.
      required:
        - message
        - status
      properties:
        message:
          description: >-
            Always the literal string `Unauthorized` from the `auth.api_or_key`
            middleware. Login endpoints return `Invalid Credentials` instead.
          type: string
          example: Unauthorized
        status:
          type: string
          example: error
      type: object
    RequestRejection:
      description: >-
        Request or workflow rejection. Framework field-validation failures
        contain errors; semantic rejections may contain message without errors;
        legacy/provider failures may use error and error_code. The operation
        description identifies the rejected condition. Domain responses may add
        current revision, limits or other conflict context.
      anyOf:
        - $ref: '#/components/schemas/ValidationErrorResponse'
        - $ref: '#/components/schemas/ErrorResponse'
        - required:
            - error
          properties:
            error:
              description: Legacy or provider-facing error message.
              type: string
              example: The request could not be completed.
            error_code:
              description: Stable domain error code, when provided.
              type: string
              example: WORKFLOW_UNAVAILABLE
          type: object
    FundraisingHubProjection:
      properties:
        status:
          description: Serialized value.
          type: string
          example: Example
          nullable: false
        ready:
          description: Workflow state.
          type: boolean
          example: true
        projection_version:
          description: Count.
          type: integer
          example: 2
          nullable: false
        required_projection_version:
          description: Count.
          type: integer
          example: 2
          nullable: false
        started_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        completed_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        last_reconciled_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        calculated_for_date:
          description: Organization-local calendar date.
          type: string
          format: date
          example: '2026-10-20'
          nullable: true
        last_error:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
      type: object
    FundraisingHubPortfolioRow:
      description: >-
        Projected relationship portfolio row. Giving includes qualified
        relationship attribution; financial-ledger overview totals are a
        distinct basis.
      properties:
        portfolio_subject_type:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        portfolio_subject_id:
          description: Count.
          type: integer
          example: 2
          nullable: false
        relationship_group_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        donor_id:
          description: Count.
          type: integer
          example: 2
          nullable: false
        donor_name:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        email:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        phone:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        street:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        address_line2:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        city:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        state:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        zip:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        household_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        household_name:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        household_primary_contact_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        household_size:
          description: Count.
          type: integer
          example: 2
          nullable: false
        household_member_names:
          type: array
          items:
            type: string
            example: Example
        assigned_fundraiser_user_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        assigned_fundraiser_name:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        donor_assigned_fundraiser_user_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        household_assigned_fundraiser_user_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        assignment_scope:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        lifetime_total:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        direct_lifetime_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        soft_credit_lifetime_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        first_gift_date:
          description: Organization-local calendar date.
          type: string
          format: date
          example: '2026-10-20'
          nullable: true
        last_gift_date:
          description: Organization-local calendar date.
          type: string
          format: date
          example: '2026-10-20'
          nullable: true
        last_gift_amount:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: true
        last_gift_source:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        last_gift_source_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        last_gift_legal_donor_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        last_gift_legal_donor_name:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        last_gift_soft_credit_type_key:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        largest_gift:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        largest_gift_date:
          description: Organization-local calendar date.
          type: string
          format: date
          example: '2026-10-20'
          nullable: true
        average_gift:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        total_gifts:
          description: Count.
          type: integer
          example: 2
          nullable: false
        direct_total_gifts:
          description: Count.
          type: integer
          example: 2
          nullable: false
        soft_credit_total_gifts:
          description: Count.
          type: integer
          example: 2
          nullable: false
        current_period_gift_count:
          description: Count.
          type: integer
          example: 2
          nullable: true
        comparison_period_gift_count:
          description: Count.
          type: integer
          example: 2
          nullable: true
        ytd_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        direct_ytd_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        soft_credit_ytd_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        previous_ytd_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        last_year_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        year_before_giving:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        giving_trend:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: true
        trend_status:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        giving_basis:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        donor_segment:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        retention_status:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        is_deceased:
          description: Workflow state.
          type: boolean
          example: true
        last_interaction_date:
          description: Organization-local calendar date.
          type: string
          format: date
          example: '2026-10-20'
          nullable: true
        last_touch_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        last_meaningful_touch_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        next_scheduled_touch_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        days_since_contact:
          description: Count.
          type: integer
          example: 2
          nullable: true
        contact_status:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        recorded_interactions:
          description: Count.
          type: integer
          example: 2
          nullable: true
        total_interactions:
          description: Count.
          type: integer
          example: 2
          nullable: false
        contact_count:
          description: Count.
          type: integer
          example: 2
          nullable: false
        meaningful_interactions:
          description: Count.
          type: integer
          example: 2
          nullable: false
        meaningful_contact_count:
          description: Count.
          type: integer
          example: 2
          nullable: false
        engagement_rate:
          description: Amount or percentage.
          type: number
          example: 25
          nullable: false
        at_risk:
          description: Workflow state.
          type: boolean
          example: true
        lapsed:
          description: Workflow state.
          type: boolean
          example: true
        upgrade_potential:
          description: Workflow state.
          type: boolean
          example: true
        needs_contact:
          description: Workflow state.
          type: boolean
          example: true
        risk_reasons:
          type: array
          items:
            type: string
            example: Example
        open_work_items:
          description: Count.
          type: integer
          example: 2
          nullable: false
        comparison_year:
          description: Count.
          type: integer
          example: 2
          nullable: false
        relationship_manager_user_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        relationship_manager_name:
          description: Serialized value.
          type: string
          example: Example
          nullable: true
        donor_relationship_manager_user_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        household_relationship_manager_user_id:
          description: Count.
          type: integer
          example: 2
          nullable: true
        plan_summary:
          description: Included when stewardship planning is enabled.
          oneOf:
            - $ref: '#/components/schemas/StewardshipPlanSummary'
            - type: string
              enum:
                - null
              nullable: true
      type: object
    FundraisingHubPagination:
      properties:
        total:
          description: Count.
          type: integer
          example: 2
          nullable: false
        per_page:
          description: Count.
          type: integer
          example: 2
          nullable: false
        current_page:
          description: Count.
          type: integer
          example: 2
          nullable: false
        last_page:
          description: Count.
          type: integer
          example: 2
          nullable: false
      type: object
    ValidationErrorResponse:
      title: ValidationErrorResponse
      description: >-
        Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The
        `errors` map is keyed by the failing field name; each value is an array
        of human-readable error messages for that field. Most controllers also
        include a top-level `status: error`.
      required:
        - errors
      properties:
        errors:
          description: >-
            Map of field name to array of validator error messages. Example:
            `{email: [The email field is required.], amount: [The amount must be
            a number.]}`.
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        status:
          description: Always the literal string `error`.
          type: string
          example: error
        message:
          description: >-
            Optional summary message — present on some endpoints, absent on
            others.
          type: string
          example: The given data was invalid.
          nullable: true
      type: object
    ErrorResponse:
      title: ErrorResponse
      description: >-
        Generic error envelope used by most controllers. Most error responses
        pair a human-readable `message` with `status: error`. Some endpoints
        additionally include `errors` (validator errors), `error` (legacy
        single-error string), `code`, or domain-specific context fields.
      required:
        - message
      properties:
        message:
          description: Human-readable error message.
          type: string
          example: Something went wrong. Please try again.
        status:
          description: >-
            Always the literal string `error` for failures. Some endpoints omit
            this field.
          type: string
          example: error
        error:
          description: Legacy single error code/string used by older endpoints.
          type: string
          example: invalid_request
          nullable: true
        code:
          description: >-
            Optional application-level error code (not all endpoints populate
            this).
          type: string
          example: DONOR_NOT_FOUND
          nullable: true
      type: object
    StewardshipPlanSummary:
      description: >-
        Summary-safe plan header with relationship-attributed giving and
        operational rollup status.
      properties:
        id:
          description: Record identifier in this organization.
          type: integer
          example: 42
          nullable: false
        version:
          description: Optimistic concurrency version.
          type: integer
          example: 2
          nullable: false
        subject:
          properties:
            type:
              type: string
              enum:
                - donor
                - household
                - relationship_group
              example: donor
            id:
              description: Record identifier in this organization.
              type: integer
              example: 42
              nullable: false
          type: object
        stage:
          type: string
          enum:
            - qualifying
            - managed
          example: qualifying
        status:
          type: string
          enum:
            - draft
            - active
            - paused
            - completed
            - archived
          example: draft
        tier:
          type: string
          enum:
            - A
            - B
            - C
            - null
          example: A
          nullable: true
        stage_entered_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        action_donor_id:
          description: Record identifier in this organization.
          type: integer
          example: 42
          nullable: true
        period:
          properties:
            start:
              description: Calendar date.
              type: string
              format: date
              example: '2026-10-20'
              nullable: true
            end:
              description: Calendar date.
              type: string
              format: date
              example: '2026-10-20'
              nullable: true
          type: object
        currency:
          description: ISO currency of the plan.
          type: string
          maxLength: 3
          minLength: 3
          example: USD
        goal_amount:
          description: Monetary amount in the plan currency.
          type: number
          example: 1000
          nullable: true
        attributed_actual:
          description: Monetary amount in the plan currency.
          type: number
          example: 1000
          nullable: true
        direct_actual:
          description: Monetary amount in the plan currency.
          type: number
          example: 1000
          nullable: true
        soft_credit_actual:
          description: Monetary amount in the plan currency.
          type: number
          example: 1000
          nullable: true
        variance_amount:
          description: Monetary amount in the plan currency.
          type: number
          example: 1000
          nullable: true
        gift_count:
          description: Count.
          type: integer
          example: 2
          nullable: true
        giving_status:
          type: string
          enum:
            - pending
            - currency_mismatch
            - ready
            - stale
            - failed
          example: pending
        giving_last_successful_at:
          description: Timestamp.
          type: string
          format: date-time
          example: '2026-10-20T12:00:00Z'
          nullable: true
        currency_breakdown:
          type: array
          items:
            properties:
              currency:
                description: Stored workflow value.
                type: string
                example: Example
                nullable: false
              attributed_actual:
                description: Monetary amount in the plan currency.
                type: number
                example: 1000
                nullable: true
              direct_actual:
                description: Monetary amount in the plan currency.
                type: number
                example: 1000
                nullable: true
              soft_credit_actual:
                description: Monetary amount in the plan currency.
                type: number
                example: 1000
                nullable: true
              gift_count:
                description: Count.
                type: integer
                example: 2
                nullable: false
            type: object
        next_move:
          properties:
            id:
              description: Record identifier in this organization.
              type: integer
              example: 42
              nullable: false
            title:
              description: Stored workflow value.
              type: string
              example: Example
              nullable: true
            planned_at:
              description: Timestamp.
              type: string
              format: date-time
              example: '2026-10-20T12:00:00Z'
              nullable: true
          type: object
          nullable: true
        open_move_count:
          description: Count.
          type: integer
          example: 2
          nullable: false
        overdue_move_count:
          description: Count.
          type: integer
          example: 2
          nullable: false
        health:
          properties:
            status:
              description: Stored workflow value.
              type: string
              example: Example
              nullable: false
            reasons:
              type: array
              items:
                type: string
                example: overdue_move
          type: object
        metric_basis:
          type: string
          enum:
            - relationship_attribution
          example: relationship_attribution
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: Passport bearer token authentication for legacy admin sessions.
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      description: Gratona API key sent with the compatibility header X-HYS-API-Key.
      name: X-HYS-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.