> ## 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.

# Keep reviewed outgoing gift groups in Gratona

> Accepts 1 to 100 distinct safe_to_keep_local groups in one currency using current tokens/counts/totals. Rechecks full payment topology, source mappings and all related outgoing work before installing durable per-record keep-local controls and marking reviewed work skipped. Those controls prevent later edits from recreating outgoing work for this connection. Gift owners, payments and provider records are unchanged. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



## OpenAPI

````yaml post /integrations/hub/connections/{connection_id}/outbound-donation-owner-decisions/keep-local
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:
  /integrations/hub/connections/{connection_id}/outbound-donation-owner-decisions/keep-local:
    post:
      tags:
        - Integrations
      summary: Keep reviewed outgoing gift groups in Gratona
      description: >-
        Accepts 1 to 100 distinct safe_to_keep_local groups in one currency
        using current tokens/counts/totals. Rechecks full payment topology,
        source mappings and all related outgoing work before installing durable
        per-record keep-local controls and marking reviewed work skipped. Those
        controls prevent later edits from recreating outgoing work for this
        connection. Gift owners, payments and provider records are unchanged.
        Requires the integration platform global/configured client feature gate
        (normally integration_platform_foundation). Requires permission: one of
        access_account_settings.
      operationId: integrationHubKeepOutboundDonationOwnerDecisionsLocal
      parameters:
        - name: connection_id
          in: path
          description: Connection id in the current organization.
          required: true
          schema:
            type: integer
          example: 42
      requestBody:
        description: Validated request fields for this operation.
        required: true
        content:
          application/json:
            schema:
              required:
                - items
              properties:
                items:
                  description: 'Items. Validation: required, array, min:1, max:100.'
                  type: array
                  items:
                    required:
                      - current_owner_id
                      - expected_record_count
                      - expected_total_amount
                      - review_token
                    properties:
                      current_owner_id:
                        description: >-
                          Items item / current owner id. Validation: required,
                          integer, min:1.
                        type: integer
                        minimum: 1
                        example: 1
                      expected_record_count:
                        description: >-
                          Items item / expected record count. Validation:
                          required, integer, min:1.
                        type: integer
                        minimum: 1
                        example: 1
                      expected_total_amount:
                        description: >-
                          Items item / expected total amount. Validation:
                          required, numeric, min:0.
                        type: number
                        minimum: 0
                        example: 25
                      review_token:
                        description: >-
                          Items item / review token. Validation: required,
                          string, size:64.
                        type: string
                        maxLength: 64
                        minLength: 64
                        example: >-
                          aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                    type: object
                  maxItems: 100
                  minItems: 1
              type: object
      responses:
        '200':
          description: Operation result.
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/IntegrationHubOwnerKeepLocal'
                  message:
                    description: Operation receipt.
                    type: string
                    example: Example
                    nullable: false
                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: >-
            Feature, connection, run, donor or organization-owned record is
            unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: >-
            Request, changed review, payment/currency/identity dependency or
            unsafe work state validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestRejection'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    IntegrationHubOwnerKeepLocal:
      properties:
        run_id:
          description: Organization-owned record identifier.
          type: integer
          example: 42
          nullable: false
        resolution_count:
          description: Count.
          type: integer
          minimum: 0
          example: 2
        record_count:
          description: Count.
          type: integer
          minimum: 0
          example: 2
        donation_ids:
          type: array
          items:
            description: Organization-owned record identifier.
            type: integer
            example: 42
            nullable: false
        outbox_event_ids:
          type: array
          items:
            description: Organization-owned record identifier.
            type: integer
            example: 42
            nullable: false
        control_ids:
          type: array
          items:
            description: Organization-owned record identifier.
            type: integer
            example: 42
            nullable: false
        total_amount:
          description: Decimal amount formatted to two places.
          type: string
          example: '125.00'
        currency:
          description: Display value.
          type: string
          example: Example
          nullable: false
        side_effects:
          $ref: '#/components/schemas/IntegrationHubOwnerSideEffects'
        preview:
          $ref: '#/components/schemas/IntegrationHubOwnerPreview'
      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
    IntegrationHubOwnerSideEffects:
      description: >-
        refunds_held_for_review appears only when undoing a keep-local decision.
        Other counters reflect local gift owner changes and zero
        provider/payment/message writes.
      properties:
        gifts_changed:
          description: Count.
          type: integer
          minimum: 0
          example: 2
        donors_created:
          type: integer
          enum:
            - 0
        donations_created:
          type: integer
          enum:
            - 0
        payments_changed:
          type: integer
          enum:
            - 0
        messages_sent:
          type: integer
          enum:
            - 0
        provider_requests_sent:
          type: integer
          enum:
            - 0
        sync_cursors_changed:
          type: integer
          enum:
            - 0
        refunds_held_for_review:
          description: Count.
          type: integer
          minimum: 0
          example: 2
      type: object
    IntegrationHubOwnerPreview:
      description: >-
        Local review only, grouped by archived owner and payment currency. Fully
        includes persisted payment-group allocations; no provider writes or
        sends occur.
      properties:
        connection_id:
          description: Organization-owned record identifier.
          type: integer
          example: 42
          nullable: false
        decision_count:
          description: Count.
          type: integer
          minimum: 0
          example: 2
        safe_decision_count:
          description: Count.
          type: integer
          minimum: 0
          example: 2
        record_count:
          description: Count.
          type: integer
          minimum: 0
          example: 2
        total_amount:
          description: Decimal amount formatted to two places.
          type: string
          example: '125.00'
        currency:
          description: >-
            Currency of the first group, or USD if none. Totals are summed
            across all groups without currency conversion; use each decision
            currency when reviewing.
          type: string
          example: Example
          nullable: true
        decisions:
          type: array
          items:
            $ref: '#/components/schemas/IntegrationHubOwnerDecision'
        side_effects:
          $ref: '#/components/schemas/IntegrationHubOwnerSideEffects'
        recent_resolution:
          description: >-
            Most recent decision that passes the preview undo-availability
            checks; the undo endpoint rechecks all related records under lock.
          properties:
            run_id:
              description: Organization-owned record identifier.
              type: integer
              example: 42
              nullable: false
            decision:
              type: string
              enum:
                - keep_local
                - use_mapped_donor
            record_count:
              description: Count.
              type: integer
              minimum: 0
              example: 2
            total_amount:
              description: Decimal amount formatted to two places.
              type: string
              example: '125.00'
            currency:
              description: Display value.
              type: string
              example: Example
              nullable: false
            created_at:
              description: Timestamp.
              type: string
              format: date-time
              nullable: true
          type: object
          nullable: true
      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
    IntegrationHubOwnerDecision:
      description: >-
        Archived-donor payment allocation group waiting for a missing donor
        mapping. Selecting a mapped donor and keeping local have distinct safety
        criteria; use the corresponding boolean and blockers.
      properties:
        current_owner:
          $ref: '#/components/schemas/IntegrationHubOwnerDonor'
        record_count:
          description: Count.
          type: integer
          minimum: 0
          example: 2
        total_amount:
          description: Decimal amount formatted to two places.
          type: string
          example: '125.00'
        currency:
          description: Display value.
          type: string
          example: Example
          nullable: false
        currencies:
          type: array
          items:
            type: string
        date_from:
          description: Timestamp.
          type: string
          format: date-time
          nullable: true
        date_to:
          description: Timestamp.
          type: string
          format: date-time
          nullable: true
        donation_ids:
          type: array
          items:
            description: Organization-owned record identifier.
            type: integer
            example: 42
            nullable: false
        outbox_event_ids:
          type: array
          items:
            description: Organization-owned record identifier.
            type: integer
            example: 42
            nullable: false
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/IntegrationHubOwnerCandidate'
        safe_to_select:
          type: boolean
          example: true
        safe_to_keep_local:
          type: boolean
          example: true
        blockers:
          type: array
          items:
            type: string
        keep_local_blockers:
          type: array
          items:
            type: string
        review_token:
          description: >-
            Current group token binds owner, payment allocations, outgoing work,
            candidates, identity mappings and blockers.
          type: string
          maxLength: 64
          minLength: 64
          example: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      type: object
    IntegrationHubOwnerDonor:
      properties:
        id:
          description: Organization-owned record identifier.
          type: integer
          example: 42
          nullable: false
        name:
          description: Display value.
          type: string
          example: Example
          nullable: false
        email:
          description: Display value.
          type: string
          example: Example
          nullable: true
        username:
          description: Display value.
          type: string
          example: Example
          nullable: true
        archived_at:
          description: Timestamp.
          type: string
          format: date-time
          nullable: true
        profile:
          properties:
            display_name:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
            email:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
            username:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
            organization_name:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
          type: object
      type: object
    IntegrationHubOwnerCandidate:
      description: >-
        Active mapped donor candidate. Only the single candidate satisfying
        exact-email plus compatible-name and all safety guards can be
        safe_to_select.
      properties:
        id:
          description: Organization-owned record identifier.
          type: integer
          example: 42
          nullable: false
        name:
          description: Display value.
          type: string
          example: Example
          nullable: false
        email:
          description: Display value.
          type: string
          example: Example
          nullable: true
        username:
          description: Display value.
          type: string
          example: Example
          nullable: true
        provider_object_id:
          description: Display value.
          type: string
          example: Example
          nullable: false
        mapping_id:
          description: Organization-owned record identifier.
          type: integer
          example: 42
          nullable: false
        mapping_updated_at:
          description: Timestamp.
          type: string
          format: date-time
          nullable: true
        profile:
          properties:
            display_name:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
            email:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
            username:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
            organization_name:
              description: >-
                Normalized matching value; unavailable and placeholder email
                values are null.
              type: string
              example: Example
              nullable: true
          type: object
        match_signals:
          type: array
          items:
            type: string
            enum:
              - display_name
              - organization_name
              - email
              - username
              - compatible_display_name
        has_open_identity_conflict:
          type: boolean
          example: true
        safe_to_select:
          type: boolean
          example: 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.