> ## 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. # Read a donor tax-summary contribution projection > Returns one active organization donor statement in organization timezone and resolved jurisdiction period. Omitted year selects the most recent available year, not necessarily the current year. Includes settled positive deductible contributions; fully refunded/nonsettled/zero/non-deductible gifts are excluded, while ambiguous partial refunds/currency/status require review. QCD IRA-owner gifts are retained as non-deductible reconciliation rows. Optional other-owner soft-credit recognition remains separate and never increases deductible totals. Totals remain grouped by currency; no conversion, PDF, email or mutation is performed. Requires permission: one of donors_view, donors_manage, donor-all. ## OpenAPI ````yaml get /admin/tax-summaries/donors/{donor_id} 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/tax-summaries/donors/{donor_id}: get: tags: - Donations summary: Read a donor tax-summary contribution projection description: >- Returns one active organization donor statement in organization timezone and resolved jurisdiction period. Omitted year selects the most recent available year, not necessarily the current year. Includes settled positive deductible contributions; fully refunded/nonsettled/zero/non-deductible gifts are excluded, while ambiguous partial refunds/currency/status require review. QCD IRA-owner gifts are retained as non-deductible reconciliation rows. Optional other-owner soft-credit recognition remains separate and never increases deductible totals. Totals remain grouped by currency; no conversion, PDF, email or mutation is performed. Requires permission: one of donors_view, donors_manage, donor-all. operationId: givingTaxSummaryDonor parameters: - name: donor_id in: path description: Donor id in the current organization. required: true schema: type: integer example: 42 - name: year in: query description: >- Statement period year,1900 through the current year plus one. Omit to select latest available year. required: false schema: type: integer maximum: 2027 minimum: 1900 nullable: true example: 2026 - name: include_soft_credits in: query description: Include separate recognition on other-owner gifts; default false. required: false schema: type: boolean nullable: true example: false responses: '200': description: Operation result. content: application/json: schema: properties: success: type: boolean example: true data: $ref: '#/components/schemas/GivingTaxStatement' 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. '404': description: The donor or organization is unavailable. content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '422': description: Year/recognition input or organization timezone is invalid. content: application/json: schema: $ref: '#/components/schemas/RequestRejection' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: GivingTaxStatement: description: >- Organization-timezone statement projection. Totals stay separated by currency. No PDF, email or tax return is produced. properties: contract_version: type: string enum: - v1 example: v1 statement_status: type: string enum: - ready - review_required - empty example: ready includes_soft_credits: type: boolean example: true soft_credits: type: array items: $ref: '#/components/schemas/GivingTaxSoftCredit' soft_credit_currency_groups: type: array items: $ref: '#/components/schemas/GivingTaxSoftCreditCurrencyGroup' scope: properties: type: type: string enum: - donor - household example: donor id: type: integer example: 42 nullable: false donor_ids: type: array items: type: integer example: 42 nullable: false type: object tax_year: description: >- Requested statement period year, or most recent available period; null when none exists. type: integer example: 2026 nullable: true organization_timezone: type: string example: Africa/Kampala period: description: >- Inclusive lower and exclusive upper boundaries for the organization's local calendar/fiscal period. properties: from_utc: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: false until_utc: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: false type: object nullable: true jurisdiction: $ref: '#/components/schemas/GivingTaxJurisdiction' as_of: type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: false available_years: type: array items: type: integer example: 2026 contributions: type: array items: $ref: '#/components/schemas/GivingTaxContribution' excluded_contributions: type: array items: $ref: '#/components/schemas/GivingTaxExcludedContribution' currency_groups: type: array items: $ref: '#/components/schemas/GivingTaxCurrencyGroup' warnings: type: array items: properties: code: type: string example: review_required_partial_refund count: type: integer minimum: 0 example: 1 blocking: type: boolean example: true message: type: string example: One or more contributions need review. type: object exclusion_counts: description: >- Counts keyed by exclusion reason; serialized as an empty array when there are none. oneOf: - type: object additionalProperties: type: integer minimum: 0 example: 1 - type: array items: {} maxItems: 0 audit_summary: properties: candidate_count: type: integer minimum: 0 example: 1 included_count: type: integer minimum: 0 example: 1 excluded_count: type: integer minimum: 0 example: 1 review_required_count: type: integer minimum: 0 example: 1 counts_by_reason: description: >- Counts keyed by exclusion reason; serialized as an empty array when there are none. oneOf: - type: object additionalProperties: type: integer minimum: 0 example: 1 - type: array items: {} maxItems: 0 type: object fingerprint: description: >- SHA256 of statement scope, eligible/non-deductible/recognition evidence and configured jurisdiction identity; null for no selected year. type: string example: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff nullable: true 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 NotFoundResponse: title: NotFoundResponse description: >- Returned with HTTP 404 when a resource lookup misses (typically because the id doesn't exist OR is scoped to a different `client_id`). Note: many endpoints intentionally collapse 'not found' and 'forbidden' into a single 404 to avoid leaking which records exist in another tenant. required: - message properties: message: description: >- Human-readable message. Often a more specific string like `Donor not found` or `Trip not found`. type: string example: Not Found 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 GivingTaxSoftCredit: description: >- Recognition on another scope owner's qualified gift; proportional refunds reduce amount. Never included in deductible or reconciliation totals. properties: soft_credit_id: type: integer example: 42 nullable: false donation_id: type: integer example: 42 nullable: false donor_id: type: integer example: 42 nullable: false date: type: string format: date example: '2026-10-20' designation: type: string example: Education giver_name: type: string example: Jane Donor type: type: string example: Soft credit giving_source: type: string enum: - direct - daf - qcd example: direct giving_source_label: type: string example: Direct currency: type: string example: $ currency_code: type: string example: USD amount: description: >- Decimal amount rounded/formatted to two places; no currency conversion. type: string example: '25.00' amount_minor: type: integer example: 2500 type: object GivingTaxSoftCreditCurrencyGroup: properties: currency_code: type: string example: USD currency_symbol: type: string example: $ total_minor: type: integer example: 2500 total: description: >- Decimal amount rounded/formatted to two places; no currency conversion. type: string example: '25.00' count: type: integer minimum: 0 example: 1 type: object GivingTaxJurisdiction: properties: country_code: type: string example: US country_name: type: string example: United States supports_qcd: type: boolean example: true tax_period_basis: type: string enum: - calendar_year - fiscal_year example: calendar_year fiscal_year_start_month: type: integer maximum: 12 minimum: 1 example: 7 nullable: true period_label: type: string example: 1 January2026 –31 December2026 nullable: true is_configured: type: boolean example: true statement_title: type: string example: Tax Summary registration_label: type: string example: EIN registration_number: description: Empty unless organization profile enables printing its registration. type: string example: '' receipt_acknowledgement: description: Serialized text. type: string example: Example nullable: false page_preset: type: string enum: - us_letter_portrait - a4_portrait example: us_letter_portrait type: object nullable: true GivingTaxContribution: properties: id: type: integer example: 42 nullable: false donation_id: type: integer example: 42 nullable: false donor_id: type: integer example: 42 nullable: false ira_owner_donor_id: type: integer example: 42 nullable: true date: type: string format: date example: '2026-10-20' type: type: string enum: - Sponsorship - Donation - Recurring Donation example: Donation designation: type: string example: Education designation_name: type: string example: Education program_id: type: integer example: 42 nullable: true program_name: type: string example: Education program method: type: string example: Check method_id: type: integer example: 42 nullable: true currency: type: string example: $ currency_code: type: string example: USD amount: description: >- Decimal amount rounded/formatted to two places; no currency conversion. type: string example: '25.00' amount_minor: description: >- Amount multiplied by100 and rounded, including currencies with other conventional minor units. type: integer example: 2500 giving_source: type: string enum: - direct - daf - qcd example: direct giving_source_label: type: string example: Direct is_in_kind: type: boolean example: true is_tax_deductible: description: Always true for included contributions. type: boolean example: true in_kind_category: description: Serialized text. type: string example: Example nullable: true in_kind_category_label: description: Serialized text. type: string example: Example nullable: true notes: description: Serialized text. type: string example: Example nullable: true type: object GivingTaxExcludedContribution: description: >- Excluded from deductible totals; non-deductible QCD/direct contributions remain available for reconciliation and fingerprinting. properties: id: type: integer example: 42 nullable: false donation_id: type: integer example: 42 nullable: false donor_id: type: integer example: 42 nullable: false ira_owner_donor_id: type: integer example: 42 nullable: true date: type: string format: date example: '2026-10-20' type: type: string enum: - Sponsorship - Donation - Recurring Donation example: Donation designation: type: string example: Education designation_name: type: string example: Education program_id: type: integer example: 42 nullable: true program_name: type: string example: Education program method: type: string example: Check method_id: type: integer example: 42 nullable: true currency: type: string example: $ currency_code: type: string example: USD amount: description: >- Decimal amount rounded/formatted to two places; no currency conversion. type: string example: '25.00' amount_minor: description: >- Amount multiplied by100 and rounded, including currencies with other conventional minor units. type: integer example: 2500 giving_source: type: string enum: - direct - daf - qcd example: direct giving_source_label: type: string example: Direct reason: type: string example: excluded_non_deductible blocking: type: boolean example: true type: object GivingTaxCurrencyGroup: properties: currency_code: type: string example: USD currency_symbol: type: string example: $ cash_total: description: >- Decimal amount rounded/formatted to two places; no currency conversion. type: string example: '25.00' in_kind_total: description: >- Decimal amount rounded/formatted to two places; no currency conversion. type: string example: '25.00' tax_deductible_total: description: >- Decimal amount rounded/formatted to two places; no currency conversion. type: string example: '25.00' cash_total_minor: type: integer example: 2500 in_kind_total_minor: type: integer example: 2500 tax_deductible_total_minor: type: integer example: 2500 contribution_count: type: integer minimum: 0 example: 1 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 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.