> ## 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. # Preview adding selected donors to an event invite list > Resolves explicit rows or all donor-worksheet matches with current donor visibility. Default maximum is 5,000 donors; empty/inaccessible explicit selections fail. Returns up to five masked samples and a single-use actor/event-bound preview (default expiry 15 minutes). Optional reviewed plan requires saved current definition, event start, future dates and assignees able to see every selected donor. Performs no invitations, task creation or communication. Requires event setup management; archived event invitation history is read-only (409). ## OpenAPI ````yaml post /admin/events/{eventId}/invitees/selection/preview 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/events/{eventId}/invitees/selection/preview: post: tags: - Events summary: Preview adding selected donors to an event invite list description: >- Resolves explicit rows or all donor-worksheet matches with current donor visibility. Default maximum is 5,000 donors; empty/inaccessible explicit selections fail. Returns up to five masked samples and a single-use actor/event-bound preview (default expiry 15 minutes). Optional reviewed plan requires saved current definition, event start, future dates and assignees able to see every selected donor. Performs no invitations, task creation or communication. Requires event setup management; archived event invitation history is read-only (409). operationId: EventInvitationController_selectionPreview parameters: - name: eventId in: path description: Record ID in the authenticated organization. required: true schema: type: integer example: 42 example: 42 requestBody: required: true content: application/json: schema: required: - selection properties: selection: $ref: '#/components/schemas/EventApiInvitationSelectionInput' owner_user_id: description: Active staff owner for added/reactivated invitees. type: integer example: 42 nullable: true plan: required: - id - revision - definition_hash - steps properties: id: description: Saved event plan ID. type: integer example: 42 revision: description: Current plan revision. type: integer minimum: 1 example: 1 definition_hash: description: Current plan definition SHA-256. type: string maxLength: 64 minLength: 64 example: >- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa steps: type: array items: required: - step_key - enabled properties: step_key: description: Enabled persisted plan step key. type: string maxLength: 64 example: personal_call enabled: description: Choose this step; omitted choices are skipped. type: boolean example: true due_date: description: >- Required for each enabled step, today or later in the event timezone. type: string format: date example: '2026-11-01' nullable: true assignee_strategy: description: Task assignee strategy. type: string enum: - invitee_owner - specific_user - unassigned - null example: invitee_owner nullable: true assignee_user_id: description: >- Specific assignee; must access the event and applicable donor(s). type: integer example: 42 nullable: true type: object maxItems: 10 minItems: 1 type: object nullable: true type: object responses: '200': description: Preview adding selected donors to an event invite list completed. content: application/json: schema: properties: data: $ref: '#/components/schemas/EventApiInvitationSelectionPreview' type: object '401': description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Insufficient permission or feature access. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found in the organization or feature unavailable. content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '409': description: Version, idempotency, preview or archived-event conflict. content: application/json: schema: properties: message: description: Error explanation. type: string example: Version, idempotency, preview or archived-event conflict. error_code: description: Event domain code. type: string example: event_invitee_conflict details: properties: current_version: description: Current invitee version when provided. type: integer example: 42 current_lock_version: description: Current plan lock when provided. type: integer example: 42 current_revision: description: Current plan revision when provided. type: integer example: 42 current_definition_hash: description: Current definition hash when provided. type: string example: >- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa type: object additionalProperties: true type: object '422': description: Invalid request, owner, plan step/date or selection. content: application/json: schema: $ref: '#/components/schemas/RequestRejection' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: EventApiInvitationSelectionInput: required: - donor_ids - selection_mode properties: donor_ids: description: >- selected_rows uses an array of positive accessible donor IDs; all_total requires the literal all. oneOf: - type: array items: description: Selected donor ID. type: integer minimum: 1 example: 42 - description: All matching donors. type: string enum: - all example: all selection_mode: description: Explicit rows or all matching donor-worksheet results. type: string enum: - selected_rows - all_total example: selected_rows hysform_id: description: Donor form ID or all; defaults all. oneOf: - type: integer example: 42 - type: string example: all - type: string enum: - null nullable: true selected_count: description: UI selection count hint; actual donors are resolved server-side. type: integer minimum: 1 example: 10 nullable: true query: description: Donor worksheet search. type: string maxLength: 255 example: Jane nullable: true filterGroups: type: array items: description: >- Donor worksheet filter group; preserved and resolved by the donor listing filter contract. type: object additionalProperties: true maxItems: 50 nullable: true savedFilterId: description: Saved donor worksheet filter ID; nullable. example: 42 nullable: true fields: description: Requested donor worksheet field descriptors. type: array items: type: string maxItems: 100 nullable: true sortKey: description: Donor worksheet sort key. type: string maxLength: 100 example: display_name nullable: true sortOrder: description: Donor worksheet sort direction. type: string enum: - asc - desc - null example: asc nullable: true column_order: description: Donor worksheet column order. type: array items: type: string maxItems: 100 nullable: true keysArray: description: Donor worksheet selected keys. type: array items: type: string maxItems: 100 nullable: true filter: description: Legacy donor worksheet archived/deleted flag. example: 'false' nullable: true type: description: Legacy worksheet filter type. type: string maxLength: 50 example: donor nullable: true endpoint: description: Legacy worksheet endpoint hint. type: string maxLength: 50 example: donor nullable: true Donor_Group: description: Legacy donor group selection. example: all nullable: true selectedTab: description: Legacy donor worksheet tab. type: string maxLength: 100 example: all nullable: true type: object EventApiInvitationSelectionPreview: properties: preview_token: description: Actor/event-bound single-use preview token. type: string example: issued-preview-token preview_expires_at: description: Expiry; default 15 minutes. type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true event: properties: id: description: Event ID. type: integer example: 42 name: description: Event name. type: string example: Annual Gala type: object owner: properties: id: description: Staff user ID. type: integer example: 42 name: description: Staff display name. type: string example: Alex Smith type: object nullable: true selection_mode: description: Accepted selection mode. type: string enum: - selected_rows - all_total example: selected_rows counts: properties: selected: description: Selected. type: integer example: 42 new: description: New. type: integer example: 42 already_active: description: Already active. type: integer example: 42 reactivate: description: Reactivate. type: integer example: 42 skipped: description: Skipped. type: integer example: 42 staff_tasks: description: Staff tasks. type: integer example: 42 type: object samples: description: At most five masked donors. type: array items: properties: id: description: Accessible donor ID. type: integer example: 42 display_name: description: Resolved donor name. type: string example: Jane Doe email: description: Masked email; null if no valid address. type: string example: j***@example.org nullable: true type: object maxItems: 5 plan: properties: id: description: Accepted plan ID. type: integer example: 42 name: description: Plan name. type: string example: Personal invitation revision: description: Accepted plan revision. type: integer minimum: 1 example: 1 definition_hash: description: Definition SHA-256. type: string example: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa steps: type: array items: properties: step_key: description: >- Stable existing step key; unknown/duplicate keys are replaced with generated custom keys on save. type: string maxLength: 80 example: personal_call label: description: Nonblank step label. type: string maxLength: 120 example: Personal call task_title_template: description: >- Nonblank task title; only {donor_name} and {event_name} tokens are allowed. type: string maxLength: 255 example: Call {donor_name} about {event_name} invitation_method: description: Invitation contact method. type: string enum: - phone_call - text_message - email - handwritten_note - printed_mail - in_person - voicemail - other - null example: phone_call nullable: true days_before_event: description: >- Suggested date offset before the event start in event timezone. type: integer maximum: 365 minimum: 0 example: 28 due_date: description: Reviewed task due date. type: string format: date example: '2026-11-01' nullable: true assignee_strategy: description: Task assignee strategy. type: string enum: - invitee_owner - specific_user - unassigned example: invitee_owner resolved_assignee_user_id: description: Resolved staff user for one invitee. type: integer example: 42 nullable: true assignee_user_id: description: Bulk choice specific user. type: integer example: 42 nullable: true enabled: description: Bulk selected step. type: boolean example: false type: object enabled_step_count: description: Selected step count. type: integer example: 42 new_task_count: description: Staff tasks to create. type: integer example: 42 type: object nullable: true communications_sent: description: Always false. type: boolean example: false notice: description: Delivery notice. type: string example: No messages will be sent. 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 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 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 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.