# Agent Primitives
Source: https://api-docs.helpyousponsor.com/agent-primitives

Use Gratona MCP tools and primitive APIs from ChatGPT, Codex, and other agent clients.

Gratona exposes a read-only agent surface for authenticated admins. Agent
clients can search and summarize donor, recipient, sponsorship, donation,
dashboard, note, activity, saved-view, and report data that the connected admin
is already allowed to view in their Gratona workspace.

The same backend primitive registry powers REST, MCP, and the repo-local CLI.
Do not build integrations that pass a user-supplied `client_id`; Gratona derives the
workspace boundary from the authenticated admin or API key and applies primitive
scopes plus Gratona permission sets for every request.

## Current MCP Tool Surface

| Tool | What it does | Required access |
| - | - | - |
| `search` | Standard connector-style search across permitted donor and recipient records. | Search scope plus donor-form or program permission. |
| `hys_donors_lookup` | Finds a donor by name, email, or text and returns a bounded donor snapshot. | Donor search/get scopes plus donor-form permission. |
| `hys_records_get` | Fetches a returned `donor:{id}`, `entity:{id}`, or `donation:{id}` record. | Matching primitive scope plus record-level Gratona permission. |
| `hys_donors_list` | Lists permitted donors with filters, pagination, and optional includes. | Donor list scope plus donor-form permission. |
| `hys_donors_search` | Searches permitted donors. | Donor search scope plus donor-form permission. |
| `hys_donors_get` | Fetches one permitted donor with optional related records. | Donor get scope plus donor-form permission. |
| `hys_entities_list` | Lists permitted recipients/entities by program, visibility, and sponsorship state. | Entity list scope plus program permission. |
| `hys_entities_get` | Fetches one permitted recipient/entity. | Entity get scope plus program permission. |
| `hys_donations_list` | Lists permitted donation records. | Donation list scope plus donation/report visibility. |
| `hys_donations_get` | Fetches one permitted donation record. | Donation get scope plus donation/report visibility. |
| `hys_donations_summary` | Summarizes giving in a permitted date range. | Donation summary scope plus donation/report visibility. |
| `hys_sponsorships_summary` | Summarizes sponsorship health across permitted donors and programs. | Sponsorship scope plus donor and program visibility. |
| `hys_notes_list` | Lists full permitted notes for a donor or recipient. | Notes scope plus target record permission. |
| `hys_activity_logs_list` | Lists permitted activity history and metadata for a donor or recipient. | Activity-log scope plus target record permission. |
| `hys_filters_list` | Lists saved views and report filters available to the admin. | Filter scope plus module/form/program permission. |
| `hys_reports_list` | Lists saved report definitions, schedules, and recipient metadata available to the admin. | Report scope plus report/module/form/program permission. |
| `hys_dashboard_snapshot` | Returns high-level workspace metrics and signals. | Dashboard scope plus filtered aggregate visibility. |
| `hys_dashboard_brief` | Returns a concise board-prep or staff-summary brief. | Dashboard scope plus filtered aggregate visibility. |
| `hys_forms_list` | Lists forms the admin can use for donor or program workflows. | Forms scope plus form/program permission. |
| `hys_programs_list` | Lists programs visible to the admin. | Program scope plus program permission. |
| `hys_system_context` | Shows connected admin, workspace, scopes, and permission keys without secrets. | System context scope. |
| `hys_snapshot_widget_render` | Renders a compact ChatGPT snapshot from already fetched permitted data. | Render-only; it does not fetch broader data. |

Create, update, delete, and archive tools are hidden by default. Mutation tools
should only be enabled after explicit scopes, idempotency keys, audit metadata,
confirmation UX, and production tests are complete.

## ChatGPT And Codex

Use the production MCP endpoint for public ChatGPT and Codex connections:

```text theme={null}
https://api.helpyousponsor.com/mcp
```

Use staging or a short-lived HTTPS tunnel for private Developer Mode tests:

```text theme={null}
https://api-staging.helpyousponsor.com/mcp
```

ChatGPT should authenticate with OAuth 2.1 account linking in production.
Private developer-mode smoke tests may use a scoped Gratona API key or bearer token,
but production API keys must not be placed in query strings.

Useful admin prompts:

* "Find Mattie Charles and summarize her profile, giving, sponsorships, notes, and recent activity."
* "Summarize donations for the last 90 days and fetch one donation record."
* "Show sponsorship health for Education and one sponsored recipient."
* "List saved views and reports that would help me plan today's follow-up work."
* "Show notes and activity for donor 26303."
* "What can I access in this Gratona workspace?"

When a prompt does not include enough information for a record-specific lookup,
the assistant should ask a short follow-up question instead of guessing.

## MCP Endpoints

| Endpoint | Purpose |
| - | - |
| `GET /mcp/health` | Public health check for the MCP server. |
| `GET /mcp/manifest` | Server metadata, public endpoints, and authentication summary. |
| `POST /mcp` | Primary Streamable HTTP JSON-RPC endpoint. |
| `GET /mcp/sse` | SSE transport compatibility endpoint. |
| `POST /mcp/messages` | JSON-RPC compatibility endpoint. |
| `GET /.well-known/oauth-protected-resource` | OAuth protected-resource metadata for ChatGPT discovery. |
| `GET /.well-known/oauth-authorization-server` | OAuth authorization-server metadata. |

Every unauthenticated MCP request returns an OAuth bearer challenge with the
protected-resource metadata URL so compatible clients can discover the auth
configuration.

## Auth And Permissions

Gratona enforces access in layers:

1. Authentication resolves the admin, API key or OAuth token, scopes, and Gratona
   workspace.
2. The primitive registry filters discovery and invocation by primitive scope.
3. Each primitive applies Gratona group permission sets such as donor forms, program
   access, reports, notes, activity logs, and dashboard permissions.
4. Record queries always use the server-derived workspace boundary.

Admins can receive donor PII, custom fields, notes, activity, reports, and saved
views when their Gratona permissions allow them. The connector does not redact
permitted admin data at the app layer; it avoids exposing secrets, request
tokens, API keys, payment processor identifiers, trace IDs, and unrelated
internal diagnostics.

## REST Primitive API

Use REST when you need direct HTTP access from scripts or services.

* Base URL: `https://api.helpyousponsor.com`
* Auth header: `X-HYS-API-Key: hys_...`
* Discovery: `GET /v3/primitives`
* Primitive schema: `GET /v3/primitives/{name}/schema`
* Invoke: `POST /v3/primitives/{name}/invoke`
* Dry-run validation: `POST /v3/primitives/{name}/validate`

Example:

```bash theme={null}
curl --request POST \
  --url https://api.helpyousponsor.com/v3/primitives/donors.search/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-HYS-API-Key: hys_your_key_here' \
  --data '{
    "query": "smith",
    "limit": 10
  }'
```

## Schema Discovery

Agents can inspect the Gratona data model surface when granted `schema:read`.

* `GET /v3/schema/models`
* `GET /v3/schema/models/{name}`
* `GET /v3/schema/enums`
* `GET /v3/schema/capabilities`

The MCP server exposes model schemas through `resources/list` and
`resources/read`. Current resources include donor, entity, donation, commitment,
program, household, donor-entity relationship, soft credit, form, field, and
donor-field schemas.

## Scope Planning

Use the smallest key or OAuth grant that still lets the agent do the job.

| Use case | Recommended scopes |
| - | - |
| Donor lookup only | `primitives:donors:search`, `primitives:donors:get` |
| Donor and recipient read-only workflows | `primitives:donors:*`, `primitives:entities:*` |
| Giving summaries | `primitives:donations:list`, `primitives:donations:get`, `primitives:donations:summary` |
| Staff brief with notes and activity | `primitives:dashboard:*`, `primitives:notes:list`, `primitives:activity_logs:list` |
| Saved views and reports | `primitives:filters:list`, `primitives:reports:list` |
| Broad internal admin smoke testing | `primitives:*`, `schema:read` |

Tool discovery only returns operations the current credentials can use. A broad
primitive scope does not bypass Gratona group permissions.


# Get admin dashboard data
Source: https://api-docs.helpyousponsor.com/api-reference/admin-dashboard/get-admin-dashboard-data

get /dashboard
Returns aggregated dashboard statistics for the authenticated admin's client (organization): commitment and donation counts, per-program breakdowns, billing plan, last payment, and Stripe gateway health. Results are cached for one week. On a cache miss the endpoint dispatches a background reload job and returns a partial payload (data.org plus a 'reloaded' flag); subsequent calls return the fully populated dashboard once the job finishes.



# Add new setting
Source: https://api-docs.helpyousponsor.com/api-reference/admin/add-new-setting

post /admin/settings



# Admin details
Source: https://api-docs.helpyousponsor.com/api-reference/admin/admin-details

get /client/admins/{id}



# Bootstrap data for the new-settings form
Source: https://api-docs.helpyousponsor.com/api-reference/admin/bootstrap-data-for-the-new-settings-form

get /admin/add_settings
Returns the active payment-gateway snapshot for the caller's client (`Donation::checkUseCC`) so the new-settings form can decide whether to render the CC payment-method options. The `donation` field is a fresh, unsaved Donation instance kept for legacy template ergonomics. Requires permission: `manage_programs`.



# Change a role access level for a program
Source: https://api-docs.helpyousponsor.com/api-reference/admin/change-a-role-access-level-for-a-program

put /admin/access/resources/{resource_type}/{resource_id}/roles/{role_id}
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Use a level from the resource response allowed_levels and its role version as expected_version. Full-access roles and derived sponsorship access cannot be edited here. Program changes that couple several programs must use the central editor. Mutation and access safeguards are rechecked; response refreshes all roles for this resource.



# Change a role access level for an organization feature
Source: https://api-docs.helpyousponsor.com/api-reference/admin/change-a-role-access-level-for-an-organization-feature

put /admin/access/resources/{resource_type}/roles/{role_id}
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Use a level from the resource response allowed_levels and its role version as expected_version. Full-access roles and derived sponsorship access cannot be edited here. Program changes that couple several programs must use the central editor. Mutation and access safeguards are rechecked; response refreshes all roles for this resource.



# Confirm workspace setup choices
Source: https://api-docs.helpyousponsor.com/api-reference/admin/confirm-workspace-setup-choices

post /admin/workspace-setup
Requires workspace setup rollout. Confirms registered answers once and pins the selected recipes in durable bootstrap work. Repeating identical choices is safe; conflicting confirmations are rejected. A successful confirmation can precede background starter preparation; use activation/starter-preview to read progress.



# Create an empty access role
Source: https://api-docs.helpyousponsor.com/api-reference/admin/create-an-empty-access-role

post /admin/access/roles
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Creates a deny-by-default role at version 1. Permissions are not accepted by this operation; configure them through the role update after creation. Records an audit event.



# Create my customer feedback provider session
Source: https://api-docs.helpyousponsor.com/api-reference/admin/create-my-customer-feedback-provider-session

post /admin/customer-feedback/session
Creates Featurebase and/or Intercom identity tokens for the current user and organization, with no-store, private caching. Default token lifetime is 15 minutes, configurable from 5 to 60 minutes. Disabled providers return enabled false without token fields. Both providers disabled returns 404; incomplete enabled-provider setup returns 503; missing user/organization identity returns 403.



# Decommission the current organization account
Source: https://api-docs.helpyousponsor.com/api-reference/admin/decommission-the-current-organization-account

post /admin/account/decommission
Requires explicit access_delete_account permission unless the caller has the platform lifecycle capability. Immediately closes the workspace, disables administrator access, revokes credentials and cancels active subscriptions; durable archival is queued separately. Repeating a decommission returns the existing snapshot and already_decommissioned true. This route always targets the caller organization. Platform administrator membership safety can prevent closure with 409.



# Delete a setting
Source: https://api-docs.helpyousponsor.com/api-reference/admin/delete-a-setting

delete /admin/settings/{settings_id}



# Delete an empty access role
Source: https://api-docs.helpyousponsor.com/api-reference/admin/delete-an-empty-access-role

delete /admin/access/roles/{role_id}
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Requires the current role version. The role must contain no members and cannot be assigned to the actor. The actor ceiling still applies; records the deletion at the next version.



# Edit a setting
Source: https://api-docs.helpyousponsor.com/api-reference/admin/edit-a-setting

put /admin/settings/{settings_id}



# Edit an existing admin
Source: https://api-docs.helpyousponsor.com/api-reference/admin/edit-an-existing-admin

put /client/admins/{id}



# Get all settings
Source: https://api-docs.helpyousponsor.com/api-reference/admin/get-all-settings

get /admin/settings



# Get details for a setting
Source: https://api-docs.helpyousponsor.com/api-reference/admin/get-details-for-a-setting

get /admin/settings/{settings_id}



# Get details for campaign settings
Source: https://api-docs.helpyousponsor.com/api-reference/admin/get-details-for-campaign-settings

get /admin/campaign/settings/{settings_id}



# Invite a team member
Source: https://api-docs.helpyousponsor.com/api-reference/admin/invite-a-team-member

post /client/admin/{client_id}



# Issue a new API key for the current admin
Source: https://api-docs.helpyousponsor.com/api-reference/admin/issue-a-new-api-key-for-the-current-admin

post /admin/generate_api_key
Creates a new `ApiKey` row scoped to the calling admin and their client via `ApiKeyService::generate`, then returns the **plain-text key once** alongside the persisted metadata. Subsequent reads only see the `key_prefix`. The legacy `token` field is kept as an alias of `api_key` for older admin-UI clients. Requires permission: `developer_settings` (also satisfied by `group_all`); user `id=1` is unconditionally allowed.



# List organization access roles
Source: https://api-docs.helpyousponsor.com/api-reference/admin/list-organization-access-roles

get /admin/access/roles
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Returns member details and server-derived access/editor metadata for every role, ordered by name.



# List permission sets or admin groups
Source: https://api-docs.helpyousponsor.com/api-reference/admin/list-permission-sets-or-admin-groups

get /client/admin/{client_id}



# List the calling admin's API keys
Source: https://api-docs.helpyousponsor.com/api-reference/admin/list-the-calling-admins-api-keys

get /admin/api_keys
Returns the API keys belonging to the authenticated admin within the active client, ordered newest first. Plain-text key material is never returned — only the `key_prefix` is included so users can identify each key. Includes `revoked_at` and `last_used_at` for housekeeping. Requires permission: `developer_settings` (also satisfied by `group_all`); user `id=1` is unconditionally allowed.



# Manually deactivate an admin
Source: https://api-docs.helpyousponsor.com/api-reference/admin/manually-deactivate-an-admin

get /admin/account/{id}/deactivate



# Mark a legacy onboarding checklist step complete
Source: https://api-docs.helpyousponsor.com/api-reference/admin/mark-a-legacy-onboarding-checklist-step-complete

patch /admin/onboarding_checklist
Requires existing organization checklist metadata; read the checklist first to initialize it. Marks the submitted step key as 1 and records activity on its first completion. Common keys: org_profile program_forms payments_gateways test_donation tailor_programs sender_email auto_emails iframe_embed_code verify_donation_process admin_accounts set_permissions upload_donor_db import_program_info admin_training review_documentation. The validator requires a value but does not enforce an allowlist.



# Patch a campaign's default amount and/or frequency
Source: https://api-docs.helpyousponsor.com/api-reference/admin/patch-a-campaigns-default-amount-andor-frequency

patch /admin/settings/{settings_id}/defaults
Lightweight patch for campaign-style program settings — updates only `default_amount` and/or `default_frequency` inside the setting's `program_settings` JSON without touching the rest of the configuration. Restricted to settings whose `program_settings.program_type` is `campaign` or `peer_to_peer` (returns 422 otherwise). The supplied `default_amount` must match one of the values in the setting's existing `transaction_amount` list (returns 422 when not). `default_frequency` must be `one_time`, `recurring`, or empty/null. The caller must own a program that uses this setting (returns 403 otherwise). Flushes the affected programs' caches on save. Requires permission: `manage_programs`.



# Prepare an administrator for mailbox reactivation
Source: https://api-docs.helpyousponsor.com/api-reference/admin/prepare-an-administrator-for-mailbox-reactivation

get /admin/account/{id}/activate



# Preview private workspace starters
Source: https://api-docs.helpyousponsor.com/api-reference/admin/preview-private-workspace-starters

get /admin/workspace-activation/starter-preview
Returns verified private sample summaries selected by the confirmed setup. Preparing, needs_review and unavailable are normal 200 states with null cards and empty sponsorship_models. Ready state includes privacy labels and any selected campaign, sponsorship, trip and recipient-form previews. Unexpected service failures return 503.



# Queue dashboard statistics refresh
Source: https://api-docs.helpyousponsor.com/api-reference/admin/queue-dashboard-statistics-refresh

get /admin/reload_stats
Queues a dashboard statistics rebuild for the current organization and writes a short-lived reloading marker. The success response acknowledges queueing; calculations can still be running.



# Read access change audit history
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-access-change-audit-history

get /admin/access/history
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Returns the newest audit entries first, including before/after semantic snapshots and source/request correlation.



# Read access roles for a feature or program
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-access-roles-for-a-feature-or-program

get /admin/access/resources/{resource_type}
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Global types activity_logs, donors, donations and sponsorships use the shorter route with no resource ID. Type program requires the longer route with an organization-owned, non-synthetic program ID. sponsorships is derived from programs and has no contextual editing.



# Read access roles for a feature or program
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-access-roles-for-a-feature-or-program-1

get /admin/access/resources/{resource_type}/{resource_id}
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Global types activity_logs, donors, donations and sponsorships use the shorter route with no resource ID. Type program requires the longer route with an organization-owned, non-synthetic program ID. sponsorships is derived from programs and has no contextual editing.



# Read activity action and table facet counts
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-activity-action-and-table-facet-counts

get /admin/activityLogs/facets
Requires activity_logs_view, interactions_manage or donors_manage. Results enforce current program, participation-site/cohort, owner-only, restricted SMS-line and manual-interaction privacy access. Page mentions appear only on accessible donor/recipient timelines and may record exposure for normal user requests. Email Intelligence V2 removes legacy provider rows from the broad timeline. Email body text and preview pointers follow the current body policy, including mailbox, program and private-owner restrictions where applicable. Returns count maps keyed by action and table_name. General/donor facets ignore actions and table_names so the sidebar retains every choice within the remaining scopes; they apply the other privacy/exclusion/unmatched scopes. A nonblank query/search/q returns counts for current authorized metadata/body search matches. Recipient facets use the database row filters and ignore text search. Unknown recipient or search failure, including an over-broad query, returns an empty facets array with HTTP 200.



# Read an access role and allowed transitions
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-an-access-role-and-allowed-transitions

get /admin/access/roles/{role_id}
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. The editor schema describes current capabilities, restrictions, scopes and advisory transition choices; mutations recheck all decisions.



# Read my effective access manifest
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-my-effective-access-manifest

get /admin/access/manifest
Requires a signed-in team user. This read does not require the role-management rollout or the groups permission. Returns the current role authority and restrictions; a missing tenant role returns null role, empty access/authority and can_manage false. Use refresh_url after an access change.



# Read my workspace activation guide
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-my-workspace-activation-guide

get /admin/workspace-activation
Returns the confirmed setup projection for the current user, including available tasks, safe completion summaries and next action. No V2 profile returns 404. A disabled rollout or invalid track returns a successful unavailable projection; it does not fall back to the legacy checklist.



# Read organization or record activity
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-organization-or-record-activity

get /admin/activityLogs
Requires activity_logs_view, interactions_manage or donors_manage. Results enforce current program, participation-site/cohort, owner-only, restricted SMS-line and manual-interaction privacy access. Page mentions appear only on accessible donor/recipient timelines and may record exposure for normal user requests. Email Intelligence V2 removes legacy provider rows from the broad timeline. Email body text and preview pointers follow the current body policy, including mailbox, program and private-owner restrictions where applicable. Returns activity rows and pagination; per_page accepts 10, 15 or 20, otherwise defaults to 10. General/donor feeds without a search phrase use current database rows. Nonblank query/search/q searches metadata and authorized email bodies through the index, then rechecks current rows and disclosure before returning results. More than 20,000 indexed candidates returns 422 with empty activities and null pagination; narrow the phrase or date range. Recipient activity reads the database and ignores text search. Other search failures return an empty 200 response with message. additional_data remains a JSON-encoded string. fresh=true reads the newest ten committed donor entries directly with a fixed 90-day window; it ignores text search and requires the other documented filters to be absent.



# Read the canonical permissions editor schema
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-the-canonical-permissions-editor-schema

get /admin/permissions/schema
Returns the configured permission schema directly, including sections, presets and the server access registry. Dynamic items refer to choices supplied by the group editor; use the Access role detail for actor-specific allowed transitions. If configuration is unavailable returns version 1 with empty sections and presets.



# Read the legacy onboarding checklist
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-the-legacy-onboarding-checklist

get /admin/onboarding_checklist
Initializes missing checklist metadata and records completion evidence from configured payment gateways, sender email and multiple team accounts/roles. The checklist property is a JSON-encoded map of step keys to 0 or 1. completion_percentage uses all current map entries.



# Read the team access matrix
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-the-team-access-matrix

get /admin/access/overview
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Includes organization feature areas and each non-synthetic program, with contextual role levels and available edits.



# Read workspace plan entitlements and AI usage
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-workspace-plan-entitlements-and-ai-usage

get /admin/entitlements
Returns current feature availability, lock state, source and optional quota/trial data. Quota usage enrichment can be absent on failure; a complete resolution failure returns data null so clients can fail open. Degraded pricing resolution is marked in the payload.



# Read workspace setup choices
Source: https://api-docs.helpyousponsor.com/api-reference/admin/read-workspace-setup-choices

get /admin/workspace-setup
Requires workspace setup rollout. An existing confirmation returns confirmed true and its safe profile summary. Otherwise returns the primary goal question and, when primary_goal is provided, its dependent starting-point question. Choice values come from the active versioned setup definition.



# Record a manual activation step event
Source: https://api-docs.helpyousponsor.com/api-reference/admin/record-a-manual-activation-step-event

post /admin/workspace-activation/tasks/{taskKey}
Only tasks with the returned can_complete_manually, can_skip or can_reopen capability accept the corresponding event. Submit current projection/task identities and a stable idempotency key; replay requires the same command. Stale projection, task version or digest returns 409. Automatic or unavailable tasks cannot be completed manually. Returns the refreshed projection after recording the event.



# Remove an admin
Source: https://api-docs.helpyousponsor.com/api-reference/admin/remove-an-admin

delete /client/admins/{id}



# Retired legacy client archive endpoint
Source: https://api-docs.helpyousponsor.com/api-reference/admin/retired-legacy-client-archive-endpoint

post /admin/clients/archive
This compatibility endpoint no longer mutates organization lifecycle. Use the account decommission and restore endpoints instead.



# Retired legacy teammate enrollment endpoint
Source: https://api-docs.helpyousponsor.com/api-reference/admin/retired-legacy-teammate-enrollment-endpoint

post /admin_login
This numeric client/group enrollment endpoint is permanently retired. Use the current teammate invitation flow.



# Revoke an API key or a Passport access token
Source: https://api-docs.helpyousponsor.com/api-reference/admin/revoke-an-api-key-or-a-passport-access-token

post /admin/revoke_api_token
Dual-purpose endpoint. When `api_key_id` is supplied, marks the matching `ApiKey` as revoked via `ApiKeyService::revoke` (after the `developer_settings` permission check); the key must belong to the calling admin within the active client. When `token_id` is supplied instead, looks up the token on `request->user()->tokens` and calls `revoke()` on the Passport access token (no extra permission gate). Exactly one of `api_key_id` / `token_id` is required.



# Update an access role with version protection
Source: https://api-docs.helpyousponsor.com/api-reference/admin/update-an-access-role-with-version-protection

put /admin/access/roles/{role_id}
Requires a signed-in team user, the team_access_roles_v1 rollout and Manage Access roles (`groups`). API keys remain accepted by route middleware but cannot replace the user actor required by this controller. Omitted name/permissions retain their existing values; a null name becomes empty and is rejected. Permissions must satisfy registered prerequisites and the actor ceiling. Full-access inherited positives stay locked; self-lockout is refused. A no-op retains the version.



# View all admins
Source: https://api-docs.helpyousponsor.com/api-reference/admin/view-all-admins

get /admins



# Admin user login
Source: https://api-docs.helpyousponsor.com/api-reference/auth/admin-user-login

post /login
Authenticates an admin user (a staff member of a client organization) and returns a Passport access token plus billing, entitlement and access snapshots for the organization. This is the entry point for the admin web app. The login flow also refuses logins for incomplete registrations, archived/decommissioned clients, inactive staff memberships, or users without an access role. A temporary organization lifecycle lock returns a retryable 409 response.



# Check a retired teammate enrollment link
Source: https://api-docs.helpyousponsor.com/api-reference/auth/check-a-retired-teammate-enrollment-link

get /admin_signup/{client_id}/{group_id}
The numeric client/group enrollment endpoint is permanently retired. Request a current teammate invitation from the organization administrator.



# Check User Activation Status
Source: https://api-docs.helpyousponsor.com/api-reference/auth/check-user-activation-status

get /user/{id}/activation/status
Checks the activation status of a user based on the user ID.



# Complete an administrator account setup link
Source: https://api-docs.helpyousponsor.com/api-reference/auth/complete-an-administrator-account-setup-link

post /password/setup
Uses the users_setup password broker and its setup expiry window. Valid mailbox proof activates only an eligible pending membership before setting the password. Invalid/expired token, unknown mailbox or blocked membership returns400. For compatibility, success returns HTTP200 with status=error; use the HTTP result and message to interpret it.



# Get a legacy organization logout flag
Source: https://api-docs.helpyousponsor.com/api-reference/auth/get-a-legacy-organization-logout-flag

get /logout_status/{client_id}
Returns the legacy clients.logout value when the column and organization exist, otherwise null. This compatibility read does not revoke credentials or end a session.



# Get the currently authenticated admin user
Source: https://api-docs.helpyousponsor.com/api-reference/auth/get-the-currently-authenticated-admin-user

get /user
Returns the authenticated admin user along with current permissions, feature entitlements and the server-derived access manifest. Used by the admin web app on app boot / route guard checks. Requires authentication via Passport bearer token or API key. Returns 401 if unauthenticated and 403 when onboarding, workspace, membership or access-role eligibility blocks access.



# Redeem an administrator activation link
Source: https://api-docs.helpyousponsor.com/api-reference/auth/redeem-an-administrator-activation-link

post /user/email/verification
Consumes a one-time, purpose-bound invitation credential. Successful redemption proves mailbox ownership, activates the member, and returns the same authenticated administrator session payload used by passwordless sign-in.



# Redeem an administrator email sign-in link
Source: https://api-docs.helpyousponsor.com/api-reference/auth/redeem-an-administrator-email-sign-in-link

get /admin/passwordless_verify/{token}
Consumes the one-time passwordless challenge shared by the email link and verification-code transports. Exactly one redemption can create a session. A valid mailbox proof must still pass current organization, membership and access-role eligibility. Successful redemption issues a bearer token and returns the authenticated user, access manifest, entitlements and billing context. A lifecycle lock conflict returns409 with Retry-After30seconds.



# Request an admin passwordless sign-in
Source: https://api-docs.helpyousponsor.com/api-reference/auth/request-an-admin-passwordless-sign-in

post /admin/passwordless_login
For an operational admin account, issues a six-digit numeric code and magic link. The newest challenge for the admin account and normalized email invalidates the previous code and expires after 15 minutes. Unknown and non-operational accounts receive the same generic response without issuing a challenge.



# Resend a team invitation or mailbox verification email
Source: https://api-docs.helpyousponsor.com/api-reference/auth/resend-a-team-invitation-or-mailbox-verification-email

post /user/{id}/send_verification_email
For a pending team member, revokes the previous invitation and sends a new one-time passwordless workspace invitation. For an active legacy member still awaiting mailbox verification, sends the compatibility verification email.



# Reset a password using a reset token
Source: https://api-docs.helpyousponsor.com/api-reference/auth/reset-a-password-using-a-reset-token

post /password/reset
Public endpoint that completes the password-reset flow started by `POST /password/forgot`. Consumes the signed token emailed to the user and updates the password hash. Legacy alias: `POST /reset-password`. Note: the `Password::PASSWORD_RESET` success branch returns HTTP 200 with `status=error` due to a long-standing bug in the controller — preserved here for backwards compatibility; integrators should treat HTTP 200 as success regardless of the `status` field.



# Send a password reset link
Source: https://api-docs.helpyousponsor.com/api-reference/auth/send-a-password-reset-link

post /password/forgot
Public endpoint that triggers Laravel's password broker to email a reset link to the supplied address. Used by the admin login page when an admin user clicks 'Forgot password?'. Always returns 200 with a generic success message when the email is well-formed (regardless of whether the address exists in the database) so that callers cannot enumerate registered users; only validator errors return non-200. Legacy alias: `POST /password/remind`.



# Send an administrator activation email
Source: https://api-docs.helpyousponsor.com/api-reference/auth/send-an-administrator-activation-email

post /email/verification-notification
Checks the supplied mailbox password and administrator eligibility, then sends a purpose-only activation credential. Resending revokes older activation credentials. This request does not create a web session. An already verified email returns400; invalid credentials or an ineligible membership return401.



# User Logout
Source: https://api-docs.helpyousponsor.com/api-reference/auth/user-logout

get /logout
Returns a logout confirmation. When the request has an authenticated user with a Passport access token, that token is revoked; requests without a resolved user also receive a successful confirmation.



# Verify an admin passwordless code
Source: https://api-docs.helpyousponsor.com/api-reference/auth/verify-an-admin-passwordless-code

post /admin/passwordless_verify_code
Accepts the latest six-digit numeric code. Five failed well-formed attempts burn the active challenge across source IPs; success also invalidates its magic link and challenge state.



# Verify my administrator email
Source: https://api-docs.helpyousponsor.com/api-reference/auth/verify-my-administrator-email

post /email/verify
Requires an authenticated administrator activation/bearer credential or accepted API key. The supplied id must equal the authenticated user. Already verified returns200 with status=error; newly verified returns200 with status=success. Requires permission: one of admins, manage_programs, donors_manage, manage_settings, access_account_settings, access_payment_gateways, imports_manage.



# Get an automation primitive schema
Source: https://api-docs.helpyousponsor.com/api-reference/automation/get-an-automation-primitive-schema

get /primitives/{name}/schema
Returns the selected operation input/output JSON Schemas, required scope, permission groups, feature flags and mutation decision metadata. The caller needs the primitive required_scope (or primitives:*) and the current Gratona permission groups. This endpoint only discovers the contract and does not execute it.



# Invoke an automation primitive
Source: https://api-docs.helpyousponsor.com/api-reference/automation/invoke-an-automation-primitive

post /primitives/{name}/invoke
Executes the named operation in the authenticated organization after checking its scope, feature availability and input-dependent Gratona permissions. Obtain the operation-specific body and output schema from the schema endpoint first. Mutation side effects and replay/idempotency behavior are defined by that primitive; Idempotency-Key is made available to implementations that support it.



# List available automation primitives
Source: https://api-docs.helpyousponsor.com/api-reference/automation/list-available-automation-primitives

get /primitives
Lists registered operations filtered by credential scopes, current Gratona permissions and feature availability. Each summary links to a complete input/output schema and invocation endpoint. Discovery is read-only and is not authorization to execute a mutation.



# Validate an automation primitive input
Source: https://api-docs.helpyousponsor.com/api-reference/automation/validate-an-automation-primitive-input

post /primitives/{name}/validate
Checks the selected primitive input through its validation implementation after scope and input-dependent permission checks. The body follows the same discovered input schema as invocation; the operation itself is not invoked. A valid result normally contains data.valid=true and meta.dry_run=true, while validation failures identify the offending fields.



# Client payment
Source: https://api-docs.helpyousponsor.com/api-reference/client/client-payment

post /client/pay



# Edit client account
Source: https://api-docs.helpyousponsor.com/api-reference/client/edit-client-account

put /client



# Edit client integration
Source: https://api-docs.helpyousponsor.com/api-reference/client/edit-client-integration

post /integrations/{name}



# Get client card details
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-client-card-details

get /client/credit-card



# Get client payment status
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-client-payment-status

get /client/{id}/payment-status



# Get client payments
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-client-payments

get /client/payments



# Get client subscriptions by module
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-client-subscriptions-by-module

get /client/subscriptions



# Get details of an integration
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-details-of-an-integration

get /integrations/{name}



# Get payment intent
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-payment-intent

get /client/payment-intent



# Get price for client to pay
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-price-for-client-to-pay

get /client/{id}/price



# Get the public organization theme
Source: https://api-docs.helpyousponsor.com/api-reference/client/get-the-public-organization-theme

get /color_theme
Resolves a public numeric organization ID or unique organization slug. Optionally applies a current-organization program’s color override; unknown/archived/foreign programs fall back to the organization theme. Returns normalized colors, display identity and accessible color tokens. The enabled flag reports branding rollout availability.



# List organization donor or recipient tags
Source: https://api-docs.helpyousponsor.com/api-reference/client/list-organization-donor-or-recipient-tags

get /client_tags
Returns active organization-owned tags ordered by name. Optional tag_type is trimmed and case-normalized to donor or entity; omission/empty string lists both types. Requires permission: one of access_account_settings.



# Migrate from Stripe Connect to Stripe API keys
Source: https://api-docs.helpyousponsor.com/api-reference/client/migrate-from-stripe-connect-to-stripe-api-keys

post /admin/client/{client_id}/migrate-stripe-connect
Removes Stripe Connect configuration and sets up Stripe API keys for a client



# Read retired organization-switching response
Source: https://api-docs.helpyousponsor.com/api-reference/client/read-retired-organization-switching-response

post /admin/switch_client
Direct organization switching has been retired. Every request returns410 with SUPPORT_SESSION_REQUIRED; authorized cross-organization support must use the approved Support Session workflow. Requires permission: one of email_manager, manage_email.



# Save organization custom pricing configuration
Source: https://api-docs.helpyousponsor.com/api-reference/client/save-organization-custom-pricing-configuration

post /client/client-custom/{client_id}
Requires the path organization to match the authenticated user; an optional body client_id must also match. Saves custom pricing configuration and increments its version under a lifecycle lock. It does not collect or record a payment. Decommissioned organizations are rejected; a temporarily unavailable lock returns409, retryable:true and Retry-After30. Requires permission: one of access_payment_gateways.



# Update client credit card
Source: https://api-docs.helpyousponsor.com/api-reference/client/update-client-credit-card

post /client/credit-card



# Update the organization default accent
Source: https://api-docs.helpyousponsor.com/api-reference/client/update-the-organization-default-accent

put /admin/color_theme
Requires an authenticated user with permission to manage the organization default color. At least color or color_level must be present; unspecified values retain the current normalized theme. Accepts configured palette/shade pairs or six-digit hex with level600. A program_id is rejected; program overrides use program launch settings. Requires permission: one of manage_settings.



# View Integrations
Source: https://api-docs.helpyousponsor.com/api-reference/client/view-integrations

get /integrations



# Activate verified email sending
Source: https://api-docs.helpyousponsor.com/api-reference/communications/activate-verified-email-sending

post /admin/email/settings/sending-domains/{domainId}/activate
Requires provisioning ready, verified DNS, and a successful test at or after verified_at. The saved From address must match the base or sending domain. Activates managed sending for new donor emails and retains the prior transport as fallback; email sets on other domains are listed in other_domain_senders. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# Add a new email set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/add-a-new-email-set

post /admin/auto_emails/emailset



# Apply a mailbox one-click unsubscribe
Source: https://api-docs.helpyousponsor.com/api-reference/communications/apply-a-mailbox-one-click-unsubscribe

post /unsubscribe/one-click
Mailbox providers submit the List-Unsubscribe form value and a category-scoped signed token in the query. Opts the address out of that source category. Legacy whole-email links are rejected. Requires no bearer token or cookies. Responses use Cache-Control: no-store.



# Approve a draft message
Source: https://api-docs.helpyousponsor.com/api-reference/communications/approve-a-draft-message

post /admin/message/approve/draft/{email_id}
Approves a draft in the caller's organization. Donor-originated drafts are marked sent into the recipient mailbox without sending email or reading body IDs. Other drafts use entity_id and donor_id to deliver to one donor or all current sponsors. Requires email_manager or manage_email; the disable_message_send_without_approval restriction is enforced.



# Approve a pending recipient message
Source: https://api-docs.helpyousponsor.com/api-reference/communications/approve-a-pending-recipient-message

post /admin/recipient-messages/{id}/approve
Only pending_approval messages can be approved. Records approval, creates the local Conversations mirror and attempts email queue publication in a transaction. Local source status becomes sent after preparation; provider delivery is asynchronous and recipient preferences may suppress mail. Missing recipient/donor/thread or queue failures revert the source to pending_approval and return422. Versioned access: requires permission: one of email_manager, manage_email.



# Approve and send a draft newsletter
Source: https://api-docs.helpyousponsor.com/api-reference/communications/approve-and-send-a-draft-newsletter

post /admin/newsLetters/{id}/approve
Atomically claims a draft, stamps the current actor, clears any scheduling and queues the saved current eligible audience. Any non-draft state returns400; concurrent claim returns409. Suppressed/empty audiences become skipped; large-audience eligibility is deferred. The receipt does not confirm final delivery. Requires permission: one of newsletter.



# Approve and send a draft response
Source: https://api-docs.helpyousponsor.com/api-reference/communications/approve-and-send-a-draft-response

put /admin/message/draft/response/{email_id}/approve
Marks a saved draft response as sent and queues the response email to the donor attached to the parent thread. Admin users call this from the message detail view after composing a draft response. Requires the admin API auth middleware and user permission checks.



# Approve and send multiple draft messages
Source: https://api-docs.helpyousponsor.com/api-reference/communications/approve-and-send-multiple-draft-messages

post /admin/message/drafts/approve
Approves multiple donor-message draft records and sends each draft to its resolved donor recipients. Admin users call this from the email manager bulk actions; each draft is scoped by the authenticated client and activity logging is attempted for sent messages. Requires the admin API auth middleware and user permission checks.



# Archive a custom mailing template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/archive-a-custom-mailing-template

delete /admin/mailing_templates/{id}
Soft-deletes the tenant-owned custom template. System templates cannot be archived; existing generated records remain separate. Requires permission: one of mailings_manage, manage_email.



# Archive a profile-note category
Source: https://api-docs.helpyousponsor.com/api-reference/communications/archive-a-profile-note-category

delete /admin/notes/categories/{category_id}
Requires notes_manage and donor-context/recipient-program access. Soft-deletes the category; existing notes retain category_id but resolve the category as null and display Uncategorized. Does not delete note bodies. Requires permission: one of notes_manage.



# Assign an email to an admin
Source: https://api-docs.helpyousponsor.com/api-reference/communications/assign-an-email-to-an-admin

put /admin/email/assign_admin



# Assign an SMS conversation
Source: https://api-docs.helpyousponsor.com/api-reference/communications/assign-an-sms-conversation

post /admin/sms_inbox/conversations/{conversation_id}/assign
Sets an organization team member or clears assignment when assigned_user_id is omitted/null/zero. With Team and access enforcement enabled, the assignee must be active and have sms_inbox_reply or sms_inbox_manage. Does not change the line owner or its visibility. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_manage; plus one of beta_features.



# Assign multiple emails to an admin
Source: https://api-docs.helpyousponsor.com/api-reference/communications/assign-multiple-emails-to-an-admin

put /admin/emails/assign_admin



# Cancel a scheduled newsletter
Source: https://api-docs.helpyousponsor.com/api-reference/communications/cancel-a-scheduled-newsletter

post /admin/newsLetters/{id}/cancel
Atomically converts a future scheduled newsletter to draft and clears timezone, schedule source, recommendation and claim metadata. Already-due schedules and all other states conflict. No recipient email is sent by this operation. Requires permission: one of newsletter.



# Change an SMS conversation inbox status
Source: https://api-docs.helpyousponsor.com/api-reference/communications/change-an-sms-conversation-inbox-status

post /admin/sms_inbox/conversations/{conversation_id}/status
Moves the conversation to open, closed, spam or archived and records activity when changed. This inbox state does not change SMS consent, messaging_status or provider delivery state. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_manage; plus one of beta_features.



# Check a mailing generation audience
Source: https://api-docs.helpyousponsor.com/api-reference/communications/check-a-mailing-generation-audience

post /admin/mailing_templates/{id}/preflight
Resolves the source-specific audience and classifies every record ready/warning/skipped without creating a run. Custom print mail skips postal opt-outs and master communication pauses; tax summaries also require a ready contribution statement. Label data decides address warnings/skips. Returns all counts plus one preflight page (default 20/max 100). Custom templates support only delivery_mode=none; email modes are reserved for system Tax Summary mailings. Requires permission: one of mailings_manage, manage_email.



# Check sending domain DNS verification
Source: https://api-docs.helpyousponsor.com/api-reference/communications/check-sending-domain-dns-verification

post /admin/email/settings/sending-domains/{domainId}/check
Requires provisioning ready. Refreshes provider DNS status; verified requires an active provider domain and a nonempty set of valid sending records. If an active domain loses verification, clears managed delivery and marks degraded, restoring the saved delivery path. Checking does not activate a newly verified domain. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# Clone an auto-email set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/clone-an-auto-email-set

post /admin/auto_emails/emailset/{emailset_id}/clone
Copies the tenant set and all active tenant templates transactionally; copied templates retain their content, triggers, disabled state and other settings. Optional name is trimmed and truncated to255, otherwise Copy of source name. Journey-library sets are unavailable when the organization hides them from legacy auto pages. Returns the new set under both emailset and data and records one clone activity. Does not send email or assign the new set to programs. Requires permission: one of manage_email.



# Clone newsletter content or audience
Source: https://api-docs.helpyousponsor.com/api-reference/communications/clone-newsletter-content-or-audience

post /admin/newsLetters/{id}/clone
Creates a new draft from any existing tenant newsletter. clone_scope=everything copies template and saved audience, template copies content/design/attachment/sender only, audience copies the saved recipient snapshot/rule only. Clears all schedule/claim metadata. Title defaults to Copy of source title and trims to255. Current story evidence is checked when copied HTML contains story markers; no email is sent. Requires permission: one of newsletter.



# Count organization donor records
Source: https://api-docs.helpyousponsor.com/api-reference/communications/count-organization-donor-records

get /admin/donors/count
Counts active tenant donor records including records without an email or with communication opt-outs. This is not the eligible newsletter recipient count. Requires permission: one of donors_view, donors_manage, donor-all.



# Create a custom automated SMS template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-custom-automated-sms-template

post /admin/auto_sms/template
Requires configured Sendblue and a tenant-owned set. Supports notify_donor_photo, notify_donor_future_sponsorship or a Journeys-library trigger. Rejects an existing trigger in the set. Creates an empty disabled default variant. name is used in the receipt message rather than persisted as a template attribute. Requires permission: one of manage_sms.



# Create a custom mailing template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-custom-mailing-template

post /admin/mailing_templates
Creates a custom donor/sponsorship template with at least one letter/label document. Household scope, tax_summary preset/renderer are reserved. Document kinds are upsert keys; repeated kinds retain the last supplied document. CanvaClone requires a letter, supported letter/postcard/card page preset, nonblank HTML and settings_json.editor_ui=canvaclone. Program bindings and current Impact Story evidence are stored transactionally. Requires permission: one of mailings_manage, manage_email.



# Create a donation-type email template variant
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-donation-type-email-template-variant

post /admin/auto_emails/template/variant
Creates or returns a donation-type-specific automated email template. Ordinary variants clone the default; DAF grant, IRA / QCD and explicitly contextual DAF advisor acknowledgments start with source-specific content and remain turned off until reviewed. DAF advisor and Direct soft-credit uses share the soft_credit template. Requires the admin API auth middleware and user permission checks.



# Create a draft message
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-draft-message

post /admin/message/draft/{entity_id}/{from}/{file_id}



# Create a draft, send, or schedule a newsletter
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-draft-send-or-schedule-a-newsletter

post /admin/send/newsLetter
Creates a newsletter from content and a server-resolved audience or legacy email list. Requires nonempty selected email addresses even for a draft. status=sent becomes sending and queues durable recipient deliveries; suppression, marketing preferences, deduplication and current donor addresses are checked. Audiences over500 defer eligibility and report nullable counts. Scheduling resolves exact time at least five minutes ahead, matches any legacy fields, verifies current recommendations and permits at most10 scheduled newsletters. Draft save returns200; scheduled creation returns201. A queue receipt does not promise inbox delivery. Requires permission: one of newsletter.



# Create a new email template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-new-email-template

post /admin/auto_emails/template



# Create a new note
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-new-note

post /admin/notes/{type}/{program_id}



# Create a new note
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-new-note-1

post /notes
Creates a donor or recipient note and resolves its category within the organization. Requires notes_manage and access to the linked donor form or program.



# Create a profile-note category
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-a-profile-note-category

post /admin/notes/categories/{type}/{program_id}
Supports donor-wide categories using the literal donor bucket or recipient categories for one accessible tenant program. Requires notes_manage and appropriate context access. Trims the name and rejects case-insensitive duplicates in that active bucket. Requires permission: one of notes_manage.



# Create an automated SMS receipt variant
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-an-automated-sms-receipt-variant

post /admin/auto_sms/template/variant
Creates an enabled in_kind or soft_credit variant, copying message and administrator numbers from the default when available. An existing matching variant is returned with 200; a newly created one returns 201. The controller accepts the supplied trigger/set without requiring an existing default. Requires permission: one of manage_sms.



# Create an automated SMS set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/create-an-automated-sms-set

post /admin/auto_sms/smsset
Requires enabled, configured Sendblue credentials. Creates the named set with the supplied E.164 sender number or the integration default, and provisions disabled starter templates. Returns 200 with the created raw set. Requires permission: one of manage_sms.



# Deactivate verified email sending
Source: https://api-docs.helpyousponsor.com/api-reference/communications/deactivate-verified-email-sending

post /admin/email/settings/sending-domains/{domainId}/deactivate
Clears managed sending for an active domain and returns it to verified state, restoring the saved delivery path. Repeated deactivation of an inactive setup returns its current state. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# Delete a custom automated SMS template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/delete-a-custom-automated-sms-template

delete /admin/auto_sms/template/{id}
Soft-deletes only custom notification/Journeys triggers. Built-in transactional templates cannot be deleted by this operation. Requires permission: one of manage_sms.



# Delete a draft newsletter
Source: https://api-docs.helpyousponsor.com/api-reference/communications/delete-a-draft-newsletter

delete /admin/newsLetters/{id}
Permanently removes the tenant draft and records its deletion activity. Any non-draft state conflicts; this does not cancel sending or a future schedule. Requires permission: one of newsletter.



# Delete a note
Source: https://api-docs.helpyousponsor.com/api-reference/communications/delete-a-note

delete /admin/notes/{note_id}
Soft-deletes a staff note by ID (sets `deleted_at`; the record is retained and recoverable). The note must belong to the authenticated user's client. Admin users call this from the notes panel when removing donor or recipient notes. Requires the admin API auth middleware and user permission checks.



# Delete a note
Source: https://api-docs.helpyousponsor.com/api-reference/communications/delete-a-note-1

delete /notes/{id}
Soft-deletes a note while retaining the recoverable record, including notes on archived profiles. Requires notes_manage and profile access. Supplying expected_updated_at prevents deleting a changed note.



# Delete a template image
Source: https://api-docs.helpyousponsor.com/api-reference/communications/delete-a-template-image

get /admin/remove_template_pic/{id}
Deletes a template image object from S3 and permanently removes the corresponding upload record. Admin users call this from the template asset picker. Requires the admin API auth middleware and user permission checks.



# Delete draft donor messages
Source: https://api-docs.helpyousponsor.com/api-reference/communications/delete-draft-donor-messages

delete /admin/messages/drafts/delete
Permanently deletes selected draft donor messages for the authenticated client and writes an activity log entry for each removed draft. Admin users call this from the email manager bulk draft actions. Requires the admin API auth middleware and user permission checks.



# Delete email template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/delete-email-template

delete /admin/auto_emails/template/{id}
Delete an email template. Only allows deletion of supported custom templates.



# Download a communication coverage export
Source: https://api-docs.helpyousponsor.com/api-reference/communications/download-a-communication-coverage-export

get /admin/communications/coverage/exports/{exportId}
Streams the requesting user ready private CSV as communications-coverage.csv. Requires unchanged permissions and an available stored artifact; pending/failed or missing artifacts return 404. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.



# Download a generated mailing export
Source: https://api-docs.helpyousponsor.com/api-reference/communications/download-a-generated-mailing-export

get /admin/mailings/exports/{uploadId}
Streams the tenant-owned export ZIP as an attachment, checking current Impact Story evidence and file availability. Does not wait for queued generation or regenerate a missing export. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Download a mailing run ZIP
Source: https://api-docs.helpyousponsor.com/api-reference/communications/download-a-mailing-run-zip

get /admin/mailing_runs/{id}/download-zip
Streams the run ZIP as an attachment after checking current approved Impact Story evidence. Does not regenerate absent files. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Duplicate a custom mailing template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/duplicate-a-custom-mailing-template

post /admin/mailing_templates/{id}/duplicate
Copies the template, documents and program bindings with a Copy suffix, current actor ownership and freshly validated Impact Story evidence. System templates cannot be duplicated. Requires permission: one of mailings_manage, manage_email.



# Edit a draft donor message
Source: https://api-docs.helpyousponsor.com/api-reference/communications/edit-a-draft-donor-message

patch /admin/message/draft/{email_id}/edit
Updates the subject, message body, and optional S3 attachment marker for an existing draft donor message. Admin users call this before approving draft communications in the email manager. Requires the admin API auth middleware and user permission checks.



# Edit a note
Source: https://api-docs.helpyousponsor.com/api-reference/communications/edit-a-note

put /admin/notes/{note_id}/{program_id}



# Edit an email set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/edit-an-email-set

put /admin/auto_emails/emailset



# Edit an email template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/edit-an-email-template

put /admin/auto_emails/template



# Edit newsletter content or scheduling
Source: https://api-docs.helpyousponsor.com/api-reference/communications/edit-newsletter-content-or-scheduling

patch /admin/newsLetters/{id}/edit
Atomically edits only draft/future scheduled newsletters. Supplied audience intent replaces the snapshot; nullable content/sender values handled by isset retain stored values. A nonempty schedule or scheduled_at schedules the newsletter at least five minutes ahead and enforces the10 scheduled limit; status alone is validated but does not change lifecycle. attachment empty string clears it; fileName is the legacy fallback. Returns detail, adding eligibility counts when scheduled. Requires permission: one of newsletter.



# Email template Details
Source: https://api-docs.helpyousponsor.com/api-reference/communications/email-template-details

get /admin/auto_emails/template/{emailset_id}/{trigger}



# Export notes as PDF
Source: https://api-docs.helpyousponsor.com/api-reference/communications/export-notes-as-pdf

get /admin/notes/{type}/{id}/export
Generates a PDF export of notes for a donor or recipient entity, optionally filtered by note category. Admin users call this from the notes panel to download a human-readable record of staff notes. Requires the admin API auth middleware and user permission checks.



# Find newsletter donors by tag
Source: https://api-docs.helpyousponsor.com/api-reference/communications/find-newsletter-donors-by-tag

get /admin/donors/by-tag
Returns active organization donors with nonblank emails matching ANY supplied comma-separated tag. Results order by donor id. Optional limit clamps1..100; omitted limit returns every match. Empty tag returns an empty data array. Email suppression is applied later when dispatching. Requires permission: one of donors_view, donors_manage, donor-all.



# Generate a mailing run
Source: https://api-docs.helpyousponsor.com/api-reference/communications/generate-a-mailing-run

post /admin/mailing_templates/{id}/generate
Creates a durable run and per-recipient snapshots after preflight/evidence checks. More than one audience item queues processing; zero/one item runs synchronously. Returns 200 with run_id and current status, which may be queued/processing/completed/partially_failed/failed. Default delivery_mode=none produces artifacts; tax-summary email modes send to admin, selected donors or explicit recipients with current suppression/preferences checks. Poll run progress separately from delivery status. Requires permission: one of mailings_generate, mailings_manage, manage_email.



# Get a specific note
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-a-specific-note

get /notes/{id}
Returns a note resource for a donor or recipient, including archived profiles. Requires notes_view or notes_manage and access to the linked donor form or program.



# Get all admins
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-all-admins

get /admin/email_manager/admins



# Get all notes for an entity or donor
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-all-notes-for-an-entity-or-donor

get /notes
Returns notes for a donor or recipient, including archived profiles. Requires notes_view or notes_manage and access to the linked donor form or program.



# Get available entities
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-available-entities

get /admin/email_manager/entities



# Get available note categories
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-available-note-categories

get /notes/categories
Returns category objects and a parallel list of names. Requires notes_view or notes_manage and access to donor forms or the requested program.



# Get details of an emailset
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-details-of-an-emailset

get /admin/auto_emails/emailset/{emailset_id}



# Get email category statistics
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-email-category-statistics

post /admin/email_manager/stats



# Get note details
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-note-details

get /admin/notes/{note_id}/{program_id}



# Get sponsors of an entity
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-sponsors-of-an-entity

get /admin/email_manager/entities/{id}/sponsors



# Get unique donor or entity names for email filtering
Source: https://api-docs.helpyousponsor.com/api-reference/communications/get-unique-donor-or-entity-names-for-email-filtering

post /admin/email_manager/filter_names
Get unique donor or entity names for filtering



# Link an SMS conversation to a donor
Source: https://api-docs.helpyousponsor.com/api-reference/communications/link-an-sms-conversation-to-a-donor

post /admin/sms_inbox/conversations/{conversation_id}/link-donor
Links a donor from this organization, marks routing matched, and backfills inbound/opt-state activity. A nonempty resolved donor phone must match the participant phone; a donor without a resolved phone can be linked. A saved conversation opt-in/opt-out state is applied to donor can_receive_sms while the master communication pause remains effective. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_manage; plus one of beta_features.



# List attachments on an email activity
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-attachments-on-an-email-activity

get /activities/{id}/attachments
Returns the file attachments parsed from an inbound email Activity, each with an unsigned public S3 download URL. Errors generating individual download URLs are logged but do not fail the request — the affected attachment will be returned without a `download_url`.



# List automated SMS sets
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-automated-sms-sets

get /admin/auto_sms
Returns compact sets/templates, program association, trigger catalog and template validation results. include_template_content optionally includes bodies. Can lazily initialize disabled default SMS templates and hides the Journeys library when configured. The current authenticated sendblue response includes sensitive credential fields. Requires permission: one of manage_sms.



# List generated mailings
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-generated-mailings

get /admin/mailings
Lists newest organization mailing records with template/run summaries. Filters status, delivery_status, run/template/donor/household, template preset, run source and run selection year. delivery_status=print_only selects not_requested delivery excluding tax-summary templates/runs. per_page is clamped to 1..100, default 10. Artifact availability uses stored Upload records without remote existence checks. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# List mailing templates
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-mailing-templates

get /admin/mailing_templates
Returns organization templates, newest update first, with compact document metadata. Can create/restore the system Tax Summary template. With scope_type, filters to that scope; tax_summary selects its system preset. Program applicability is checked only when a scope and nonempty program_ids are supplied. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# List mailing visual design assets
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-mailing-visual-design-assets

get /admin/mailing_design_assets/{assetType}
Returns built-in fonts/templates/texts/shapes/frames, or matching stock images plus up to 20 newest organization image uploads. q filters names for non-images, stock names/tags and upload file/name for images. Generated mailing artifacts are excluded from uploads. remote_search_enabled is true, but this handler uses the built-in stock catalog and organization uploads without a third-party search request. Requires permission: one of mailings_manage.



# List newsletters with delivery summaries
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-newsletters-with-delivery-summaries

post /admin/newsLetters
Returns newsletters newest updated_at/id first. Pagination is clamped; title search is trimmed to255 characters. Invalid filterData becomes no filter. statusView=overview collapses partially_sent/unconfirmed to sent, except explicit filters for those states force detailed view. status_counts includes all tenant newsletters before title/status filtering. Requires permission: one of newsletter.



# List note category names
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-note-category-names

get /admin/notes/categories/{type}/{program_id}
Returns the category names available for donor or entity notes in the requested program context. Admin users call this when rendering category filters and note forms. Requires the admin API auth middleware and user permission checks.



# List organization email sending domains
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-organization-email-sending-domains

get /admin/email/settings/sending-domains
Returns safe DNS/provisioning/delivery state, newest setup first. Does not query the provider. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# List organization Sendblue lines
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-organization-sendblue-lines

get /admin/sendblue/lines
Returns registered Sendblue lines for this organization, default first then phone number. Includes saved ownership/visibility and provisioning metadata without sending a message. Requires permission: one of sendblue_lines_view, sendblue_manage, access_account_settings.



# List recent mailing runs
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-recent-mailing-runs

get /admin/mailing_runs
Returns at most 100 organization runs, newest id first. Queued/processing runs use live generated-record counters; finished runs use stored totals. Progress describes document processing separately from delivery status. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# List recipient messages for moderation
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-recipient-messages-for-moderation

get /admin/recipient-messages
Lists recipient-authored messages in this organization, pending_approval by default. status=all or blank removes the status filter. Pending/queued/rejected messages sort first, then newest updated; optional program/entity/search filters narrow the list. per_page is clamped to 1..100, default 20. Versioned access: requires permission: one of email_manager, manage_email.



# List SMS inbox conversations
Source: https://api-docs.helpyousponsor.com/api-reference/communications/list-sms-inbox-conversations

get /admin/sms_inbox/conversations
Lists newest message conversations in the selected tab, default open. Tabs unread/mine/unassigned/triage further restrict open conversations; closed includes archived; spam selects spam. Unknown tabs use the open filter. per_page is clamped to 10..100 (default 25). Counts cover all visible conversations before list filters; assignable_users retain any current ineligible assignee for reassignment. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_view, sms_inbox_reply, sms_inbox_manage; plus one of beta_features.



# Log a donor mailing manually
Source: https://api-docs.helpyousponsor.com/api-reference/communications/log-a-donor-mailing-manually

post /admin/donors/{donor_id}/mailings
Records a manual mailing activity for this organization active donor, with an optional historical logged_at (defaults now), notes and label layout. Creates an activity record without generating or sending artifacts. Requires permission: one of mailings_generate, mailings_manage, manage_email.



# Manage auto emails
Source: https://api-docs.helpyousponsor.com/api-reference/communications/manage-auto-emails

get /admin/auto_emails



# Manually associate an email activity with a donor
Source: https://api-docs.helpyousponsor.com/api-reference/communications/manually-associate-an-email-activity-with-a-donor

patch /activities/{id}/associate-donor
Admin tool: links an inbound-email Activity to a Donor (e.g. after the auto-matcher failed or matched the wrong donor). The activity row is updated and re-indexed in Meilisearch.



# Mark an SMS conversation read
Source: https://api-docs.helpyousponsor.com/api-reference/communications/mark-an-sms-conversation-read

post /admin/sms_inbox/conversations/{conversation_id}/mark-read
Sets the shared conversation last_read_at and resets unread_count to zero. Does not clear the needs_reply flag and does not send a provider read receipt. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_reply, sms_inbox_manage; plus one of beta_features.



# Mark email as read
Source: https://api-docs.helpyousponsor.com/api-reference/communications/mark-email-as-read

put /admin/email/mark_read/{email_id}



# Page saved newsletter recipients
Source: https://api-docs.helpyousponsor.com/api-reference/communications/page-saved-newsletter-recipients

get /admin/newsLetters/{id}/recipients
Pages the saved donor-id snapshot, clamping page to the last page and pageSize1..100. Resolves current/deleted tenant donor display context, preferring the stored address and reporting drift. Blank addresses are omitted from donors while total still counts ids; legacy email-only entries without saved donor ids do not appear. Requires permission: one of newsletter.



# Post Template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/post-template

post /admin/template
Handles saving or updating a template with provided CSS,
     *          JavaScript, and HTML content based on the client ID.



# Preview a mailing PDF
Source: https://api-docs.helpyousponsor.com/api-reference/communications/preview-a-mailing-pdf

post /admin/mailing_templates/{id}/preview
Returns an inline letter/label PDF for the first printable audience record, or one printable label sheet. Uses the same audience, opt-out, template applicability and current Impact Story checks as preflight; no generation run is stored. A missing requested document or empty printable audience returns 422. Requires permission: one of mailings_manage, manage_email.



# Preview persisted auto-email content
Source: https://api-docs.helpyousponsor.com/api-reference/communications/preview-persisted-auto-email-content

get /admin/auto_emails/template/{emailset_id}/{trigger}/preview
Returns the subject and message for one configured auto-email template so an administrator can review it from a donor record. This read-only path never creates or changes template configuration, and both the email set and template reads are scoped to the authenticated organization. Requires the `manage_email` permission.



# Preview signed email preferences
Source: https://api-docs.helpyousponsor.com/api-reference/communications/preview-signed-email-preferences

post /unsubscribe/preview
Validates the signed token and returns organization branding and effective email category choices. The token scopes the address and organization; no bearer session is needed. Does not change preferences.



# Queue a commitment-based SMS test or live send
Source: https://api-docs.helpyousponsor.com/api-reference/communications/queue-a-commitment-based-sms-test-or-live-send

post /admin/test_smsset
Uses a tenant-owned commitment to render the trigger. test defaults true and sends to test_number or the current admin phone; test=false uses the donor actual number and current SMS readiness/consent. Requires an attached/resolved SMS set and configured Sendblue. pay_receipt resolves an in-kind/soft-credit variant by commitment method with enabled-default fallback. The receipt says sent but provider delivery is queued and rechecks consent. Requires permission: one of manage_sms.



# Queue a communication coverage CSV export
Source: https://api-docs.helpyousponsor.com/api-reference/communications/queue-a-communication-coverage-csv-export

post /admin/communications/coverage/export
Queues targets or rollups with normalized filters and selected recognized columns. Stores a private artifact owned by the requesting user and the exact permission fingerprint. The worker rechecks access before and after generation. Returns 200 with queued/export_id; poll status before download. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.



# Queue a generated mailing ZIP export
Source: https://api-docs.helpyousponsor.com/api-reference/communications/queue-a-generated-mailing-zip-export

post /admin/mailings/bulk-export
Selects tenant-owned generated records from the supplied positive ids, dropping duplicates and ignoring unavailable ids. Queues a ZIP of all/letter/label artifacts and returns 200 with an export Upload id and status path. Checks current Impact Story evidence before queueing and again in the worker. Poll status before downloading. Requires permission: one of mailings_generate, mailings_manage, manage_email.



# Queue a manual SMS reply
Source: https://api-docs.helpyousponsor.com/api-reference/communications/queue-a-manual-sms-reply

post /admin/sms_inbox/conversations/{conversation_id}/messages
Requires an active Sendblue line and a conversation that is neither blocked nor opted out. Supply nonblank text or unused outbound attachment ids uploaded for this organization. Creates one queued SMS per attachment, attaching text to the first; text-only sends create one message. Attachments are claimed atomically before jobs dispatch. Returns refreshed detail with HTTP 200; queued status does not establish provider delivery, and the worker rechecks donor consent. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_reply, sms_inbox_manage; plus one of beta_features.



# Queue an automated SMS trigger
Source: https://api-docs.helpyousponsor.com/api-reference/communications/queue-an-automated-sms-trigger

get /admin/auto_sms/send/{program_id}/{trigger}/{to}
Executes the selected program default SMS template. Requires a program SMS set, active sender line, configured Sendblue, enabled template and nonempty rendered message. to=donor uses the selected donor and requires current SMS consent/readiness; to=admin uses comma-separated template to_numbers. Returns 200 after queueing; it does not establish delivery. A missing program/set returns 500; unavailable recipients/template/consent returns 422. Requires permission: one of manage_sms.



# Queue an automated SMS trigger
Source: https://api-docs.helpyousponsor.com/api-reference/communications/queue-an-automated-sms-trigger-1

get /admin/auto_sms/send/{program_id}/{trigger}/{to}/{donor_id}
Executes the selected program default SMS template. Requires a program SMS set, active sender line, configured Sendblue, enabled template and nonempty rendered message. to=donor uses the selected donor and requires current SMS consent/readiness; to=admin uses comma-separated template to_numbers. Returns 200 after queueing; it does not establish delivery. A missing program/set returns 500; unavailable recipients/template/consent returns 422. Requires permission: one of manage_sms.



# Queue an automated SMS trigger
Source: https://api-docs.helpyousponsor.com/api-reference/communications/queue-an-automated-sms-trigger-2

get /admin/auto_sms/send/{program_id}/{trigger}/{to}/{donor_id}/{entity_id}
Executes the selected program default SMS template. Requires a program SMS set, active sender line, configured Sendblue, enabled template and nonempty rendered message. to=donor uses the selected donor and requires current SMS consent/readiness; to=admin uses comma-separated template to_numbers. Returns 200 after queueing; it does not establish delivery. A missing program/set returns 500; unavailable recipients/template/consent returns 422. Requires permission: one of manage_sms.



# Read a generated mailing
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-generated-mailing

get /admin/mailings/{id}
Returns the organization compact generated mailing, template/run summary and artifact paths after checking current storage availability. Does not expose rendered HTML or frozen address/merge snapshots. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read a generated mailing export status
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-generated-mailing-export-status

get /admin/mailings/exports/{uploadId}/status
Returns persisted/cache job progress and verifies stored availability before declaring ready. A ready progress record with a missing file becomes failed. Checks current Impact Story evidence. The ready download_url omits v1; use the corresponding documented download endpoint. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read a generated mailing PDF
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-generated-mailing-pdf

get /admin/mailings/{id}/artifact/{kind}
Streams the selected letter or label inline. Requires the generated mailing, Upload record and stored file in this organization. Rechecks approved Impact Story evidence and can withdraw a run when evidence is invalid. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read a mailing run label sheet
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-mailing-run-label-sheet

get /admin/mailing_runs/{id}/artifact/{kind}
Streams a run label_sheet PDF inline after checking current approved Impact Story evidence. Only label_sheet is supported. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read a mailing run progress
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-mailing-run-progress

get /admin/mailing_runs/{id}
Returns this organization run with live generated-record counts and progress. total/ready/skipped/failed/queued and processed counts are distinct from delivery status. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read a mailing template editor
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-mailing-template-editor

get /admin/mailing_templates/{id}
Returns the tenant-owned template with full HTML/serialized design/settings, bindings, form-aware merge groups and latest-record preview context. System templates can be read but cannot be edited, archived or duplicated. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read a newsletter and audience snapshot
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-newsletter-and-audience-snapshot

get /admin/newsLetters/{id}
Returns stored content without raw recipient arrays, derived delivery totals, current-versus-snapshot audience explanation, and the first50 recipient ids. Saved addresses remain visible with email drift flags; sending resolves current tenant donor addresses. Missing record returns404 with status=success in the legacy envelope. Requires permission: one of newsletter.



# Read a newsletter send-time recommendation
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-newsletter-send-time-recommendation

get /admin/newsLetters/timing-recommendation
Returns a cached unexpired recommendation or computes one from tenant newsletter aggregates over the last 180days. Requires at least 50 delivered messages, 4 campaigns and 2 comparison slots with at least 2 campaigns each; latest delivery must be within 45days. The next winning local two-hour slot is at least 30minutes ahead. Results expire after one day. Insufficient/stale data and unexpected failures, including an invalid timezone, return 200 with a non-ready status; manual scheduling remains available. Requires permission: one of newsletter.



# Read a recipient message mailbox detail
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-a-recipient-message-mailbox-detail

get /admin/recipient-messages/{id}
Returns a tenant-owned recipient-authored message in the legacy mailbox shape, including sender/donor details and attachment availability. No attachment yields null availability; an unavailable attachment reports false and a reason. admins and responses are empty in this projection. Versioned access: requires permission: one of email_manager, manage_email.



# Read an automated SMS set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-an-automated-sms-set

get /admin/auto_sms/smsset/{smsset_id}
Returns the tenant-owned stored set, without provisioning templates or sending messages. Requires permission: one of manage_sms.



# Read an automated SMS template editor
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-an-automated-sms-template-editor

get /admin/auto_sms/template/{smsset_id}/{trigger}
Reads the selected trigger/variant, default donation_type=default, and creates an enabled empty template when absent. Returns known/unknown shortcodes, eligible form fields, validation results and three latest commitment preview options. Receipt triggers include all variant records. The current authenticated sendblue projection contains credential fields. Requires permission: one of manage_sms.



# Read an SMS conversation
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-an-sms-conversation

get /admin/sms_inbox/conversations/{conversation_id}
Returns a newest-first page of message records, ordered chronologically inside that page (default 50, maximum 100), plus current line/donor reply eligibility. Reading can refresh saved messaging_status but does not mark the conversation read. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_view, sms_inbox_reply, sms_inbox_manage; plus one of beta_features.



# Read communication coverage export status
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-communication-coverage-export-status

get /admin/communications/coverage/exports/{exportId}/status
Requires this organization export, the original requesting user and an unchanged permission fingerprint. Returns queued/processing/ready/failed. download_url is an API path without the version prefix; use the documented v1 download endpoint when ready. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.



# Read communication coverage target history
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-communication-coverage-target-history

get /admin/communications/coverage/targets/{coverageTargetId}
Finds a permitted target across all target types/statuses while respecting program/source/channel context. Returns its projection, current queue summary and one newest-first timeline page; there is no timeline total/page metadata. A full timeline event can be context-only, so check qualifies_for_target. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.



# Read communication coverage totals
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-communication-coverage-totals

get /admin/communications/coverage/summary
Returns selected audience totals, effective normalized filter defaults and quick-view counts. Defaults to sponsorship_pair, active/due, message_manager and email/print. Written coverage requires a successful/logged outbound email/print from staff/recipient within the target eligibility period and matching target scope; broadcasts/transactional touches are context. Work-queue filters do not reduce summary totals. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.



# Read donor communication preferences
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-donor-communication-preferences

get /donor/{id}/communication-preferences
Returns effective delivery states and underlying saved choices for this donor primary email, including archived donor records. Requires access to every donor form with a record sharing the address. A donor master do-not-email block also pauses SMS/postal delivery without losing saved choices. Requires permission: one of donors_view, donors_manage, donor-all.



# Read donor mailing activity
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-donor-mailing-activity

get /admin/donors/{donor_id}/mailings
Returns recent manual/generated mailing logs for an active tenant-owned donor. per_page is clamped to 1..100, default 25; reads up to four times that many newest activities then selects the most recent by logged_at when present. This is a bounded recent list, without page cursors or totals. Artifact flags probe current storage. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read donor portal notification preferences
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-donor-portal-notification-preferences

get /frontend/donor/dashboard/notification-preferences/{client_id}/{program_id}/{session_id}
Requires a valid logged-in donor session for the client, and a program in that client or the global none context. The session lifetime refreshes for one hour on use. Returns category/event catalog overrides and address-level effective/saved communication choices.



# Read mailing template merge options
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-mailing-template-merge-options

get /admin/mailing_templates/meta/options
Returns organization programs excluding the synthetic root, form-aware merge schema, Unlayer tag groups and a latest-record preview context. scope_type defaults donor; program_ids narrows form groups, while preview context independently selects the latest suitable record. No mailing is generated. Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read newsletter composer merge tags
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-newsletter-composer-merge-tags

get /admin/newsLetters/composer-metadata
Returns merge availability and one selected donor-form field set. No donor form disables profile tags; multiple forms require all standardized. The system unsubscribe_url shortcode remains available regardless. Does not return donor records. Requires permission: one of newsletter.



# Read per-recipient newsletter delivery results
Source: https://api-docs.helpyousponsor.com/api-reference/communications/read-per-recipient-newsletter-delivery-results

get /admin/newsLetters/{id}/delivery-results
Returns durable delivery rows oldest id first with derived summary and pagination. pending combines queued/sending; unconfirmed represents ambiguous provider handoff and should be reconciled before retry. sent confirms provider acceptance; separate delivered evidence can still show unknown/not_delivered. Error explanations are safe descriptions rather than raw provider messages. Requires permission: one of newsletter.



# Reconcile email sending domain provisioning
Source: https://api-docs.helpyousponsor.com/api-reference/communications/reconcile-email-sending-domain-provisioning

post /admin/email/settings/sending-domains/{domainId}/reconcile
Rechecks an incomplete/uncertain setup under its provisioning lock, recovering only the same ambiguous create attempt. A ready setup returns saved state. Before next_reconcile_at, creation waits while discovery can still run. An unresolved outcome returns 202; an external conflict returns 409. Does not activate sending. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# Record mailing delivery statuses
Source: https://api-docs.helpyousponsor.com/api-reference/communications/record-mailing-delivery-statuses

patch /admin/mailings/delivery-status
Updates matching tenant-owned mailing delivery_status to sent or not_sent, ignores unavailable ids, sets/clears delivered_at and clears delivery errors. Recalculates each affected run delivery summary. This records the operator decision without sending mail. Requires permission: one of groups, admins, new_form, forms, manage_programs, donors_manage, donations, manage_email, email_manager, manage_sms, sms_manager, sms_inbox_view, sms_inbox_reply, sms_inbox_manage, sendblue_manage, mailings_view, mailings_generate, mailings_manage, manage_settings, access_account_settings, access_payment_gateways, tasks_manage, trips_manage, events_manage, events_sponsor_manage, imports_manage, households_manage, notes_manage, reports_manage.



# Refresh a saved tag newsletter audience
Source: https://api-docs.helpyousponsor.com/api-reference/communications/refresh-a-saved-tag-newsletter-audience

post /admin/newsLetters/{id}/audience/refresh
Rebuilds the saved ANY-tag snapshot from current tenant donors, preserving explicit additions and manual removals. Only editable draft/future scheduled newsletters with saved tags can refresh. Does not dispatch email; returns refreshed detail and first50 recipient ids. Requires permission: one of newsletter.



# Reject a pending recipient message
Source: https://api-docs.helpyousponsor.com/api-reference/communications/reject-a-pending-recipient-message

post /admin/recipient-messages/{id}/reject
Only pending_approval messages can be rejected. Stores the trimmed rejection reason, current actor/time and rejected status, and records activity. Does not send the message. Versioned access: requires permission: one of email_manager, manage_email.



# Remove an automated SMS set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/remove-an-automated-sms-set

delete /admin/auto_sms/smsset/{smsset_id}
Soft-deletes this organization set and all its non-deleted templates in a transaction. Does not remove historical messages or provider phone lines. Requires permission: one of manage_sms.



# Remove an email set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/remove-an-email-set

delete /admin/auto_emails/emailset/{emailset_id}



# Remove an inactive sending domain
Source: https://api-docs.helpyousponsor.com/api-reference/communications/remove-an-inactive-sending-domain

delete /admin/email/settings/sending-domains/{domainId}
Requires the setup to be inactive. Deletes a ready domain from the provider before removing its local setup; non-ready provisioning/conflict records are removed locally. Refuses concurrent setup activity. Does not remove an active domain. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# Rename a profile-note category
Source: https://api-docs.helpyousponsor.com/api-reference/communications/rename-a-profile-note-category

put /admin/notes/categories/{category_id}
Requires notes_manage plus access to the donor category context or recipient program. Trims the supplied name and rejects a case-insensitive duplicate in the same organization/program bucket. Notes retain their category relationship. Requires permission: one of notes_manage.



# Resolve donor and recipient message context
Source: https://api-docs.helpyousponsor.com/api-reference/communications/resolve-donor-and-recipient-message-context

get /admin/message-context
Checks requested profiles against current organization, donor-form and program visibility. Returns visible names and allowed scopes plus can_compose when both profiles have a completed relationship. Omitting both ids returns an empty data array. This context endpoint does not send, create or assign a message; can_compose does not by itself grant other operation permissions. Requires permission: one of email_manager, manage_email, send_status.



# Retrieve Template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/retrieve-template

get /admin/template
Fetches a specific template and associated pictures based on the client ID.



# Retry failed newsletter deliveries
Source: https://api-docs.helpyousponsor.com/api-reference/communications/retry-failed-newsletter-deliveries

post /admin/newsLetters/{id}/retry
Requires overall failed state. With send_immediately=true or no schedule, claims and retries only failed durable rows after current address/preferences checks; sent and ambiguous rows remain untouched. Otherwise reschedules at least five minutes ahead subject to the10 scheduled limit and current recommendation checks. Large-audience eligibility may be pending.200 reports current state rather than completion. Requires permission: one of newsletter.



# Save an automated SMS template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/save-an-automated-sms-template

put /admin/auto_sms/template
Updates the tenant-owned template selected by id, or creates one for smsset_id/trigger/donation_type. Known program/donor/recipient/participant shortcodes are checked; unrecognized codes return 400. Omitted message clears it, omitted to_numbers clears administrator recipients, and omitted disabled enables the template. Use a supported trigger from the catalog. Requires permission: one of manage_sms.



# Save newsletter content and audience
Source: https://api-docs.helpyousponsor.com/api-reference/communications/save-newsletter-content-and-audience

post /admin/save/recipients
Creates a NEW newsletter and snapshot; it does not update an existing newsletter. Requires from/title/message; status is consumed directly from the payload without enum validation. log_activity optionally records a draft action. Does not dispatch email or validate a send schedule. Returns detail plus the first50 saved recipient ids. Tag/all selection is resolved server-side rather than trusting a parallel email list. Requires permission: one of groups, admins, new_form, forms, manage_programs, donors_manage, donations, manage_email, email_manager, manage_sms, sms_manager, sms_inbox_view, sms_inbox_reply, sms_inbox_manage, sendblue_manage, mailings_view, mailings_generate, mailings_manage, manage_settings, access_account_settings, access_payment_gateways, tasks_manage, trips_manage, events_manage, events_sponsor_manage, imports_manage, households_manage, notes_manage, reports_manage.



# Save preferences from a signed email link
Source: https://api-docs.helpyousponsor.com/api-reference/communications/save-preferences-from-a-signed-email-link

post /unsubscribe
The signed token scopes the email address and organization. With only token, a category link opts out of its source category; a legacy link stops all email. Explicit changes apply only the named categories. Individual account_security changes are forbidden, and category links cannot disable all email. restore_all_email is exclusive of individual changes/disable_all_email; disable_all_email cannot be combined with enabling categories. SMS/postal changes are rejected. Restore clears stored opt-outs while donor/form suppression remains.



# Search automated SMS commitment preview options
Source: https://api-docs.helpyousponsor.com/api-reference/communications/search-automated-sms-commitment-preview-options

get /admin/auto_sms/template/{smsset_id}/{trigger}/sponsorships
Returns latest commitment choices attached through a recipient relationship to programs using this SMS set. Search matches donor/profile names, recipient title fields and numeric commitment/relationship ids. limit defaults 20, maximum 50. No attached program returns an empty array. Requires permission: one of manage_sms.



# Search commitment preview options
Source: https://api-docs.helpyousponsor.com/api-reference/communications/search-commitment-preview-options

get /admin/auto_emails/template/{emailset_id}/{trigger}/sponsorships
Returns donor-to-recipient sponsorship options that can be used to preview shortcode output for an automated email template. Admin users call this from the template editor; results are scoped to programs attached to the email set and filtered by the authenticated client. Requires the admin API auth middleware and user permission checks.



# Search communication coverage rollups
Source: https://api-docs.helpyousponsor.com/api-reference/communications/search-communication-coverage-rollups

post /admin/communications/coverage/rollups/search
Returns program groups by default, or recipient/program groups when rollup_type=recipient. Counts aggregate all permitted audience rows in each group; at least one row must match work filters. Defaults sort coverage_rate_30d ascending, independent of the target-list severity default. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.



# Search communication coverage targets
Source: https://api-docs.helpyousponsor.com/api-reference/communications/search-communication-coverage-targets

post /admin/communications/coverage/targets/search
Returns a page of permitted target projections matching coverage-status/assignment/unread/approval/no-thread filters, with audience totals before those work filters. Defaults page 1/per_page 25, severity descending. A welcome gap means no qualifying touch in a target period begun within 7 days; staleness uses selected 30/60/90 day threshold. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.



# Search emails using Meilisearch
Source: https://api-docs.helpyousponsor.com/api-reference/communications/search-emails-using-meilisearch

post /admin/email_manager/search



# Send a message
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-a-message

get /admin/message/send/{entity_id}/{donor_id}/{from}/{file_id}



# Send a message
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-a-message-1

post /admin/message/send/{entity_id}/{from}/{file_id}



# Send a recipient profile-update email
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-a-recipient-profile-update-email

post /admin/auto_emails/send/{program_id}/profile_update/donor/{donor_id}/{entity_id}
Explicitly queues profile-update email for ALL distinct current sponsors of the selected recipient, including relationships funded separately. The donor_id is required context and idempotency scope; it does not narrow delivery to that donor. Requires active recipient in the selected tenant program and enabled/available template, current donor/form/category preferences and valid address. Companion SMS is disabled.200 means all eligible attempts were queued;207 reports partial queueing;422 means no eligible sends or invalid context;500 reports zero-delivery failures. Idempotency-Key is actor/organization/program/donor/recipient scoped, cached24 hours: completed calls replay the same status/body, in-flight calls409; zero-send server failures release the key. A partial receipt must not be retried with a new key to avoid duplicates. Requires permission: one of manage_programs, manage_email.



# Send a test automated email
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-a-test-automated-email

post /admin/test_emailset
Queues an automated email using a tenant-owned commitment and trigger. Tests go only to the authenticated admin, bypass sample donor/form email restrictions, and do not notify the donor. A test can target one donation-type variant; it is sent only when that variant and the standard template are both on, and source details such as the DAF sponsor or IRA custodian use clearly labeled sample values. With `test` false, donor email preferences apply and successful queueing records donor activity. Requires admin API authentication and user permission checks.



# Send a verified-domain test email
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-a-verified-domain-test-email

post /admin/email/settings/sending-domains/{domainId}/test
Sends a real verification message to the organization saved From address over the candidate managed SMTP transport. Requires provisioning ready, verified DNS and an aligned From domain. Records tested_at only after the transport accepts the message. The organization delivery configuration is unchanged until activation; acceptance does not establish inbox delivery. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# Send an email
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-an-email

get /admin/auto_emails/send/{program_id}/{trigger}/{to}/{donor_id}/{entity_id}



# Send an email response
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-an-email-response

post /admin/email/response



# Send an existing newsletter now
Source: https://api-docs.helpyousponsor.com/api-reference/communications/send-an-existing-newsletter-now

post /admin/send/newsLetter/{id}/send
Atomically claims the current saved audience, clears scheduling and dispatches current eligible recipients. Sending/sent newsletters return400; failed state retries only failed deliveries. Durable sent/ambiguous rows are not resent. Audiences over500 defer eligibility. Other non-sending/sent lifecycle states may be claimed; the receipt reports current sending/sent/skipped/failed state. Requires permission: one of newsletter.



# Start or reuse a donor SMS conversation
Source: https://api-docs.helpyousponsor.com/api-reference/communications/start-or-reuse-a-donor-sms-conversation

post /admin/sms_inbox/conversations/start
Reuses the latest visible donor conversation, on the selected line when supplied; otherwise creates a conversation on an active visible Sendblue line. New conversations require donor SMS consent, no do-not-email master pause and an SMS-ready phone. Existing conversations can still return with can_reply=false. Returns a warning if another visible line already has a conversation. Does not send a message. Conversations and available lines respect line visibility: restricted lines require assignment to the viewer or sms_inbox_manage/group_all. Requires permission: one of sms_inbox_reply, sms_inbox_manage; plus one of beta_features.



# Start verified email domain setup
Source: https://api-docs.helpyousponsor.com/api-reference/communications/start-verified-email-domain-setup

post /admin/email/settings/sending-domains
Derives the base domain from the organization saved From address and creates the prefix subdomain, default mg with us region. Public mailbox domains are rejected. Setup is idempotent for the same subdomain; a normal receipt returns 201 even when reusing an existing setup. Add the returned sending DNS records, then check verification. An ambiguous provider outcome returns 202 with code/data and can reconcile later; existing externally claimed domains return 409 with a suggested prefix. Existing active/ready setup must be removed before changing prefixes. Requires verified_sending_domains enabled for the organization and the current user/group to have manage_email, email_manager or group_all. Requires permission: one of manage_email.



# Synchronize organization Sendblue lines
Source: https://api-docs.helpyousponsor.com/api-reference/communications/synchronize-organization-sendblue-lines

post /admin/sendblue/lines/sync
Synchronizes configured Sendblue lines from client-managed provider credentials or managed assignment settings. Disabled mode marks registered lines disabled and returns an empty list. Client-managed sync disables lines no longer configured; an unset default is selected from synced lines. Refuses cross-organization phone reassignment. Incomplete client-managed credentials or ownership conflicts return 422. Requires permission: one of sendblue_manage.



# Update a custom mailing template
Source: https://api-docs.helpyousponsor.com/api-reference/communications/update-a-custom-mailing-template

put /admin/mailing_templates/{id}
Rejects system templates. Updates supplied scalar fields; omitted/null nullable scalar values retain the prior value. Supplied program_ids replaces all bindings. Supplied documents replaces the set of kinds and removes omitted kinds; at least one is required when present. Document/visual-designer and current Impact Story rules also apply. Requires permission: one of mailings_manage, manage_email.



# Update a note
Source: https://api-docs.helpyousponsor.com/api-reference/communications/update-a-note

put /notes/{id}
Updates a note body and optionally its category, including notes on archived profiles. Requires notes_manage and profile access. Supplying expected_updated_at prevents overwriting a changed note.



# Update an automated SMS set
Source: https://api-docs.helpyousponsor.com/api-reference/communications/update-an-automated-sms-set

put /admin/auto_sms/smsset
Updates the tenant-owned set name and sender number. Omitted/null from_number clears the override. Nonempty from_number must use E.164 format. Does not synchronize registered provider lines. Requires permission: one of manage_sms.



# Update donor communication preferences
Source: https://api-docs.helpyousponsor.com/api-reference/communications/update-donor-communication-preferences

patch /donor/{id}/communication-preferences
Updates only supplied fields. Email categories, master do_not_email and postal choices apply across donor records sharing the normalized primary address; SMS consent changes only this donor. Enabling SMS requires sms_consent_confirmed=true. account_security cannot be disabled individually. restore_email_delivery clears address-level/email-event blocks and donor master flags, preserving form-level suppression. Requires access to every matching donor form. Requires permission: one of donors_manage.



# Update donor portal notification preferences
Source: https://api-docs.helpyousponsor.com/api-reference/communications/update-donor-portal-notification-preferences

put /frontend/donor/dashboard/notification-preferences/{client_id}/{program_id}/{session_id}
Requires a valid donor session and client-owned program or none context. Saves catalog category/event overrides atomically with channel choices. Valid email categories are returned by GET; email event changes are mirrored to donor records sharing the address. Account access cannot be disabled individually. sms_opt_out=true opts matching records out; false does not grant SMS consent. restore_all_email clears stored email opt-outs and event overrides while donor/form master suppression remains unless do_not_email is separately cleared. Postal changes apply to every matching donor.



# Update the status of an email
Source: https://api-docs.helpyousponsor.com/api-reference/communications/update-the-status-of-an-email

put /admin/email/status/{email_id}/update



# Update the status of multiple emails
Source: https://api-docs.helpyousponsor.com/api-reference/communications/update-the-status-of-multiple-emails

put /admin/emails/status/{mail_status}/update



# Upload a pending SMS attachment
Source: https://api-docs.helpyousponsor.com/api-reference/communications/upload-a-pending-sms-attachment

post /admin/sms_inbox/attachments
Uploads a JPG/JPEG/PNG/GIF image or PDF directly to Sendblue, maximum 10 MiB, and creates an unclaimed tenant-owned outbound attachment. Supply the returned id to a manual reply. Optional donor_id is recorded only when found in this organization; an unknown donor is ignored. Does not send a message. Requires permission: one of sms_inbox_reply, sms_inbox_manage; plus one of beta_features.



# Upload a template image
Source: https://api-docs.helpyousponsor.com/api-reference/communications/upload-a-template-image

post /admin/upload_pic_to_template
Uploads a client template image to the Gratona S3 bucket and records the public upload as a template asset. Admin users call this while editing HTML email/page templates. Requires the admin API auth middleware and user permission checks.



# Upload an auto-email editor image to S3
Source: https://api-docs.helpyousponsor.com/api-reference/communications/upload-an-auto-email-editor-image-to-s3

get /admin/auto_email_s3_upload
Uploads the `file` entry from the raw multipart request into the public Gratona S3 bucket and echoes a TinyMCE-compatible `filelink` JSON payload. This legacy endpoint reads `$_FILES` directly even though the route is registered as GET. Requires the admin API auth middleware and user permission checks.



# View a specific email
Source: https://api-docs.helpyousponsor.com/api-reference/communications/view-a-specific-email

get /admin/emails/{email_id}



# View all admin emails
Source: https://api-docs.helpyousponsor.com/api-reference/communications/view-all-admin-emails

post /admin/email_manager/admin/{id}/emails



# View email manager
Source: https://api-docs.helpyousponsor.com/api-reference/communications/view-email-manager

post /admin/email_manager



# View notes
Source: https://api-docs.helpyousponsor.com/api-reference/communications/view-notes

post /admin/notes



# Add a commitment donation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/add-a-commitment-donation

post /admin/commitment/{commitment_id}/donation



# Add a new designation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/add-a-new-designation

post /admin/designation



# Add a new donation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/add-a-new-donation

post /admin/donation



# Add manual donation recognition credits
Source: https://api-docs.helpyousponsor.com/api-reference/donations/add-manual-donation-recognition-credits

post /admin/donations/{donation_id}/soft-credits
Creates a manual recognition credit for a Direct gift, or atomically creates credits for split_donations. Each allocation must belong to this organization, be Direct, have a unique donor credit and an amount no greater than the donation. Duplicate split IDs and existing donor credits return400. A recognition credit does not add financial revenue. DAF/QCD managed recognition must be changed through the gift source fields. Requires permission: one of donations, reports_view, reports_manage.



# Attach a credit card to a donor on the active gateway
Source: https://api-docs.helpyousponsor.com/api-reference/donations/attach-a-credit-card-to-a-donor-on-the-active-gateway

post /admin/add_cc
Sends raw card details (or a tokenized `payment_method`) through `Donation::createCustomer` to register the card with the client's active payment gateway and store the resulting reference on the donor. Refreshes the donor cache on success. Note: returns HTTP 200 even on gateway failure (failure message is returned in the body); caller must inspect the message text. Validation: `donor_id required`. Requires permission: `donations_manage`.



# Ccommitment details
Source: https://api-docs.helpyousponsor.com/api-reference/donations/ccommitment-details

get /admin/commitment/{commitment_id}/donation



# Change an organization giving-institution role
Source: https://api-docs.helpyousponsor.com/api-reference/donations/change-an-organization-giving-institution-role

patch /admin/donors/{donorId}/giving-institution
Requires daf_qcd_giving_v1 and donor mutation access. Enabling requires an organization donor. Omitted role preserves current role; disabling clears role and directory key. Directory-linked records retain their directory role. DAF financial ownership, recommending-advisor credits and recorded custodian relationships prevent incompatible flag/role changes with409. Saves and logs only actual changes. Requires permission: one of donors_manage.



# Combined hard- and soft-credit transaction history for a donor
Source: https://api-docs.helpyousponsor.com/api-reference/donations/combined-hard-and-soft-credit-transaction-history-for-a-donor

get /admin/donors/{donor_id}/all-credits
Returns the donor's full giving history — both direct donations (`hard_credit`) and soft credits (`soft_credit`) — merged and sorted by date desc, then paginated. Soft-credited rows whose underlying donation has been soft-deleted are filtered out. Also returns top-level `totals` for hard credits, soft credits, and influenced (sum) so the UI can show the donor scoreboard without a second request. Requires permission: `donors_view` (also satisfied by `donors_manage`).



# Create a custom donation field
Source: https://api-docs.helpyousponsor.com/api-reference/donations/create-a-custom-donation-field

post /admin/donation-fields
Creates a server-keyed donation field in the current organization and queues search-field refresh. Select fields require at least one nonblank option; options are trimmed and deduplicated.  Supports required/visibility and conditional display controls. Conditions must reference an earlier select field with sufficient visibility and matching options; only registered input types support required/conditional controls. Requires permission: one of manage_settings.



# Create, link, or convert a giving institution
Source: https://api-docs.helpyousponsor.com/api-reference/donations/create-link-or-convert-a-giving-institution

post /admin/donors/{hysform_id}/giving-institutions
Requires daf_qcd_giving_v1 and donor-form mutation access. Supply at least one of existing_donor_id, catalog_key, organization_name; conversion takes priority, then catalog key, then manual name. New directory/manual organization records have no personal/login identity and email is suppressed. Reuses compatible accessible existing institutions; a deleted linked record is not restored. Conversion preserves history/contact details and disables portal eligibility; already-marked institutions are reused without changing role. Directory role must match; saved grant/advisor/custodian relationships can prevent conversion. Returns201 only for a new record, otherwise200 with created=false. Requires permission: one of donors_manage.



# Delete a scheduled report (and its filter preference)
Source: https://api-docs.helpyousponsor.com/api-reference/donations/delete-a-scheduled-report-and-its-filter-preference

delete /admin/reports/schedule/{id}
Removes a `ScheduledReport` row, then force-deletes its associated `FilterPreference` row when one exists. Idempotent at the schedule level — returns 404 only if the schedule itself is missing. Requires permission: `donations_manage` (also satisfied by `reports_manage`).



# Designation Details
Source: https://api-docs.helpyousponsor.com/api-reference/donations/designation-details

get /admin/designation/{designation_id}



# Donation count + amount roll-up for a date window
Source: https://api-docs.helpyousponsor.com/api-reference/donations/donation-count-+-amount-roll-up-for-a-date-window

get /admin/donations/statistics
Returns counted and summed donation totals scoped to the caller's client across the supplied date range. Splits monetary versus in-kind donations (in-kind is detected by the `IN_KIND` method constant) so the dashboard can render them separately. Excludes refunded rows from `donations`/totals; counts zero-amount rows and `transaction_status = failed` rows as `failed`. Defaults `date_from` and `date_to` to today when omitted. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# Donation details
Source: https://api-docs.helpyousponsor.com/api-reference/donations/donation-details

get /admin/donation/{donation_id}



# Donation view options
Source: https://api-docs.helpyousponsor.com/api-reference/donations/donation-view-options

get /admin/donations/options



# Download a finished donation/soft-credit export
Source: https://api-docs.helpyousponsor.com/api-reference/donations/download-a-finished-donationsoft-credit-export

get /admin/donations/exports/{uploadId}
Resolves the export's S3 link. Default behavior issues an HTTP 302 redirect to a short-lived presigned URL, suitable for `<a download>` links. When called with `?resolve=1`, returns the URL as JSON instead so SPA code can handle the download itself. The upload must belong to the caller's client. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# Edit a commitment
Source: https://api-docs.helpyousponsor.com/api-reference/donations/edit-a-commitment

get /admin/commitments/{commitment_id}



# Edit a commitment
Source: https://api-docs.helpyousponsor.com/api-reference/donations/edit-a-commitment-1

put /admin/commitments/{commitment_id}



# Edit a designation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/edit-a-designation

put /admin/designation/{designation_id}



# Edit a donation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/edit-a-donation

put /admin/donation/{donation_id}



# Edit multiple commitments
Source: https://api-docs.helpyousponsor.com/api-reference/donations/edit-multiple-commitments

patch /admin/commitments



# Email tax summaries (selected donors or admin recipients)
Source: https://api-docs.helpyousponsor.com/api-reference/donations/email-tax-summaries-selected-donors-or-admin-recipients

post /admin/donors/send_tax_summary
Generates and queues delivery of year-end tax summary letters via `MailingGenerationService`. The delivery mode is derived from inputs: `email_selected_donors` when `send_to_selected_donors=true`, `email_explicit` when an explicit `recipients` list is supplied, otherwise `email_admin` (the calling admin gets the summary). `donor_ids` accepts an array of integer ids OR the literal string `all`; when `all` is combined with `send_to_selected_donors=true`, `hysform_id` becomes required. Returns 200 once the generation is queued. Requires permission: `mailings_generate` (also satisfied by `mailings_manage` or `manage_email`).



# Email year-end statements to households
Source: https://api-docs.helpyousponsor.com/api-reference/donations/email-year-end-statements-to-households

post /admin/households/send_year_end
Companion to `sendYearEndDonors` that operates on tenant-owned `Household` rows instead of individual donors. For each household ID provided, queues `Household::queueSendYearEndDonor` against a tenant-validated primary contact and donor set. The authenticated tenant is authoritative; any payload `client_id` is ignored. Requires `donors_manage` or `group_all`.



# Fetch a single saved report definition
Source: https://api-docs.helpyousponsor.com/api-reference/donations/fetch-a-single-saved-report-definition

get /admin/donation-reports/{id}
Returns one `Report` row by id (404 when missing). Used by the scheduled-report editor to load the source report before scheduling. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# Find giving-source people and advisors
Source: https://api-docs.helpyousponsor.com/api-reference/donations/find-giving-source-people-and-advisors

get /admin/donations/giving-people
Returns at most25 suggestions from the first100 active accessible donor candidates ordered by id. Blank search returns an empty array. All search words narrow email/name/identity fields; final resolved-profile substring matching can further reduce results. Excludes giving institutions. Default role=person excludes organization records; advisor also allows ordinary organizations. Respects donor-form scope and returns private,no-store cache policy. Requires permission: one of donations, reports_view, reports_manage.



# Get a donation worksheet with query filters
Source: https://api-docs.helpyousponsor.com/api-reference/donations/get-a-donation-worksheet-with-query-filters

get /admin/donations
GET variant of the donation worksheet, with the same organization/form scope and tab-specific projection as POST. Date defaults use organization time. Saved views fill omitted filters/columns and date presets. Search, filtering and sorting use the registered field contracts; totals and graphs can be skipped with includeSummary=false. Supplying report_name creates a saved report even through GET, so omit it for a read-only request. Prefer POST for large nested filter/column payloads. Requires permission: one of donations, reports_view, reports_manage.



# Get a donation’s recognition credits
Source: https://api-docs.helpyousponsor.com/api-reference/donations/get-a-donation’s-recognition-credits

get /admin/donations/{donation_id}/soft-credits
Returns the organization-owned donation, its active soft credits with donor/type relations and the active manual credit types. Automatically managed DAF/QCD recognition types are omitted from the type picker, while existing managed credits remain visible. Requires permission: one of donations, reports_view, reports_manage.



# Get all donations by a specific donor
Source: https://api-docs.helpyousponsor.com/api-reference/donations/get-all-donations-by-a-specific-donor

get /admin/donors/{donor_id}/donations



# Get all donations by donors
Source: https://api-docs.helpyousponsor.com/api-reference/donations/get-all-donations-by-donors

get /admin/donors/donations



# Get commitments graph
Source: https://api-docs.helpyousponsor.com/api-reference/donations/get-commitments-graph

get /commitments/{date_from}/{date_to}/graph



# Get donations graph
Source: https://api-docs.helpyousponsor.com/api-reference/donations/get-donations-graph

get /donations/{date_from}/{date_to}/graph



# Get form fields for a specific donor group
Source: https://api-docs.helpyousponsor.com/api-reference/donations/get-form-fields-for-a-specific-donor-group

get /admin/form/{donor_group}/fields



# Init the legacy add-credit-card form
Source: https://api-docs.helpyousponsor.com/api-reference/donations/init-the-legacy-add-credit-card-form

get /admin/add_cc
Bootstrap call for the legacy 'admin adds a credit card on behalf of a donor' UI. Returns the donor record and resolved display name so the form can render the donor banner before posting card details to `postAddCC`. Validation: `donor_id required`. Requires permission: `donations_manage`.



# List a donor’s sponsorship coverage options
Source: https://api-docs.helpyousponsor.com/api-reference/donations/list-a-donor’s-sponsorship-coverage-options

get /admin/donations/coverage-options
Returns current sponsorship suggestions separately from eligible recurring commitment options for the active organization donor. Recipient programs are permission scoped, including explicit denials; archived recipients on existing relationships can remain available historically. available/unavailable_reason describe each schedule’s eligibility and do not apply any coverage. Requires permission: one of donations, reports_view, reports_manage.



# List custom donation field definitions
Source: https://api-docs.helpyousponsor.com/api-reference/donations/list-custom-donation-field-definitions

get /admin/donation-fields
Returns all custom donation input definitions for the current organization, including stable keys, renderer codes and select options. Definitions determine valid custom_fields values on gift-entry requests. Requires permission: one of donations, manage_settings.



# List donation/soft-credit export jobs currently queued or processing
Source: https://api-docs.helpyousponsor.com/api-reference/donations/list-donationsoft-credit-export-jobs-currently-queued-or-processing

get /admin/donations/exports/active
Returns up to 10 donation- and soft-credit-export `Upload` rows from the last 24 hours whose status is `queued` or `processing`. Powers the `Active exports` indicator in the admin UI so users can resume polling without losing the upload id. Each row is enriched with `PdfRenderService::queuedUploadStatus`. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# List emailsets and program forms when creating a designation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/list-emailsets-and-program-forms-when-creating-a-designation

get /admin/designation



# List organization recognition credits
Source: https://api-docs.helpyousponsor.com/api-reference/donations/list-organization-recognition-credits

get /admin/soft-credits
Returns active soft credits with organization-bound donations, donor/type relations, designation and donor-name summaries, ordered newest first. date_from/date_to filter the donation’s creation date, not the credit date. pageIndex is one-based and at least1; pageSize is clamped1–100. Requires permission: one of donations, reports_view, reports_manage.



# List the distinct years that have donation activity
Source: https://api-docs.helpyousponsor.com/api-reference/donations/list-the-distinct-years-that-have-donation-activity

get /admin/donors/donation_years
Returns the descending list of tax period years for which the caller's client has donation activity, using its jurisdiction profile and organization timezone. Fiscal periods are labelled by the year they end in. Backs the tax-summary year picker. Requires permission: `donors_view` (also satisfied by `donors_manage`).



# Patch a scheduled report's cadence or recipients
Source: https://api-docs.helpyousponsor.com/api-reference/donations/patch-a-scheduled-reports-cadence-or-recipients

put /admin/reports/schedule/{id}
Selectively updates `frequency`, `start_date`, and/or `recipient_emails` on an existing `ScheduledReport`. Each field is only written when present in the request. Enforces tenant scope — returns 403 when the schedule does not belong to the caller's client. Requires permission: `donations_manage` (also satisfied by `reports_manage`).



# Poll a single donation/soft-credit export
Source: https://api-docs.helpyousponsor.com/api-reference/donations/poll-a-single-donationsoft-credit-export

get /admin/donations/exports/{uploadId}/status
Returns the current state of one donation/soft-credit export `Upload` (scoped to the caller's client, 404 otherwise). Mirrors a row of `activeDonationExports` but works for any status — including `completed` so the UI can flip to a download button. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# Poll donations that were updated after creation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/poll-donations-that-were-updated-after-creation

get /admin/donations/updated-feed
Returns active organization donations whose updated_at is later than created_at, newest update first with ID as a tie breaker. updated_after defaults to the UTC start of day90 days ago and is inclusive. For subsequent pages send both next_cursor values as cursor_updated_at and cursor_id; the cursor moves backwards within the update window. This is a current-state update feed, not an immutable event history. Includes recognition credits and disclosure-aware source summaries. Requires permission: one of donations, reports_view, reports_manage.



# Preview a commitment payment receipt
Source: https://api-docs.helpyousponsor.com/api-reference/donations/preview-a-commitment-payment-receipt

post /admin/commitment/{commitment_id}/donation/receipt-preview
Resolves donor and designation from the organization-owned commitment and renders the actual receipt plan for the proposed payment. Amount may be zero, selecting pay_fail rather than pay_receipt. Does not create a payment, advance the commitment, charge or send email. Honors manual recognition requirements, configured templates, suppression and preferences. Requires permission: one of donations, reports_view, reports_manage.



# Preview a staff-entered donation receipt
Source: https://api-docs.helpyousponsor.com/api-reference/donations/preview-a-staff-entered-donation-receipt

post /admin/donations/receipt-preview
Validates the proposed gift and renders the actual receipt plan without creating a donation, charging, advancing a commitment or sending email. Split amounts must align and sum to the gift total. Plans honor suppression, notification preferences, source-specific templates, disclosure and recipient selection. HTTP200 may report skipped/suppressed/unavailable. DAF/QCD source preview requires the organization rollout and eligible owner/advisor/custodian records. Requires permission: one of donations, reports_view, reports_manage.



# Preview gift ownership and sponsorship coverage
Source: https://api-docs.helpyousponsor.com/api-reference/donations/preview-gift-ownership-and-sponsorship-coverage

post /admin/donations/giving-preview
Validates base gift fields, then returns the financial owner, advisor/IRA owner, custodian, tax treatment and optional commitment coverage plan without writing. Source or coverage problems are returned in data.errors with HTTP200; base field validation returns422. Only already-received cash/check/wire/external gifts can cover existing schedules. Scope and currency must match; no currency conversion is performed. Caller commitment_id is ignored; use commitment_links. Requires permission: one of donations, reports_view, reports_manage.



# Queue a CSV export of donations or soft credits (async)
Source: https://api-docs.helpyousponsor.com/api-reference/donations/queue-a-csv-export-of-donations-or-soft-credits-async

get /admin/export_donations
Reserves an `Upload` row to back the export, marks it `queued`, then dispatches `ProcessDonations`. Returns 200 immediately with the upload id and a `status_url` to poll. Pass `export_type=soft_credits` to switch the file stem (and underlying query) to soft credits; otherwise produces `donations-export.csv`. Any additional filter inputs (date range, filter groups, etc.) are forwarded to the job verbatim. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# Queue a single donor's donation history export
Source: https://api-docs.helpyousponsor.com/api-reference/donations/queue-a-single-donors-donation-history-export

get /admin/export_donor_donations
Donor-scoped export — reserves an upload, dispatches `ProcessDonations` with the request's `donor_id` (and any other filters), and returns a status URL to poll while the CSV is generated. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# Read a donor tax-summary contribution projection
Source: https://api-docs.helpyousponsor.com/api-reference/donations/read-a-donor-tax-summary-contribution-projection

get /admin/tax-summaries/donors/{donor_id}
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.



# Read a household tax-summary contribution projection
Source: https://api-docs.helpyousponsor.com/api-reference/donations/read-a-household-tax-summary-contribution-projection

get /admin/tax-summaries/households/{household_id}
Returns a statement for the household current active donor members and organization jurisdiction/timezone. Household permission and every member donor-form scope are required. Omitted year selects the most recent available period. Gifts within the household scope are counted once; recognition on already-owned gifts and QCD IRA-owner reconciliation gifts is omitted from soft credits. Deductible cash/in-kind totals and recognition totals stay separate per currency. Ambiguous evidence marks review_required; an empty statement can have null year/period/fingerprint. No PDF, email or mutation is performed. Requires permission: one of households_view, households_manage.



# Read an institution historical QCD custody activity
Source: https://api-docs.helpyousponsor.com/api-reference/donations/read-an-institution-historical-qcd-custody-activity

get /admin/donors/{donor_id}/custodian-activity
Requires a visible organization donor marked as a giving institution. Returns historical QCD gifts naming it as intermediary while another donor is financial owner, newest created_at/id first; institution-owned gifts remain in normal giving. Financial owners are narrowed by donor-form visibility. Only primary designation is projected, and recipient names require program view/manage plus program access. Shows recorded history including nonqualified/refunded statuses; no credit is reassigned and amounts are not converted. Requires permission: one of donors_view, donors_manage.



# Refresh donation status from Stripe
Source: https://api-docs.helpyousponsor.com/api-reference/donations/refresh-donation-status-from-stripe

get /admin/donations/{donation_id}/refresh



# Refund a donation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/refund-a-donation

post /admin/donation/{donation_id}/refund



# Remove a designation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/remove-a-designation

delete /admin/designation/{designation_id}



# Remove a donation
Source: https://api-docs.helpyousponsor.com/api-reference/donations/remove-a-donation

delete /admin/donation/{donation_id}



# Remove a donor card on the active gateway
Source: https://api-docs.helpyousponsor.com/api-reference/donations/remove-a-donor-card-on-the-active-gateway

get /admin/delete_cc
Calls `Donation::deleteCard` to remove the donor's stored card on the active gateway and refreshes the donor cache on success. Verb is GET (legacy ergonomics) — newer integrations should prefer the donor-scoped `DELETE /admin/donor-credit-card/{donor_id}`. Returns 200 even on gateway failure — caller must inspect the message. Validation: `donor_id required`. Requires permission: `donations_manage`.



# Remove a manual recognition credit
Source: https://api-docs.helpyousponsor.com/api-reference/donations/remove-a-manual-recognition-credit

delete /admin/donations/{donation_id}/soft-credits/{id}
Soft-deletes a credit that belongs to the current organization and the route donation, after recording the activity. Automatic DAF/QCD credits cannot be removed through manual controls. Requires permission: one of donations, reports_view, reports_manage.



# Reorder custom donation fields
Source: https://api-docs.helpyousponsor.com/api-reference/donations/reorder-custom-donation-fields

put /admin/donation-fields/order
Requires every current organization field ID exactly once, plus expected_field_ids in the previously observed order. A changed order returns409. Revalidates conditional dependencies and visibility against the new order; invalid graphs return422. Requires permission: one of manage_settings.



# Repair a sponsorship missing its commitment record
Source: https://api-docs.helpyousponsor.com/api-reference/donations/repair-a-sponsorship-missing-its-commitment-record

get /admin/commitment/fix
Recovery tool for sponsorships (`DonorEntity` rows) that ended up without a matching `Commitment`. Creates a minimal placeholder commitment (type=monthly, frequency=1, method=manual, designation = entity_id, funding flag derived from the program type) so admins can edit it back into a usable state via `editCommitment`. Persists immediately. Currently reads `client_id` from the legacy session — caller must have an active admin session even though the route is also bearer-protected. Validation: `donor_entity_id required`. Requires permission: `donations_manage`.



# Schedule a saved report for recurring delivery
Source: https://api-docs.helpyousponsor.com/api-reference/donations/schedule-a-saved-report-for-recurring-delivery

post /admin/reports/schedule
Creates a `ScheduledReport` row tying a `Report` to a delivery cadence. Refuses to create a duplicate when the report already has a scheduled-report row (returns HTTP 409). The new schedule inherits the report's `client_id`. Requires permission: `donations_manage` (also satisfied by `reports_manage`).



# Search donation designation recipients
Source: https://api-docs.helpyousponsor.com/api-reference/donations/search-donation-designation-recipients

get /admin/donations/designations/search
Returns entity-type designation options for the admin Add/Edit Donation drawers. Uses a client-scoped cached recipient list so admins can search across all recipients, including fully sponsored ones, without loading thousands of rows into the initial form payload.



# Search giving institutions and the starter directory
Source: https://api-docs.helpyousponsor.com/api-reference/donations/search-giving-institutions-and-the-starter-directory

get /admin/donations/giving-institutions
Requires daf_qcd_giving_v1; unavailable workspaces return404. Lists accessible tenant institution records plus unlinked reviewed directory suggestions, maximum25 in each section. With role, accepts that role or legacy unrecorded roles. id lookup ignores role/search and returns at most one accessible institution with no other suggestions. Search of two or more characters can also suggest ordinary organizations for explicit conversion; directory reads make no external provider call. Requires permission: one of donations, reports_view, reports_manage.



# Soft-delete a single commitment by id
Source: https://api-docs.helpyousponsor.com/api-reference/donations/soft-delete-a-single-commitment-by-id

delete /admin/commitments
Soft-deletes one `Commitment` row. The route handler is registered under both `/admin/commitments` (DELETE, v1) and `/admin/remove_commitment` (GET, legacy) and the case-mismatched `RemoveCommitment` symbol — neither route declares a path param so the `commitment_id` is read from the request (body or query). Requires permission: `donations_manage`.



# Suggest previously disclosed DAF fund names
Source: https://api-docs.helpyousponsor.com/api-reference/donations/suggest-previously-disclosed-daf-fund-names

get /admin/donations/daf-fund-names
Requires daf_qcd_giving_v1. Returns up to20 distinct nonblank fund names from active DAF gifts for this exact sponsor/advisor pair with named disclosure and active automatic advisor recognition. Both parties must be visible in the staff donor-form scope; inaccessible/missing parties return an empty list. Requires permission: one of donations, reports_view, reports_manage.



# Top 10 most recent commitments (dashboard widget)
Source: https://api-docs.helpyousponsor.com/api-reference/donations/top-10-most-recent-commitments-dashboard-widget

get /admin/10_commitments
Returns the 10 most-recently-created commitments for the caller's client, augmented with display names for the donor and entity. Donor and entity names are extracted from each row's `json_fields` by walking keys that contain `name` and using the first match — this is the legacy display logic the dashboard still relies on. Requires permission: `donations_view` (also satisfied by `donations_manage`).



# Update a custom donation field
Source: https://api-docs.helpyousponsor.com/api-reference/donations/update-a-custom-donation-field

put /admin/donation-fields/{fieldId}
Updates the current organization’s field label; input type, options and stable field key remain fixed. Required/visibility and conditional display controls can also be updated, with the whole ordered dependency graph validated. Requires permission: one of manage_settings.



# Update a manual recognition credit
Source: https://api-docs.helpyousponsor.com/api-reference/donations/update-a-manual-recognition-credit

put /admin/donations/{donation_id}/soft-credits/{id}
Updates the organization-owned credit on this donation. soft_credit_donor_id takes precedence over donor_id; omitted/empty donor IDs retain the current donor. Amount must be positive and no greater than the donation. A donor can have only one active credit per gift. Automatic DAF/QCD recognition is read-only here. Relationship attribution changes only when an override or reason is supplied. Requires permission: one of donations, reports_view, reports_manage.



# Update an existing donor card on the active gateway
Source: https://api-docs.helpyousponsor.com/api-reference/donations/update-an-existing-donor-card-on-the-active-gateway

post /admin/update_cc
Forwards the supplied card data to `Donation::updateCard` to mutate the donor's existing card on the active payment gateway (e.g. expiry rotation). Returns 200 even on gateway failure — the failure message lands in the response body. Validation: `donor_id required`. Requires permission: `donations_manage`.



# View all designations
Source: https://api-docs.helpyousponsor.com/api-reference/donations/view-all-designations

get /admin/designations



# View all donations
Source: https://api-docs.helpyousponsor.com/api-reference/donations/view-all-donations

post /admin/donations/{all}



# Add a one-time donation from the donor dashboard
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/add-a-one-time-donation-from-the-donor-dashboard

post /frontend/donor/dashboard/{client_id}/{program_id}/{session_id}
Creates an additional donation from the donor portal — a logged-in donor adds a one-off gift on top of (or independent of) their existing commitments. Requires an authenticated Redis donor session.



# Apply a modify-commitment-amount change
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/apply-a-modify-commitment-amount-change

post /frontend/modify_amount
Companion POST for `modifyCommitmentAmount`. Saves the new amount on the commitment when the magic-link token validates. Used by the donor's email-driven amount-change flow.



# Approve a PayPal payment from the donor dashboard
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/approve-a-paypal-payment-from-the-donor-dashboard

post /frontend/donor/dashboard/approve_paypal/{client_id}/{program_id}/{session_id}
Completes a PayPal authorization initiated from the donor dashboard. Requires a logged-in Redis donor session.



# Check donor bank verification completion
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/check-donor-bank-verification-completion

post /frontend/donor/dashboard/bank-verification/{client_id}/{program_id}/{session_id}
Uses the logged-in session donor within the client path, refreshes session TTL to one hour, and rechecks owned pending Stripe bank authorizations against their original processor, customer, payment method and active mandate. A verified chargeable US bank account is saved and the original due checkout collection may be queued exactly once through the shared handoff. Provider failures/pending authorizations remain a successful check with updated=false and a message; this response does not prove a queued charge settled.



# Continue 3DS card verification
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/continue-3ds-card-verification

put /frontend/donor/dashboard/card-verify/{client_id}/{program_id}/{charge_id}/{session_id}
Resumes a Stripe SetupIntent / charge that requires 3D Secure customer authentication. Called by the donor-portal Stripe Elements flow after the user completes the 3DS challenge. The `charge_id` is the Stripe SetupIntent / PaymentIntent id returned by `postUpdateCard`. Requires a logged-in donor session.



# Delete a file
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/delete-a-file

delete /frontend/donor/dashboard/file/{client_id}/{program_id}/{id}/{entity_id}/{session_id}



# Donor Credit Card Information
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/donor-credit-card-information

get /frontend/donor/dashboard/card/{client_id}/{program_id}/{session_id}
Allows a donor to update their credit card information.



# Donor View
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/donor-view

get /frontend/donor/dashboard/{client_id}/{program_id}/{session_id}
Displays the donor's profile and related information,
     *          handling the retrieval of donor data based on session ID.



# Donor View Entity
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/donor-view-entity

get /frontend/donor/dashboard/entity/{client_id}/{program_id}/{entity_id}/{session_id}
Displays a specific entity's profile and related information to the donor.



# Donor View Entity Message History
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/donor-view-entity-message-history

get /frontend/donor/dashboard/entity/messages/{client_id}/{program_id}/{entity_id}/{session_id}
Returns message history for a specific donor entity.



# Forgot Username
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/forgot-username

get /frontend/forgot_username/{client_id}/{program_id}/{session_id}
Handles the process for users who have forgotten their username by initiating a new session.



# Get Donor Information
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/get-donor-information

get /frontend/donor/dashboard/details/{client_id}/{program_id}/{session_id}
Allows a donor to get their information.



# Get files for a donor
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/get-files-for-a-donor

get /frontend/donor/dashboard/files/{client_id}/{program_id}/{id}/{entity_id}/{session_id}



# Get Login Information
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/get-login-information

get /frontend/login/{client_id}/{program_id}/{session_id}
Retrieves login information and related details for a specific client and program.



# Get PayPal credentials
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/get-paypal-credentials

get /donor/paypal



# Handle Donor File Uploads
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/handle-donor-file-uploads

get /frontend/donor/dashboard/uploads/{client_id}/{program_id}/{entity_id}/{session_id}



# List eligible one-time donation designations
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/list-eligible-one-time-donation-designations

get /frontend/donor/dashboard/donation-designations/{client_id}/{program_id}/{session_id}
Requires an active donor session in the requested organization. Returns current sponsorship recipients and other recipients or campaign designations allowed by the organization, independently of dashboard history pagination.



# Log in a donor across organizations
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/log-in-a-donor-across-organizations

post /frontend/global_donor/login
Authenticates a donor by username or email across all clients rather than a single client/program route. If multiple donor accounts match the credentials, the endpoint creates a short-lived Redis account-selection token and returns `selection_required`; otherwise it creates a donor Redis session and returns the donor, client, program context, and redirect URL. Public donor portal clients use this endpoint when scoped login route parameters are unavailable.



# Mark email as read
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/mark-email-as-read

put /frontend/donor/dashboard/entity/mark_read/{client_id}/{program_id}/{entity_id}/{email_id}/{session_id}



# Post Donor View Entity Message
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/post-donor-view-entity-message

post /frontend/donor/dashboard/entity/compose_message/{client_id}/{program_id}/{entity_id}/{parent_id}/{session_id}
Allows a donor to send a message to an entity.



# Post Forgot Username
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/post-forgot-username

post /frontend/forgot_username/{client_id}/{program_id}/{session_id}
Handles the process for users who have forgotten their username
     *          by verifying the email and sending the username to the user.



# Post Login
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/post-login

post /frontend/login/{client_id}/{program_id}/{session_id}
Handles the login process for a user, including validation and authentication.



# Post Logout
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/post-logout

get /frontend/logout/{client_id}/{program_id}/{session_id}
Handles user logout by terminating the session and clearing related data.



# Post Reset Password
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/post-reset-password

post /frontend/reset_password/{client_id}/{program_id}/{session_id}
Handles the password reset process including
     *          verification and sending a temporary password to the user.



# Remove a saved donor payment method
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/remove-a-saved-donor-payment-method

delete /frontend/donor/dashboard/card/{client_id}/{program_id}/{session_id}
Uses the logged-in donor session within the requested client. Removes an owned Stripe payment method/legacy source or the donor’s saved Flutterwave v4 method. A current default or active saved bank method cannot be removed while an unexpired active card/bank commitment (methods3,8,9,10,12) depends on payment details; update that method first. Stripe origin/customer ownership is checked and a concurrent verified replacement is preserved. Missing/blank card_id returns404; unsupported gateway returns422.



# Render compose-message-to-entity page payload
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/render-compose-message-to-entity-page-payload

get /frontend/donor_view_entity_compose_message/{client_id}/{program_id}/{entity_id}/{parent_id}/{session_id}
Returns the data needed for the donor-portal compose-message screen — recipient entity, the parent thread message (if replying), the donor's profile, and form constraints. Requires a logged-in Redis donor session.



# Render modify-commitment-amount page payload
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/render-modify-commitment-amount-page-payload

get /frontend/modify_amount
Public donor-portal endpoint that returns the data needed to render the modify-commitment-amount UI from a magic-link email (donor + commitment context). Authentication is via signed query parameters in the link, not a session.



# Request a global donor passwordless sign-in
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/request-a-global-donor-passwordless-sign-in

post /frontend/global_donor/passwordless_login
Returns a generic result and, for matching accounts, issues a six-digit numeric code plus magic link. The newest code for the normalized global email scope invalidates its predecessor and expires after 15 minutes.



# Reset Password
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/reset-password

get /frontend/reset_password/{client_id}/{program_id}/{session_id}
Initiates a password reset process by generating a new session and returning session details.



# Resolve forms attached to a donor or entity
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/resolve-forms-attached-to-a-donor-or-entity

get /frontend/get_forms/{type}/{id}/{hysform_id}/{client_id}
Read-only donor-session compatibility endpoint for historical archived updates, formerly called Progress Reports. The `session_id` header must identify a logged-in donor in the requested client, and entity results are limited to updates created during that donor's current or archived recipient relationship.



# Retrieve 3DS card verification state
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/retrieve-3ds-card-verification-state

get /frontend/donor/dashboard/card-verify/{client_id}/{program_id}/{charge_id}/{session_id}
Returns the current Stripe verification state for a card-update flow. Used by the donor-portal Stripe Elements view to poll/resume after the 3DS challenge.



# Save file upload to database
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/save-file-upload-to-database

post /frontend/donor/recordUpload/{client_id}/{session_id}



# Select a global donor account
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/select-a-global-donor-account

post /frontend/global_donor/select_account
Completes global donor login after a password or passwordless flow returns `selection_required`. The controller validates the selection token and account id, loads the selected donor scoped by client and donor id from Redis, deletes the selection token, then creates a donor session and redirect for the selected account.



# Start Email Sign-In
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/start-email-sign-in

post /frontend/passwordless_login/{client_id}/{program_id}/{session_id}
Starts the email-based sign-in flow with a six-digit numeric code and magic link. A new issue invalidates the previous code for the tenant, program, donor, and email scope.



# Update Donor Information
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/update-donor-information

put /frontend/donor/dashboard/details/{client_id}/{program_id}/{session_id}
Allows a donor to update their information.



# Update donor PayPal credentials
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/update-donor-paypal-credentials

post /donor/{donor_id}/paypal



# Update Donor's Credit Card Information
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/update-donors-credit-card-information

post /frontend/donor/dashboard/card/{client_id}/{program_id}/{session_id}



# Update the donor's PayPal email
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/update-the-donors-paypal-email

post /frontend/donor/dashboard/paypal/{client_id}/{program_id}/{session_id}
Donor-portal endpoint that saves the donor's PayPal address. Requires a logged-in Redis donor session in the `{session_id}` path parameter — when missing/expired the response is 422 with a `redirect` to the login page (legacy behavior).



# Uploads a file for a donor
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/uploads-a-file-for-a-donor

post /frontend/donor/dashboard/upload/{client_id}/{program_id}/{entity_id}/{session_id}



# Verify a global donor magic link
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/verify-a-global-donor-magic-link

get /frontend/global_donor/passwordless_verify/{token}
Consumes a global donor passwordless magic-link token from Redis. A valid token resolves the donor accounts cached for the email, deletes the token and clears the active verification challenge, then either completes donor login or returns an account-selection response. The endpoint also caches successful verification results for 60 seconds so repeated browser loads of the same link can return the same response.



# Verify a global donor passwordless code
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/verify-a-global-donor-passwordless-code

post /frontend/global_donor/passwordless_verify_code
Accepts only the latest six-digit numeric code. Five failed well-formed attempts burn the active challenge across source IPs.



# Verify Email Sign-In
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/verify-email-sign-in

get /frontend/passwordless_verify/{client_id}/{program_id}/{token}
Verifies the email sign-in token and logs in the donor.



# Verify the donor passwordless verification code
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/verify-the-donor-passwordless-verification-code

post /frontend/passwordless_verify_code/{client_id}/{program_id}
Second step of the donor-portal passwordless login flow. Only the latest six-digit numeric code is accepted. Five failed well-formed attempts burn the active challenge across source IPs. On success returns the donor record, client info, session id, and saved-payment snapshot, then clears challenge state.



# View an archived form submission
Source: https://api-docs.helpyousponsor.com/api-reference/donor-portal/view-an-archived-form-submission

get /frontend/view_forms/{archived_form_id}
Returns a privacy-minimized, read-only historical archived update for a logged-in donor. The `session_id` header must identify a donor in `client_id`, and the archive must belong to that donor or have been created during one of their current or archived recipient relationships.



# Add a new donor
Source: https://api-docs.helpyousponsor.com/api-reference/donor-signup/add-a-new-donor

post /frontend/signup_donor/{client_id}/{program_id}/{session_id}



# Sign up a new donor
Source: https://api-docs.helpyousponsor.com/api-reference/donor-signup/sign-up-a-new-donor

get /frontend/signup_donor/{client_id}/{program_id}/{session_id}



# Activate donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/activate-donors

post /admin/donors/activate



# Add a new donor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/add-a-new-donor

post /admin/donor/{hysform_id}



# Add multiple donors to a household
Source: https://api-docs.helpyousponsor.com/api-reference/donors/add-multiple-donors-to-a-household

post /admin/households/{household_id}/donors
Reviews all supplied rows, accepting active organization donors with no household and collecting row-level errors for unavailable/already-linked donors. Accepted members persist together; success can contain errors. Explicit primary_contact_id takes precedence over the first make_primary row and is used only if present in the final member set. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs.



# Add one donor to a household
Source: https://api-docs.helpyousponsor.com/api-reference/donors/add-one-donor-to-a-household

post /admin/households/{household_id}/donors/{donor_id}
Requires an active donor outside any household; already-present or other-household membership returns 422. Stores the requested relationship. Literal boolean make_primary=true selects this donor as primary; optional primary_relationship updates the existing household primary (or fallback primary) relationship. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs.



# Archive a single donor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/archive-a-single-donor

get /admin/donor/archive
Soft-deletes one donor and cascades the archive to their sponsorships and commitments: every `DonorEntity` is deleted (and the entity's status recalculated), every `Commitment` is deleted, then the donor itself. Sponsorship and donor caches are warmed afterwards. Same handler is mounted at `/admin/donor/archive` (`v1/admin`) and the legacy `/admin/archive_donor`. Requires permission: `donors_manage` and is gated by the `disable_donor_archive` client restriction.



# Archive donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/archive-donors

post /admin/donors/archive



# Assign or clear a donor relationship manager
Source: https://api-docs.helpyousponsor.com/api-reference/donors/assign-or-clear-a-donor-relationship-manager

patch /admin/donor/{donor_id}/assignment
Changes direct donor or household assignment after checking all affected donor-form scopes and assignee eligibility. A direct donor manager continues to override household fallback. Household scope requires membership. Material open-plan authority changes return 409 with a five-minute impact token; resubmit the same assignment with that plan_impact_version. Plan ownership and open tasks are preserved for review; projection warnings can accompany success.



# Assign relationship managers to selected donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/assign-relationship-managers-to-selected-donors

patch /admin/donors/assignment
Updates explicit active donors or all matching records. Explicit cross-organization/unavailable IDs reject the request. All-results mode requires an authorized form context and resolves saved/search/date filters; unresolved search fails safely. Household scope requires every selected donor to have a household and updates each household once after checking all active member forms. Returns the selected donor count, including unchanged assignments. Material plan impact requires a confirmed token before this atomic mutation.



# Bulk-edit fields across many donors (async)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/bulk-edit-fields-across-many-donors-async

patch /admin/program/donors
Queues a `bulkEditDonors` job for each targeted donor that applies the supplied field/value updates (admin name is captured for the activity log). Use `donor_ids` as an array of IDs to target a specific set, or the literal string `all` (with `hysform_id`) to operate on every donor of that form. The handler returns immediately once the jobs are dispatched; updates land asynchronously through the queue worker. Requires permission: `donors_manage`.



# Calculate donor worksheet footer totals
Source: https://api-docs.helpyousponsor.com/api-reference/donors/calculate-donor-worksheet-footer-totals

post /admin/donors/{hysform_id}/footer-calculations
Aggregates every matching donor, independently of pagination, using SQL aggregates or bounded row projection. Validates the calculation array, then keeps allowed field keys/operations, case-normalizes operations and deduplicates by field. Invalid entries can leave an empty calculations array with length0. Filled checks ignore blank, HTML-only and No data values; date results use Unix seconds and display formatting. Requires permission: one of donors_manage.



# Clear the default donor saved view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/clear-the-default-donor-saved-view

delete /admin/donors/default-saved-view
Preference belongs to the authenticated user and organization. Only active saved view/report definitions in a valid existing context are eligible; current context permission is checked. Campaign and recipient surfaces remain separate. Idempotently removes the personal default; the saved definition remains available.



# Clear the default worksheet saved view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/clear-the-default-worksheet-saved-view

delete /admin/saved-view-defaults/{module}
Module path accepts recipients, campaigns, sponsorships or donations. Preference belongs to the authenticated user and organization. Only active saved view/report definitions in a valid existing context are eligible; current context permission is checked. Campaign and recipient surfaces remain separate. Idempotently removes the personal default; the saved definition remains available.



# Count donors matching worksheet filters
Source: https://api-docs.helpyousponsor.com/api-reference/donors/count-donors-matching-worksheet-filters

post /admin/donors/filter-count
Counts the same active/archive, saved view, search and advanced-filter donor scope without materializing a page. hysform_id is supplied in the body; omission selects all forms. Invalid sponsoring-program filters are rejected. A search that cannot be evaluated safely while the index is unavailable returns422 instead of an inaccurate count. Requires permission: one of donors_manage.



# Create a household
Source: https://api-docs.helpyousponsor.com/api-reference/donors/create-a-household

post /admin/households
Creates an active household and attaches the primary plus deduplicated additional donors under one membership lock. Every member must be active in this organization and outside any existing household. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs.



# Create a household from two donor records
Source: https://api-docs.helpyousponsor.com/api-reference/donors/create-a-household-from-two-donor-records

post /admin/households/create-from-donor
Creates an active household from distinct primary and related donors, both active in this organization and outside any household. Stores the related donor relationship and optional primary relationship, address and custom fields. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs.



# Delete a saved donation definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-a-saved-donation-definition

delete /admin/donationFilter/saved_filters
Permanently removes a source-matching saved definition after permission/context checks. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Deletion returns 422 while any organization schedule references it; delete the schedule first.



# Delete an empty household
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-an-empty-household

delete /admin/households/{household_id}
Requires every active donor to be removed first; otherwise 422 includes donor_count. Deletes the household row after confirming archival decisions for any open stewardship plans. Donors are not deleted. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs.



# Delete donor card details
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-donor-card-details

delete /admin/donor-credit-card/{donor_id}



# Delete donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-donors

delete /admin/delete/donors



# Delete donors saved definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-donors-saved-definition

delete /admin/donors/saved_filters
Permanently removes a source-matching saved definition after permission/context checks. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Deletion returns 422 while any organization schedule references it; delete the schedule first.



# Delete entities saved definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-entities-saved-definition

delete /admin/entities/saved_filters
Permanently removes a source-matching saved definition after permission/context checks. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Deletion returns 422 while any organization schedule references it; delete the schedule first.



# Delete files saved definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-files-saved-definition

delete /admin/files/saved_filters
Permanently removes a source-matching saved definition after permission/context checks. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Deletion returns 422 while any organization schedule references it; delete the schedule first.



# Delete sponsorships saved definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/delete-sponsorships-saved-definition

delete /admin/sponsorships/saved_filters
Permanently removes a source-matching saved definition after permission/context checks. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Deletion returns 422 while any organization schedule references it; delete the schedule first.



# Dismiss one duplicate donor pair
Source: https://api-docs.helpyousponsor.com/api-reference/donors/dismiss-one-duplicate-donor-pair

post /admin/donors/duplicates/mark-not-duplicate
Creates or refreshes a durable suppression for one canonical donor pair from the current published scan. Only that pair is dismissed; other suggestions involving either donor remain available. The suppression survives rescans. A stale scan or unknown pair is rejected. Idempotent — calling twice is safe. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Donors table headers
Source: https://api-docs.helpyousponsor.com/api-reference/donors/donors-table-headers

get /admin/donors/{hysform_id}/headers/{trashed}



# Download a finished donor export
Source: https://api-docs.helpyousponsor.com/api-reference/donors/download-a-finished-donor-export

get /admin/donors/exports/{uploadId}
Resolves the export's S3 link. Default behavior issues an HTTP 302 redirect to a short-lived presigned URL, suitable for `<a download>` links. When called with `?resolve=1`, returns the URL as JSON instead so SPA code can handle the download itself. The upload must belong to the caller's client. Requires permission: `donors_view` (also satisfied by `donors_manage`).



# Edit a donor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/edit-a-donor

patch /donor/{id}/edit
Updates a donor in the authenticated organization, including archived donors while preserving their archived state. Send configured donor-form fields as top-level properties; required fields and conditional visibility depend on the donor form. A donor type change requires the loaded type, profile revision, and explicit confirmation. Requires permission: `donors_manage`.



# Field-mapping options for the migrate-fields tool
Source: https://api-docs.helpyousponsor.com/api-reference/donors/field-mapping-options-for-the-migrate-fields-tool

get /admin/donors/migrate-fields/options
Returns the standardized field catalog (key + display label from `DonorStandardFieldSetting`), the donor form's custom fields (`Donorfield` rows ordered by `field_order`), and the default custom-key mapping that `postMigrateDonorFields` would apply if no `mapping` override is supplied. Used by the admin UI to render the migration dialog. Requires permission: `donors_manage`.



# Filter donor worksheet rows
Source: https://api-docs.helpyousponsor.com/api-reference/donors/filter-donor-worksheet-rows

post /admin/all_donors/filter/{hysform_id}
Searches active or archived organization donors in one form or all forms. Resolves saved views, allowed filters and selected columns, retaining canonical identity/photo fields. Returns a paged configurable projection and full matching count. Uses current search/SQL fallbacks; an advanced date field can override the top-level creation-date range. Dates in row projections follow organization display formatting. Requires permission: one of donors_manage.



# Get a donor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-a-donor

get /donor/{id}



# Get a donor relationship schedule and history
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-a-donor-relationship-schedule-and-history

get /donors/{donorId}/relationship-context
Combines accessible upcoming tasks, meetings, confirmed event attendance and active/requested trips. Dates use the resolved organization/admin timezone; pending trip requests remain in upcoming but do not become next_scheduled_moment. Activity includes event/trip/invitation state history. Task, calendar, event and trip permissions/privacy filter their own projections.



# Get all donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-all-donors

get /admin/all_donors



# Get all donors with pagination, search and sort
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-all-donors-with-pagination-search-and-sort

get /admin/donors/{hysform_id}



# Get donor card details
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-donor-card-details

get /admin/donor-credit-card/{donor_id}



# Get donor form fields
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-donor-form-fields

get /admin/donor/{hysform_id}



# Get field options for donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-field-options-for-donors

get /admin/donors/{hysform_id}/fields/{type}



# Get household details
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-household-details

get /admin/households/{household_id}
Returns primary contact, current member donor summaries, address/custom fields and gross donation totals. This summary uses household donation records without qualified-payment filtering or subtracting refunds.



# Get personal donation worksheet columns
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-personal-donation-worksheet-columns

get /admin/donations/{hysform_id}/column-preferences
Personal organization/user preferences are scoped to the form/program path context or all. Donation tab_scope selects a separate preference. Unavailable stored fields are removed; no effective preference returns exists=false with empty arrays.



# Get personal donor worksheet columns
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-personal-donor-worksheet-columns

get /admin/donors/{hysform_id}/column-preferences
Personal organization/user preferences are scoped to the form/program path context or all. Unavailable stored fields are removed; no effective preference returns exists=false with empty arrays.



# Get personal sponsorship worksheet columns
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-personal-sponsorship-worksheet-columns

get /admin/sponsorships/{program_id}/column-preferences
Personal organization/user preferences are scoped to the form/program path context or all. Unavailable stored fields are removed; no effective preference returns exists=false with empty arrays.



# Get statistics of donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-statistics-of-donors

get /admin/statistics/donors



# Get the active duplicate-detection ruleset for a form
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-the-active-duplicate-detection-ruleset-for-a-form

get /admin/donors/{hysform_id}/duplicates/rules
Returns the configured `DuplicateRule` for the given donor form (matcher fields, comparators, threshold, enabled flag). Used by the admin UI to populate the rule editor before a scan. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Get the default donor saved view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-the-default-donor-saved-view

get /admin/donors/default-saved-view
Preference belongs to the authenticated user and organization. Only active saved view/report definitions in a valid existing context are eligible; current context permission is checked. Campaign and recipient surfaces remain separate. Returns null when unset or unavailable; structurally invalid stale defaults are cleared.



# Get the default worksheet saved view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/get-the-default-worksheet-saved-view

get /admin/saved-view-defaults/{module}
Module path accepts recipients, campaigns, sponsorships or donations. Preference belongs to the authenticated user and organization. Only active saved view/report definitions in a valid existing context are eligible; current context permission is checked. Campaign and recipient surfaces remain separate. Returns null when unset or unavailable; structurally invalid stale defaults are cleared.



# Hard-delete a single archived donor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/hard-delete-a-single-archived-donor

delete /admin/donor/delete
Permanently removes one previously-archived donor along with their trashed sponsorships and all commitments — uses `forceDelete()` on `DonorEntity`, `Commitment`, and the donor record itself, then evicts the row from the trashed-donor cache. The donor must already be archived (`withTrashed()` lookup) and must belong to the `client_id` supplied via the `client_id` request header. Same handler is mounted at `/admin/donor/delete` (DELETE) and the legacy `/admin/delete_donor` (GET). Requires permission: `donors_manage` and is gated by the `disable_donor_delete` client restriction.



# Kick off a legacy duplicate-detection scan (async)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/kick-off-a-legacy-duplicate-detection-scan-async

post /admin/donors/{hysform_id}/duplicates/{trashed}
Creates a `DuplicateScanRun` row and dispatches `CheckDuplicateDonorsJob` to scan the form for duplicate donors in the background. Returns the scan run ID immediately (HTTP 202) — poll `/admin/duplicates/scans/{scan_run_id}/progress` to watch progress, then read results from `/admin/donors/duplicates/results`. Use `startEnhancedDuplicateScan` for the newer rule-based flow. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Kick off the rule-based duplicate scan (async)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/kick-off-the-rule-based-duplicate-scan-async

post /admin/donors/{hysform_id}/duplicates/enhanced
Newer scan flow that uses the configured `DuplicateRule` ruleset. Creates a `DuplicateScanRun` row (with `scan_settings.enhanced=true`) and dispatches `EnhancedDuplicateDetectionJob`. Returns the scan run ID immediately (HTTP 202) — poll `/admin/duplicates/scans/{scan_run_id}/progress` and read results from `/admin/donors/duplicates/results`. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Legacy donor payment-source refresh (disabled)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/legacy-donor-payment-source-refresh-disabled

post /admin/client-donor-update-sources
This legacy route is disabled. Payment-source reconciliation must be implemented as an explicit, audited platform billing operation.



# Link reciprocal donor contacts
Source: https://api-docs.helpyousponsor.com/api-reference/donors/link-reciprocal-donor-contacts

post /admin/donors/{donor_id}/relationships
Creates the forward and reverse donor-contact links using their independent relationship labels. Both donors must be active in this organization, and payload primary must match the route donor. Donors in the same nonempty household cannot be external related contacts. Identical existing links are retained.



# List active households
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-active-households

get /admin/households
Searches active organization households by partial name/address and exact primary contact. Returns household summaries plus organization email sets with their templates and linked program; summaries use current donor membership.



# List all donors for a form (legacy unpaginated table)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-all-donors-for-a-form-legacy-unpaginated-table

get /admin/show_all_donors/{client_id}/{hysform_id}/{trashed}
Returns every donor for the given hysform via `Donor::getDonors()`. Pre-dates the paginated `showAllDonorsAjax` listing — kept for legacy admin UIs and CSV-style exports that need the full set in one shot. Same handler is mounted at `/admin/show_all_donors/...` (legacy `routes/api.php`) and `/v1/admin/show_all_donors/...`. Requires permission: `donors_view`.



# List donation saved definitions
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-donation-saved-definitions

get /admin/donationFilter/saved_filters/{hysform_id}
Lists active donation definitions for the normalized donor form/all context, newest first. Optional tab scope zero includes legacy null scope; absent scope lists all tabs. Nonnegative numeric scopes are accepted.



# List donor-export jobs currently queued or processing
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-donor-export-jobs-currently-queued-or-processing

get /admin/donors/exports/active
Returns up to 10 donor-export `Upload` rows from the last 24 hours whose status is `queued` or `processing`. Powers the `Active exports` indicator in the admin UI so users can resume polling without losing the upload id. Each row is enriched with `PdfRenderService::queuedUploadStatus` (progress %, last status message, etc.). Requires permission: `donors_view` (also satisfied by `donors_manage`).



# List donor household and external contacts
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-donor-household-and-external-contacts

get /admin/donors/{donor_id}/relationships
Returns other members of the donor household and forward external contact links. External relationships include current primary-contact state and raw synchronization configuration. The relationship labels are directional; household rows exclude the donor itself.



# List donor saved definitions
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-donor-saved-definitions

get /admin/donors/saved_filters/{hysform_id}
Lists active saved donor definitions for a donor-form or all-records context, newest first, including legacy null module definitions.



# List eligible donor relationship managers
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-eligible-donor-relationship-managers

get /admin/donors/assignees
Returns eligible team members for the current role rollout, retaining a requested current assignee even when replacement is needed. donor_id can reference an archived donor for eligibility review; donor/household resource scopes require the actor to access every affected donor form. include_inactive defaults true; when enforcement is enabled, ineligible users are excluded except the current assignee.



# List fields and comparators available to the rule editor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-fields-and-comparators-available-to-the-rule-editor

get /admin/donors/{hysform_id}/duplicates/field-types
Returns the union of system fields (`email`, `username`), standardized title fields (from `DonorStandardFieldSetting`), and form-specific title fields (`Donorfield` rows where `is_title=1`) — keyed by `field_key` and deduplicated. Also returns the supported comparator and field-type vocabularies so the admin UI can render rule pickers without hard-coding the choices. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# List file saved definitions
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-file-saved-definitions

get /admin/files/saved_filters/{program_id}
Lists active saved upload definitions for the exact supplied program context, newest first. This read endpoint does not normalize all to zero.



# List grouped duplicate-donor results
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-grouped-duplicate-donor-results

get /admin/donors/duplicates/results
Returns paginated groups of likely-duplicate donors. Each group is an array of `Donor` objects (primary donor first, then linked duplicates) reconstructed from the `DuplicateDonor` link table; groups where the user has marked donors as not-duplicate are filtered out automatically. Supports both `page` and `pageIndex` query keys for backwards compatibility. Free-text `search` matches the primary donor or any of its linked duplicates across username, email, and form `is_title` fields. `fieldFilters` and `filterRules` further narrow the result set on standardized columns, custom JSON fields, or year-to-date contribution buckets. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# List household custom form fields
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-household-custom-form-fields

get /admin/household/fields
Returns active fields from all organization forms whose type is household, ordered by field_order. Returns 404 with status=error when no household form exists.



# List household donations
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-household-donations

get /admin/households/{household_id}/donations
Returns newest-first donation rows from current household donors and totals over all rows, independent of pagination. Amounts are formatted strings; the summary is gross and separately reports refunds, without qualified-payment filtering.



# List household member donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-household-member-donors

get /admin/households/{household_id}/donors
Returns paginated current members with identity, contact preference and relationship labels; the primary flag is derived from the household primary donor.



# List merge batches (paginated)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-merge-batches-paginated

get /admin/duplicates/merge/batches
Returns a paginated list of `DuplicateMergeBatch` records for the caller's client. Each batch includes bounded donor, operator, field-name, and relationship-count summaries for admin review. Restore ledgers, field values, processor identifiers, and internal errors are never returned. Standard Laravel pagination envelope (20 per page). Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# List recipient/campaign saved definitions
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-recipientcampaign-saved-definitions

get /admin/entities/saved_filters/{program_id}
Lists active recipient/campaign definitions with null sponsorship scope, newest first. For all/zero context, program_surface optionally separates campaigns and recipients; recipients include legacy missing surface metadata.



# List sponsorship saved definitions
Source: https://api-docs.helpyousponsor.com/api-reference/donors/list-sponsorship-saved-definitions

get /admin/sponsorships/saved_filters/{program_id}/{sponsorship}
Lists active sponsorship definitions with effective normalized context/sponsorship scope, including compatible null-module legacy definitions. all normalizes to zero.



# Merge donors (single-shot, async)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/merge-donors-single-shot-async

post /admin/donors/merge
Retired unsafe merge endpoint. Always returns 410 without dispatching a job or changing donor data. Run a current duplicate scan and use the tracked merge-batch endpoint instead. Requires permission: `donors_manage`.



# Migrate donor field data between custom JSON and standardized columns
Source: https://api-docs.helpyousponsor.com/api-reference/donors/migrate-donor-field-data-between-custom-json-and-standardized-columns

post /admin/donors/migrate-fields
Kicks off a background migration that copies donor field values either from per-form `json_fields` into the standardized donor columns (e.g. `first_name`, `phone`, `street`) or vice versa. The `custom_to_standardized` direction routes through `DonorStandardizationService::startMigration` (returns the run record); `standardized_to_custom` dispatches `MigrateDonorFieldsJob` directly. Optional `mapping` overrides the default custom-key mapping. Requires permission: `donors_manage`.



# Poll a duplicate-scan run's status
Source: https://api-docs.helpyousponsor.com/api-reference/donors/poll-a-duplicate-scan-runs-status

get /admin/duplicates/scans/{scan_run_id}/progress
Returns the current state of a `DuplicateScanRun` so the admin UI can render a progress bar and stop polling when the job completes. Scoped to the caller's client. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Poll a merge batch's status
Source: https://api-docs.helpyousponsor.com/api-reference/donors/poll-a-merge-batchs-status

get /admin/duplicates/merge/batches/{batch_id}/progress
Returns the current state of a `DuplicateMergeBatch`, including aggregate post-merge refresh counts. Operation ledgers and internal ancillary errors are never returned. Scoped to the authenticated user's client. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Poll a single donor-export job
Source: https://api-docs.helpyousponsor.com/api-reference/donors/poll-a-single-donor-export-job

get /admin/donors/exports/{uploadId}/status
Returns the current state of one donor-export `Upload` (scoped to the caller's client, 404 otherwise). Mirrors a row of `activeDonorExports` but works for any status — including `completed` so the UI can flip to a download button. Requires permission: `donors_view` (also satisfied by `donors_manage`).



# Post field options for donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/post-field-options-for-donors

post /admin/donors/field_options



# Preview existing donor tags before replacement
Source: https://api-docs.helpyousponsor.com/api-reference/donors/preview-existing-donor-tags-before-replacement

post /admin/program/donors/tags/replacement-preview
Returns current tags/counts for selected active tenant donors without changing them. donor_ids=all requires hysform_id and selects that entire form, ignoring current worksheet search/filter fields. Explicit arrays select matching active organization donors and ignore missing ids. values is optional but must be an array/object when supplied; only values.tags comma validation is used. Proposed replacement values do not affect the returned counts. Requires permission: one of manage_programs.



# Preview field-level conflicts before merging donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/preview-field-level-conflicts-before-merging-donors

post /admin/donors/duplicates/preview-merge
Dry-run for a current published duplicate group. Returns conflicts only for profile columns whose winner can be selected by the merge endpoint; custom values and tags follow deterministic fill-empty/union behavior. Full donor records, credentials, and payment-provider identifiers are never returned. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Preview sponsorship archive or restoration
Source: https://api-docs.helpyousponsor.com/api-reference/donors/preview-sponsorship-archive-or-restoration

post /admin/sponsorships/lifecycle-preview
Requires configured sponsorship lifecycle rollout (or the legacy lifecycle-controls flag) and access to every selected effective program. Resolves explicit ids or current filtered all selection; restore always selects archived relationships. At most250 relationship ids may be previewed. Returns one row per associated commitment, or a relationship-only row where none exists, so count is preview row count and can exceed relationship count. Produces a10-minute encrypted token bound to organization, actor, action, exact relationship ids and current relationship/commitment state. No archive, restore or charge is applied. Requires permission: one of manage_programs.



# Queue a confirmed manual donor merge
Source: https://api-docs.helpyousponsor.com/api-reference/donors/queue-a-confirmed-manual-donor-merge

post /admin/donors/duplicates/manual-merge
Consumes a current actor-owned review after confirming same-person identity and a trimmed 10–2,000 character reason. Rechecks permissions, profile/dependency snapshot and stewardship impact before admitting exactly one queued merge. Same review and identical command recover the original batch; changed, expired or stale reviews return 409. Dependencies can return 422 blockers. Worker execution rechecks authority and snapshot before merging; HTTP 202 confirms admission, not completion.



# Queue a CSV export of donors (async)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/queue-a-csv-export-of-donors-async

post /admin/donors/{hysform_id}/export
Reserves an `Upload` row to back the export, marks it `queued`, then dispatches `GenerateDonorExportJob`. Returns 200 immediately with the upload id and a `status_url` to poll. The `hysform_id` may be the literal string `all` to export every donor across the caller's client (file stem becomes `all-donors-export`); otherwise the form must exist. Pass any additional filter inputs in the body — they're forwarded verbatim to the job. Requires permission: `donors_view` (also satisfied by `donors_manage`).



# Queue a tracked, undoable batch of donor merges
Source: https://api-docs.helpyousponsor.com/api-reference/donors/queue-a-tracked-undoable-batch-of-donor-merges

post /admin/duplicates/merge/batch
Creates a `DuplicateMergeBatch` row, then dispatches a single `ProcessMergeBatchJob` that processes every merge in the supplied `merges[]` array. Per-merge `field_choices` let the caller resolve conflicts surfaced by `previewMerge`. Unlike `mergeDonors`, this flow tracks original assignments so the batch can later be undone via `undoMergeBatch` and re-applied via `restoreMergeBatch`. Same handler is mounted at `/admin/duplicates/merge/batch` and `/admin/donors/duplicates/merge-batch`. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Re-apply a previously undone merge batch
Source: https://api-docs.helpyousponsor.com/api-reference/donors/re-apply-a-previously-undone-merge-batch

post /admin/duplicates/merge/batches/{batch_id}/restore
Reverses an `undone` merge batch in a single transaction: re-assigns donations / commitments / sponsorships / activity logs onto the primary donor, soft-deletes the secondary donors again, removes the duplicate-link rows, and flips the batch + operations back to `completed` (clearing `undone_at` / `undone_by`). The batch must currently be in `undone` status. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Reconcile a donor pending bank verification
Source: https://api-docs.helpyousponsor.com/api-reference/donors/reconcile-a-donor-pending-bank-verification

post /admin/donor-credit-card/{donor_id}/reconcile-bank-verification
Rechecks the donor original owned Stripe SetupIntents and chargeable US bank payment methods, finalizes a verified method and resumes pending checkout authorizations. Successful claimed handoffs can seed due anchors and QUEUE first due commitment charges, individually or batched; this is not merely a provider status lookup. Webhook/manual attempts share a guarded handoff claim. Individual provider errors are caught and reported within HTTP200 success with updated=false/message and remaining pending_count. Counts describe handoff completion, not settled donations. Requires permission: one of donors_manage.



# Remove a donor from a household
Source: https://api-docs.helpyousponsor.com/api-reference/donors/remove-a-donor-from-a-household

delete /admin/households/{household_id}/donors/{donor_id}
Detaches the member and preserves its donor record. Removing the primary requires a new_primary_contact_id from this household or a force key; the current controller checks force presence. Replacement must remain in the proposed member set. A missing confirmation returns 422 with requires_confirmation/is_primary_contact. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs.



# Remove a saved donor view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/remove-a-saved-donor-view

delete /admin/donor/view/{report_id}/{hysform_id}



# Remove reciprocal donor contact links
Source: https://api-docs.helpyousponsor.com/api-reference/donors/remove-reciprocal-donor-contact-links

delete /admin/donors/{donor_id}/relationships
Removes both directions of the pair within the organization. Returns success when no pair exists. Omitted/null related_contact does not remove a populated pair.



# Replace the duplicate-detection ruleset for a form
Source: https://api-docs.helpyousponsor.com/api-reference/donors/replace-the-duplicate-detection-ruleset-for-a-form

put /admin/donors/{hysform_id}/duplicates/rules
Persists a new ruleset for the donor form via `DuplicateRule::setRulesForForm` (records the editing user). Optional `threshold` (0–1 confidence floor) and `enabled` flag are written in a follow-up update on the same row when present. Returns the freshly-loaded rule. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Restore a single archived donor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/restore-a-single-archived-donor

get /admin/donor/activate
Restores one previously-archived donor (`Donor::restore()`), re-indexes them in Meilisearch, and refreshes the donor cache + Mailchimp sync. Cascading restoration of sponsorships/commitments is wired but disabled at the handler level (`with_commitments = false`); the input flag is currently ignored. Same handler is mounted at `/admin/donor/activate` (`v1/admin`) and the legacy `/admin/activate_donor`. Requires permission: `donors_manage` and is gated by the `disable_donor_restore` client restriction.



# Retry post-merge donor refresh work
Source: https://api-docs.helpyousponsor.com/api-reference/donors/retry-post-merge-donor-refresh-work

post /admin/duplicates/merge/batches/{batch_id}/retry-refresh
Queues an idempotent retry of donor totals and cache refreshes for committed merge operations whose ancillary refresh has not completed. Completed batches recalculate active primary donors and refresh the full donor cache set; undone batches recalculate all active primary and secondary donors. This never repeats donor merge mutations. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Review selected donor records for manual merge
Source: https://api-docs.helpyousponsor.com/api-reference/donors/review-selected-donor-records-for-manual-merge

post /admin/donors/duplicates/manual-review
Requires the manual merge rollout plus duplicates_manage or donors_manage and access to the donor form. Select two to twenty-five distinct active donors in the same form and one primary to keep. Creates a fifteen-minute actor-bound snapshot review with current profile conflicts, qualified lifetime giving and dependency blockers. Does not merge records. Locked relationship work returns 409 with Retry-After: 15.



# Save a donation worksheet definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-a-donation-worksheet-definition

post /admin/donationFilter/saved_filters
Creates or updates a raw saved view/report definition. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Donor/donation view validators discard unavailable columns/filter/footer keys; report definitions strictly validate field capabilities, operators, values and date presets. Existing reports stay reports. Initial report creation also creates an entitled schedule; later edits here preserve its schedule. Column identity/order are normalized for report updates. A schedule rejection can occur after the definition is saved.



# Save a donor worksheet definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-a-donor-worksheet-definition

post /admin/donors/saved_filters
Creates or updates a raw saved view/report definition. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Donor/donation view validators discard unavailable columns/filter/footer keys; report definitions strictly validate field capabilities, operators, values and date presets. Existing reports stay reports. Initial report creation also creates an entitled schedule; later edits here preserve its schedule. Column identity/order are normalized for report updates. A schedule rejection can occur after the definition is saved.



# Save a file worksheet definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-a-file-worksheet-definition

post /admin/files/saved_filters
Creates or updates a raw saved view/report definition. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Donor/donation view validators discard unavailable columns/filter/footer keys; report definitions strictly validate field capabilities, operators, values and date presets. Existing reports stay reports. Initial report creation also creates an entitled schedule; later edits here preserve its schedule. Column identity/order are normalized for report updates. A schedule rejection can occur after the definition is saved.



# Save a recipient or campaign worksheet definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-a-recipient-or-campaign-worksheet-definition

post /admin/entities/saved_filters
Creates or updates a raw saved view/report definition. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Donor/donation view validators discard unavailable columns/filter/footer keys; report definitions strictly validate field capabilities, operators, values and date presets. Existing reports stay reports. Initial report creation also creates an entitled schedule; later edits here preserve its schedule. Column identity/order are normalized for report updates. A schedule rejection can occur after the definition is saved.



# Save a sponsorship worksheet definition
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-a-sponsorship-worksheet-definition

post /admin/sponsorships/saved_filters
Creates or updates a raw saved view/report definition. The endpoint source must match module_id and the saved definition context/scope. Source view management or reports management plus context access is required. client_id is required for compatibility but always replaced by the authenticated organization. Donor/donation view validators discard unavailable columns/filter/footer keys; report definitions strictly validate field capabilities, operators, values and date presets. Existing reports stay reports. Initial report creation also creates an entitled schedule; later edits here preserve its schedule. Column identity/order are normalized for report updates. A schedule rejection can occur after the definition is saved.



# Save personal donation worksheet columns
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-personal-donation-worksheet-columns

put /admin/donations/{hysform_id}/column-preferences
Personal organization/user preferences are scoped to the form/program path context or all. Donation tab_scope selects a separate preference. Unavailable stored fields are removed; no effective preference returns exists=false with empty arrays. Select 1–100 available keys; aliases are normalized, duplicate keys removed, and omitted selected keys appended to the order. Unavailable selected keys fail validation. Sponsorship identity aliases and donation donor_name are returned in worksheet-local form.



# Save personal donor worksheet columns
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-personal-donor-worksheet-columns

put /admin/donors/{hysform_id}/column-preferences
Personal organization/user preferences are scoped to the form/program path context or all. Unavailable stored fields are removed; no effective preference returns exists=false with empty arrays. Select 1–100 available keys; aliases are normalized, duplicate keys removed, and omitted selected keys appended to the order. Unavailable selected keys fail validation. Sponsorship identity aliases and donation donor_name are returned in worksheet-local form.



# Save personal sponsorship worksheet columns
Source: https://api-docs.helpyousponsor.com/api-reference/donors/save-personal-sponsorship-worksheet-columns

put /admin/sponsorships/{program_id}/column-preferences
Personal organization/user preferences are scoped to the form/program path context or all. Unavailable stored fields are removed; no effective preference returns exists=false with empty arrays. Select 1–100 available keys; aliases are normalized, duplicate keys removed, and omitted selected keys appended to the order. Unavailable selected keys fail validation. Sponsorship identity aliases and donation donor_name are returned in worksheet-local form.



# Search donors by name (typeahead)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/search-donors-by-name-typeahead

get /admin/donors
Returns up to 10 donors matching the search query across the donor's indexed standard and custom fields, scoped to the authenticated client and permitted donor forms. Backed by Meilisearch (`Donor::search`) for fast typeahead lookups; empty `search` returns the top 10 by relevance for the empty token. Each result is enriched with resolved display-name, location, and donor-type context. Existing consumers receive the full donor rows; `projection=quick_actions` returns only compact display fields. Requires permission: `donors_view` (also satisfied by `donors_manage` or `donor-all`).



# Select a saved donor report
Source: https://api-docs.helpyousponsor.com/api-reference/donors/select-a-saved-donor-report

post /admin/donor/view/{report_id}/{hysform_id}
Loads a saved donor report into the administrator display preferences. The donor form must match the report; use `all` for a report saved for the all-donors view. Requires permission: `donors_manage`. The final trashed path segment may be omitted.



# Select a saved donor report for the archived view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/select-a-saved-donor-report-for-the-archived-view

post /admin/donor/view/{report_id}/{hysform_id}/{trashed}
Loads a saved donor report into the administrator display preferences. The donor form must match the report; use `all` for a report saved for the all-donors view. Requires permission: `donors_manage`. The final segment selects the archived-view response message.



# Send notification to donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/send-notification-to-donors

post /admin/donors/notify



# Send signup email to a donor
Source: https://api-docs.helpyousponsor.com/api-reference/donors/send-signup-email-to-a-donor

post /admin/donor/{commitment_id}/email



# Send year end statements to donors
Source: https://api-docs.helpyousponsor.com/api-reference/donors/send-year-end-statements-to-donors

post /admin/donors/send_year_end



# Set a donor primary external contact
Source: https://api-docs.helpyousponsor.com/api-reference/donors/set-a-donor-primary-external-contact

patch /admin/donors/{donor_id}/relationships/primary
Requires an existing forward link to the active related donor. Replaces any other primary link, stores the requested synchronization keys and immediately copies supported values from the related donor. Future source updates synchronize those keys. id/client_id and internal attributes are ignored, tags/household_relationship are skipped, and dn-prefixed keys address custom profile fields.



# Set a donor's default Stripe card
Source: https://api-docs.helpyousponsor.com/api-reference/donors/set-a-donors-default-stripe-card

post /admin/make_default_card/{donor_id}
Updates the donor's `default_source` on Stripe (when the active gateway is Stripe) and persists the chosen `card_id` to `donors.stripe_card_id`. The donor's `stripe_cust_id` is read from the `donors` row to address the Stripe customer. Requires permission: `donors_manage`.



# Set the default donor saved view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/set-the-default-donor-saved-view

put /admin/donors/default-saved-view
Preference belongs to the authenticated user and organization. Only active saved view/report definitions in a valid existing context are eligible; current context permission is checked. Campaign and recipient surfaces remain separate. Replaces this user’s default with an accessible definition, including legacy donor definitions. Returns 404 when the saved definition is unavailable.



# Set the default worksheet saved view
Source: https://api-docs.helpyousponsor.com/api-reference/donors/set-the-default-worksheet-saved-view

put /admin/saved-view-defaults/{module}
Module path accepts recipients, campaigns, sponsorships or donations. Preference belongs to the authenticated user and organization. Only active saved view/report definitions in a valid existing context are eligible; current context permission is checked. Campaign and recipient surfaces remain separate. Replaces this user’s default with an accessible definition, including legacy donor definitions. Returns 404 when the saved definition is unavailable.



# Set the organization primary donor profile
Source: https://api-docs.helpyousponsor.com/api-reference/donors/set-the-organization-primary-donor-profile

put /admin/forms/{hysform_id}/primary
Sets the organization’s primary donor HysForm. The profile must be active, organization-owned and type donor. Repeated selection retains that primary profile; unavailable profiles return 404.



# Stop using a related donor as primary contact
Source: https://api-docs.helpyousponsor.com/api-reference/donors/stop-using-a-related-donor-as-primary-contact

patch /admin/donors/{donor_id}/relationships/remove_primary
Clears is_primary and synchronization fields on the existing forward primary link. Values previously copied into the donor remain stored. Returns 422 when that contact is not the donor’s current primary external contact.



# Sync the donor's default Stripe source (or read it back)
Source: https://api-docs.helpyousponsor.com/api-reference/donors/sync-the-donors-default-stripe-source-or-read-it-back

post /admin/donor-credit-card-details/{donor_id}/{action}
Reconciles the donor's Stripe customer with the `donors.stripe_card_id` we have stored locally. When `action=update`, calls `Stripe::customers->update` to set `default_source` to the donor's stored card; for any other action value, reads the customer from Stripe instead. Returns 200 only when Stripe confirms `default_source` matches our stored card. The route is registered twice in `routes/v1/admin.php` with the same path/handler (legacy duplicate). Requires permission: `donors_manage`.



# Undo a completed merge batch
Source: https://api-docs.helpyousponsor.com/api-reference/donors/undo-a-completed-merge-batch

delete /admin/duplicates/merge/batches/{batch_id}
Reverses a `completed` merge batch in a single transaction: restores soft-deleted secondary donors, reassigns donations / commitments / sponsorships / activity logs back to their original donors using `original_donor_assignments`, recreates the duplicate-link rows, and marks the batch + operations as `undone`. The batch must have `can_be_undone=true`. Requires permission: `duplicates_manage` (also satisfied by `donors_manage`).



# Update a household member relationship
Source: https://api-docs.helpyousponsor.com/api-reference/donors/update-a-household-member-relationship

patch /admin/households/{household_id}/donors/{donor_id}
Requires donor_id in the body to match the path and an active member of this organization/household. Updates the member relationship; primary_relationship can separately change the household primary (or fallback primary) donor relationship. This endpoint preserves household membership and primary selection.



# Update donor credit card details
Source: https://api-docs.helpyousponsor.com/api-reference/donors/update-donor-credit-card-details

post /admin/donor-credit-card/{donor_id}



# Update donor profile fields inline
Source: https://api-docs.helpyousponsor.com/api-reference/donors/update-donor-profile-fields-inline

patch /donor/{id}/field
Updates one through eight allowlisted canonical/compatibility fields on an organization donor, including archived donors while retaining archive status. Resolved donor type rejects incompatible personal/organization identity. Legacy donor forms require full edit for address fields. Enforces email/username uniqueness, country/subdivision and preferred-contact rules; normalizes tags, geo labels and phone. Saves immediately, synchronizes configured primary-contact fields to related donors, records activity/notification and refreshes search. Does not accept profile_revision optimistic concurrency; response includes directly applied canonical fields rather than every derived/synchronized change. Requires permission: one of donors_manage.



# Update household and membership
Source: https://api-docs.helpyousponsor.com/api-reference/donors/update-household-and-membership

patch /admin/households/{household_id}
Applies supplied household properties. donor_ids replaces membership while omitted membership stays intact; primary changes can attach the new primary. Referenced donors are checked in the organization before mutation, and existing membership in another household is rejected. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs.



# Add a plain-text donor comment
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/add-a-plain-text-donor-comment

post /donors/{donor_id}/comments
Compatibility donor-comment interface backed by the collaboration thread. IDs can be positive legacy IDs or negative IDs for newer comments; zero is invalid. Requires current donor/thread access. Support sessions can read but cannot write. Requires contribution access and creates a collaboration plain-text document.



# Add an email privacy rule
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/add-an-email-privacy-rule

post /email-calendar/policies
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Account-scoped rules require mailbox ownership; omitting account_id creates a workspace rule and requires workspace manager plus confirmed true. Value is lowercased/trimmed; leading @ is removed for domains. A matching existing rule is reactivated; classification runs asynchronously.



# Approve my historical email import
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/approve-my-historical-email-import

post /email-calendar/accounts/{account_id}/approve-import
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Requires explicit confirmed acceptance after preview reaches awaiting_approval. Connection generation, policy/classifier versions and live sync authority must still match. Approval is mailbox-owner only; shared mailboxes are currently rejected. Queues promotion and returns approved with requires_workspace_admin_approval false.



# Change legacy email body visibility
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/change-legacy-email-body-visibility

patch /interactions/email/{activity_id}/visibility
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Only the connected account owner may change visibility. V2 bodies remain private to their owner and always reject this operation with409.



# Create a calendar event for a donor
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/create-a-calendar-event-for-a-donor

post /donors/{donor_id}/interactions/calendar/events
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Uses an owned connected calendar-enabled account; end_at must follow start_at. Writes the event to the provider and links it to the donor.



# Delete a donor comment
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/delete-a-donor-comment

delete /donors/{donor_id}/comments/{comment_id}
Compatibility donor-comment interface backed by the collaboration thread. IDs can be positive legacy IDs or negative IDs for newer comments; zero is invalid. Requires current donor/thread access. Support sessions can read but cannot write. Requires contribution access plus author or thread-management authority. Optional revision detects concurrent changes.



# Delete a manual interaction
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/delete-a-manual-interaction

delete /interactions/manual/{activity_id}
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Requires body access and all existing relationship access; acknowledgement-linked interactions may be protected from deletion. Related event invitation state is reconciled.



# Disconnect my email/calendar account
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/disconnect-my-emailcalendar-account

delete /email-calendar/accounts/{account_id}
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Optional delete_synced_data attempts cleanup after disconnect. Deletion failure does not undo disconnection: inspect delete_synced_data_failed and message; deleted_data holds cleanup counters when available.



# Edit my donor comment
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/edit-my-donor-comment

patch /donors/{donor_id}/comments/{comment_id}
Compatibility donor-comment interface backed by the collaboration thread. IDs can be positive legacy IDs or negative IDs for newer comments; zero is invalid. Requires current donor/thread access. Support sessions can read but cannot write. Only the author may edit. Optional revision detects concurrent changes and returns409 when stale.



# Link an email interaction to a donor
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/link-an-email-interaction-to-a-donor

patch /interactions/email/{activity_id}/link
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. V2 requires current donor visibility and ownership of an eligible ingress copy, then promotes that copy through the current policy. Legacy email sets its donor and linked match metadata.



# List a donor comments
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/list-a-donor-comments

get /donors/{donor_id}/comments
Compatibility donor-comment interface backed by the collaboration thread. IDs can be positive legacy IDs or negative IDs for newer comments; zero is invalid. Requires current donor/thread access. Support sessions can read but cannot write. Returns the newest100 comments and current edit/delete capabilities; ordinary reads reconcile legacy comments into the collaboration thread.



# List donor gifts eligible for acknowledgement
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/list-donor-gifts-eligible-for-acknowledgement

get /donors/{donor_id}/interactions/manual/acknowledgement-candidates
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Requires donation acknowledgement permission. Lists unacknowledged qualified payments excluding in-kind gifts, at or before occurred_at (clamped to the current minute). Cursor pagination; dates follow the resolved administrator timezone.



# List email privacy policy rules
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/list-email-privacy-policy-rules

get /email-calendar/policies
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Returns active rules plus removals still processing. Owners see rules for their accounts; workspace managers also see workspace rules.



# List legacy unmatched email interactions
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/list-legacy-unmatched-email-interactions

get /interactions/unmatched
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. This legacy queue is unavailable with404 when email intelligence v2 is enabled. Returns email rows with unreviewed, no_match or ambiguous match status.



# List my connected email/calendar accounts
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/list-my-connected-emailcalendar-accounts

get /email-calendar/accounts
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Workspace managers additionally receive other active owners alias-only records, without their private sync/preview/body controls. Returns current provider drivers, defaults and workspace capabilities.



# List my private email review queue
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/list-my-private-email-review-queue

get /email-calendar/review
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Only approved/complete mailbox preview generations are eligible. Without classification, lists review disposition; a classification filter matches that class instead. Rows never include full body text.



# List permission groups for shared interactions
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/list-permission-groups-for-shared-interactions

get /interactions/manual/shared-visibility-options
Returns organization permission-group IDs/names and the current user group ID for choosing a shared body audience.



# Log a donor manual interaction
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/log-a-donor-manual-interaction

post /donors/{donor_id}/interactions/manual
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. type, occurred_at and a nonblank subject are required. A body idempotency_key or fallback Idempotency-Key header reuses the interaction without replaying acknowledgement mutations. Donation acknowledgement needs donations/full-organization permission; selected gifts must qualify and occur no later than the interaction. Attachments use multipart form data.



# Preview donor email merge text
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/preview-donor-email-merge-text

post /donors/{donor_id}/email-compose/preview
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Renders donor merge fields in subject/body without sending.



# Preview email retention changes
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/preview-email-retention-changes

post /email-calendar/settings/impact
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Requires workspace manager authority. In intelligence v2, matching_mode accepts only existing_records_only and auto_create_donors is forced false. Metadata sharing needs an explicit confirm_metadata_sharing attestation. Disabling bodies or shortening retention can remove retained content: preview returns a fifteen-minute actor/settings/count-bound token, then save must supply that token and confirmed_retention_impact true. Changing the proposal or concurrent settings invalidates confirmation.



# Preview historical mailbox import
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/preview-historical-mailbox-import

post /email-calendar/accounts/{account_id}/preview
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Owned individual accounts must be connected, email-sync enabled and in not_previewed or awaiting_approval state. Starts a fresh preview generation and queues scanning;202 is an acknowledgement, not a finished preview.



# Preview the effect of an email privacy rule
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/preview-the-effect-of-an-email-privacy-rule

post /email-calendar/policies/preview
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Uses the same account-owner/workspace-manager boundary as saving a rule. Returns current counts of eligible emails newly hidden by the proposal; preview is advisory and does not grant write authority.



# Promote or exclude an owned email candidate
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/promote-or-exclude-an-owned-email-candidate

patch /email-calendar/review/{ingress_id}
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Promote requires donor_id, interactions_manage and access to that donor form. Current policy and account state are checked before promotion. Exclude records the owner decision. Neither action changes mailbox ownership or body sharing.



# Queue a validated manual-interaction import
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/queue-a-validated-manual-interaction-import

post /interactions/manual/imports/{import_id}/process
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Also requires manual_interactions_import. Validate at least one valid or skipped duplicate row first. Production queues processing; local/sync environments may process immediately. Receipt status and counts describe the current job state rather than guaranteeing completion.



# Read a donor unified interaction timeline
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-a-donor-unified-interaction-timeline

get /donors/{donor_id}/interactions
Requires current donor visibility. Email/calendar and manual sections are enabled independently by their flags; imported CRM relationship activities remain available. Legacy and connected-source email rows retain metadata under their current body policy. Legacy local_body/snippet can be null and can_view_body false when current mailbox, program or owner access does not permit reading the body. Authorized message-center legacy rows can resolve the original message body even after it was scrubbed from the activity log. Returns up to ten upcoming calendar events plus recent events, at most 25 combined. Email filters do not filter the separate manual/CRM pagination.



# Read a manual interaction body
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-a-manual-interaction-body

get /interactions/manual/{activity_id}/body
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Returns body_plain only after current body-visibility authorization.



# Read accessible interaction relationships
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-accessible-interaction-relationships

get /interactions/manual/{activity_id}/relationships
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Returns the visible event, donor participants and related task summaries.



# Read an owned email review item
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-an-owned-email-review-item

get /email-calendar/review/{ingress_id}
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Returns subject/participant metadata, current classification and body-fetch state; full body retrieval uses the separate body operation.



# Read donor email compose options
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-donor-email-compose-options

get /donors/{donor_id}/email-compose-context
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Returns owned writable Google/Microsoft accounts and whether the donor can be emailed under suppression, communication preferences and intelligence recording policy.



# Read or fetch a private email body
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-or-fetch-a-private-email-body

get /interactions/email/{activity_id}/body
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. For v2 the caller must own the selected donor-specific ingress copy and see the donor; unowned/missing copies are concealed with404. Workspace body policy may forbid retrieval; expired retained content returns410.202 queues fetching;200 returns available body fields. donor_id selects the relevant promoted relationship.



# Read or queue a retained private review body
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-or-queue-a-retained-private-review-body

post /email-calendar/review/{ingress_id}/body
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. 200 returns available plain/html text and purge deadline. Otherwise202 returns status fetching. Workspace disabled-body policy forbids retrieval; retention-purged content returns410 and must be opened in the original mailbox.



# Read workspace email ingestion health
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-workspace-email-ingestion-health

get /email-calendar/health
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Requires workspace manager authority. Returns account-state and ingress-status counts without exposing another owner private email content.



# Read workspace email/calendar settings
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/read-workspace-emailcalendar-settings

get /email-calendar/settings
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Creates default settings if none exist.



# Reconnect my email/calendar account
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/reconnect-my-emailcalendar-account

post /email-calendar/accounts/{account_id}/reconnect
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Returns an authorization URL with state lifetime and optional redirect URI for the selected available driver. Managed provider-start failures return502 with a reason.



# Remove an email privacy policy rule
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/remove-an-email-privacy-policy-rule

delete /email-calendar/policies/{policy_id}
Requires email/calendar availability and the email intelligence v2 workspace rollout. Review and body operations are private to the current mailbox owner and current preview generation under the active privacy policy. Requires mailbox ownership for account rules or workspace manager for workspace rules. Revokes the rule and queues review holds for newly eligible content; repeating while removal is pending schedules reconciliation again.



# Return an email donor relationship to review
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/return-an-email-donor-relationship-to-review

patch /interactions/email/{activity_id}/unlink
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. For v2 choose donor_id or use its primary donor: only an owned eligible metadata copy can be returned to review and the response is moved_to_review plus ingress_id. Legacy emails clear their donor match and return the updated activity.



# Save workspace email/calendar settings
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/save-workspace-emailcalendar-settings

put /email-calendar/settings
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Requires workspace manager authority. In intelligence v2, matching_mode accepts only existing_records_only and auto_create_donors is forced false. Metadata sharing needs an explicit confirm_metadata_sharing attestation. Disabling bodies or shortening retention can remove retained content: preview returns a fifteen-minute actor/settings/count-bound token, then save must supply that token and confirmed_retention_impact true. Changing the proposal or concurrent settings invalidates confirmation.



# Send donor email through my connected account
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/send-donor-email-through-my-connected-account

post /donors/{donor_id}/email-compose/send
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Requires an owned connected/sync-enabled email account, donor email and allowed message preferences. account_id may select it; otherwise the first writable account is used.201 returns the recorded email.202 means the provider accepted the send but recording donor history remains pending; avoid blindly resending.



# Send donor email through my connected account
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/send-donor-email-through-my-connected-account-1

post /donors/{donor_id}/interactions/email/send
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Requires an owned connected/sync-enabled email account, donor email and allowed message preferences. account_id may select it; otherwise the first writable account is used.201 returns the recorded email.202 means the provider accepted the send but recording donor history remains pending; avoid blindly resending.



# Start a new email/calendar connection
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/start-a-new-emailcalendar-connection

post /email-calendar/accounts/{provider}/connect
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Returns an authorization URL with state lifetime and optional redirect URI for the selected available driver. Managed provider-start failures return502 with a reason.



# Suggest a summary for a manual interaction
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/suggest-a-summary-for-a-manual-interaction

post /interactions/manual/summarize
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Also requires manual_interactions_ai_summary. Uses note/body/title text without saving an interaction. Empty text returns empty_source; unavailable AI returns a local fallback summary with ai_unavailable true.



# Update a Gratona-created calendar event
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/update-a-gratona-created-calendar-event

patch /email-calendar/events/{event_id}
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Only the connected owner can update an event created from Gratona. Submitted end/start values must remain ordered; provider write failures return422.



# Update a manual interaction
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/update-a-manual-interaction

patch /interactions/manual/{activity_id}
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Partial update retains omitted fields; resulting subject must stay nonblank. The body owner/visibility gate applies before mutation. Existing acknowledged gifts constrain occurrence-date changes. New/removal attachments must leave no more than ten files.



# Update connected account settings or aliases
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/update-connected-account-settings-or-aliases

patch /email-calendar/accounts/{account_id}
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Only the owner may change sync/body settings. An explicit workspace manager may edit aliases on another account; that request can contain only aliases_json and aliases_confirmed. Any alias update requires explicit manager authority and aliases_confirmed true. Aliases are normalized/deduplicated; identity/source changes queue reclassification in v2.



# Upload a manual-interaction CSV
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/upload-a-manual-interaction-csv

post /interactions/manual/imports
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Also requires manual_interactions_import. Accepts CSV/TXT up to10MiB and previews headers/first row and mappable fields. Shared storage must be configured when production processing is asynchronous.



# Validate a manual-interaction import mapping
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/validate-a-manual-interaction-import-mapping

post /interactions/manual/imports/{import_id}/validate
Requires manual_interactions and current interaction/record authority. Body visibility can restrict read/edit/delete even when timeline metadata is visible. Shared visibility requires a valid organization shared_group_id. Event invitation participants and related tasks require access and current version boundaries. Also requires manual_interactions_import. Donors must resolve by ID/email; ID disambiguates duplicate email matches. Required type/occurred_at mappings and valid row content determine readiness. Historical backfill defaults source_system to generic_csv, duplicate mode to skip and disables AI summary/title generation.



# Verify a managed connection callback identity
Source: https://api-docs.helpyousponsor.com/api-reference/email-calendar/verify-a-managed-connection-callback-identity

post /email-calendar/composio/complete-auth
Requires email/calendar deployment availability and the route permissions. Connected account operations use the authenticated tenant and mailbox owner; body/metadata sharing remains separately authorized. Consumes the managed connection session URI and returns the verified callback URL for completing this user connection.



# Get email settings
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/get-email-settings

get /admin/email/settings



# Get export completion email preference
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/get-export-completion-email-preference

get /admin/export-email-settings
Returns the current organization’s manual export completion email preference, defaulting to true when no explicit preference is stored. Requires permission: one of manage_email.



# Get legacy delivery-log configuration
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/get-legacy-delivery-log-configuration

get /admin/mailgun_logs
Returns the current organization, its raw email-setting record and the selected Mailgun log source. Requires organization Mailgun credentials or configured platform delivery and a sender address. The authenticated response can contain saved credential fields; treat the payload as confidential. Requires permission: one of email_manager, manage_email.



# Get sender email delivery health
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/get-sender-email-delivery-health

get /admin/email/settings/delivery-health
Returns sender identity and projected transport health for the current organization, or emailsettings:null when no settings row exists. Stored health from another transport becomes unknown. Incomplete custom SMTP activates fallback; responsibility and action_required indicate who can resolve it. Requires permission: one of manage_email.



# Get the first sender delivery log page
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/get-the-first-sender-delivery-log-page

get /admin/mailgun_logs_data
Returns up to five normalized Mailgun analytics events using organization credentials, or platform credentials filtered by the configured sender address. Looks back30 days with a provider-retention fallback. Missing configuration returns HTTP200 with a message. The response repeats items/data and total_count/total for older clients. Requires permission: one of email_manager, manage_email.



# Page through sender delivery logs
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/page-through-sender-delivery-logs

post /admin/mailgun_logs_data
Retrieves the requested one-based analytics page by following provider tokens. pageIndex is clamped1–20 and pageSize1–10. Uses organization credentials or sender-filtered platform credentials and provider retention limits. Missing configuration returns HTTP200 with a message. Requires permission: one of email_manager, manage_email.



# Post email settings
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/post-email-settings

post /admin/email/settings



# Read legacy Mailgun event results
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/read-legacy-mailgun-event-results

get /admin/mailgun_logs/{message_id}
Fetches the configured organization Mailgun domain’s legacy events response. The message_id path segment is currently not applied as a filter: the handler returns the full provider payload immediately. Empty upstream content returns data as an empty array. Prefer the normalized delivery-log endpoints for the current UI contract. Requires permission: one of email_manager, manage_email.



# Save and verify email transport settings
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/save-and-verify-email-transport-settings

post /integrations/mailgun
Builds candidate email delivery settings, sends a real verification email to from_address and saves only after successful delivery and a concurrent-change check. Custom SMTP host, login and password must be complete together. Omitted settings preserve saved values; clear_mailgun removes the custom transport. Provider verification failures include EMAIL_DELIVERY_VERIFICATION_FAILED, attempted_transport and responsibility. Requires permission: one of manage_email, access_account_settings.



# Update export completion email preference
Source: https://api-docs.helpyousponsor.com/api-reference/email-settings/update-export-completion-email-preference

put /admin/export-email-settings
Saves whether manually requested exports send completion emails and records an activity entry when the preference changes. This does not alter scheduled or other transactional email delivery. Requires permission: one of manage_email.



# Activate Entity
Source: https://api-docs.helpyousponsor.com/api-reference/entities/activate-entity

get /admin/entity/{entity_id}/activate
Handles the activation (restoration) of an archived entity based on the provided entity ID.



# Activate Multiple Entities
Source: https://api-docs.helpyousponsor.com/api-reference/entities/activate-multiple-entities

post /admin/entities/{program_id}/activate
Handles the activation (restoration) of multiple archived entities within a specific program.



# Add New Entity
Source: https://api-docs.helpyousponsor.com/api-reference/entities/add-new-entity

post /admin/entity/{program_id}
Posts data to add a new entity based on the provided program ID.



# Archive Entities
Source: https://api-docs.helpyousponsor.com/api-reference/entities/archive-entities

delete /admin/entities/{program_id}
Handles the removal (archival) of one or multiple entities,
     *          including archival of sponsorships, removal of commitments, and updates to the cache.



# Archive Entity
Source: https://api-docs.helpyousponsor.com/api-reference/entities/archive-entity

delete /admin/entity/{entity_id}
Handles the removal (archival) of an entity based on the provided entity ID.



# Download a finished recipient export
Source: https://api-docs.helpyousponsor.com/api-reference/entities/download-a-finished-recipient-export

get /admin/entities/exports/{uploadId}
Resolves the export's S3 link. Default behavior issues an HTTP 302 redirect to a short-lived presigned URL, suitable for `<a download>` links. When called with `?resolve=1`, returns the URL as JSON instead so SPA code can handle the download itself. The upload must belong to the caller's client. Requires permission: `manage_programs`.



# Edit a recipient
Source: https://api-docs.helpyousponsor.com/api-reference/entities/edit-a-recipient

patch /admin/program/entity
Updates a recipient in the authenticated organization and preserves its archived state. Send configured recipient-form fields as top-level properties. Set `partial_update` to true to preserve omitted profile values and existing sponsorship relationships; full profile submissions replace the custom profile. Requires permission: `manage_programs`.



# Entity table headers
Source: https://api-docs.helpyousponsor.com/api-reference/entities/entity-table-headers

get /admin/entities/{program_id}/headers/{trashed}



# Generate Entity Status Report
Source: https://api-docs.helpyousponsor.com/api-reference/entities/generate-entity-status-report

get /admin/entities/{program_id}/status-report
Generates a report of entities based on their status for a given time period



# Get Detailed Field Options
Source: https://api-docs.helpyousponsor.com/api-reference/entities/get-detailed-field-options

get /admin/fields/options/{program_id}/{type}
Retrieves detailed field options for a specific program and type,
     *          including program information, fields, reports, and details.



# Get program recipient form
Source: https://api-docs.helpyousponsor.com/api-reference/entities/get-program-recipient-form

get /admin/entity/{program_id}
Gets the program recipient form based on the provided program ID and client information.



# Get Program Statistics
Source: https://api-docs.helpyousponsor.com/api-reference/entities/get-program-statistics

get /admin/program/{program_id}/statistics
Retrieves statistical data for a specific program based on the provided program ID.



# List all entities for a program (legacy unpaginated)
Source: https://api-docs.helpyousponsor.com/api-reference/entities/list-all-entities-for-a-program-legacy-unpaginated

post /admin/show_all_entities
Returns every entity for the given program via `Entity::getEntities()`. Pre-dates the paginated `showAllEntitiesAjax` listing — kept for legacy admin UIs and CSV-style exports that need the full set in one shot. When the underlying `getEntities()` call signals an error in its return shape, the handler returns that error verbatim. Requires permission: `manage_programs`.



# List recipient-export jobs currently queued or processing
Source: https://api-docs.helpyousponsor.com/api-reference/entities/list-recipient-export-jobs-currently-queued-or-processing

get /admin/entities/exports/active
Returns up to 10 recipient-export `Upload` rows from the last 24 hours whose status is `queued` or `processing`. Powers the `Active exports` indicator in the admin UI so users can resume polling without losing the upload id. Each row is enriched with `PdfRenderService::queuedUploadStatus`. Requires permission: `manage_programs`.



# Look up entities by their unique-field value within a program
Source: https://api-docs.helpyousponsor.com/api-reference/entities/look-up-entities-by-their-unique-field-value-within-a-program

get /admin/get-entity/{program_id}
Resolves the program's recipient form, finds the field flagged `is_unique=1`, and returns every entity in the program whose `json_fields[<unique_field>]` matches the supplied `search` value. Used by import workflows to detect existing recipients before creating duplicates. Returns 400 when the recipient form has no unique field. Validation: `program_id required`, `search required`. Requires permission: `manage_programs`.



# Move and entity to a different program
Source: https://api-docs.helpyousponsor.com/api-reference/entities/move-and-entity-to-a-different-program

post /admin/move/{entity_id}
Handles the process of moving an entity to a different program,
     *          including updating entity records and clearing relevant caches.



# Move Multiple Entities
Source: https://api-docs.helpyousponsor.com/api-reference/entities/move-multiple-entities

put /admin/entities/move
Handles the process of moving multiple entities to a different program,
     *          including updating entity records and clearing relevant caches.



# Permanently delete an entity
Source: https://api-docs.helpyousponsor.com/api-reference/entities/permanently-delete-an-entity

delete /admin/entity/{entity_id}/delete



# Permanently delete entities
Source: https://api-docs.helpyousponsor.com/api-reference/entities/permanently-delete-entities

delete /admin/entities/{program_id}/delete



# Poll a single recipient export
Source: https://api-docs.helpyousponsor.com/api-reference/entities/poll-a-single-recipient-export

get /admin/entities/exports/{uploadId}/status
Returns the current state of one recipient-export `Upload` (scoped to the caller's client, 404 otherwise). Mirrors a row of `activeEntityExports` but works for any status — including `completed` so the UI can flip to a download button. Requires permission: `manage_programs`.



# Post Edit Multiple Entities
Source: https://api-docs.helpyousponsor.com/api-reference/entities/post-edit-multiple-entities

patch /admin/program/entities
Handles the submission of edited data for multiple entities,
     *          including updating various fields and maintaining archival status if applicable.



# Post Field Options
Source: https://api-docs.helpyousponsor.com/api-reference/entities/post-field-options

post /admin/fields/options/{program_id}/{type}
Saves field options for a specific program, and optionally, a specific type.
     *          This includes saving preferences in Redis and handling report saving.



# Queue a CSV export of recipients (async)
Source: https://api-docs.helpyousponsor.com/api-reference/entities/queue-a-csv-export-of-recipients-async

get /admin/entities/{program_id}/export
Reserves an `Upload` row to back the export, marks it `queued`, then dispatches `GenerateEntityExportJob`. Returns 200 immediately with the upload id and a `status_url` to poll. The program must belong to the caller's client (404 otherwise). Any extra body parameters (filters, column overrides) are forwarded to the job verbatim. Requires permission: `manage_programs`.



# Remove a saved report
Source: https://api-docs.helpyousponsor.com/api-reference/entities/remove-a-saved-report

delete /admin/view/{report_id}/{program_id}



# Select a saved program report
Source: https://api-docs.helpyousponsor.com/api-reference/entities/select-a-saved-program-report

get /admin/programs/view/{report_id}/{program_id}
Loads a saved recipient or sponsorship report into the administrator display preferences and clears the program table cache. Selecting a sponsorship report also makes it the default sponsorship report. A specific program is required. The final trashed path segment may be omitted.



# Select a saved program report for the archived view
Source: https://api-docs.helpyousponsor.com/api-reference/entities/select-a-saved-program-report-for-the-archived-view

get /admin/programs/view/{report_id}/{program_id}/{trashed}
Loads a saved recipient or sponsorship report into the administrator display preferences and clears the program table cache. Selecting a sponsorship report also makes it the default sponsorship report. A specific program is required. The optional final route segment is accepted for compatibility; it does not change report selection.



# Show All Entities for a specific program
Source: https://api-docs.helpyousponsor.com/api-reference/entities/show-all-entities-for-a-specific-program

get /admin/entities/{program_id}
Shows all entities for a given program ID,
     *          with various filtering, sorting, and pagination options.



# View compatible programs when moving entities
Source: https://api-docs.helpyousponsor.com/api-reference/entities/view-compatible-programs-when-moving-entities

get /admin/move/{entity_id}/compatible_programs
Moves an entity to a different program,
     *          retrieves necessary details for the move operation including compatible programs,
     *          entity details, and more.



# View Entity Details
Source: https://api-docs.helpyousponsor.com/api-reference/entities/view-entity-details

get /admin/program/entities/{id}
Retrieves details of an entity for editing,
     *          including its profile, fields, sponsors, donations, and more.



# Add a donor to an event invite list
Source: https://api-docs.helpyousponsor.com/api-reference/events/add-a-donor-to-an-event-invite-list

post /admin/events/{eventId}/invitees
Adds an accessible donor once per event. Existing active rows return already_active; removed rows reactivate, retaining prior owner unless a new one is supplied. Idempotent replay retains the original response status; reusing a key with different choices returns 409. Requires event setup management; archived event invitation history is read-only (409).



# Add a hosted-table guest
Source: https://api-docs.helpyousponsor.com/api-reference/events/add-a-hosted-table-guest

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/tables/{tableId}/host/{sessionId}/guests
Requires the donor portal session in the path and that donor must be the table host. Event management stays available for completed/unpublished events unless the event is unavailable. Adds a standalone registered attendee without an order or donor identity. Capacity counts all non-cancelled table guests. Seat labels may be recorded for the host guest.



# Add an event person
Source: https://api-docs.helpyousponsor.com/api-reference/events/add-an-event-person

post /admin/events/{eventId}/people
Adds one accessible donor or staff member with a role. Exactly one donor_id/user_id is required, and duplicate identity/role combinations are rejected. Requires the event management capability; all referenced records must belong to this event and organization.



# Archive an event
Source: https://api-docs.helpyousponsor.com/api-reference/events/archive-an-event

post /admin/events/{id}/archive
Sets archived status and records event activity. Requires the event management capability; all referenced records must belong to this event and organization.



# Archive event setup
Source: https://api-docs.helpyousponsor.com/api-reference/events/archive-event-setup

post /admin/events/{eventId}/setup/{setup}/{id}/archive
Archives setup, disables its operational state, and removes affected scope references. Activity dependencies are preserved. Requires grouped event registration features. Requires the event management capability; all referenced records must belong to this event and organization.



# Archive event setup
Source: https://api-docs.helpyousponsor.com/api-reference/events/archive-event-setup-1

post /admin/events/{eventId}/sponsor-packages/{id}/archive
Archives setup, disables its operational state, and removes affected scope references. Activity dependencies are preserved. Requires grouped event registration features. Requires the event management capability; all referenced records must belong to this event and organization.



# Assign or clear an event attendee seat
Source: https://api-docs.helpyousponsor.com/api-reference/events/assign-or-clear-an-event-attendee-seat

put /admin/events/{eventId}/attendees/{attendeeId}/seat
Updates the table and optional seat label, replacing the previous seat assignment. Omitting/nulling the table clears it. An occupied seat label is rejected within the selected table. Requires events_manage.



# Assign owners to selected event invitees
Source: https://api-docs.helpyousponsor.com/api-reference/events/assign-owners-to-selected-event-invitees

patch /admin/events/{eventId}/invitees/bulk-owner
Updates up to 100 distinct active invitees atomically. Every row must be accessible and its version current; any failure rolls back all owner changes. Owner null unassigns. Requires event setup management; archived event invitation history is read-only (409).



# Award an active event auction bid
Source: https://api-docs.helpyousponsor.com/api-reference/events/award-an-active-event-auction-bid

post /admin/events/{eventId}/auction-bids/{bidId}/award
Marks a placed, winning or already-won bid as won, stores the award time/user and creates a checkout token if needed. Other active bids for the item become outbid. Requires events_manage.



# Cancel a hosted-table guest
Source: https://api-docs.helpyousponsor.com/api-reference/events/cancel-a-hosted-table-guest

delete /frontend/public/events/{clientSlugOrId}/{eventSlug}/tables/{tableId}/host/{sessionId}/guests/{attendeeId}
Requires the donor portal session in the path and that donor must be the table host. Event management stays available for completed/unpublished events unless the event is unavailable. Cancels only a host-console guest, retaining its audit metadata and releasing any assigned seat. Ticket-order guests must be managed through their order.



# Cancel a waitlist signup
Source: https://api-docs.helpyousponsor.com/api-reference/events/cancel-a-waitlist-signup

delete /frontend/public/events/{clientSlugOrId}/{eventSlug}/waitlist/{token}
Cancels a waiting/offered signup, releases held inventory and attempts to offer the next signup. Cancelled/expired entries are replayed; a signup already converted to an order cannot be cancelled here.



# Cancel an event auction bid
Source: https://api-docs.helpyousponsor.com/api-reference/events/cancel-an-event-auction-bid

post /admin/events/{eventId}/auction-bids/{bidId}/cancel
Sets bid status cancelled and stores cancellation time/user; repeated cancellation preserves its state. Returns the bid with item, order and donor relations. Requires events_manage.



# Cancel or record a refund for event registration
Source: https://api-docs.helpyousponsor.com/api-reference/events/cancel-or-record-a-refund-for-event-registration

post /admin/events/{eventId}/orders/{orderId}/cancel
Cancels registration/groups/attendees/sponsors, releases seats and inventory, updates receipt and recorded donation refund state, and queues lifecycle follow-up. This endpoint records a refund; it does not submit a provider refund. refund_amount defaults to the total and is clamped to 0–total. Repeated cancellation/refund returns the existing state. Unresolved saved-method charges must be reconciled first. A bank payment awaiting settlement cannot be manually completed or cancelled.



# Charge an explicitly authorized saved event card
Source: https://api-docs.helpyousponsor.com/api-reference/events/charge-an-explicitly-authorized-saved-event-card

post /admin/events/{eventId}/orders/{orderId}/charge-saved-payment-method
Attempts an off-session Stripe card charge for a pending positive order after recording the donor authorization. The donor must match the purchaser, the reference must remain eligible, and reviewed amount must match. Confirmed success completes the order; failure leaves it pending. An indeterminate or concurrent result returns 409 and requires reconciliation. Retry the same authorization key and method; a new key cannot bypass an unresolved attempt.



# Check in a complete event order
Source: https://api-docs.helpyousponsor.com/api-reference/events/check-in-a-complete-event-order

post /admin/events/{eventId}/check-ins/group
Checks in every attendee on the selected order in one transaction. An ineligible attendee rejects the group transaction; repeat admissions produce duplicate logs. Order lifecycle, configured blocked payment statuses and registration-group completeness are checked before admission. Processing payments are also ineligible. Requires events_checkin or events_manage. Check-in mode must be enabled on the event.



# Check in an attendee manually
Source: https://api-docs.helpyousponsor.com/api-reference/events/check-in-an-attendee-manually

post /admin/events/{eventId}/check-ins/manual
Checks in the selected attendee and creates a manual or duplicate log. Order lifecycle, configured blocked payment statuses and registration-group completeness are checked before admission. Processing payments are also ineligible. Requires events_checkin or events_manage. Check-in mode must be enabled on the event.



# Check in an event QR ticket
Source: https://api-docs.helpyousponsor.com/api-reference/events/check-in-an-event-qr-ticket

post /admin/events/{eventId}/check-ins/scan
Resolves a ticket only within this event and creates a check-in or duplicate log. Order lifecycle, configured blocked payment statuses and registration-group completeness are checked before admission. Processing payments are also ineligible. Requires events_checkin or events_manage. Check-in mode must be enabled on the event.



# Complete a staff event payment
Source: https://api-docs.helpyousponsor.com/api-reference/events/complete-a-staff-event-payment

post /admin/events/{eventId}/orders/{orderId}/complete-payment
Marks a pending registration completed using supplied or retained payment references; this staff endpoint does not itself verify or charge a processor. Free totals become free; cash/check/offline become offline, other positive totals become paid. Repeats of paid/free/offline are idempotent. Expired reservations return 409. Unresolved saved-method charges must be reconciled first. A bank payment awaiting settlement cannot be manually completed or cancelled.



# Create a staff event registration
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-a-staff-event-registration

post /admin/events/{eventId}/orders
Requires event registration permission. Creates a legacy registration using event ticket prices, donor access rules and capacity. Select at least a ticket, package, auction item or positive donation. Existing retry key returns its order. Staff defaults create_donor and send_confirmation to false. Closed RSVPs require registration_override_confirmed. Pending payments remain pending until completed or charged; this endpoint does not start browser checkout.



# Create an event
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event

post /admin/events
Creates a draft by default, resolves a unique slug and organization timezone, normalizes event dates to UTC and applies an optional starter preset. Historical templates are archived with public registration and messaging disabled. Requires the event management capability; all referenced records must belong to this event and organization.



# Create an event auction item
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-auction-item

post /admin/events/{eventId}/auction-items
Configures bidding prices, stock, visibility and auction status. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Create an event communication
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-communication

post /admin/events/{eventId}/communications
Saves a communication template with normalized shortcodes, notification preferences and Message Manager approval metadata. Scheduled messages are later handled by the queue; only email is automatically delivered. Communications hold blocks scheduling. Relative schedules require a dated event and resolve in its timezone. The structured schedule must match legacy send_at when both are supplied. Requires events_manage.



# Create an event preview link
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-preview-link

post /admin/events/{eventId}/preview-links
Issues a read-only preview capability. Expiry defaults to 168 hours; explicit null means no expiry. The returned URL stores its secret in a fragment rather than a query parameter.



# Create an event promo code
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-promo-code

post /admin/events/{eventId}/promo-codes
Codes are normalized to uppercase and percentages cannot exceed 100. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Create an event question
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-question

post /admin/events/{eventId}/questions
A reused field_key updates an existing active question or restores an unused archived question; an archived question with saved answers returns 409. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Create an event settings profile
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-settings-profile

post /admin/events/settings
Creates reusable event defaults with program_type events. Nonpositive donation ask amounts are removed; defaults apply to omitted settings. Requires the event management capability; all referenced records must belong to this event and organization.



# Create an event sponsor package
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-sponsor-package

post /admin/events/{eventId}/sponsor-packages
Configures benefits, included tickets/tables and optional deliverable definitions. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Create an event table
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-table

post /admin/events/{eventId}/tables
Configures seating capacity and an optional existing donor host. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Create an event ticket type
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-an-event-ticket-type

post /admin/events/{eventId}/ticket-types
Dates use the event timezone. Maximum per order must be at least the effective minimum. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Create or rotate an event invitation link
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-or-rotate-an-event-invitation-link

post /admin/events/{eventId}/invitation-links
Available only for invite-only events. An optional donor binding must be accessible to the caller. Binding an active invitee requires its current version, revokes older links for that invitee and increments its version. Lifetime defaults to 720 hours; null means no expiry.



# Create public event registration
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-public-event-registration

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/orders
Creates a registration and starts a processor handoff when money remains due. V2 requires a current quote and stable retry key, validates all group slots/required questions and reserves inventory for the event reservation window (5–60 minutes, default 15). Legacy retries return the order for the same key; V2 rejects a changed cart. Free/approved check orders complete immediately. Public donor identity fields follow event form context; event settings suppress disabled giving asks.



# Create reviewed invitation staff tasks
Source: https://api-docs.helpyousponsor.com/api-reference/events/create-reviewed-invitation-staff-tasks

post /admin/events/{eventId}/invitees/{inviteeId}/plans
Applies the reviewed saved plan using current invitee version, plan revision and hash. Creates canonical donor/event-linked staff tasks only for steps without existing mappings; accepted definition/dates are snapshotted. Does not contact invitees. Requires an event start and accessible active invitee. Requires event setup management; archived event invitation history is read-only (409). Also requires task management permission.



# Delete an event
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-event

delete /admin/events/{id}
Soft-deletes the event. Requires the event management capability; all referenced records must belong to this event and organization.



# Delete an unused event auction item
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-unused-event-auction-item

delete /admin/events/{eventId}/auction-items/{id}
Permanently deletes only a record without direct activity dependencies and removes references from related setup. Used setup must be archived instead. Requires the event management capability; all referenced records must belong to this event and organization.



# Delete an unused event communication
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-unused-event-communication

delete /admin/events/{eventId}/communications/{id}
Permanently deletes only communication setup without a recorded delivery timestamp. Used communication records return a setup-in-use conflict and must be archived. Requires events_manage.



# Delete an unused event promo code
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-unused-event-promo-code

delete /admin/events/{eventId}/promo-codes/{id}
Permanently deletes only a record without direct activity dependencies and removes references from related setup. Used setup must be archived instead. Requires the event management capability; all referenced records must belong to this event and organization.



# Delete an unused event question
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-unused-event-question

delete /admin/events/{eventId}/questions/{id}
Permanently deletes only a record without direct activity dependencies and removes references from related setup. Used setup must be archived instead. Requires the event management capability; all referenced records must belong to this event and organization.



# Delete an unused event sponsor package
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-unused-event-sponsor-package

delete /admin/events/{eventId}/sponsor-packages/{id}
Permanently deletes only a record without direct activity dependencies and removes references from related setup. Used setup must be archived instead. Requires the event management capability; all referenced records must belong to this event and organization.



# Delete an unused event table
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-unused-event-table

delete /admin/events/{eventId}/tables/{id}
Permanently deletes only a record without direct activity dependencies and removes references from related setup. Used setup must be archived instead. Requires the event management capability; all referenced records must belong to this event and organization.



# Delete an unused event ticket type
Source: https://api-docs.helpyousponsor.com/api-reference/events/delete-an-unused-event-ticket-type

delete /admin/events/{eventId}/ticket-types/{id}
Permanently deletes only a record without direct activity dependencies and removes references from related setup. Used setup must be archived instead. Requires the event management capability; all referenced records must belong to this event and organization.



# Download an event export
Source: https://api-docs.helpyousponsor.com/api-reference/events/download-an-event-export

get /admin/events/exports/{uploadId}
Streams the organization-scoped artifact as an attachment. Returns 404 if the file is unavailable; protected report artifacts enforce their report access policy.



# Download an event ticket wallet pass
Source: https://api-docs.helpyousponsor.com/api-reference/events/download-an-event-ticket-wallet-pass

get /frontend/public/events/{clientSlugOrId}/{eventSlug}/orders/{token}/attendees/{attendeeId}/wallet-pass
The order magic token authorizes this attendee. Ticket activation and group-detail checks match the QR endpoint. Returns a signed Apple Wallet pass attachment, or a configuration-required JSON response when signing is unavailable.



# Duplicate event setup
Source: https://api-docs.helpyousponsor.com/api-reference/events/duplicate-event-setup

post /admin/events/{id}/duplicate
Creates a draft copy with a unique slug, clearing event/registration dates, publication/completion state and scheduled address release. Copies setup, seats without guests, communications as drafts, automation rules as paused, and saved reports; resets inventory/redemption counts. Requires the event management capability; all referenced records must belong to this event and organization.



# Export event attendees as CSV
Source: https://api-docs.helpyousponsor.com/api-reference/events/export-event-attendees-as-csv

get /admin/events/{eventId}/reports/attendees.csv
Streams an attendee CSV including contact details, registration-group/attendee answers, purchaser, table, attendance time, ticket code and QR status. Requires report or check-in capability; formatted dates use the event timezone.



# Export event orders as CSV
Source: https://api-docs.helpyousponsor.com/api-reference/events/export-event-orders-as-csv

get /admin/events/{eventId}/reports/orders.csv
Streams orders and purchaser contacts, registration unit/admission counts, monetary amounts, gateway/transaction and receipt details, sponsor packages, QuickBooks event-revenue status and conversion interests. Requires events_finance or events_manage.



# Get a hosted event table
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-a-hosted-event-table

get /frontend/public/events/{clientSlugOrId}/{eventSlug}/tables/{tableId}/host/{sessionId}
Requires the donor portal session in the path and that donor must be the table host. Event management stays available for completed/unpublished events unless the event is unavailable. Returns active guests with editable flags; ticket-order guests are visible but cannot be edited by the host.



# Get a public event HTML document
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-a-public-event-html-document

get /frontend/public/events/{clientId}/{eventSlug}/document
Returns crawlable HTML with event title, date in event timezone, privacy-filtered location and canonical/Open Graph/schema.org metadata where permitted. Invite-only events require X-Event-Invitation; unavailable events return 404.



# Get a public event page
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-a-public-event-page

get /frontend/public/events/{clientSlugOrId}/{eventSlug}
Returns public registration information, inventory, form policy, payment choices and privacy-filtered location. Invite-only pages require an invitation capability or a valid waitlist offer; inaccessible events return 404. Search and caching headers follow event visibility.



# Get a staff event order
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-a-staff-event-order

get /admin/events/{eventId}/orders/{orderId}
Returns the raw organization/event order, registration, attendees with ticket/table, promo code, and sponsor packages. Raw Eloquent monetary values are decimal strings; this differs from the management projection returned by mutation endpoints.



# Get a waitlist signup
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-a-waitlist-signup

get /frontend/public/events/{clientSlugOrId}/{eventSlug}/waitlist/{token}
Resolves a management or offer token within this event. Returns the safe signup projection with no raw management token. Requires grouped registration features; completed/unpublished event management is supported.



# Get an event export status
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-an-event-export-status

get /admin/events/exports/{uploadId}/status
Returns progress/failure status for an organization-scoped export upload, including the download path when ready. Protected report artifacts also enforce their report access policy.



# Get an event report summary
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-an-event-report-summary

get /admin/events/{eventId}/reports/summary
Returns attendance, registration groups, waitlist, donation conversion, attribution, sponsor/bid breakdowns and check-in timeline. The revenue block is null without finance capability; revenue aggregation includes pending orders only when the event setting permits it.



# Get an event ticket QR image
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-an-event-ticket-qr-image

get /frontend/public/events/{clientSlugOrId}/{eventSlug}/orders/{token}/attendees/{attendeeId}/qr.svg
The order magic token authorizes this ticket. The order must be completed and paid/free/offline, the attendee must not be cancelled, and required registration-group details must be complete. Returns a private SVG image cached for five minutes.



# Get checkout data for a waitlist offer
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-checkout-data-for-a-waitlist-offer

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/waitlist/{token}/accept
Validates the current, unexpired offer token and returns ticket/quantity checkout parameters. This request does not create the order; submit its waitlist_offer_token with checkout. Grouped registration features are required.



# Get event check-in context
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-event-check-in-context

get /admin/events/{eventId}/check-ins/context
Returns minimal event, attendance counts and available walk-in ticket choices. Requires events_checkin or events_manage. Check-in mode must be enabled on the event.



# Get event details
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-event-details

get /admin/events/{id}
Returns private event details, setup, user capabilities, availability and optional invitation-date review notice. compact=true suppresses the setup arrays and readiness work. Requires the event view capability; all records are scoped to the authenticated organization.



# Get event registration management details
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-event-registration-management-details

get /frontend/public/events/{clientSlugOrId}/{eventSlug}/orders/{token}
The secret order token authorizes access. Management remains available for completed/unpublished events when the event is available. Returns guest groups, question snapshots/answers, sponsors, receipts and payment state; active ticket links require completed payment and complete or optional group details.



# Get event registration setup
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-event-registration-setup

get /admin/events/{eventId}/registration-setup
Returns tickets, questions, promotions, sponsorship packages, seating tables and auction items together; auction items include bid_summary. Requires the event view capability; all records are scoped to the authenticated organization.



# Get event setup overview
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-event-setup-overview

get /admin/events/{eventId}/overview
Returns setup and communication counts, reminder/follow-up indicators and readiness checks for this event. Requires the event view capability; all records are scoped to the authenticated organization.



# Get event setup selectors
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-event-setup-selectors

get /admin/events/setup-options
Returns event settings, programs/campaigns, up to 250 trips and designations, up to 500 recipient-group records, 50 cover images and 500 email templates. section=email_templates returns only the email template list. Sample trip-linked records are excluded. Requires event-view permission or a route-authorized Events role.



# Get the event invitation plan
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-the-event-invitation-plan

get /admin/events/{eventId}/invitation-plan
Returns the saved plan or an unmaterialized starter definition with id=null, revision=0 and lock_version=0. Requires event view capability and organization/donor visibility. Also requires task view permission.



# Get the organization event sitemap
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-the-organization-event-sitemap

get /frontend/public/events/{clientId}/sitemap.xml
Returns a sitemap containing only public, published, search-indexing-eligible events. Unlisted, invite-only, internal and unavailable events are excluded. Cache lifetime is five minutes and the response itself is noindex,follow.



# Get the public event URL
Source: https://api-docs.helpyousponsor.com/api-reference/events/get-the-public-event-url

get /admin/events/{id}/public-url
Returns an enabled public URL only when the access policy allows an unauthenticated public page. Invite-only events require invitation access and therefore have no enabled public URL here. Requires the event view capability; all records are scoped to the authenticated organization.



# Import offline event check-ins
Source: https://api-docs.helpyousponsor.com/api-reference/events/import-offline-event-check-ins

post /admin/events/{eventId}/check-ins/offline-import
Processes up to 1,000 array rows in order. Rows not marked present are skipped, then identity resolves by attendee ID, event ticket code or email. Valid original timestamps replace the check-in timestamp; invalid timestamps are ignored. A service validation error stops the request after earlier successful rows. Requires events_checkin or events_manage. Check-in mode must be enabled on the event.



# Join an event waitlist
Source: https://api-docs.helpyousponsor.com/api-reference/events/join-an-event-waitlist

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/waitlist
Adds or replays an active waitlist signup only when the selected option is sold out, active and waitlist-enabled. An existing active email/ticket entry is returned rather than duplicated. Requires grouped registration features and an accessible public event.



# List an event waitlist
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-an-event-waitlist

get /admin/events/{eventId}/waitlist
Lists staff waitlist records by waiting, offered, converted, expired and cancelled state, then signup time. Includes ticket and converted-order summaries. Requires grouped registration features and authorized Events view access.



# List donor event registrations
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-donor-event-registrations

get /frontend/events/{client_id}/{session_id}
Requires the donor portal session in the path. Lists that donor’s organization-scoped registrations with monetary/receipt/ticket/sponsor projections and available giving next steps, plus tables hosted by the donor. Sample-linked events are excluded; hosted tables are restricted to public lifecycle statuses.



# List event attendees
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-attendees

get /admin/events/{eventId}/attendees
Returns attendees with ticket/table, purchaser-order summaries and registration-group/question answers. Searches first name, last name or email and sorts by surname then first name. Requires event-view permission or a route-authorized Events role.



# List event auction bids
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-auction-bids

get /admin/events/{eventId}/auction-bids
Returns bids with item, order and donor summaries ordered by amount descending, then newest first. Requires event-view permission or a route-authorized Events role.



# List event auction item records
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-auction-item-records

get /admin/events/{eventId}/auction-items
Returns event-owned setup records; auction rows include current bid aggregates. Requires the event view capability; all records are scoped to the authenticated organization.



# List event communications
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-communications

get /admin/events/{eventId}/communications
Returns communication templates and manually targeted records newest first, excluding per-recipient fanout copies. Template shortcodes are normalized to bracket form. Requires an authorized Events view role.



# List event invitation links
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-invitation-links

get /admin/events/{eventId}/invitation-links
Returns invitation-link metadata newest first. Donor-bound links are visible only when the caller can access that donor; raw tokens are never listed.



# List event invitation-plan presets
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-invitation-plan-presets

get /admin/events/{eventId}/invitation-plans/presets
Returns the read-only Personal invitation preset: personal call 28 days, handwritten note 21 days, follow-up 10 days and final logistics call 3 days before the event. Requires event view capability and organization/donor visibility.



# List event invitees
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-invitees

get /admin/events/{eventId}/invitees
Returns active invitees with masked donor contacts, computed stages, visible plan tasks/interactions and actions. Summary respects search/owner visibility before stage, method, plan-state and work-scope filters. Task and interaction projections follow their separate record visibility rules. Requires event view capability and organization/donor visibility.



# List event-linked interactions
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-linked-interactions

get /admin/events/{eventId}/interactions
Returns up to 50 newest visible event-linked interactions. Records are omitted when any manually linked donor is inaccessible; snippets follow interaction body-sharing policy. Requires both an authorized Events view role and activity_logs_view, interactions_manage or donors_manage.



# List event orders
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-orders

get /admin/events/{eventId}/orders
Returns newest event orders with attendee counts and promo-code summaries. Monetary values on raw order records are decimal strings. Requires events_finance, events_reports or events_manage.



# List event people
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-people

get /admin/events/{eventId}/people
Lists event roles backed by donors the caller can access or staff in the same organization, ordered by sort_order. Requires the event view capability; all records are scoped to the authenticated organization.



# List event preview links
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-preview-links

get /admin/events/{eventId}/preview-links
Returns preview-link metadata newest first. Raw tokens/URLs are only available when a link is initially issued.



# List event promo code records
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-promo-code-records

get /admin/events/{eventId}/promo-codes
Returns event-owned setup records. Requires the event view capability; all records are scoped to the authenticated organization.



# List event question records
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-question-records

get /admin/events/{eventId}/questions
Returns event-owned setup records. Requires the event view capability; all records are scoped to the authenticated organization.



# List event settings profiles
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-settings-profiles

get /admin/events/settings
Lists reusable events settings profiles and usage counts. Returns compact records without readiness and timestamps. Requires the event view capability; all records are scoped to the authenticated organization.



# List event setup with lifecycle metadata
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-setup-with-lifecycle-metadata

get /admin/events/{eventId}/setup/{setup}
Returns typed setup rows plus deletion/archive eligibility and dependency counts. Requires grouped event registration features. Requires the event view capability; all records are scoped to the authenticated organization.



# List event sponsor package records
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-sponsor-package-records

get /admin/events/{eventId}/sponsor-packages
Returns event-owned setup records. Requires the event view capability; all records are scoped to the authenticated organization.



# List event sponsors
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-sponsors

get /admin/events/{eventId}/sponsors
Returns newest sponsors with package, donor, logo, deliverables, logo URL and included guest/seat summaries. Included guests match the sponsor ticket-slot metadata. Requires event-view permission or a route-authorized Events role.



# List event starter presets
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-starter-presets

get /admin/events/templates
Returns the configured preset manifests keyed by stable preset key. Historical-event creation is supported separately and is deliberately excluded from the starter selector. Requires event-view permission or a route-authorized Events role.



# List event table records
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-table-records

get /admin/events/{eventId}/tables
Returns event-owned setup records. Requires the event view capability; all records are scoped to the authenticated organization.



# List event ticket type records
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-event-ticket-type-records

get /admin/events/{eventId}/ticket-types
Returns event-owned setup records. Requires the event view capability; all records are scoped to the authenticated organization.



# List events
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-events

get /admin/events
Lists events by lifecycle view, text search and sortable fields. include_summary adds organization-wide counts and the next event, rather than counts restricted by list filters. Requires the event view capability; all records are scoped to the authenticated organization.



# List masked donor payment methods for an event
Source: https://api-docs.helpyousponsor.com/api-reference/events/list-masked-donor-payment-methods-for-an-event

get /admin/events/{eventId}/donors/{donorId}/saved-payment-methods
Returns at most 100 masked Stripe cards for a donor the staff actor can access. Opaque references are event/donor scoped and expire; use a freshly selected eligible reference for an authorized charge. Provider/configuration failure returns an empty methods list with an explanatory message.



# Mark an event attendee as a no-show
Source: https://api-docs.helpyousponsor.com/api-reference/events/mark-an-event-attendee-as-a-no-show

post /admin/events/{eventId}/check-ins/no-show
Only registered or already no-show attendees on completed registrations can be marked. The event must have a start date and must already have started; repeat calls retain no-show status. Requires events_checkin or events_manage. Check-in mode must be enabled on the event.



# Offer the next event waitlist place
Source: https://api-docs.helpyousponsor.com/api-reference/events/offer-the-next-event-waitlist-place

post /admin/events/{eventId}/waitlist/{entryId}/offer
Reserves ticket units and event admissions for the next waiting signup for that ticket, then queues its offer email. An active offer is replayed; communication holds and out-of-order offers return 409. Expiry defaults to the event reservation policy, clamped to 5–60 minutes.



# Place a public event auction bid
Source: https://api-docs.helpyousponsor.com/api-reference/events/place-a-public-event-auction-bid

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/auction-bids
Places a winning bid on an open, public item with sufficient stock and marks earlier winning bids outbid. Amount must reach the next minimum: starting bid or at least one currency unit, then current high bid plus a configured increment of at least one. Returns a secret bid-specific checkout capability; payment occurs separately.



# Preview adding selected donors to an event invite list
Source: https://api-docs.helpyousponsor.com/api-reference/events/preview-adding-selected-donors-to-an-event-invite-list

post /admin/events/{eventId}/invitees/selection/preview
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).



# Preview an event communication
Source: https://api-docs.helpyousponsor.com/api-reference/events/preview-an-event-communication

post /admin/events/{eventId}/communications/preview
Reviews selected, eligible, suppressed and missing-email recipient counts, sender, schedule and private-address effects without creating or sending anything. The structured schedule must match legacy send_at when both are supplied. Requires events_manage.



# Preview an event page
Source: https://api-docs.helpyousponsor.com/api-reference/events/preview-an-event-page

get /admin/events/{eventId}/preview
Returns a read-only public projection for event staff, including drafts. Preview writes, payment gateways and payment-method choices are disabled. Location respects public disclosure policy; headers prevent indexing and caching.



# Preview invitation tasks for an invitee
Source: https://api-docs.helpyousponsor.com/api-reference/events/preview-invitation-tasks-for-an-invitee

post /admin/events/{eventId}/invitees/{inviteeId}/plan-preview
Requires an event start and saved plan. Resolves selected enabled steps, due dates and assignees, counts mapped versus new tasks, and sends no communication. Dates must be today/future in event timezone; assignees must access both event and donor. Requires event view capability and organization/donor visibility. Also requires task view permission.



# Publish an event
Source: https://api-docs.helpyousponsor.com/api-reference/events/publish-an-event

post /admin/events/{id}/publish
Enables the public page, checks every required readiness item and sets published status for a draft. Records its initial publication timestamp; missing setup or payment paths block publication. Requires the event management capability; all referenced records must belong to this event and organization.



# Queue a reviewed event invite-list selection
Source: https://api-docs.helpyousponsor.com/api-reference/events/queue-a-reviewed-event-invite-list-selection

post /admin/events/{eventId}/invitees/selection/apply
Consumes the unexpired preview and verifies actor/event binding and current plan definition. Queues add/reactivate/owner changes and optional staff tasks, rechecking donor access per record. Repeat the same Idempotency-Key and preview token to recover its operation. A consumed/expired preview, concurrent application or changed definition returns 409. Does not send communication. Requires event setup management; archived event invitation history is read-only (409).



# Queue failed event invite-list records for retry
Source: https://api-docs.helpyousponsor.com/api-reference/events/queue-failed-event-invite-list-records-for-retry

post /admin/events/{eventId}/invitees/selection/operations/{operationId}/retry
Only the initiating actor may retry an event_invitees operation for this event in failed/completed_with_errors state. Verifies durable failed donor IDs, then queues a new operation for failed rows only using the original accepted context. A stable retry key recovers the same new operation. Successful/skipped rows are not retried. Requires event setup management; archived event invitation history is read-only (409).



# Quote public event registration
Source: https://api-docs.helpyousponsor.com/api-reference/events/quote-public-event-registration

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/quote
Requires grouped-registration V2 to be enabled. Prices active available tickets/packages, promo discount, donation and optional fees in event currency; reserves no stock. Quote expires after five minutes. A waitlist offer credits pre-reserved matching ticket units. Check payment requires the event offline option and disables fee coverage.



# Register and check in an event walk-in
Source: https://api-docs.helpyousponsor.com/api-reference/events/register-and-check-in-an-event-walk-in

post /admin/events/{eventId}/check-ins/walk-in
Requires events_checkin or events_manage and enabled check-in mode. Creates one legacy ticket registration with offline payment and no donor creation, then checks its attendee in with walk_in source. Ticket availability and event capacity are enforced. Reuse the same idempotency key to avoid another registration; repeated admission creates a duplicate check-in log.



# Remove a donor from an event invite list
Source: https://api-docs.helpyousponsor.com/api-reference/events/remove-a-donor-from-an-event-invite-list

delete /admin/events/{eventId}/invitees/{inviteeId}
Marks the invitee removed without deleting invitation history or registration. Invitation access links remain valid unless revoke_access_link=true. Version always increments; stale writes return 409. Requires event setup management; archived event invitation history is read-only (409).



# Remove an event person
Source: https://api-docs.helpyousponsor.com/api-reference/events/remove-an-event-person

delete /admin/events/{eventId}/people/{personId}
Soft-deletes the caller-accessible event person and records activity. Requires the event management capability; all referenced records must belong to this event and organization.



# Reorder event setup rows
Source: https://api-docs.helpyousponsor.com/api-reference/events/reorder-event-setup-rows

put /admin/events/{eventId}/setup/{setup}/reorder
Saves zero-based sort positions in the supplied order. Every ID must be active in this event; only tickets, questions, sponsorship packages, tables and auction items support sorting. Requires grouped registration features. Requires the event management capability; all referenced records must belong to this event and organization.



# Repair a missing invitation staff task
Source: https://api-docs.helpyousponsor.com/api-reference/events/repair-a-missing-invitation-staff-task

post /admin/events/{eventId}/invitees/{inviteeId}/plan-tasks/{stepKey}/repair
Returns an existing available task, restores its deleted canonical task, or recreates a missing task from its accepted snapshot and generated date. Invalidated original assignees become unassigned. Requires event start, saved plan and current active invitee version. Sends no communication. Requires event setup management; archived event invitation history is read-only (409). Also requires task management permission.



# Reschedule reviewed event invitation tasks
Source: https://api-docs.helpyousponsor.com/api-reference/events/reschedule-reviewed-event-invitation-tasks

post /admin/events/{eventId}/invitation-task-date-review
Atomically reschedules up to 1,000 distinct open canonical invitation-plan tasks. Every task must be mutable, its expected version current, and proposed date exactly match the current event/snapshot calculation; stale dates/versions return 409. Completed/deleted/unavailable tasks reject the batch. Requires event setup management; archived event invitation history is read-only (409). Also requires task management permission.



# Reset an event invitation plan to the preset
Source: https://api-docs.helpyousponsor.com/api-reference/events/reset-an-event-invitation-plan-to-the-preset

post /admin/events/{eventId}/invitation-plan/reset
Saves a new revision of the Personal invitation definition. confirm_reset must be true; generated staff tasks retain their accepted snapshots. Requires event setup management; archived event invitation history is read-only (409). Also requires task management permission.



# Resolve an event preview link
Source: https://api-docs.helpyousponsor.com/api-reference/events/resolve-an-event-preview-link

post /frontend/public/event-previews/{clientId}/resolve
Exchanges the secret preview token for a read-only event page in the specified organization. Expired, revoked or mismatched tokens return 404. Payment methods and registration writes stay disabled, with private/no-store and noindex headers.



# Restore an event invitee
Source: https://api-docs.helpyousponsor.com/api-reference/events/restore-an-event-invitee

post /admin/events/{eventId}/invitees/{inviteeId}/restore
Clears removed metadata and increments version, preserving disposition, owner and invitation history. Requires current version and donor access. Requires event setup management; archived event invitation history is read-only (409).



# Restore event setup
Source: https://api-docs.helpyousponsor.com/api-reference/events/restore-event-setup

post /admin/events/{eventId}/sponsor-packages/{id}/restore
Restores archived setup and re-enables its operational state; auction and communication rows return as drafts. Requires grouped event registration features. Requires the event management capability; all referenced records must belong to this event and organization.



# Restore event setup
Source: https://api-docs.helpyousponsor.com/api-reference/events/restore-event-setup-1

post /admin/events/{eventId}/setup/{setup}/{id}/restore
Restores archived setup and re-enables its operational state; auction and communication rows return as drafts. Requires grouped event registration features. Requires the event management capability; all referenced records must belong to this event and organization.



# Review event invitation task dates
Source: https://api-docs.helpyousponsor.com/api-reference/events/review-event-invitation-task-dates

get /admin/events/{eventId}/invitation-task-date-review
Recomputes proposed dates from the current event start and each applied snapshot offset. Lists only visible tasks; missing tasks require task management. Edited baseline dates are flagged and not selected by default. Requires an event start. Requires event view capability and organization/donor visibility. Also requires task view permission.



# Revoke accessible event invitation links
Source: https://api-docs.helpyousponsor.com/api-reference/events/revoke-accessible-event-invitation-links

delete /admin/events/{eventId}/invitation-links
Revokes active invitation capabilities the caller can access, returning the count and incrementing affected invitee versions. Inaccessible donor-bound links are excluded.



# Revoke all event preview links
Source: https://api-docs.helpyousponsor.com/api-reference/events/revoke-all-event-preview-links

delete /admin/events/{eventId}/preview-links
Revokes every still-active preview capability for this event and returns the affected count.



# Revoke an event invitation link
Source: https://api-docs.helpyousponsor.com/api-reference/events/revoke-an-event-invitation-link

delete /admin/events/{eventId}/invitation-links/{linkId}
Revokes one accessible invitation link. If it is tied to an invitee, increments the invitee version. Donor visibility is required for donor-bound links.



# Revoke an event preview link
Source: https://api-docs.helpyousponsor.com/api-reference/events/revoke-an-event-preview-link

delete /admin/events/{eventId}/preview-links/{linkId}
Revokes the selected organization/event preview capability. Repeat revocation preserves the unavailable state.



# Save the event invitation plan
Source: https://api-docs.helpyousponsor.com/api-reference/events/save-the-event-invitation-plan

put /admin/events/{eventId}/invitation-plan
Replaces the definition and increments revision/lock. Existing applied task snapshots remain unchanged. Supply the current lock, or zero for first save. One to ten steps must be enabled; offsets are 0–365 days, titles allow only donor_name/event_name tokens, specific assignees must be active and see this event. Unknown or duplicate step keys become new generated keys. Requires event setup management; archived event invitation history is read-only (409). Also requires task management permission.



# Search event attendees for check-in
Source: https://api-docs.helpyousponsor.com/api-reference/events/search-event-attendees-for-check-in

get /admin/events/{eventId}/check-ins/search
Searches names, email, QR token, order number and table name. Filter issues includes cancelled/transferred attendees and groups with missing required details. Requires events_checkin or events_manage. Check-in mode must be enabled on the event.



# Start winning auction bid checkout
Source: https://api-docs.helpyousponsor.com/api-reference/events/start-winning-auction-bid-checkout

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/auction-bids/{bidId}/checkout
Requires auction availability and the bid-specific checkout token; this is separate from the order management token. Only winning/awarded unpurchased bids can begin checkout. Missing purchaser contact defaults from the bid. Creates a legacy auction registration even when grouped registration is enabled, bypassing the public registration window, and returns a provider handoff when pending. A bid already linked to an order returns that existing registration with HTTP 200.



# Unpublish an event
Source: https://api-docs.helpyousponsor.com/api-reference/events/unpublish-an-event

post /admin/events/{id}/unpublish
Disables the public page and search indexing, clears publication time, and places communications on hold. A future scheduled address release is disabled. Completed, reconciled and archived events cannot be unpublished. Requires the event management capability; all referenced records must belong to this event and organization.



# Update a hosted-table guest
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-a-hosted-table-guest

put /frontend/public/events/{clientSlugOrId}/{eventSlug}/tables/{tableId}/host/{sessionId}/guests/{attendeeId}
Requires the donor portal session in the path and that donor must be the table host. Event management stays available for completed/unpublished events unless the event is unavailable. Only a guest created from the host console without an order can be changed. Omitted contact fields are preserved, while explicit null email/phone clears them.



# Update a sponsor deliverable
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-a-sponsor-deliverable

put /admin/events/{eventId}/sponsors/{sponsorId}/deliverables/{deliverableId}
Updates deliverable status and optional notes/due date. Completing sets the completion timestamp/user; any other status clears those completion fields. Null notes/due_at retain previous values. Requires events_sponsor_manage or events_manage.



# Update an event auction item
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-auction-item

put /admin/events/{eventId}/auction-items/{id}
Configures bidding prices, stock, visibility and auction status. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Update an event communication
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-communication

put /admin/events/{eventId}/communications/{id}
Saves a communication template with normalized shortcodes, notification preferences and Message Manager approval metadata. Scheduled messages are later handled by the queue; only email is automatically delivered. Communications hold blocks scheduling. Relative schedules require a dated event and resolve in its timezone. The structured schedule must match legacy send_at when both are supplied. Requires events_manage.



# Update an event invitee
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-invitee

patch /admin/events/{eventId}/invitees/{inviteeId}
Checks expected_version before supplied changes. Null owner unassigns; null response clears it. Declined/closed disposition or a declined response requires confirm_disposition=true. Reopening a previously declined invitee requires explicitly clearing/replacing the declined response. Attendance remains derived from registration. Requires event setup management; archived event invitation history is read-only (409).



# Update an event person
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-person

put /admin/events/{eventId}/people/{personId}
Updates supplied role/name/visibility/order values and revalidates the resulting identity. Exactly one donor or staff identity must remain; the identity/role combination must be unique. Requires the event management capability; all referenced records must belong to this event and organization.



# Update an event promo code
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-promo-code

put /admin/events/{eventId}/promo-codes/{id}
Codes are normalized to uppercase and percentages cannot exceed 100. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Update an event question
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-question

put /admin/events/{eventId}/questions/{id}
A reused field_key updates an existing active question or restores an unused archived question; an archived question with saved answers returns 409. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Update an event settings profile
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-settings-profile

put /admin/events/settings/{settingId}
Merges supplied values into the existing events profile, preserving other settings. Profiles of other program types return 404. Requires the event management capability; all referenced records must belong to this event and organization.



# Update an event sponsor package
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-sponsor-package

put /admin/events/{eventId}/sponsor-packages/{id}
Configures benefits, included tickets/tables and optional deliverable definitions. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Update an event table
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-table

put /admin/events/{eventId}/tables/{id}
Configures seating capacity and an optional existing donor host. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Update an event ticket type
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-an-event-ticket-type

put /admin/events/{eventId}/ticket-types/{id}
Dates use the event timezone. Maximum per order must be at least the effective minimum. Omitted fields are preserved when updating. Requires the event management capability; all referenced records must belong to this event and organization.



# Update event details
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-event-details

put /admin/events/{id}
Updates supplied fields, normalizes dates in the effective event timezone and recomputes relative communication schedules when event dates/timezone change. Communications hold release requires explicit confirmation, and scheduled address release requires a release date. Requires the event management capability; all referenced records must belong to this event and organization.



# Update event registration guest details
Source: https://api-docs.helpyousponsor.com/api-reference/events/update-event-registration-guest-details

put /frontend/public/events/{clientSlugOrId}/{eventSlug}/orders/{token}
The secret order token authorizes changes when magic-link management is enabled. Cancelled/refunded/expired registrations cannot be edited. V2 requires the current version or returns 409 with current_version. Only guests, groups and sponsors on this order are mutable; applicable active question types/options are validated and blank answers removed. Sponsor logo upload must belong to the organization; supplied contact nulls clear values. Group completeness and ticket readiness are recalculated.



# Upload an event sponsor logo
Source: https://api-docs.helpyousponsor.com/api-reference/events/upload-an-event-sponsor-logo

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/orders/{token}/storage/uploads
Uploads the multipart file and returns its final public URL/key. Active HTML, JavaScript, XML and SVG content/extensions are rejected. HEIC/HEIF images are converted to JPEG, so use the returned key and filename. Storage or receipt failures return500; invalid files, MIME/key mismatches or conversion failures return422. Requires a valid event registration magic token and enabled magic-link order management. The event must be available and not a sample-trip target. The key must begin event-sponsor-logos/{clientSlugOrId}/{eventSlug}/ after slash sanitization. Only supported PNG/JPEG/GIF/WebP/HEIC/HEIF images are accepted.



# Verify public registration payment
Source: https://api-docs.helpyousponsor.com/api-reference/events/verify-public-registration-payment

post /frontend/public/events/{clientSlugOrId}/{eventSlug}/orders/{token}/complete-payment
The secret order token authorizes access. Repeated paid/free/offline completion returns the existing registration. PayPal captures and verifies the provider order. Stripe reconciliation verifies ownership, amount, currency and provider state; a bank payment can remain processing until settlement, and late/refunded evidence can require reconciliation without activating tickets.



# Abort an import upload session
Source: https://api-docs.helpyousponsor.com/api-reference/files/abort-an-import-upload-session

post /admin/import_files/upload-sessions/{upload_session_id}/abort
Marks the user-owned session and files aborted and attempts deletion of temporary storage objects. Storage deletion failures are logged while the abort still succeeds. Validation/processing/consumption or a validation job prevents abort with409. Requires permission: one of imports_manage.



# Complete Box OAuth for file uploads
Source: https://api-docs.helpyousponsor.com/api-reference/files/complete-box-oauth-for-file-uploads

get /admin/box_response
Exchanges a Box authorization code for access and refresh tokens and stores them on the target client account. The endpoint is used after an admin authorizes Box for upload storage integration. Requires admin file access through `user.permissions`.



# Confirm a staged import file upload
Source: https://api-docs.helpyousponsor.com/api-reference/files/confirm-a-staged-import-file-upload

post /admin/import_files/upload-sessions/{upload_session_id}/files/{file_id}/complete
Call after PUT completes. size_bytes must match the original selection and verified storage size. Declared MIME must agree with verified MIME. Photos require successful storage verification; documents may be marked uploaded with verification=deferred when storage inspection is unavailable. Reconfirming an already uploaded file returns a smaller200 receipt containing only message and file_id. An expired session returns410. Requires permission: one of imports_manage.



# Create an import upload session
Source: https://api-docs.helpyousponsor.com/api-reference/files/create-an-import-upload-session

post /admin/import_files/{program_id}/upload-sessions
Creates a user-owned24hour staging session for a program in the current organization. Submit1–1000 unique filenames, then PUT each file to its returned signed upload_url with the exact Content-Type header. URLs expire after60minutes; the advertised parallel limit is3. Photos permit JPG/JPEG/PNG/GIF up to10MiB each. Document per-file and all batch limits follow deployed PHP upload/post limits. donors is normalized to donor. This step creates staging records; it does not import records. Requires permission: one of imports_manage.



# Delete a file
Source: https://api-docs.helpyousponsor.com/api-reference/files/delete-a-file

delete /file/{id}



# Download a prepared file bundle
Source: https://api-docs.helpyousponsor.com/api-reference/files/download-a-prepared-file-bundle

get /files/download-bundle/{token}
Streams a completed ZIP bundle for a token created by the file download bundle job. The token must belong to the authenticated admin's client and user, and expired tokens return gone. The response is an `application/zip` file when successful.



# Edit a file
Source: https://api-docs.helpyousponsor.com/api-reference/files/edit-a-file

put /file/{id}



# Fetch files for multiple recipients
Source: https://api-docs.helpyousponsor.com/api-reference/files/fetch-files-for-multiple-recipients

post /files/entities/batch
Returns non-mailing-artifact uploads grouped by recipient for the authenticated admin's client. The bulk file permissions drawer uses this endpoint before applying a batch permission change. The request body determines which recipient IDs to inspect and whether current profile images should be included.



# Filter recipient files in a program
Source: https://api-docs.helpyousponsor.com/api-reference/files/filter-recipient-files-in-a-program

post /files/filter/{program_id}
Applies advanced recipient filters and returns matching recipients with their file counts for the authenticated admin's client. The file-management UI uses this endpoint to build scoped selections for bulk permission changes and file bundles. Requires admin file access through `user.permissions`.



# Get an import upload session
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-an-import-upload-session

get /admin/import_files/upload-sessions/{upload_session_id}
Returns the authenticated user’s staging session and per-file status. Expired sessions are marked expired before the response. A session owned by another user or organization returns404. Requires permission: one of imports_view, imports_manage.



# Get bulk operation progress
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-bulk-operation-progress

get /admin/bulk-edit-operations/{operationId}
Returns an organization-visible bulk operation, including progress and paginated failed-record labels. Any authorized admin in the same organization may view it. failed_record_ids is a compatibility sample of at most100 and is empty for event invitations; use failed_records_pagination for the complete failure list. retry_selection is returned only for failed/completed-with-errors commitment or invitation operations whose persisted failure identities are complete. Requires permission: one of groups, admins, forms, manage_programs, programs_view, donors_view, donations, manage_email, email_manager, manage_sms, sms_manager, sms_inbox_view, sms_inbox_reply, sms_inbox_manage, sendblue_manage, mailings_view, mailings_generate, mailings_manage, manage_settings, access_account_settings, access_payment_gateways, tasks_view, tasks_manage, trips_view, events_view, events_checkin, events_finance, events_reports, events_sponsor_manage, imports_view, activity_logs_view, households_view, notes_view, reports_view.



# Get CSV import progress
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-csv-import-progress

get /admin/import/csv/{import_id}/progress
Returns the authenticated user’s CSV import progress and bounded waiting-since warnings. Warning details are limited to100; total_warnings and waiting_since_skip_counts preserve overall counts. Completed or failed imports report progress100 even when some rows were skipped or failed. Requires permission: one of imports_view, imports_manage.



# Get document upload validation progress
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-document-upload-validation-progress

get /admin/import_files/document-validation-progress/{validation_job_id}
Returns progress and completed validation issues for a document validation job owned by the authenticated admin and client. Completed and failed jobs include file-level validation errors and warnings when present. Requires admin file access through `user.permissions`.



# Get donor/recipient import batch progress (deprecated - use /import/batch/{batch_id}/progress)
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-donorrecipient-import-batch-progress-deprecated--use-importbatch-progress

get /admin/import/donors-recipients/batch/{batch_id}/progress



# Get file details
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-file-details

get /file/{id}



# Get files table
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-files-table

get /files/{type}/{id}/table



# Get import batch progress for any batch type, including attendance and enrollment
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-import-batch-progress-for-any-batch-type-including-attendance-and-enrollment

get /admin/import/batch/{batch_id}/progress



# Get import validation progress for recipients and donors
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-import-validation-progress-for-recipients-and-donors

get /admin/import/validation-progress/{validation_job_id}



# Get list of all import batches (payments, donors, recipients)
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-list-of-all-import-batches-payments-donors-recipients

get /admin/import/batches



# Get list of donor/recipient import batches (deprecated)
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-list-of-donorrecipient-import-batches-deprecated

get /admin/import/donors-recipients/batches
Deprecated. Use GET /import/batches with type=donors or type=recipients.



# Get list of payment import batches (deprecated)
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-list-of-payment-import-batches-deprecated

get /admin/import/payments/batches
Deprecated. Use GET /import/batches with type=payments.



# Get payment import batch progress
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-payment-import-batch-progress

get /admin/import/payments/batch/{batch_id}/progress



# Get payment validation progress
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-payment-validation-progress

get /admin/import/payments/validation-progress/{validation_job_id}



# Get photo upload validation progress
Source: https://api-docs.helpyousponsor.com/api-reference/files/get-photo-upload-validation-progress

get /admin/import_files/validation-progress/{validation_job_id}
Returns progress and completed validation issues for a photo validation job owned by the authenticated admin and client. Completed and failed jobs include row/file-level validation errors and warnings when present. Requires admin file access through `user.permissions`.



# Import CSV for a specific program
Source: https://api-docs.helpyousponsor.com/api-reference/files/import-csv-for-a-specific-program

get /csv_import/{program_id}



# Import CSV for a specific program
Source: https://api-docs.helpyousponsor.com/api-reference/files/import-csv-for-a-specific-program-1

post /csv_import/{program_id}



# Make placeholder picture
Source: https://api-docs.helpyousponsor.com/api-reference/files/make-placeholder-picture

get /picture/{id}/placeholder



# Make profile picture
Source: https://api-docs.helpyousponsor.com/api-reference/files/make-profile-picture

get /picture/{id}/profile



# Post a record upload
Source: https://api-docs.helpyousponsor.com/api-reference/files/post-a-record-upload

post /admin/recordUpload



# Preview a saved import CSV
Source: https://api-docs.helpyousponsor.com/api-reference/files/preview-a-saved-import-csv

get /admin/import/batch/{batch_id}/csv-preview
Returns normalized headers and at most100 data rows from the user-owned saved CSV, respecting the batch’s saved row offset. With no batch_type, IDs are resolved in payments, donors_recipients, then relationships order; specify the family to avoid ambiguity. Remote URLs and unsafe paths are rejected. No records are imported by this request. Requires permission: one of imports_view, imports_manage.



# Process the import job for donors and recipients
Source: https://api-docs.helpyousponsor.com/api-reference/files/process-the-import-job-for-donors-and-recipients

post /csv_process/{program_id}



# Process the import job for payments
Source: https://api-docs.helpyousponsor.com/api-reference/files/process-the-import-job-for-payments

post /csv_process/{program_id}/payments



# Process validated document uploads
Source: https://api-docs.helpyousponsor.com/api-reference/files/process-validated-document-uploads

post /admin/import_files/process-validated-documents/{validation_job_id}
Queues the document import job from a completed and valid document validation job owned by the authenticated admin and client. The validation job is deleted after dispatch, and upload-session state is advanced when staged uploads are used. Requires admin file access through `user.permissions`.



# Process validated photo uploads
Source: https://api-docs.helpyousponsor.com/api-reference/files/process-validated-photo-uploads

post /admin/import_files/process-validated/{validation_job_id}
Queues upload jobs from a completed and valid photo validation job owned by the authenticated admin and client. The validation job is deleted after jobs are queued, and upload-session state is advanced when staged uploads are used. Requires admin file access through `user.permissions`.



# Queue a bulk file permission update
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-a-bulk-file-permission-update

patch /files/permissions/bulk
Queues a background selection job that updates upload permissions for explicitly selected files, selected recipients, a search result, or an advanced filter. The job may schedule the permission change, generate blurred thumbnails, and notify donors depending on the payload. Requires admin file access through `user.permissions`.



# Queue a bulk profile-file assignment
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-a-bulk-profile-file-assignment

post /files/profile/bulk
Queues a background job that sets or unsets recipient profile photos for the authenticated admin's client. The controller validates that all selected uploads belong to the client, are image files, belong to recipients, and include at most one file per recipient. Requires admin file access through `user.permissions`.



# Queue a recipient file deletion bundle
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-a-recipient-file-deletion-bundle

post /files/delete-bundle
Creates a deletion-history activity for the authenticated admin's client and dispatches a queued job to soft-delete the selected recipient files. The confirmation email is sent after the background deletion finishes. Same handler is mounted on the canonical `/files/delete-bundle` route and requires file access through `user.permissions`.



# Queue a recipient file download bundle
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-a-recipient-file-download-bundle

post /files/download-bundle
Queues a background job that gathers recipient files for the authenticated admin's client and emails the admin a tokenized ZIP download link when the bundle is ready. The endpoint accepts either all files for a program or an explicit list of upload IDs. Same handler is mounted on the canonical `/files/download-bundle` route and requires file access through `user.permissions`.



# Queue document imports from a CSV mapping
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-document-imports-from-a-csv-mapping

post /admin/import_files/{type}/{program_id}/import-documents
Stages uploaded document files and dispatches `ImportDocumentsWithCsvJob` to attach them to recipients or donors using a previously uploaded CSV. The request identifies CSV columns for unique-field matching, source filenames, and permissions. Requires admin file access through `user.permissions`.



# Queue photo files for import
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-photo-files-for-import

post /admin/import_files/{type}/{program_id}
Stages uploaded photo files and dispatches one `UploadSingleFileJob` per file so admins can attach images to recipients or donors by a unique field. The endpoint validates file size and image MIME rules through the photo upload helper before queueing. Requires admin file access through `user.permissions`.



# Queue the import job for commitment relationships
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-the-import-job-for-commitment-relationships

post /csv_process/{program_id}/relationships



# Queue thumbnails for existing uploads
Source: https://api-docs.helpyousponsor.com/api-reference/files/queue-thumbnails-for-existing-uploads

get /admin/create_thumbnails
Finds image uploads without thumbnails and dispatches a thumbnail-generation job for each one. This is an authenticated admin maintenance endpoint exposed in the admin route group, not a cron route. Requires admin file access through `user.permissions`.



# Reconcile a legacy payment import summary
Source: https://api-docs.helpyousponsor.com/api-reference/files/reconcile-a-legacy-payment-import-summary

post /admin/import/payments/batch/{batch_id}/reconcile
Queues summary reconciliation for a completed payment batch with skipped rows that actually belong to this batch. Available only when persisted donation counts reveal missing created-row counters; imports with refund or soft-credit inclusion are excluded. Requires permission: one of imports_manage.



# Restore an undone import batch
Source: https://api-docs.helpyousponsor.com/api-reference/files/restore-an-undone-import-batch

post /admin/import/batch/{batch_type}/{batch_id}/restore
Restores an eligible user-owned undone batch from soft deletion. payments restores imported gifts and associated source/refund/soft-credit lifecycle rows; donors_recipients restores donors or recipients; relationships restores commitment relationships and recurring mappings. Parent records must be restored first, later source identities/refunds/commitments must not conflict, and pending recipient refresh may block payment restores. Derived search and related-record work is queued. Returns an empty204 response on success. Requires permission: one of imports_manage.



# Resume a stalled payment import
Source: https://api-docs.helpyousponsor.com/api-reference/files/resume-a-stalled-payment-import

post /admin/import/payments/batch/{batch_id}/resume
Requeues a pending/processing payment import only after at least two minutes without a progress update. Uses an optimistic claim to reject a concurrent change. Resumes the existing batch, including derived finalization when applicable; no new import batch is created. Requires permission: one of imports_manage.



# Resume saved commitment import finalization
Source: https://api-docs.helpyousponsor.com/api-reference/files/resume-saved-commitment-import-finalization

post /admin/import/relationships/batch/{batch_id}/resume
Queues finalization for a failed, non-undone relationship import whose source records are already persisted. It finishes derived search/related-record updates without requiring another CSV upload. Requires permission: one of imports_manage.



# Retry payment import recipient reconciliation
Source: https://api-docs.helpyousponsor.com/api-reference/files/retry-payment-import-recipient-reconciliation

post /admin/import/payments/batch/{batch_id}/retry-recipient-refresh
Queues only derived recipient sponsorship refresh work for a previously committed import lifecycle action. Donation mutations are not replayed. Already up-to-date returns200 and queued=false. A refresh currently processing returns409 and queued=false. A newly dispatched retry returns202 and queued=true; the included summary is the pre-dispatch snapshot. Requires permission: one of imports_manage.



# Rotate picture
Source: https://api-docs.helpyousponsor.com/api-reference/files/rotate-picture

get /picture/{id}/rotate



# Search recipient files in a program
Source: https://api-docs.helpyousponsor.com/api-reference/files/search-recipient-files-in-a-program

get /files/search/{program_id}
Searches recipients in a program and returns their matching non-mailing-artifact files for the authenticated admin's client. The endpoint is used by file-management drawers to locate uploads by recipient title fields and file metadata. Requires admin file access through `user.permissions`.



# Start a batch import for donors or recipients
Source: https://api-docs.helpyousponsor.com/api-reference/files/start-a-batch-import-for-donors-or-recipients

post /admin/import/donors-recipients/batch



# Start a batch import for relationships
Source: https://api-docs.helpyousponsor.com/api-reference/files/start-a-batch-import-for-relationships

post /admin/import/relationships/batch



# Start a batch payment import
Source: https://api-docs.helpyousponsor.com/api-reference/files/start-a-batch-payment-import

post /admin/import/payments/batch



# Undo a donor/recipient import batch (deprecated - use /import/batch/{batch_id})
Source: https://api-docs.helpyousponsor.com/api-reference/files/undo-a-donorrecipient-import-batch-deprecated--use-importbatch-

delete /admin/import/donors-recipients/batch/{batch_id}



# Undo a payment import batch
Source: https://api-docs.helpyousponsor.com/api-reference/files/undo-a-payment-import-batch

delete /admin/import/payments/batch/{batch_id}



# Undo an import batch for a specific batch type
Source: https://api-docs.helpyousponsor.com/api-reference/files/undo-an-import-batch-for-a-specific-batch-type

delete /admin/import/batch/{batch_type}/{batch_id}



# Upload a file
Source: https://api-docs.helpyousponsor.com/api-reference/files/upload-a-file

get /file/{type}/{id}/upload



# Upload a file
Source: https://api-docs.helpyousponsor.com/api-reference/files/upload-a-file-1

post /file/{type}/{id}/upload



# Upload a portal session file
Source: https://api-docs.helpyousponsor.com/api-reference/files/upload-a-portal-session-file

post /frontend/storage/uploads/{client_id}/{session_id}
Uploads the multipart file and returns its final public URL/key. Active HTML, JavaScript, XML and SVG content/extensions are rejected. HEIC/HEIF images are converted to JPEG, so use the returned key and filename. Storage or receipt failures return500; invalid files, MIME/key mismatches or conversion failures return422. Requires a current donor/recipient portal session in the URL, or the matching public-add-recipient upload session. Only approved generated basenames, matching entity image keys and trip-task-completions UUID keys are allowed. Valid sessions refresh their lifetime to one hour. Recipient sessions with valid workspace/program/recipient/user context receive an upload_receipt for a subsequent recipient message.



# Upload an authenticated workspace file
Source: https://api-docs.helpyousponsor.com/api-reference/files/upload-an-authenticated-workspace-file

post /storage/uploads
Uploads the multipart file and returns its final public URL/key. Active HTML, JavaScript, XML and SVG content/extensions are rejected. HEIC/HEIF images are converted to JPEG, so use the returned key and filename. Storage or receipt failures return500; invalid files, MIME/key mismatches or conversion failures return422. Accepts approved generated basename keys and shared trip/sticker namespaces, current-workspace newsletter keys, validated account-logo/program-placeholder/email-template image keys, and current-workspace donation attachment keys. Donation attachments permit PDF, office documents, text/CSV and common images up to10MiB. This endpoint stores bytes; callers attach the returned key through the owning feature API. Requires permission: one of admins, manage_programs, donors_manage, manage_settings, access_account_settings, access_payment_gateways, imports_manage.



# Validate document uploads before import
Source: https://api-docs.helpyousponsor.com/api-reference/files/validate-document-uploads-before-import

post /admin/import_files/{type}/{program_id}/validate-documents
Creates or reuses a document validation job for CSV-mapped document imports without attaching files to records. The endpoint can validate direct multipart files or files already staged in an upload session. Requires admin file access through `user.permissions`.



# Validate donor data without persisting to database
Source: https://api-docs.helpyousponsor.com/api-reference/files/validate-donor-data-without-persisting-to-database

post /admin/import/donors/dry-run



# Validate payment data without persisting to database
Source: https://api-docs.helpyousponsor.com/api-reference/files/validate-payment-data-without-persisting-to-database

post /admin/import/payments/dry-run



# Validate photo uploads before import
Source: https://api-docs.helpyousponsor.com/api-reference/files/validate-photo-uploads-before-import

post /admin/import_files/{program_id}/validate
Creates or reuses a file validation job for staged photo imports without persisting uploads to recipient or donor records. The endpoint can validate direct multipart files or files already staged in an upload session. Requires admin file access through `user.permissions`.



# Validate recipient data without persisting to database
Source: https://api-docs.helpyousponsor.com/api-reference/files/validate-recipient-data-without-persisting-to-database

post /admin/import/recipients/dry-run



# Validate relationship data without persisting to database
Source: https://api-docs.helpyousponsor.com/api-reference/files/validate-relationship-data-without-persisting-to-database

post /admin/import/relationships/dry-run



# Add a form field
Source: https://api-docs.helpyousponsor.com/api-reference/forms/add-a-form-field

post /admin/form/field/{id}/{type}
Add a new field to a form



# Bootstrap data for the edit-form-field UI
Source: https://api-docs.helpyousponsor.com/api-reference/forms/bootstrap-data-for-the-edit-form-field-ui

get /admin/edit_form_field/{id}/{type}
Returns the field record (`Donorfield` when `type=donor`, otherwise `Field`) along with the catalog of allowed field types for that bucket and the active payment gateway snapshot (used to gate credit-card-related field types). Powers the field edit modal in the admin form builder. Requires permission: `manage_programs`.



# Bulk-create or bulk-update form fields
Source: https://api-docs.helpyousponsor.com/api-reference/forms/bulk-create-or-bulk-update-form-fields

post /admin/form/bulk_edit
Walks the request body (an array of field-data rows), and per row either creates a new field (`id` missing or 0) or updates the matching field. Stops short and returns the first error response if any single row update/create fails. Queues the tenant-scoped Meilisearch filter refresh and reindex after the database change commits. The exact field-data shape mirrors the single-field create/update payloads (label, key, type, data, permissions, required, is_title, sortable, filter, field_order, etc.). Requires permission: `manage_programs`.



# Create a new form
Source: https://api-docs.helpyousponsor.com/api-reference/forms/create-a-new-form

post /admin/forms



# Delete a form
Source: https://api-docs.helpyousponsor.com/api-reference/forms/delete-a-form

delete /admin/forms/{hysform_id}
Delete a form by its id



# Delete a form field
Source: https://api-docs.helpyousponsor.com/api-reference/forms/delete-a-form-field

delete /admin/form/field
Delete an existing field in a form



# Donor field permissions with per-program overrides
Source: https://api-docs.helpyousponsor.com/api-reference/forms/donor-field-permissions-with-per-program-overrides

get /admin/program/{program_id}/donor-field-overrides
Returns the donor form's full field catalog (custom `Donorfield` rows + standardized fields when `standardizedFieldsEnabled`) with each row's default permissions plus any per-program override stored in `program_permissions`. Powers the per-program permission editor on the program settings screen. Requires permission: `manage_programs`.



# Edit a form field
Source: https://api-docs.helpyousponsor.com/api-reference/forms/edit-a-form-field

put /admin/form/field
Edit an existing field in a form



# Form Details
Source: https://api-docs.helpyousponsor.com/api-reference/forms/form-details

get /admin/forms/{hysform_id}
Form Details



# Form field types
Source: https://api-docs.helpyousponsor.com/api-reference/forms/form-field-types

get /admin/form/field/{id}/{type}



# Get all donor forms by client id
Source: https://api-docs.helpyousponsor.com/api-reference/forms/get-all-donor-forms-by-client-id

get /donors/{client_id}/forms
List donor forms for a client.



# Get all forms
Source: https://api-docs.helpyousponsor.com/api-reference/forms/get-all-forms

get /admin/forms
Returns a list of all forms for a specific client



# Get donor standardization run status
Source: https://api-docs.helpyousponsor.com/api-reference/forms/get-donor-standardization-run-status

get /admin/forms/{hysform_id}/standardization/runs/{run_id}
Returns one tenant-scoped diagnostic run. By default the response is compact for polling. Set include_results=true to include the summary and at most 100 issue rows.



# Get form fields for a program
Source: https://api-docs.helpyousponsor.com/api-reference/forms/get-form-fields-for-a-program

get /admin/program/{program_id}/form-fields
Returns both donor fields and entity fields for a specific program



# Get the standardized donor field settings for a donor form
Source: https://api-docs.helpyousponsor.com/api-reference/forms/get-the-standardized-donor-field-settings-for-a-donor-form

get /admin/forms/{hysform_id}/standard-field-settings
Returns the ordered server-authoritative donor field registry with applicability, presentation kind, capabilities, effective configuration, revisions, email policy, and rollout state. Requires form access.



# Manage a form
Source: https://api-docs.helpyousponsor.com/api-reference/forms/manage-a-form

get /admin/forms/{hysform_id}/manage



# Persist a reordered form-field list
Source: https://api-docs.helpyousponsor.com/api-reference/forms/persist-a-reordered-form-field-list

get /admin/form/fields/order/{type}
Walks `item[]` from the request and writes its index back to each field's `field_order`, in order. Operates on `Donorfield` rows when `type=donor`, otherwise `Field` rows. Refuses to reorder donor fields that are locked compatibility fields (returns 422). Flushes the relevant per-form caches, clears the cached entity/donor data, and queues the tenant-scoped entity/sponsorship search refresh so title-field display-name order remains current. Verb is GET (legacy ergonomics) — newer integrations should expect this to migrate to PUT/PATCH. Requires permission: `manage_programs`.



# Queue a donor standardization audit
Source: https://api-docs.helpyousponsor.com/api-reference/forms/queue-a-donor-standardization-audit

post /admin/forms/{hysform_id}/standardization/audit
Queues the tenant-scoped donor audit and returns its pending run immediately. Poll GET /admin/forms/{hysform_id}/standardization/runs/{run_id} for completion. The legacy GET route remains synchronous for compatibility.



# Reset program donor-field visibility overrides
Source: https://api-docs.helpyousponsor.com/api-reference/forms/reset-program-donor-field-visibility-overrides

delete /admin/program/{program_id}/donor-field-overrides
Removes this program’s custom and standardized donor-field permission overrides so inherited donor-form settings apply again. Requires the current expected_program_revision; a stale revision returns409 with the current program_revision. Changed field rows increment their revisions and the program revision increments only when at least one override was removed. Refreshes cached donor field options after commit. Requires permission: one of manage_programs.



# Standardization step 1 — audit current state
Source: https://api-docs.helpyousponsor.com/api-reference/forms/standardization-step-1-—-audit-current-state

get /admin/forms/{hysform_id}/standardization/audit
First step of the donor-form standardization rollout. Runs `DonorStandardizationService::audit` to inventory current custom fields against the standardized field catalog, returning the resulting run record plus a fresh rollout payload. Caller's user id is logged on the run. Form must be a donor form belonging to the active client (404 otherwise). Requires permission: `manage_programs`.



# Standardization step 2 — preview the migration with a candidate mapping
Source: https://api-docs.helpyousponsor.com/api-reference/forms/standardization-step-2-—-preview-the-migration-with-a-candidate-mapping

post /admin/forms/{hysform_id}/standardization/preview
Dry-run for the standardization migration. Runs `DonorStandardizationService::preview` against the supplied custom-field → standardized-field `mapping` (or empty) and returns the resulting preview run record. No data is written. Body field `mapping` is silently ignored when not an array. Requires permission: `manage_programs`.



# Standardization step 3 — queue the data migration
Source: https://api-docs.helpyousponsor.com/api-reference/forms/standardization-step-3-—-queue-the-data-migration

post /admin/forms/{hysform_id}/standardization/migrate
Live migration. Runs `DonorStandardizationService::startMigration` to queue the background job that copies legacy custom-field values into the standardized columns using the supplied mapping. Returns the run record so the UI can poll progress. Mirrors the `previewStandardization` body shape. Requires permission: `manage_programs`.



# Standardization step 4 — verify the migrated data
Source: https://api-docs.helpyousponsor.com/api-reference/forms/standardization-step-4-—-verify-the-migrated-data

post /admin/forms/{hysform_id}/standardization/verify
Post-migration verification. Runs `DonorStandardizationService::verify` to compare standardized columns against their legacy custom-field sources for drift, returning the verification run plus a fresh rollout payload. Required to flip the form into the `verified` state before `finalize`. Requires permission: `manage_programs`.



# Standardization step 5 — finalize and lock the form
Source: https://api-docs.helpyousponsor.com/api-reference/forms/standardization-step-5-—-finalize-and-lock-the-form

post /admin/forms/{hysform_id}/standardization/finalize
Final step. Pre-checks `buildRolloutEligibility` (returns 422 with the failing reasons when the form is not ready) and then calls `DonorStandardizationService::finalize` to lock the form into the standardized state. Returns the run plus a fresh rollout payload. After this point the legacy custom fields participating in the migration are read-only. Requires permission: `manage_programs`.



# Standardization step 6 — roll back the rollout
Source: https://api-docs.helpyousponsor.com/api-reference/forms/standardization-step-6-—-roll-back-the-rollout

post /admin/forms/{hysform_id}/standardization/rollback
Reverses an earlier standardization rollout step. Runs `DonorStandardizationService::rollback` to unlock the form and restore the previous custom-field configuration, returning the rollback run plus a fresh rollout payload. Generally only safe before `finalize` — post-finalize rollback may leave gaps. Requires permission: `manage_programs`.



# Update a form
Source: https://api-docs.helpyousponsor.com/api-reference/forms/update-a-form

put /admin/forms/{hysform_id}
Update a form



# Upsert a per-program donor-field permission override
Source: https://api-docs.helpyousponsor.com/api-reference/forms/upsert-a-per-program-donor-field-permission-override

put /admin/program/{program_id}/donor-field-overrides
Sets the per-program permission override on a single donor field — either a custom field (via `donorfield_id`) or a standardized field (via `standard_field_key`). Exactly one identifier is required. Null or the field default removes the override. Loaded field and program revisions are required for stale-write protection. Requires permission: `manage_programs`.



# Upsert one standardized donor field setting
Source: https://api-docs.helpyousponsor.com/api-reference/forms/upsert-one-standardized-donor-field-setting

put /admin/forms/{hysform_id}/standard-field-settings
Partially updates one configurable standardized donor field. Invalid values return 422; omitted attributes, compatibility mappings, and program overrides are preserved. `expected_revision` is required for stale-write protection. Requires the `forms` permission.



# Add a designation to the checkout
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/add-a-designation-to-the-checkout

post /frontend/checkout/designation/{client_id}/{program_id}/{currency}/{session_id}



# Checkout
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/checkout

get /frontend/order/{client_id}/{program_id}/{session_id}
Order to sponsor an entity



# Create a new donor and process their donation
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/create-a-new-donor-and-process-their-donation

post /frontend/checkout/signup/{client_id}/{program_id}/{session_id}



# Handle the checkout process for sponsorships
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/handle-the-checkout-process-for-sponsorships

get /frontend/order/sponsorships/{client_id}/{program_id}/{session_id}



# Login a donor and process their donation
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/login-a-donor-and-process-their-donation

post /frontend/checkout/login/{client_id}/{program_id}/{session_id}



# Update the frequency for a specific designation in the checkout
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/update-the-frequency-for-a-specific-designation-in-the-checkout

put /frontend/checkout/designation/frequency/{client_id}/{program_id}/{designation_id}/{frequency}/{session_id}



# View a random entity
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/view-a-random-entity

get /frontend/entities/random/{client_id}/{program_id}
Returns a random entity from a specific client and program



# View entity details
Source: https://api-docs.helpyousponsor.com/api-reference/frontend/view-entity-details

get /frontend/entity/{client_id}/{program_id}/{entity_id}/{session_id}



# Acknowledge a fundraising gift
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/acknowledge-a-fundraising-gift

post /admin/donation/{donation_id}/acknowledge
Records acknowledgement evidence for one readable organization gift and closes matching acknowledgement Work. Do Not Acknowledge gifts are rejected. The operation records work already performed and does not send a receipt. Requires permission: one of donations.



# Add a stewardship-plan move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/add-a-stewardship-plan-move

post /admin/fundraising/stewardship-plans/{plan_id}/moves
Creates a planned move. The contact defaults to the plan contact and must be eligible; owner must be an active organization user. A supplied version is validated but is not used for creation concurrency. The status field is prohibited. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Apply selected relationship-provisioning candidates
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/apply-selected-relationship-provisioning-candidates

post /admin/fundraising/relationship-provisioning/apply
Requires stewardship_relationship_groups_v1 and unrestricted donor-form visibility. Revalidates the exact preview fingerprint and applies 1–100 available candidate keys independently; failures are reported per candidate and successful accounts are retained. Requires permission: donors_view; plus one of manage_settings, access_account_settings; plus one of donors_manage.



# Approve a handwritten-card order
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/approve-a-handwritten-card-order

post /admin/handwrytten/orders/{handwryttenOrderId}/approve
Approves a current, unblocked commercial quote and records approval evidence. Rejected cards require a new draft; submitted orders cannot gain a new local approval. An already-approved submitted order is returned unchanged. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_manage, manage_email.



# Archive a stewardship plan
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/archive-a-stewardship-plan

post /admin/fundraising/stewardship-plans/{plan_id}/archive
Uses the plan version and required reason. Archives the plan and saves an annual review; history is retained. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Assign a donor or household relationship manager
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/assign-a-donor-or-household-relationship-manager

put /admin/fundraising/caseload/{donor_id}/assignment
Assigns an eligible resource-authorized fundraiser; relationship_manager_user_id takes precedence over legacy assigned_fundraiser_user_id. Null/omitted clears assignment. Household scope applies to the whole household. Reconciles plan authority and owners; a committed assignment can return projection_refresh_pending. Requires permission: donors_view; plus one of donors_manage.



# Assign a donor or household relationship manager
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/assign-a-donor-or-household-relationship-manager-1

put /admin/fundraising/portfolio/{donor_id}/assignment
Assigns an eligible resource-authorized fundraiser; relationship_manager_user_id takes precedence over legacy assigned_fundraiser_user_id. Null/omitted clears assignment. Household scope applies to the whole household. Reconciles plan authority and owners; a committed assignment can return projection_refresh_pending. Requires permission: donors_view; plus one of donors_manage.



# Assign a giving-anniversary owner
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/assign-a-giving-anniversary-owner

post /admin/giving-anniversaries/opportunities/{id}/assign
Assigns a tenant-owned staff user as the manual owner; omit or set owner_user_id=null to clear the owner. Requires permission: donors_view; plus one of donors_manage, donations, interactions_manage, mailings_generate, mailings_manage, manage_email.



# Assign a stewardship-relationship manager
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/assign-a-stewardship-relationship-manager

put /admin/fundraising/relationship-groups/{relationship_group_id}/assignment
Requires stewardship_relationship_groups_v1. Assigns an eligible fundraiser across the relationship's governed donor resources; null clears explicit assignment. Rechecks plan impact and refreshes projection/owners; committed recovery warnings may be included. Requires permission: donors_view; plus one of donors_manage.



# Cancel a stewardship-plan move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/cancel-a-stewardship-plan-move

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/cancel
Uses the move version and requires a non-empty reason. Only planned/in-progress moves can be canceled; cancellation retains immutable history. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Cancel a submitted handwritten-card order
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/cancel-a-submitted-handwritten-card-order

post /admin/handwrytten/orders/{handwryttenOrderId}/cancel
Requests provider cancellation for an order not yet sent/delivered/completed. Local drafts cannot use this operation. Confirmed cancellation updates status and restores eligible reserved/spent balance; provider refusal returns validation error. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_manage, manage_email.



# Complete a stewardship-plan move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/complete-a-stewardship-plan-move

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/complete
Uses the move version. Completion defaults to manual; task requires a completed linked Task and interaction requires linked completion evidence. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Create a handwritten-card draft and quote
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/create-a-handwritten-card-draft-and-quote

post /admin/handwrytten/drafts
Requires message_template or message. Resolves optional donor/mailing/Work sources, eligible country, sender defaults, card/font, merge fields, suppression, budget and current customer price. A created blocked draft returns 201 with blocking reasons; it has not been approved or sent. Source recipients must agree and active duplicates are refused. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_generate, mailings_manage, manage_email.



# Create a handwritten-card stewardship rule
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/create-a-handwritten-card-stewardship-rule

post /admin/handwrytten/rules
Creates a rule, inactive by default. Trigger/action/approval/budget configurations are saved as supplied. Giving and sponsorship anniversary triggers belong to the canonical anniversary queue. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# Create a stewardship plan
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/create-a-stewardship-plan

post /admin/fundraising/stewardship-plans
Creates a draft qualifying or managed plan for one relationship and period. Qualifying plans apply the ten-step qualification template by default. Overlapping non-archived subject scope conflicts; action_donor_id must be eligible for this subject. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Create a stewardship relationship
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/create-a-stewardship-relationship

post /admin/fundraising/relationship-groups
Requires stewardship_relationship_groups_v1. Creates an active group with one unique donor/household core and up to100 distinct links. All-qualified giving vehicles can belong to one active group only. Material plan impact requires a current lifecycle preview and explicit repairs. Requires permission: donors_view; plus one of donors_manage.



# Deactivate a stewardship relationship
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/deactivate-a-stewardship-relationship

delete /admin/fundraising/relationship-groups/{relationship_group_id}
Requires stewardship_relationship_groups_v1. Deactivates while retaining historical links, removes live portfolio projection and reconciles affected plans/owners. Plan repairs/confirmation are required when material impact exists. Requires permission: donors_view; plus one of donors_manage.



# Dismiss a giving-anniversary opportunity
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/dismiss-a-giving-anniversary-opportunity

post /admin/giving-anniversaries/opportunities/{id}/dismiss
Marks the work item dismissed and records the supplied reason/note in lifecycle evidence. Requires permission: donors_view; plus one of donors_manage, donations, interactions_manage, mailings_generate, mailings_manage, manage_email.



# Download a handwriting-preview font
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/download-a-handwriting-preview-font

get /admin/handwrytten/orders/{handwryttenOrderId}/proof/font
Streams the available font for the order from its matching active catalog; returns 404 when no preview asset exists and 502 when the provider asset cannot be downloaded. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of groups, admins, forms, manage_programs, programs_view, donors_view, donations, manage_email, email_manager, manage_sms, sms_manager, sms_inbox_view, sms_inbox_reply, sms_inbox_manage, sendblue_manage, mailings_view, mailings_generate, mailings_manage, manage_settings, access_account_settings, access_payment_gateways, tasks_view, tasks_manage, trips_view, events_view, events_checkin, events_finance, events_reports, events_sponsor_manage, imports_view, activity_logs_view, households_view, notes_view, reports_view.



# Export a fundraising cohort bucket
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/export-a-fundraising-cohort-bucket

get /admin/fundraising/cohorts/{bucket}/export
Streams the entire permitted bucket as CSV with donor/household and comparison amount fields. Requires permission: one of donors_view.



# Export a personal engagement worksheet
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/export-a-personal-engagement-worksheet

get /admin/fundraising/portfolio/md-pep/export
Requires stewardship_major_donor_plans_v1. Downloads an XLSX for the complete permitted portfolio selection, with the same year, 2,000-row, currency and private-strategy rules as the worksheet. Requires permission: one of donors_view.



# Export fundraising relationship contacts
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/export-fundraising-relationship-contacts

get /admin/fundraising/interactions/export
Streams all permitted canonical contact rows as CSV with meaningfulness and manager fields. Respects current viewer privacy; does not send communications. Requires permission: one of donors_view.



# Export fundraising stewardship Work
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/export-fundraising-stewardship-work

get /admin/fundraising/work-items/export
Streams the full permitted Work selection as CSV with owner/source fields, respecting relationship and plan-feature visibility. Requires permission: one of donors_view.



# Export fundraising transactions
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/export-fundraising-transactions

get /admin/fundraising/transactions/export
Streams the entire permitted transaction selection as CSV, including acknowledgement and method fields. Formula-leading cells are escaped. Requires permission: one of donors_view.



# Export giving-anniversary opportunities
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/export-giving-anniversary-opportunities

get /admin/giving-anniversaries/opportunities/export
Downloads CSV rows for the same permitted anniversary, relationship, milestone and giving-gap filters as the queue. Cells are escaped against spreadsheet formula execution. Requires permission: one of donors_view.



# Install fundraising default saved views
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/install-fundraising-default-saved-views

post /admin/fundraising/install-default-views
Creates or restores the Upcoming Giving Anniversaries view, idempotently by organization/name/module; returns ids and which views were newly created. Requires permission: donors_view; plus one of reports_manage, manage_settings.



# Link a Task to a stewardship move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/link-a-task-to-a-stewardship-move

put /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/task
Uses the move version. The Task must be visible, belong to this organization and have the move action contact as its primary donor. Synchronizes task completion evidence. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Link interaction evidence to a stewardship move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/link-interaction-evidence-to-a-stewardship-move

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/evidence
Uses the move version. Evidence must be accessible and linked to its action contact. Completion evidence completes the move; future or canceled calendar events cannot provide completion. Linking an existing record updates its role. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# List available handwritten-card catalog items
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-available-handwritten-card-catalog-items

get /admin/handwrytten/catalog
Returns active catalog items grouped by item_type, optionally filtered by type. Managed catalog uses public stock; no active catalog returns an empty array. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of access_account_settings, manage_settings, mailings_view, mailings_generate, mailings_manage, manage_email.



# List eligible relationship managers
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-eligible-relationship-managers

get /admin/fundraising/fundraisers
Returns role/resource-eligible candidates, retaining current assignees who now need reassignment. Optional donor/household/group scope requires matching donor visibility. Requires permission: one of donors_view.



# List eligible relationship managers
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-eligible-relationship-managers-1

get /admin/fundraising/relationship-managers
Returns role/resource-eligible candidates, retaining current assignees who now need reassignment. Optional donor/household/group scope requires matching donor visibility. Requires permission: one of donors_view.



# List eligible unacknowledged gifts
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-eligible-unacknowledged-gifts

get /admin/fundraising/unacknowledged-gifts
Returns the transaction contract with unacknowledged and qualified scope enforced, excluding Do Not Acknowledge gifts and respecting the stewardship work policy. Requires permission: one of donors_view.



# List fundraising caseload
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-fundraising-caseload

get /admin/fundraising/caseload
Legacy alias of the portfolio list with the same projection, household, relationship, planning and donor-visibility rules. Requires permission: one of donors_view.



# List fundraising portfolio relationships
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-fundraising-portfolio-relationships

get /admin/fundraising/portfolio
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.



# List fundraising relationship contacts
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-fundraising-relationship-contacts

get /admin/fundraising/interactions
Lists canonical qualifying contacts with viewer-specific privacy filtering; optional meaningful filter narrows rows while summary retains the contact scope. Returns comparison statistics when a comparison period was selected. Requires permission: one of donors_view.



# List fundraising stewardship Work
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-fundraising-stewardship-work

get /admin/fundraising/work-items
Pages persisted Work with status/type facets and projection freshness. Plan move Work is included only when its feature is enabled and plan summary is readable; can_manage_plan controls the permitted action. Requires permission: one of donors_view.



# List fundraising transactions
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-fundraising-transactions

get /admin/fundraising/transactions
Lists scoped gift ledger rows and complete filtered net totals. Qualified/exceptions/all status scopes and acknowledgement backlog/period scope are distinct. Currency and resolved method labels are returned per gift. Requires permission: one of donors_view.



# List giving-anniversary opportunities
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-giving-anniversary-opportunities

get /admin/giving-anniversaries/opportunities
Lists permission-scoped anniversary work items, due items first. Default status includes active opportunities; status=all includes terminal items. Timing narrows the active tab while summary counts retain the wider status scope. Requires permission: one of donors_view.



# List handwritten-card orders
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-handwritten-card-orders

get /admin/handwrytten/queue
Returns newest-first order projections with approval/status/queue-state filters and current operational readiness. Practice verification appears as verification_complete in item status. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email.



# List handwritten-card stewardship rules
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-handwritten-card-stewardship-rules

get /admin/handwrytten/rules
Lists organization-owned first/major-gift and lapsed-donor rules, newest first. Giving anniversaries use the canonical anniversary queue. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# List one fundraising cohort bucket
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-one-fundraising-cohort-bucket

get /admin/fundraising/cohorts/{bucket}
Pages one financial-ledger cohort. include_transactions adds up to100 gift rows per side to each row. An unknown bucket returns an empty selection. Requires permission: one of donors_view.



# List stewardship-plan reviews
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-stewardship-plan-reviews

get /admin/fundraising/stewardship-plans/{plan_id}/reviews
Requires can_view_strategy in addition to summary access. Returns newest review first; redacted summaries remain placeholders. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility.  Requires permission: one of donors_view.



# List stewardship relationships
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/list-stewardship-relationships

get /admin/fundraising/relationship-groups
Requires stewardship_relationship_groups_v1. Lists active readable relationships, core members and typed links, ordered by display name. Requires permission: one of donors_view.



# Mark a giving anniversary acted
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/mark-a-giving-anniversary-acted

post /admin/giving-anniversaries/opportunities/{id}/mark-acted
Records the staff action and note, sets acted status and timestamp and clears snooze/dismissal state. This marks work performed; it does not send a message. Requires permission: donors_view; plus one of donors_manage, donations, interactions_manage, mailings_generate, mailings_manage, manage_email.



# Prepare a lost-donor reactivation action
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/prepare-a-lost-donor-reactivation-action

post /admin/fundraising/cohorts/{bucket}/reactivation
Only bucket=lost_donors is supported. Enabled action may prepare an audience, install a saved cohort view or create deduplicated reactivation Work, optionally routed to relationship managers. Does not send outreach. Requires permission: donors_view; plus one of donors_manage.



# Preview a fundraising stewardship digest
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/preview-a-fundraising-stewardship-digest

get /admin/fundraising/digest/preview
Returns current configured digest settings, overview metrics/alerts and25 Work rows. This operation does not send a digest. Requires permission: one of donors_view.



# Preview relationship changes affecting stewardship plans
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/preview-relationship-changes-affecting-stewardship-plans

post /admin/fundraising/stewardship-plans/lifecycle-impact
Requires the relationship-groups feature and donors_manage. Command and operation must match. Returns affected scopes, collisions and repairs plus a five-minute impact_version; this preview does not perform the proposed mutation. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility.  Requires permission: donors_view; plus one of donors_manage.



# Preview stewardship relationship provisioning
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/preview-stewardship-relationship-provisioning

get /admin/fundraising/relationship-provisioning/preview
Requires stewardship_relationship_groups_v1 and unrestricted donor-form visibility. Reads enabled reciprocal relationship mappings and soft-credit evidence, returning available/blocked/review candidates with a policy/evidence fingerprint. Does not create groups. Requires permission: one of donors_view.



# Purchase or resume a Postal Mail balance pack
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/purchase-or-resume-a-postal-mail-balance-pack

post /admin/handwrytten/credits/purchase
Charges the organization saved billing method for a configured pack and returns its successful ledger entry. Requires raw access_payment_gateways and complete funding readiness. Reuse idempotency_key, or pending_purchase_reference from credits, to resume an existing attempt; pending/manual-review/terminal payment outcomes return 422 rather than a successful top-up. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: access_payment_gateways (raw capability).



# Queue bulk fundraising gift acknowledgement
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/queue-bulk-fundraising-gift-acknowledgement

post /admin/donations/acknowledge
Returns202 with a durable operation receipt. Supply donation_ids, or select_all_matching=true with validated transaction filters. Selection is restricted to readable unacknowledged gifts and excludes Do Not Acknowledge. Poll status_url for completion; queue acceptance does not imply gifts are already updated. Requires permission: one of donations.



# Read a donor comparison-period gift evidence
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-donor-comparison-period-gift-evidence

get /admin/fundraising/transactions/donor/{donor_id}/evidence
Returns up to100 individual donor gift rows per current/comparison window plus complete summaries. Defaults status_scope to all; does not expand to household sibling gifts. Requires permission: one of donors_view.



# Read a donor giving-anniversary summary
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-donor-giving-anniversary-summary

get /admin/donors/{donor_id}/giving-anniversaries
Returns canonical milestone signals and up to ten readable opportunities for this donor. Shared household/relationship evidence is exposed only when the viewer can read the whole subject. Requires permission: one of donors_view.



# Read a donor stewardship-relationship memberships
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-donor-stewardship-relationship-memberships

get /admin/fundraising/relationship-groups/for-donor/{donor_id}
Returns readable core, household and linked relationships for a live donor. The first relationship is ranked by current donor role. This method has no direct relationship-feature gate. Requires permission: one of donors_view.



# Read a fundraising donor profile
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-fundraising-donor-profile

get /admin/fundraising/caseload/{donor_id}
Returns ready donor relationship facts, eligible action contacts and recent gifts/attribution/interactions. Requires readable donor relationship closure; private email details and unreadable linked groups are excluded. Requires permission: one of donors_view.



# Read a fundraising donor profile
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-fundraising-donor-profile-1

get /admin/fundraising/portfolio/{donor_id}
Returns ready donor relationship facts, eligible action contacts and recent gifts/attribution/interactions. Requires readable donor relationship closure; private email details and unreadable linked groups are excluded. Requires permission: one of donors_view.



# Read a fundraising household profile
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-fundraising-household-profile

get /admin/fundraising/portfolio/household/{household_id}
Returns aggregated ready household facts, member contacts and recent relationship evidence. Every household member must be readable. Requires permission: one of donors_view.



# Read a fundraising relationship profile
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-fundraising-relationship-profile

get /admin/fundraising/relationship-groups/{relationship_group_id}/profile
Requires stewardship_relationship_groups_v1 and a ready portfolio projection. Returns relationship-attributed facts and permitted contact evidence for the core and giving vehicles. Requires permission: one of donors_view.



# Read a giving-anniversary opportunity
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-giving-anniversary-opportunity

get /admin/giving-anniversaries/opportunities/{id}
Reads one permitted work item with refreshed action-contact readiness, source giving information and reverse-chronological lifecycle events. Requires permission: one of donors_view.



# Read a handwritten-card proof
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-handwritten-card-proof

get /admin/handwrytten/orders/{handwryttenOrderId}/proof
Returns resolved message, address checks, matching artwork/handwriting preview and blocking reasons for one organization-owned order. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email.



# Read a personal engagement worksheet
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-personal-engagement-worksheet

get /admin/fundraising/portfolio/md-pep
Requires stewardship_major_donor_plans_v1. Reads the complete selected portfolio to calculate currency-aware totals, then pages worksheet rows. Plan period must stay within one calendar year; at most 2,000 complete search matches. Strategy/month moves appear only for manageable plans. Requires permission: one of donors_view.



# Read a stewardship-plan workspace
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-stewardship-plan-workspace

get /admin/fundraising/stewardship-plans/{plan_id}
Returns summary metrics and permission-dependent strategy, move and review detail. Opening records a workspace telemetry event. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility.  Requires permission: one of donors_view.



# Read a stewardship relationship
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-a-stewardship-relationship

get /admin/fundraising/relationship-groups/{relationship_group_id}
Requires stewardship_relationship_groups_v1 and full subject readability. Returns core, links and detailed missing-attribution evidence. Requires permission: one of donors_view.



# Read fundraising donor cohorts
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-fundraising-donor-cohorts

get /admin/fundraising/cohorts
Compares qualified financial-ledger donor/household totals across current and comparison windows using configured upgrade/downgrade thresholds. Returns summaries/explanation and up to50 rows per bucket. Requires permission: one of donors_view.



# Read fundraising filter options
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-fundraising-filter-options

get /admin/fundraising/filter-options
Returns visible states, comparison modes, manager candidates, acknowledgement sources and reporting field definitions. Requires permission: one of donors_view.



# Read fundraising hub settings
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-fundraising-hub-settings

get /admin/fundraising/settings
Returns canonical settings, normalized defaults, setup state and this user's comparison default. Requires permission: one of donors_view.



# Read fundraising overview metrics
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-fundraising-overview-metrics

get /admin/fundraising/overview
Computes current/comparison financial-ledger and contact metrics, stewardship alerts and cohort summaries. Uses a short user/filter/settings cache; refresh bypasses it. Relationship donor visibility and plan feature permissions apply. Requires permission: one of donors_view.



# Read fundraising reporting field definitions
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-fundraising-reporting-field-definitions

get /admin/fundraising/reporting-fields
Returns supported donor-report fields and the default giving-anniversary saved-view specification. Requires permission: one of donors_view.



# Read giving-anniversary settings
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-giving-anniversary-settings

get /admin/giving-anniversaries/settings
Returns canonical anniversary configuration with organization timezone, milestone and digest defaults. Requires permission: one of donors_view.



# Read handwritten-card outcome attribution
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-handwritten-card-outcome-attribution

get /admin/handwrytten/attribution
Defaults to the last 90 days and governance outcome window. Refreshes stored gift associations on a cache miss; refresh bypasses the configured short cache. Reports observed subsequent giving and a matched-control comparison, excluding failed/refunded/nonpositive gifts. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email, reports_view, reports_manage.



# Read handwritten-card spending governance
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-handwritten-card-spending-governance

get /admin/handwrytten/governance
Returns workspace spend caps, approval requirements, suppression, deduplication and address-verification policy; creates defaults when absent. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# Read handwritten-card workspace settings
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-handwritten-card-workspace-settings

get /admin/handwrytten/settings
Returns saved defaults, spending governance, catalog counts and Postal Mail balance with separate funding/fulfillment readiness. May create default preference/governance rows; reading does not grant balance. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of access_account_settings, manage_settings, mailings_view, mailings_generate, mailings_manage, manage_email.



# Read plans for a relationship subject
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-plans-for-a-relationship-subject

get /admin/fundraising/stewardship-plans/subjects/{subject_type}/{subject_id}
Returns the latest non-archived matching plan and ten-plan history. The date overlap filter applies only when both period dates are supplied. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility.  Requires permission: one of donors_view.



# Read Postal Mail balance
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/read-postal-mail-balance

get /admin/handwrytten/credits
Returns available/reserved cents, configured balance packs, auto-reload state, a resumable pending purchase and monthly activity. Reading does not create a free grant. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of access_account_settings, manage_settings, mailings_view, mailings_generate, mailings_manage, manage_email.



# Record a stewardship-plan review
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/record-a-stewardship-plan-review

post /admin/fundraising/stewardship-plans/{plan_id}/reviews
Uses and increments the plan version. Records an append-only review; strategy reviews also refresh strategy-reviewed timestamps. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Record a stewardship Work completion
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/record-a-stewardship-work-completion

post /admin/handwrytten/work-items/{workItemId}/complete
Requires readable Work/donor scope. Logs a manual interaction and acknowledges eligible selected gifts. For handwritten_card, supply an existing order or draft fields; unaccepted/practice cards return pending_submission and leave work/gifts incomplete until live acceptance. Replays preserve interaction and gift selection. Other channels record work already performed; this operation does not send email or SMS. The Handwrytten feature is required only for channel=handwritten_card or a supplied handwrytten_order_id. Requires permission: donors_view; plus one of donors_manage, donations, interactions_manage, mailings_generate, mailings_manage, manage_email.



# Refresh handwritten-card delivery status
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/refresh-handwritten-card-delivery-status

post /admin/handwrytten/orders/{handwryttenOrderId}/sync-status
Polls the recorded provider connection for an assigned vendor order and reconciles monotonic delivery state, confirmed cancellation/refund and pending work completion. Does not resubmit the card. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_manage, manage_email.



# Refresh the handwritten-card catalog
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/refresh-the-handwritten-card-catalog

post /admin/handwrytten/catalog/sync
Synchronously fetches and saves the selected provider catalog, country metadata and defaults. Managed artwork is public stock, excluding private designs/inserts/signatures. Changed quote inputs invalidate unapproved drafts. Stale concurrent refreshes cannot replace newer connection state. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# Reject a handwritten-card order
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/reject-a-handwritten-card-order

post /admin/handwrytten/orders/{handwryttenOrderId}/reject
Rejects a local order and records the optional reason. Orders already submitted or being submitted cannot be rejected locally. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_manage, manage_email.



# Remove a fundraising gift acknowledgement
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/remove-a-fundraising-gift-acknowledgement

post /admin/donation/{donation_id}/unacknowledge
Requires a reason, clears the acknowledgement and retains prior evidence in its audit context. Reconciles corresponding acknowledgement Work. Requires permission: one of donations.



# Reopen a giving-anniversary opportunity
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/reopen-a-giving-anniversary-opportunity

post /admin/giving-anniversaries/opportunities/{id}/reopen
Returns a terminal/snoozed item to its date-derived upcoming, due or missed state. Reopening a household or relationship with no available member returns a conflict. Requires permission: donors_view; plus one of donors_manage, donations, interactions_manage, mailings_generate, mailings_manage, manage_email.



# Reopen a stewardship-plan move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/reopen-a-stewardship-plan-move

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/reopen
Uses the move version. Restores planned by default or in_progress when permitted. Canceled moves remain immutable; unlink completion interaction evidence before reopening. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Reorder a qualification move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/reorder-a-qualification-move

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/reorder
Uses the move version. Swaps this qualification phase with its neighbor, increments changed versions and refreshes Work ordering. Requesting an edge beyond the first/last phase conflicts. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Restore stewardship-move Work
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/restore-stewardship-move-work

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/work/reopen
Uses the move version. Clears the Work snooze and refreshes its projection without reopening the underlying move status. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Retry a failed handwritten-card submission
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/retry-a-failed-handwritten-card-submission

post /admin/handwrytten/orders/{handwryttenOrderId}/retry
Retries only approved or failed_submission orders with no assigned vendor order. An in-flight or unknown submission outcome must be reconciled first. Applies the same approval, funding, sender and provider gates as submission. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_manage, manage_email.



# Roll a managed plan into its next period
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/roll-a-managed-plan-into-its-next-period

post /admin/fundraising/stewardship-plans/{plan_id}/roll-forward
Uses the prior plan version. Requires a managed active/paused/completed plan and an annual review. Incomplete moves must all be future-scheduled and explicitly carried, or resolved first. Creates an active managed successor and completes the prior plan. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Search donor options for stewardship relationships
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/search-donor-options-for-stewardship-relationships

get /admin/fundraising/relationship-groups/donor-options
Requires stewardship_relationship_groups_v1. Returns up to the requested readable live donor/organization options (default30, maximum50). Requires permission: one of donors_view.



# Search handwritten-card recipients
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/search-handwritten-card-recipients

get /admin/handwrytten/recipients
Searches readable donor identity and email fields; requires at least two characters. Reviews at most 200 candidates and returns at most 20 matches with donor profile postal fields and resolved provider country. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_view, mailings_generate, mailings_manage, manage_email; plus one of donors_view, donors_manage.



# Skip a stewardship-plan move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/skip-a-stewardship-plan-move

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/skip
Uses the move version and requires a non-empty reason. Only planned/in-progress moves can be skipped. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Snooze a giving-anniversary opportunity
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/snooze-a-giving-anniversary-opportunity

post /admin/giving-anniversaries/opportunities/{id}/snooze
Defers the work item until the end of the selected date and records its lifecycle note. Requires permission: donors_view; plus one of donors_manage, donations, interactions_manage, mailings_generate, mailings_manage, manage_email.



# Snooze stewardship-move Work
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/snooze-stewardship-move-work

post /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/work/snooze
Uses the move version. Only an active plan's scheduled open move with an eligible action contact can be snoozed. Returns conflict if its Work projection is not available. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Submit an approved handwritten card
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/submit-an-approved-handwritten-card

post /admin/handwrytten/orders/{handwryttenOrderId}/submit
Revalidates provider identity, sender, suppression, budget, approved quote and funding before sending. Live managed submission reserves/spends Postal Mail balance and may trigger authorized auto-reload; practice does not spend balance or complete outreach. Idempotent accepted orders return existing results; an ambiguous provider outcome is retained for reconciliation and returns 422. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of mailings_manage, manage_email.



# Transition a stewardship plan
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/transition-a-stewardship-plan

post /admin/fundraising/stewardship-plans/{plan_id}/transition
Uses the plan version. Activation requires a contact; managed activation/promotion requires tier and goal. Pause requires reason and next review date. Not-qualified and complete-period require reasons; complete-period also requires every move resolved. Adds a stage/annual review. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Unlink a Task from a stewardship move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/unlink-a-task-from-a-stewardship-move

delete /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/task
Uses the move version. Removes the Task link, preserving explicit manual completion if present; otherwise task-based completion reverts to planned/in_progress. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Unlink interaction evidence from a stewardship move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/unlink-interaction-evidence-from-a-stewardship-move

delete /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}/evidence/{evidence_id}
Uses the move version and the evidence-link id. Removing the last completion evidence falls back to manual or completed-Task proof, otherwise restores planned/in_progress. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Update a stewardship-plan move
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/update-a-stewardship-plan-move

put /admin/fundraising/stewardship-plans/{plan_id}/moves/{move_id}
Uses the move version, not the plan version. Canceled moves cannot be edited. Reopen terminal moves before changing schedule, owner or contact; unlink Task and interaction evidence before changing contact. The status field is prohibited. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Update a stewardship relationship
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/update-a-stewardship-relationship

put /admin/fundraising/relationship-groups/{relationship_group_id}
Requires stewardship_relationship_groups_v1. Replaces authored core/link fields; unchanged archived core and already-retained archived links remain valid, while replacements must be live/readable. Material plan impact requires current confirmation/repairs. Requires permission: donors_view; plus one of donors_manage.



# Update fundraising hub settings
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/update-fundraising-hub-settings

put /admin/fundraising/settings
Updates supplied policies and this user's preference. initialize_stewardship requires an unconfigured organization and start date no later than today; repeated initialization conflicts. Scheduling attribution/caseload/interactions or acknowledgement changes queues refresh; planning changes queue plan reconciliation. Requires permission: donors_view; plus one of manage_settings, access_account_settings.



# Update giving-anniversary settings
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/update-giving-anniversary-settings

put /admin/giving-anniversaries/settings
Updates supplied settings and retains existing values for omitted keys. Invalid timezone identifiers and Factory are refused; an empty milestone selection falls back to the existing configured types. Requires permission: donors_view; plus one of manage_settings, access_account_settings.



# Update handwritten-card spending governance
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/update-handwritten-card-spending-governance

put /admin/handwrytten/governance
Updates supplied governance fields and preserves omitted values. Changing CASS verification invalidates unapproved quotes; approved orders retain their quoted option. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# Update handwritten-card workspace defaults
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/update-handwritten-card-workspace-defaults

put /admin/handwrytten/preferences
Saves preferences and optional governance atomically. Changing/clearing auto_reload also requires raw access_payment_gateways. Partner-owned test-mode changes run after commit and return provider_mode_sync; failed, unknown or pending reconciliation outcomes do not roll back saved defaults. Managed practice/live state is controlled by Gratona. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# Update stewardship-plan strategy
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/update-stewardship-plan-strategy

put /admin/fundraising/stewardship-plans/{plan_id}
Uses the plan version. Completed or archived plans cannot be edited. Active/paused plans retain an eligible action contact; managed plans require tier, goal and contact. Requires stewardship_major_donor_plans_v1. Relationship-group subjects also require stewardship_relationship_groups_v1. Subject access respects the viewer's donor visibility. Management requires donors_manage/group_all, or donors_view with assignment as this subject's fundraiser; strategy fields follow the same authority.  Requires permission: donors_view; plus one of donors_view, donors_manage.



# Validate the handwritten-card connection
Source: https://api-docs.helpyousponsor.com/api-reference/fundraising/validate-the-handwritten-card-connection

post /admin/handwrytten/validate-account
Validates and records the selected provider connection and current practice state. Managed mode uses the Gratona key; partner_owned is allowed only when enabled for this organization. include_catalog adds sample counts. A concurrent newer connection change rejects stale validation. Requires the configured Handwrytten feature (normally handwrytten_mailings). Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# List historical archived updates for one donor or recipient
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/list-historical-archived-updates-for-one-donor-or-recipient

get /admin/list_archived_forms/{type}/{id}/{archived_hysform_id}
Read-only compatibility endpoint for donor and recipient archive views. Historical rows remain listable even when the submit form was soft-deleted or is no longer attached to the program.



# Read one historical archived update
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/read-one-historical-archived-update

get /admin/view_archived_form/{archived_form_id}
Read-only compatibility endpoint. Resolves historical field metadata, including soft-deleted submit forms and fields, while scoping every lookup to the authenticated client.



# Retired archived-update authoring bootstrap
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-authoring-bootstrap

get /admin/submit_form/{type}/{id}/{program_id}/{form_id}
Retired with the global legacy Progress Reports authoring workflow. Historical archived updates remain readable through the archive read endpoints.



# Retired archived-update edit bootstrap
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-edit-bootstrap

get /admin/edit_archived_form/{archived_form_id}



# Retired archived-update form attachment
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-form-attachment

post /admin/program/form
Existing entity_submit and donor_submit references are frozen compatibility metadata. This endpoint does not change them.



# Retired archived-update form detachment
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-form-detachment

get /admin/remove_submit_form/{type}/{program_id}/{form_id}
Existing program references are preserved so historical data can be interpreted and rollback remains possible.



# Retired archived-update mutation
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-mutation

post /admin/edit_archived_form/{archived_form_id}



# Retired archived-update notification configuration
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-notification-configuration

get /admin/submit_form_notification/{program_id}/{form_id}



# Retired archived-update notification mutation
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-notification-mutation

post /admin/submit_form_notification/{program_id}/{form_id}



# Retired archived-update submission
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-archived-update-submission

post /admin/submit_form/{type}/{id}/{program_id}/{form_id}
No new FormArchive rows are accepted. The endpoint remains during the compatibility window so old consumers receive an intentional retirement response.



# Retired global Progress Reports email export
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-global-progress-reports-email-export

post /admin/progress_report/email
No new report email jobs are queued. Jobs already in the queue remain executable during the compatibility window.



# Retired global Progress Reports list
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-global-progress-reports-list

post /admin/progress_report



# Retired global Progress Reports module
Source: https://api-docs.helpyousponsor.com/api-reference/historical-archived-updates/retired-global-progress-reports-module

get /admin/progress_report
Reports Hub is the only global reporting destination. This compatibility endpoint never lists archived data.



# Approve a story for reuse
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/approve-a-story-for-reuse

post /admin/impact-stories/{storyId}/approve
Validates story consent against privacy and requires consent for every Library source. Rechecks source access, approval authority and story version under a lock; concurrent edits return 409. Requires the impact_stories feature. Requires permission: one of impact_stories_approve.



# Approve a story offer
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/approve-a-story-offer

post /admin/impact-stories/{storyId}/offers/{offerId}/approve
Marks the selected tenant-owned offer approved and records approval metadata. Requires the impact_stories feature. Requires permission: one of impact_stories_approve.



# Archive an Impact Story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/archive-an-impact-story

post /admin/impact-stories/{storyId}/archive
Marks the story archived and records archival evidence. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Attach a source or upload to a story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/attach-a-source-or-upload-to-a-story

post /admin/impact-stories/{storyId}/assets
Attaches a tenant-owned upload or source link. Library authorization markers cannot be supplied by the caller; approved stories are requeued when their media changes. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Attach authorized Library files to a story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/attach-authorized-library-files-to-a-story

post /admin/impact-stories/{storyId}/library-assets
Resolves every selected Library file, rechecks access under the story lock and avoids duplicate references. Changed media requires review again. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Capture a Slack thread permalink as a story draft
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/capture-a-slack-thread-permalink-as-a-story-draft

post /admin/impact-stories/intake/slack
Stores the supplied permalink and text as draft provenance, reusing an existing matching source identity. This route does not fetch Slack thread content. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Capture a story draft from a shared inbox conversation
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/capture-a-story-draft-from-a-shared-inbox-conversation

post /admin/impact-stories/intake/shared-inbox/{conversationId}
Captures permitted conversation content as a draft, reusing the existing story for the same conversation. Requires beta, story-management and SMS inbox access. Requires the impact_stories feature. Requires permission: one of beta_features; plus one of impact_stories_manage; plus one of sms_inbox_view, sms_inbox_reply, sms_inbox_manage.



# Create an Impact Story draft
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/create-an-impact-story-draft

post /admin/impact-stories
Creates an internal draft by default, records provenance and links permitted primary records. Approval and publication use separate operations. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Create an internal story draft from Library files
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/create-an-internal-story-draft-from-library-files

post /admin/impact-stories/library-media-drafts
Creates a draft from one to 25 accessible Library files. The UUID request_key makes retries return the same draft when content matches; changed content or a deleted prior draft returns 409. Program mapping is inherited only when the selected files agree. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Delete a story intake path
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/delete-a-story-intake-path

delete /admin/impact-stories/intake-paths/{pathId}
Deletes the tenant-owned intake path. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Download a story consent release
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/download-a-story-consent-release

get /admin/impact-stories/{storyId}/releases/{releaseId}/download
Downloads the private consent-release attachment for this story; no file or inaccessible release returns 404. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# Draft an offer from a story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/draft-an-offer-from-a-story

post /admin/impact-stories/{storyId}/offers
Creates an unapproved offer with beneficiary, cost, problem/solution and proposed ask copy. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Inspect program story coverage
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/inspect-program-story-coverage

get /admin/impact-stories/coverage
Returns current approval/consent coverage and stale programs visible to the user. Also reconciles missing/stale story coverage work items for follow-up. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# List governed Impact Stories
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/list-governed-impact-stories

get /admin/impact-stories
Lists stories using editorial filters and safe sort fields. Prefix sort with - for descending; unsupported fields fall back to updated_at. Each row includes current file-clearance reach. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# List saved story import mappings
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/list-saved-story-import-mappings

get /admin/impact-stories/import-mappings
Lists mappings for this organization, optionally filtered by source_type, default mappings first. Requires the impact_stories feature. Requires permission: one of impact_stories_import.



# List stories related to a donor
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/list-stories-related-to-a-donor

get /admin/impact-stories/donors/{donorId}
Returns up to 50 stories linked to the permitted donor, including body and approved offers. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# List story intake paths
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/list-story-intake-paths

get /admin/impact-stories/intake-paths
Lists configured intake paths and unpersisted default setup choices. Reading does not enable a public intake path. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# List story storage provider capabilities
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/list-story-storage-provider-capabilities

get /admin/impact-stories/storage-providers
Lists managed upload, consent release, Drive/link and Slack capture capabilities. A link-capable provider is not a connected live importer. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# Pick stories eligible for reuse
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/pick-stories-eligible-for-reuse

get /admin/impact-stories/picker
Lists approved or published stories. Donor-facing channels require matching consent and current file clearance; public_program additionally requires public-safe consent. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# Prepare an approved story for a destination
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/prepare-an-approved-story-for-a-destination

post /admin/impact-stories/{storyId}/handoff/{channel}
Checks current source authority and consent, freezes reviewed story evidence and creates or links a newsletter, mailing, report, journey template or export destination. Default status is prepared; preparation does not send a communication. Version changes return 409. Requires the impact_stories feature. Requires permission: one of impact_stories_publish.



# Preview a story import batch
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/preview-a-story-import-batch

post /admin/impact-stories/imports/preview
Stores an import receipt and at most 25 preview rows. This step does not import stories. Requires the impact_stories feature. Requires permission: one of impact_stories_import.



# Preview story reuse for a destination
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/preview-story-reuse-for-a-destination

get /admin/impact-stories/{storyId}/reuse-preview/{channel}
Checks current consent, approval and file evidence for the destination before returning a reusable story snapshot. When Spaces clearance is enabled, adds media_clearance. Requires the impact_stories feature. Requires permission: one of impact_stories_publish.



# Process a previewed story import
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/process-a-previewed-story-import

post /admin/impact-stories/imports/{batchId}/process
Processes supplied rows or the stored preview rows with merged mapping. Skips malformed rows and avoids overwriting approved, published or archived stories; counts and per-row errors are returned synchronously. Requires the impact_stories feature. Requires permission: one of impact_stories_import.



# Read a public story intake form
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/read-a-public-story-intake-form

get /frontend/impact-stories/intake/{slug}
Resolves an active public intake slug and the owning organization, allowed programs, provider capabilities and signed-release requirements. Requires the impact_stories feature.



# Read a story import receipt
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/read-a-story-import-receipt

get /admin/impact-stories/imports/{batchId}
Returns preview or processing counts and row errors for the tenant-owned import batch. Requires the impact_stories feature. Requires permission: one of impact_stories_import.



# Read an Impact Story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/read-an-impact-story

get /admin/impact-stories/{storyId}
Returns editorial detail, assets, current source previews, related records, offers, publication evidence and consent releases. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# Read Library media program context
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/read-library-media-program-context

get /admin/impact-stories/library-media-context
Resolves an authorized Library file and its shared-folder program mapping. PUT requires a positive accessible program_id and refuses support sessions; it changes the shared Library folder mapping. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# Read public stories for a program
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/read-public-stories-for-a-program

get /frontend/impact-stories/program/{client_id}/{program_id}
Returns only approved/published stories with public privacy and public-safe consent. Library references are excluded, media clearance hides or replaces blocked files, and only approved offers are exposed. Requires the impact_stories feature.



# Relate a record to a story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/relate-a-record-to-a-story

post /admin/impact-stories/{storyId}/relations
Upserts a relation for the record and role. The record must belong to this organization and be readable by the user. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Remove a story asset
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/remove-a-story-asset

delete /admin/impact-stories/{storyId}/assets/{storyAssetId}
Removes the selected asset from this story and requeues previously approved content for review. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Request context for a story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/request-context-for-a-story

post /admin/impact-stories/{storyId}/request-context
Moves the story to needs_context and records an optional review note. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Review story asset consent and caption
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/review-story-asset-consent-and-caption

patch /admin/impact-stories/{storyId}/assets/{storyAssetId}
Updates caption and consent for the selected story asset. Library access and story version are rechecked; changes can require story reapproval. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Save a story import mapping
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/save-a-story-import-mapping

post /admin/impact-stories/import-mappings
Upserts a mapping by source type and name. Selecting a new default clears the prior default for that source type. Requires the impact_stories feature. Requires permission: one of impact_stories_import.



# Save a story intake path
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/save-a-story-intake-path

post /admin/impact-stories/intake-paths
Creates or updates an intake path by path_key. Public paths use a unique slug and must be active and public before anonymous submissions are accepted. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Save Library media program context
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/save-library-media-program-context

put /admin/impact-stories/library-media-context
Resolves an authorized Library file and its shared-folder program mapping. PUT requires a positive accessible program_id and refuses support sessions; it changes the shared Library folder mapping. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Search records to relate to a story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/search-records-to-relate-to-a-story

get /admin/impact-stories/related-records
Searches currently permitted program, entity or donor records, with at most 20 interleaved results. Reference ids never grant record access. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# Submit a story for review
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/submit-a-story-for-review

post /admin/impact-stories/{storyId}/submit-review
Moves the story to ready_for_review; this does not approve it. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Submit a story with signed consent
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/submit-a-story-with-signed-consent

post /frontend/impact-stories/intake/{slug}
Creates a ready_for_review story from an active public intake path, stores the signed consent release privately and records optional media and offer details. It does not approve or publish the story. Limited to 20 submissions per organization per hour as well as the route throttle. Requires the impact_stories feature.



# Summarize Impact Stories
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/summarize-impact-stories

get /admin/impact-stories/summary
Returns story status, approval, offer, publication and consent-readiness counts. Requires the impact_stories feature. Requires permission: one of impact_stories_view, impact_stories_manage, impact_stories_approve, impact_stories_publish, impact_stories_import.



# Update an Impact Story
Source: https://api-docs.helpyousponsor.com/api-reference/impact-stories/update-an-impact-story

patch /admin/impact-stories/{storyId}
Changes validated editable story fields. Source identity/provenance is preserved; edits to an approved or published story requeue it for review. Requires the impact_stories feature. Requires permission: one of impact_stories_manage.



# Apply an imported gift-owner decision
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/apply-an-imported-gift-owner-decision

post /integrations/hub/connections/{connection_id}/historical-gift-owner-decisions/{conflict_id}/resolve
Checks the current grouped count, amount, current owner and mapped source owner under lock. keep_hys_owner resolves the conflicts without changing gift ownership; use_source_owner moves only the reviewed local gifts, preserves payment/provider records and refreshes affected fundraising projections. Repeated completed decisions return their recorded result. Verify source records before importing more gifts. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Apply reviewed outgoing gift-owner matches
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/apply-reviewed-outgoing-gift-owner-matches

post /integrations/hub/connections/{connection_id}/outbound-donation-owner-decisions/resolve
Accepts 1 to 100 distinct reviewed groups in one currency. Rechecks token, owner, count, total, selected safe mapped candidate and unreserved/undispatched waiting work under lock, then moves only those local gift allocations. Records a completed local audit run and refreshes fundraising projections; it does not queue provider sends or create donors, gifts, payments or messages. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Apply reviewed outgoing outcomes without sending
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/apply-reviewed-outgoing-outcomes-without-sending

post /integrations/hub/connections/{connection_id}/outbound-review/apply
Requires the current outgoing-review token and matching scope. Records deterministic will_skip, waiting and needs_decision outcomes with a local audit run; ready_to_send and uncheckable rows remain untouched. Work that changed under lock is left unchanged. Sends no provider requests. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Approve a historical QuickBooks preview
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/approve-a-historical-quickbooks-preview

post /integrations/hub/connections/{connection_id}/quickbooks/historical/previews/{run_id}/approve
Approves the exact snapshot_hash for a backfill or correction preview in the same connected QuickBooks company. Rechecks stored-plan integrity and every source fingerprint. Repeated approval reuses the existing execution. Captures/queues checkpoints and returns202; provider completion must be checked from the run. Requires a connected QuickBooks company for mutations. Current user/group permissions must include manage_settings, access_account_settings or group_all in addition to route access. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Approve an integration field mapping
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/approve-an-integration-field-mapping

post /integrations/hub/field-mappings/{mapping_id}/approve
Marks the selected version approved with actor/time and supersedes other approved mappings for the same organization/connection/source/target pair. Does not execute a sync. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Authorize the legacy QuickBooks connection
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/authorize-the-legacy-quickbooks-connection

get /admin/quickbooks/authorize
Returns an OAuth authorization URL and persists a fresh state for this organization. switch_company explicitly allows the callback to replace the connected QuickBooks company; follow authUrl to authorize. Requires permission: one of access_payment_gateways.



# Begin Blackbaud authorization
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/begin-blackbaud-authorization

post /integrations/hub/providers/blackbaud-raisers-edge/connect
Starts a15-minute OAuth state for this organization/user, optionally reconnecting an existing Blackbaud connection. Requires enabled/configured Blackbaud OAuth. Opening authorize_url completes the provider authorization through its callback. Requires the integration platform to be enabled globally or by its configured client feature flag (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Begin HubSpot authorization
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/begin-hubspot-authorization

post /integrations/hub/providers/hubspot/connect
Creates an actor/workspace-bound OAuth authorization state lasting 900 seconds and returns the provider URL. Optional connection_id must be an organization-owned HubSpot connection. HubSpot OAuth must be enabled and configured. Opening/finishing the provider authorization flow establishes the connection; this call does not sync records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Begin QuickBooks hub authorization
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/begin-quickbooks-hub-authorization

post /integrations/hub/providers/quickbooks/connect
Creates/updates legacy QuickBooks OAuth state and returns an authorization URL, optionally for an existing QuickBooks connection. switch_company explicitly permits a company change after authorization. Does not complete OAuth or start a data sync. Requires the integration platform to be enabled globally or by its configured client feature flag (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Begin Salesforce nonprofit authorization
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/begin-salesforce-nonprofit-authorization

post /integrations/hub/providers/{provider_key}/salesforce/connect
Selects NPSP or Nonprofit Cloud and returns a PKCE authorization URL with actor/workspace-bound state valid for 900 seconds. Optional connection_id must belong to this organization and the requested template. The selected provider OAuth must be enabled/configured; completing the provider flow establishes the connection without starting data sync. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Begin Slack private-channel authorization
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/begin-slack-private-channel-authorization

post /integrations/hub/providers/slack/connect
Starts a15-minute OAuth flow for a private staff DM. Requires Slack channel OAuth, Workspace Agent channels and rollout, an active eligible user and one of aida_view/aida_capture/aida_review/aida_settings_manage/group_all in addition to account-setting access. Requires the integration platform to be enabled globally or by its configured client feature flag (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Check integration connection health
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/check-integration-connection-health

post /integrations/hub/connections/{connection_id}/health-check
Calls the registered provider adapter, persists status/check time and current error state, and returns the updated safe connection plus provider-specific result. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Check legacy QuickBooks connection status
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/check-legacy-quickbooks-connection-status

get /admin/quickbooks/connection-status
Refreshes credentials and probes CompanyInfo. Normal disconnected/expired states return200 with connected=false and an explanatory message; needs_reauth indicates whether authorization should be repeated. Unexpected outer failures return500. Requires permission: one of access_payment_gateways.



# Check the managed handwritten-card connection
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/check-the-managed-handwritten-card-connection

post /integrations/handwrytten/readiness
Compatibility readiness check for the Gratona-managed provider. Requires configured Handwrytten feature (normally handwrytten_mailings). api_key is prohibited. include_catalog returns existing organization catalog counts; it does not fetch private provider catalog data. Also available through the root unversioned alias. Requires permission: one of account, manage_settings, mailings_manage, access_account_settings (raw capability).



# Connect or reconnect Bloomerang with an API key
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/connect-or-reconnect-bloomerang-with-an-api-key

post /integrations/hub/providers/bloomerang/connect
Verifies the key through Bloomerang and stores the connection, enforcing its existing database/account binding. New connections require api_key; a positive connection_id may omit it to reuse the stored key. Supplied replacement credentials must belong to the existing bound database. Returns safe connection state without credentials; no records are synchronized. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Create a Connected Apps connection
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/create-a-connected-apps-connection

post /integrations/hub/connections
Creates one provider record for this organization using registered provider defaults. Credentials are provider-specific JSON and cause initial connected status only when non-empty; creation does not verify them remotely. An existing provider record must be removed before recreating it. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Create an integration field-mapping draft
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/create-an-integration-field-mapping-draft

post /integrations/hub/connections/{connection_id}/field-mappings
Creates a new draft version for the source/target object pair using supplied ownership, fields, defaults and provider metadata. Does not activate it until approval. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Create an integration mapping-preview shell
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/create-an-integration-mapping-preview-shell

post /integrations/hub/connections/{connection_id}/sync-runs
Creates a completed local shell preview even when a manual/reconcile run_type is selected. Locks currently approved mappings to the run and writes preview events/counters; it does not queue provider import/export work. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Create or refresh an SAP setup workspace
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/create-or-refresh-an-sap-setup-workspace

post /integrations/hub/providers/sap/connect
Creates a connected/warning setup workspace or refreshes an existing SAP connection, discovers and stores provider metadata and ensures approved mapping templates. Company/ledger setup must be completed before exports; Connected Apps registration does not post records. New records return201; refreshes return200. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Disconnect a Connected App
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/disconnect-a-connected-app

delete /integrations/hub/connections/{connection_id}
Disables channel bindings and cancels pending outbound work. QuickBooks compatibility performs its provider-specific disconnect. Other object mappings/cursors remain available for reconnect; Slack/Twilio stored channel credentials are cleared. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Disconnect Dropbox Sign
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/disconnect-dropbox-sign

delete /integrations/dropbox-sign/oauth/disconnect
Deletes the current organization’s stored Dropbox Sign OAuth integration locally. Existing signature records are preserved; this operation does not call the provider token-revocation API. Requires permission: one of access_account_settings.



# Discover imported historical gift-owner mismatches
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/discover-imported-historical-gift-owner-mismatches

post /integrations/hub/connections/{connection_id}/historical-gift-owner-decisions/discover
For Bloomerang only, reads source transactions to verify imported gift ownership and creates local review conflicts. Ambiguous split-designation groups, missing mappings and unverified source records are excluded. Does not modify gifts, payments, sync cursors or provider records; an empty created_count alone does not mean all source rows were verified. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Discover integration provider metadata
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/discover-integration-provider-metadata

post /integrations/hub/connections/{connection_id}/metadata/discover
Calls the registered adapter with provider-specific options and stores the next active snapshot version and schema hash. Does not approve field mappings or run a data sync. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Discover local donations missing outgoing capture
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/discover-local-donations-missing-outgoing-capture

get /integrations/hub/connections/{connection_id}/outbound-discovery
Reviews qualified local non-CSV payment groups that lack provider identity or uncertain existing work. Excludes imports and fully kept-local groups. Returns grouped counts and a token for staging local review; no provider requests are sent. Only Bloomerang donations are supported; limit defaults to 500. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Enable reviewed future sending to Bloomerang
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/enable-reviewed-future-sending-to-bloomerang

post /integrations/hub/connections/{connection_id}/bloomerang/ongoing-sync/outbound/activate
Requires the opaque token from a ready outgoing activation preview plus selected ready object types. Rechecks token organization/connection, expiry, exact configuration and available types under lock, then authorizes only that future outgoing scope. Imports must already be active; pending/processing/failed history must be cleared and open conflicts resolved. No queued history is replayed and this call sends no provider request. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Ensure SAP mapping templates
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/ensure-sap-mapping-templates

post /integrations/hub/connections/{connection_id}/sap/bootstrap-mappings
Creates missing approved templates using current target context and latest metadata, preserving existing approved mappings. Returns relevant versions ordered by source/target/version; may mutate local mapping configuration. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Keep reviewed outgoing gift groups in Gratona
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/keep-reviewed-outgoing-gift-groups-in-gratona

post /integrations/hub/connections/{connection_id}/outbound-donation-owner-decisions/keep-local
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.



# Leave selected reviewed outgoing donations unsent
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/leave-selected-reviewed-outgoing-donations-unsent

post /integrations/hub/connections/{connection_id}/outbound-review/leave-unsent
Requires the current review token and selected ready_to_send event_ids. Records a local skipped decision and audit run without contacting the provider. A future material edit may create new outgoing work for a donation. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Link a program or recipient to a Bloomerang target
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/link-a-program-or-recipient-to-a-bloomerang-target

post /integrations/hub/connections/{connection_id}/bloomerang/recipient-mapping
Requires a contribution/number/campaign program, optional non-deleted recipient in that program, and an available fund/campaign/appeal target. Atomically saves an active designation_target object link, supersedes previous same-type links and removes stale different-provider-id links for that exact local target/type. Updates selected program context without creating a provider object or syncing records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List available background-check packages
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-available-background-check-packages

get /integrations/checkr/packages
Lists normalized package IDs, names and slugs using the current organization’s stored Checkr credentials. Use the slug when starting an invitation; this request does not order a background check. Requires permission: one of access_account_settings.



# List available integration providers
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-available-integration-providers

get /integrations/hub/providers
Synchronizes this organization's registry catalog and returns provider capabilities, supported objects, defaults and effective availability. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List background-check work locations
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-background-check-work-locations

get /integrations/checkr/geos
Lists normalized Checkr Geo IDs, names, state and country for the current organization’s account. Background-check work_locations must use these IDs. Requires permission: one of access_account_settings.



# List Connected Apps
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-connected-apps

get /integrations/hub/connections
Returns organization-owned connections after reconciling the legacy QuickBooks compatibility record, newest update first. Credentials are not included in this list. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List donor identity decisions
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-donor-identity-decisions

get /integrations/hub/connections/{connection_id}/donor-identity-decisions
Returns the latest reviewable conflicted identity evidence, at most 20 rows, excluding superseded/resolved source decisions and active source mappings except missing-source reviews. Includes explicit candidates, current claims, suggestions and guards; does not choose or apply a match. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List historical QuickBooks runs
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-historical-quickbooks-runs

get /integrations/hub/connections/{connection_id}/quickbooks/historical/runs
Returns the latest20 historical preview, backfill, correction-preview and correction runs for this connection, without their events. Requires a connected QuickBooks company for mutations. Current user/group permissions must include manage_settings, access_account_settings or group_all in addition to route access. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List imported historical gift-owner decisions
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-imported-historical-gift-owner-decisions

get /integrations/hub/connections/{connection_id}/historical-gift-owner-decisions
Returns open local imported-transaction owner conflicts grouped by source constituent and current Gratona owner, with actual count/total and expected guards. Does not change gift ownership or contact the provider. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List integration conflicts
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-integration-conflicts

get /integrations/hub/connections/{connection_id}/conflicts
Returns all stored conflicts for this connection, newest detected first, including resolved records, raw stored snapshots/resolution history and specialized relationship or recurring review details. No filtering or pagination is applied. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List integration field-mapping versions
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-integration-field-mapping-versions

get /integrations/hub/connections/{connection_id}/field-mappings
Returns all mapping versions for the selected connection, newest update first. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List integration metadata snapshots
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-integration-metadata-snapshots

get /integrations/hub/connections/{connection_id}/metadata-snapshots
Returns newest snapshots for the selected connection. limit defaults to 25 and is passed to the snapshot query. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List integration object links
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-integration-object-links

get /integrations/hub/connections/{connection_id}/object-mappings
Returns stored source/provider identity and designation links for the selected connection, newest update first. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List integration sync events
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-integration-sync-events

get /integrations/hub/connections/{connection_id}/sync-events
Returns operational event records for the selected connection, newest occurrence first. Includes stored payloads and link metadata; use sync-history for customer-safe summaries. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List integration sync runs
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-integration-sync-runs

get /integrations/hub/connections/{connection_id}/sync-runs
Returns stored connection runs, newest first. This compatibility list is unpaginated; use sync-history for paginated safe operational summaries. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List QuickBooks issues or activity
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-quickbooks-issues-or-activity

get /integrations/hub/connections/{connection_id}/quickbooks/issues
Defaults to unresolved failed/needs_review/retry_queued customer, item, account, settlement, refund and dispute events, omitting superseded retry sources. scope=all includes financial eligibility and applies status/record_type filters; those filters do not affect scope=issues. Default 15 rows, maximum 50. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List QuickBooks payout account choices
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-quickbooks-payout-account-choices

get /admin/quickbooks/stripe-payouts/accounts
Reads active QuickBooks accounts and up to1,000 usable active Service items from the connected company. Requires permission: one of access_payment_gateways.



# List QuickBooks settlement issues
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-quickbooks-settlement-issues

get /integrations/hub/connections/{connection_id}/quickbooks/settlement-issues
Compatibility alias for the same issue/activity listing, including customer/item/account issues. Defaults to scope=issues; scope=all enables status/record_type filters. Default 15 rows, maximum 50. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List recipient QuickBooks class assignments
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-recipient-quickbooks-class-assignments

get /admin/entities_for_campaign
Returns organization recipients/campaigns whose program_id equals the path program. class_id is returned only when entity classes are enabled for that program; otherwise null. The route without a program selects records with null program_id. Requires permission: one of programs_view, manage_programs, program-all.



# List recipient QuickBooks class assignments for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-recipient-quickbooks-class-assignments-for-a-program

get /admin/entities_for_campaign/{program_id}
Returns organization recipients/campaigns whose program_id equals the path program. class_id is returned only when entity classes are enabled for that program; otherwise null. The route without a program selects records with null program_id. Requires permission: one of programs_view, manage_programs, program-all.



# List safe integration sync history
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-safe-integration-sync-history

get /integrations/hub/connections/{connection_id}/sync-history
Returns paginated run summaries, default15 maximum 50, excluding healthy completed scheduled reconcile runs with no events. Includes counts/duration rather than raw provider payloads. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# List stored integration webhook receipts
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/list-stored-integration-webhook-receipts

get /integrations/hub/connections/{connection_id}/webhook-events
Returns selected connection receipts, newest received first, with headers and payload fields redacted by sensitive-key policy. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Mark an integration webhook for replay
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/mark-an-integration-webhook-for-replay

post /integrations/hub/webhook-events/{event_id}/replay
Updates the stored receipt to replay_queued, increments attempts and records replay time. This endpoint returns that local state; it does not itself dispatch a processing job. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Pause ongoing Bloomerang sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/pause-ongoing-bloomerang-sync

post /integrations/hub/connections/{connection_id}/bloomerang/ongoing-sync/pause
Pauses active or prepared automatic movement while preserving mappings, cursors and rollback snapshots. Optional reason is recorded only on first pause. Repeated pauses return already_paused and still quarantine pending outgoing work. Requires connected state; no provider send is performed. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Post a Stripe payout to QuickBooks
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/post-a-stripe-payout-to-quickbooks

post /admin/quickbooks/stripe-payouts/reconcile
Rebuilds the preview and posts only when ready. Uses a per-payout lock, outbox and provider idempotency identity to avoid duplicate Deposits; posted requests return the existing record. Validates current company, currency, account types and fee-recovery item. Review-needed results remain200 with status needs_review; posting failures persist failed and return422. Requires permission: one of access_payment_gateways.



# Prepare Bloomerang mapping templates
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/prepare-bloomerang-mapping-templates

post /integrations/hub/connections/{connection_id}/bloomerang/bootstrap-mappings
Creates approved defaults only for object pairs without an approved version, preserving existing approved choices. Includes constituent, household, relationship, transaction, soft-credit and refund templates. Returns matching stored versions, including older versions; it does not import or send records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Prepare HubSpot mapping templates
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/prepare-hubspot-mapping-templates

post /integrations/hub/connections/{connection_id}/hubspot/bootstrap-mappings
Creates approved defaults only for object pairs without an approved mapping, preserving current approved choices. Includes contact, selected company target, relationship, activity, deal, product and discovered supported custom-object templates. Returns matching stored versions, including older versions. Does not import or send records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Prepare ongoing Bloomerang sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/prepare-ongoing-bloomerang-sync

post /integrations/hub/connections/{connection_id}/bloomerang/ongoing-sync/activate
Applies unambiguous local donor/household identity links, records prior cursor/safeguard snapshots, initializes cursors to cursor_at and quarantines old pending outgoing work. Removes historical field/household protection while retaining notification suppression and enabling future constituent-creation/adoption choices. With readiness review enabled, returns prepared/inactive and requires a fresh inbound preview plus resume; legacy rollout activates immediately. Already-active calls only reconcile newly imported identities without moving the saved baseline. Paused/prepared activations must use resume instead. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Prepare Salesforce mapping templates
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/prepare-salesforce-mapping-templates

post /integrations/hub/connections/{connection_id}/salesforce/bootstrap-mappings
Creates approved defaults only for object pairs lacking an approved version, preserving existing approved choices. Templates match NPSP versus Nonprofit Cloud and include metadata-supported optional objects. Returns matching stored versions, including older versions; it does not import or send records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Preview a correction to historical QuickBooks sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/preview-a-correction-to-historical-quickbooks-sync

post /integrations/hub/connections/{connection_id}/quickbooks/historical/runs/{run_id}/correction-preview
Requires a backfill/correction execution whose provider checkpoints have all finished. Creates a zero-write correction preview from current sources; processed create/update/link checkpoints become corrective updates, while unprocessed writes become conflicts. Separate approval is required. Requires a connected QuickBooks company for mutations. Current user/group permissions must include manage_settings, access_account_settings or group_all in addition to route access. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Preview a historical QuickBooks sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/preview-a-historical-quickbooks-sync

post /integrations/hub/connections/{connection_id}/quickbooks/historical/preview
Builds a frozen zero-provider-write plan for selected customers, service items and/or sales receipts, at most500 total records. Program ids must belong to this organization. Eligibility, existing mappings and missing dependencies choose create/update/link/skip/conflict; stores source fingerprints and snapshot_hash. Requires a connected QuickBooks company for mutations. Current user/group permissions must include manage_settings, access_account_settings or group_all in addition to route access. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Preview a Stripe payout reconciliation
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/preview-a-stripe-payout-reconciliation

post /admin/quickbooks/stripe-payouts/preview
Retrieves the payout and automatic payout balance transactions, checks qualified ledger lineage and persists the reconciliation evidence. Only paid automatic standard bank payouts with matching currency/net totals are ready; unsupported or unmatched activity returns needs_review. Does not create a QuickBooks Deposit. Requires permission: one of access_payment_gateways.



# Preview ongoing Bloomerang sync preparation
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/preview-ongoing-bloomerang-sync-preparation

post /integrations/hub/connections/{connection_id}/bloomerang/ongoing-sync/preview
Requires a connected Bloomerang connection, approved donor mapping with provider Id, a tenant donor form and a non-future cursor_at. Scans local historical source ids and exact household membership to plan safe identity-link adoption; collisions and non-exact households are counted rather than guessed. Does not adopt mappings, alter cursors/settings or queue record movement. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Preview outgoing Bloomerang donation review
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/preview-outgoing-bloomerang-donation-review

get /integrations/hub/connections/{connection_id}/outbound-review
Classifies failed/waiting and stale unreserved donation work without sending. Returns bounded counts, financial totals, reviewable rows and an opaque token. Only Bloomerang donations are supported; limit defaults to 500. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue a Bloomerang inbound preview
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-a-bloomerang-inbound-preview

post /integrations/hub/connections/{connection_id}/bloomerang/dry-run
Requires a connected connection and queues a dry_run with mapping/bootstrap preparation, source-scan completeness checks, dependency predictions and readiness evidence. Does not apply business-record imports or write provider records; it does persist local review/conflict/event state. HTTP 202 confirms queued work, whose completed status may still contain blocked decisions. Full scan defaults page_size 25/max_pages 2; cursor mode defaults 50/10. Caps are 50 records/page and 1000 pages; inspect source_scan_errors if the source total was not reached. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue a manual Bloomerang import
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-a-manual-bloomerang-import

post /integrations/hub/connections/{connection_id}/bloomerang/import
Requires a connected connection and queues an actual inbound record import using configured mappings, matching and migration safeguards. Manual imports do not advance recurring cursors; use_cursors optionally limits source reads, and replay_from_baseline needs an active/paused saved baseline. mapped_records_only requires donor-only full scans without a constituent filter and rejects missing source identities. Accepted work can later fail context/source completeness guards. Full scan defaults 25 records/page and 2 pages; cursor reads default50/10. HTTP 202 does not confirm record creation. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue a reviewed ongoing Bloomerang poll
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-a-reviewed-ongoing-bloomerang-poll

post /integrations/hub/connections/{connection_id}/bloomerang/poll
Requires connected active ongoing sync and saved required cursors. The worker rechecks current reviewed configuration/scope before applying inbound changes; unreviewed/stale scopes are blocked. Normal polling forces cursor reads/advancement, default 50 records/page and 10 pages. mapped_records_only is a donor-only full-scan remediation that does not advance cursors; optional use_cursors must remain false. HTTP 202 only confirms queued work and does not guarantee a completed import. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue an eligible outgoing integration retry
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-an-eligible-outgoing-integration-retry

post /integrations/hub/sync-events/{event_id}/retry
Retries only a retryable outbound Bloomerang event or supported failed/needs_review QuickBooks customer, item or donation-settlement event with linked outbound work. Connection, reviewed outgoing scope, keep-local controls, migration safeguards, automatic-retry timing and settlement feature eligibility are checked. Atomically reserves work and queues a new audit attempt; HTTP 200 confirms queuing rather than provider completion. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue an inbound HubSpot poll
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-an-inbound-hubspot-poll

post /integrations/hub/connections/{connection_id}/hubspot/poll
Queues an inbound data poll using current approved mappings and configured company/contact/deal/activity scopes, updating source cursors as records are processed. page_size defaults to 100 and max_pages defaults to 10, maximum 25; accepted refresh_metadata/sample_size options do not alter the poll processing path. HTTP 202 confirms queued work and does not guarantee a successful import. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue an inbound Salesforce poll
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-an-inbound-salesforce-poll

post /integrations/hub/connections/{connection_id}/salesforce/poll
Queues inbound donor/recipient/donation work only for approved mappings that allow provider ownership, plus enabled interaction imports. NPSP and Nonprofit Cloud use their corresponding objects. page_size defaults to 100, maximum 200 per object; saved object cursor takes precedence over since, otherwise a new cursor defaults to seven days ago. Processing can change local records and advances eligible source cursors; HTTP 202 only confirms queuing. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue donors for QuickBooks customer sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-donors-for-quickbooks-customer-sync

post /admin/sync_donor_to_quickbooks
Accepts a nonempty array of tenant-owned donor ids, or all plus hysform_id to select donors in that form. Rejects invalid ids before capture. Requires a connected, non-disconnected QuickBooks Hub connection. Captures durable deduplicated outbox work; provider processing happens later and a relay repairs failed initial queue publication. Requires permission: one of groups, admins, new_form, forms, manage_programs, donors_manage, donations, manage_email, email_manager, manage_sms, sms_manager, sms_inbox_view, sms_inbox_reply, sms_inbox_manage, sendblue_manage, mailings_view, mailings_generate, mailings_manage, manage_settings, access_account_settings, access_payment_gateways, tasks_manage, trips_manage, events_manage, events_sponsor_manage, imports_manage, households_manage, notes_manage, reports_manage.



# Queue HubSpot metadata reconciliation
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-hubspot-metadata-reconciliation

post /integrations/hub/connections/{connection_id}/hubspot/reconcile
Queues metadata discovery, template preparation and mapping review without sample record import. The worker updates the metadata cursor after review. sample_size defaults to 5. HTTP 202 confirms queued local work; inspect the returned run for later completion/failure. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue HubSpot outgoing sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-hubspot-outgoing-sync

post /integrations/hub/connections/{connection_id}/hubspot/outbound-sync
Queues processing of pending/failed outgoing work using current approved provider mappings and settings. limit defaults to 100, maximum 500. The worker may create/update provider records; HTTP 202 confirms queued work and does not report completed sends. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue outgoing Salesforce nonprofit sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-outgoing-salesforce-nonprofit-sync

post /integrations/hub/connections/{connection_id}/salesforce/outbound-sync
Queues up to limit pending/failed outgoing records using current approved mappings and settings; default 100, maximum 500. Worker processing may create/update provider records. HTTP 202 confirms queued work and does not guarantee provider completion. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue recipients for QuickBooks service item sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-recipients-for-quickbooks-service-item-sync

post /admin/sync_entity_to_quickbooks
Queues deduplicated durable work for explicit recipient/campaign ids. Current organization and program permissions are checked for found recipients; unavailable ids are skipped. The legacy all selection currently resolves no recipients because this handler forwards only entity_ids to the selection resolver. Selected recipients with unresolved legacy service-item failures also carry recovery context for this connected company; recovery is recorded only after provider-confirmed success. Requires a connected QuickBooks company; accepted receipts do not establish provider completion. Requires permission: one of groups, admins, new_form, forms, manage_programs, donors_manage, donations, manage_email, email_manager, manage_sms, sms_manager, sms_inbox_view, sms_inbox_reply, sms_inbox_manage, sendblue_manage, mailings_view, mailings_generate, mailings_manage, manage_settings, access_account_settings, access_payment_gateways, tasks_manage, trips_manage, events_manage, events_sponsor_manage, imports_manage, households_manage, notes_manage, reports_manage.



# Queue reviewed outgoing Bloomerang sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-reviewed-outgoing-bloomerang-sync

post /integrations/hub/connections/{connection_id}/bloomerang/outbound-sync
Requires connected active ongoing sync and separately active outgoing authorization. Queues due outgoing work up to limit, default 100 maximum 500. Workers recheck connection/scope/migration suppression before provider changes and quarantine work when sending becomes inactive. HTTP 202 confirms queued work rather than completed provider writes. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue Salesforce metadata reconciliation
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-salesforce-metadata-reconciliation

post /integrations/hub/connections/{connection_id}/salesforce/reconcile
Queues metadata discovery, template preparation and mapping review, then advances the org-schema cursor. sample_size defaults to 10. Does not import business records. HTTP 202 confirms queued work; inspect later run/history state for completion or failure. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue SAP metadata reconciliation
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-sap-metadata-reconciliation

post /integrations/hub/connections/{connection_id}/sap/reconcile
Queues a durable reconcile run and returns202. The job refreshes provider metadata, ensures templates, repeats readiness/record previews and advances the metadata cursor. This current reconciliation implementation does not post financial exports. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Queue selected reviewed donations for sending
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/queue-selected-reviewed-donations-for-sending

post /integrations/hub/connections/{connection_id}/outbound-review/send
Requires the current review token and distinct event_ids from its ready_to_send rows. Atomically rechecks and reserves the selected work, records retry attempts, then dispatches a Bloomerang outbound job. HTTP 202 means queued; provider completion is reported by sync history. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read a Connected Apps connection
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-a-connected-apps-connection

get /integrations/hub/connections/{connection_id}
Returns detailed organization-owned connection state, redacted credentials and related snapshots/runs/conflicts. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read a historical QuickBooks run
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-a-historical-quickbooks-run

get /integrations/hub/connections/{connection_id}/quickbooks/historical/runs/{run_id}
Returns the tenant/connection-owned QuickBooks run and ordered checkpoint details. Readiness/permission checks apply; this read does not advance execution. Requires a connected QuickBooks company for mutations. Current user/group permissions must include manage_settings, access_account_settings or group_all in addition to route access. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read an integration sync run
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-an-integration-sync-run

get /integrations/hub/sync-runs/{run_id}
Returns one organization-owned run with ordered operational events, preserving provider-dependent context while removing related_outbox_event_snapshots. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read Bloomerang mapping options
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-bloomerang-mapping-options

get /integrations/hub/connections/{connection_id}/bloomerang/mapping-options
Returns tenant form/field choices, source custom fields, current approved mappings/directions, group/interaction settings, historical safeguards, provider designation targets and saved program/recipient links. Provider target retrieval uses live paged reads with snapshot fallback. Setting choices do not by themselves activate record sync. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read HubSpot mapping options
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-hubspot-mapping-options

get /integrations/hub/connections/{connection_id}/hubspot/mapping-options
Returns tenant donor forms/fields, HubSpot contact properties, latest approved contact/company mappings, current settings and eligible program/recipient fields. Selects the requested form if valid, otherwise saved form, otherwise first form by name. Deal pipelines prefer a live provider read with metadata fallback; contact properties use built-in defaults when metadata is absent. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read QuickBooks accounting attachment settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-accounting-attachment-settings

get /admin/fields_to_attach
Refreshes the connection and returns provider accounts/classes plus saved program accounting, designation revenue items and resolved override targets. Missing credentials or an expired authorization returns400; provider lookup errors can return500. The route without a program reads legacy empty-suffix settings rather than the unsuffixed global settings written by POST. Requires permission: one of programs_view, manage_programs, program-all.



# Read QuickBooks accounting attachment settings for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-accounting-attachment-settings-for-a-program

get /admin/fields_to_attach/{program_id}
Refreshes the connection and returns provider accounts/classes plus saved program accounting, designation revenue items and resolved override targets. Missing credentials or an expired authorization returns400; provider lookup errors can return500. The route without a program reads legacy empty-suffix settings rather than the unsuffixed global settings written by POST. Requires permission: one of programs_view, manage_programs, program-all.



# Read QuickBooks customer field mappings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-customer-field-mappings

get /admin/fields_to_sync
Returns standard/custom donor fields, provider customer fields and current mappings. Without a program, the configured donor form is required. With a program, its donor form and customer mappings are used; an unavailable program yields empty donor fields. Custom-field discovery refreshes stale cache; refresh_custom_fields requests a refresh even while fresh. Requires permission: one of programs_view, manage_programs, program-all.



# Read QuickBooks customer field mappings for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-customer-field-mappings-for-a-program

get /admin/fields_to_sync/{program_id}
Returns standard/custom donor fields, provider customer fields and current mappings. Without a program, the configured donor form is required. With a program, its donor form and customer mappings are used; an unavailable program yields empty donor fields. Custom-field discovery refreshes stale cache; refresh_custom_fields requests a refresh even while fresh. Requires permission: one of programs_view, manage_programs, program-all.



# Read QuickBooks deletion sync settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-deletion-sync-settings

get /admin/quickbooks/delete-sync-settings
Returns the selected program override or inherited global deletion settings. Both flags default false. Requires permission: one of access_payment_gateways.



# Read QuickBooks duplicate customer policy
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-duplicate-customer-policy

get /admin/quickbooks/customer-sync-settings
Returns the selected program override or inherited global duplicate-donor policy, default false. Requires permission: one of access_payment_gateways.



# Read QuickBooks service item field mappings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-service-item-field-mappings

get /admin/program_fields_to_sync
Returns the configured program form fields, QuickBooks Name/Description/UnitPrice/Sku target options and saved mappings. Program-specific reads also return provider item categories when available; lookup errors produce an empty category list. Without a program, program_hysform_id is interpreted as a program id. Requires permission: one of programs_view, manage_programs, program-all.



# Read QuickBooks service item field mappings for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-service-item-field-mappings-for-a-program

get /admin/program_fields_to_sync/{program_id}
Returns the configured program form fields, QuickBooks Name/Description/UnitPrice/Sku target options and saved mappings. Program-specific reads also return provider item categories when available; lookup errors produce an empty category list. Without a program, program_hysform_id is interpreted as a program id. Requires permission: one of programs_view, manage_programs, program-all.



# Read QuickBooks Stripe-payout settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-stripe-payout-settings

get /admin/quickbooks/stripe-payouts/settings
Returns the five account/item mappings for the organization's legacy QuickBooks connection. Requires permission: one of access_payment_gateways.



# Read QuickBooks sync direction
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-quickbooks-sync-direction

get /admin/quickbooks/sync-direction
Returns the selected program override or inherited global sync direction, default two_way, and display options. Requires permission: one of access_payment_gateways.



# Read recent Stripe payout reconciliations
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-recent-stripe-payout-reconciliations

get /admin/quickbooks/stripe-payouts/history
Lists recent reconciliations for the current organization QuickBooks connection, newest update first; limit defaults25 and is clamped1–100. Requires permission: one of access_payment_gateways.



# Read safe events and readiness for an integration run
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-safe-events-and-readiness-for-an-integration-run

get /integrations/hub/connections/{connection_id}/sync-history/{run_id}/events
Returns safe event changes and Bloomerang review readiness. A supplied group_key must exactly match a server-generated group or nested dependency. With group_key results are paginated; without it available readiness returns representative group events, otherwise normal pagination defaults to 25, maximum 100. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read Salesforce nonprofit mapping options
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-salesforce-nonprofit-mapping-options

get /integrations/hub/connections/{connection_id}/salesforce/mapping-options
Returns organization donor forms, compatible contribution/number/campaign programs, writable provider fields, object names/labels, approved mappings and interaction availability. Requested choices fall back to stored choices, then only to a sole available option; multiple choices can leave selection null. Provider fields use stored metadata, live describe and built-in fallback in that order. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Read the connected QuickBooks company name
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/read-the-connected-quickbooks-company-name

get /admin/quickbooks/organization
Refreshes credentials and reads CompanyInfo. Expired authorization can return200 with needs_reauth=true and a message instead of organization_name. Missing credentials return400; absent integration404. Requires permission: one of access_payment_gateways.



# Record an integration conflict
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/record-an-integration-conflict

post /integrations/hub/connections/{connection_id}/conflicts
Stores local conflict evidence with open status by default. Optional event and mapping links must belong to this organization and selected connection. Snapshot, field-list and resolution JSON are provider/workflow dependent; recording a conflict does not apply values or contact a provider. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Register a Zapier Connected App
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/register-a-zapier-connected-app

post /integrations/hub/providers/zapier/connect
Creates or reconnects an organization Zapier record using existing active, non-revoked, non-expired API-key count. Returns warning health when none exist. This operation does not issue an API key, create a Zap or authorize Zapier on the user's behalf. Requires the integration platform to be enabled globally or by its configured client feature flag (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Remove a Bloomerang program or recipient link
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/remove-a-bloomerang-program-or-recipient-link

delete /integrations/hub/connections/{connection_id}/bloomerang/recipient-mapping/{mapping_id}
Supersedes the selected active organization/connection-owned designation link. Removing the currently selected program link selects a remaining active target for that program or clears its selected program context. Recipient links do not clear program selection. Does not delete local/provider recipients or transactions. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Remove a disconnected Connected App
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/remove-a-disconnected-connected-app

delete /integrations/hub/connections/{connection_id}/remove
Requires disconnected status. Retires its pending outbound work, mappings and cursors, releases provider identity uniqueness, clears channel credentials and soft-deletes the connection. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Remove the legacy QuickBooks integration
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/remove-the-legacy-quickbooks-integration

delete /admin/quickbooks/disconnect
Deletes this organization selected legacy QuickBooks Integration record and records the disconnect activity. The operation does not call the provider token-revocation endpoint. Requires permission: one of access_payment_gateways.



# Replace integration credentials
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/replace-integration-credentials

post /integrations/hub/connections/{connection_id}/reauthorize
Stores supplied provider-specific credential JSON, marks connected and clears prior disconnect/error state. Returns detailed redacted credentials; use provider authorization flows when they are required for that integration. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Request a WhatsApp staff-link code
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/request-a-whatsapp-staff-link-code

post /integrations/hub/providers/twilio/link
Sends an eight-digit code to the supplied E.164 WhatsApp number after checking a recent inbound message (within23 hours) to the configured sender. Requires Workspace Agent channel rollout/use permission, active membership and enabled Twilio setup. Existing workspace links must be changed through support. One request per user/destination per minute; code expires after five minutes. Requires the integration platform to be enabled globally or by its configured client feature flag (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Reset ongoing sync and restore prior safeguards
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/reset-ongoing-sync-and-restore-prior-safeguards

post /integrations/hub/connections/{connection_id}/bloomerang/ongoing-sync/restore
Requires an active, paused or prepared activation with complete prior cursor/context snapshots. Removes only identity links marked as created by that activation, restores or removes saved cursors, restores the three prior migration/creation settings, marks reset/inactive and quarantines pending outgoing work. Does not undo prior donor/gift/provider data changes or replay history. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Resolve a reviewed donor identity collision
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/resolve-a-reviewed-donor-identity-collision

post /integrations/hub/connections/{connection_id}/donor-identity-decisions/{event_id}/resolve
Defaults to match_separate_donor. Uses the expected run/current-donor/claim guards under lock; competing reviews and newer evidence are rejected. Matching writes the source identity mapping and can move an existing claimed mapping only to an explicitly selected separate donor. source_record_merged resolves local evidence; a missing-source decision retires its obsolete mapping and clears only matching legacy source-id fields. Donor records are not merged and gifts/payments/contact details are preserved. Verify returned source identities before resuming sync. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Resume a historical QuickBooks execution
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/resume-a-historical-quickbooks-execution

post /integrations/hub/connections/{connection_id}/quickbooks/historical/runs/{run_id}/resume
Resumes pending/failed backfill or correction checkpoints for the same connected company. Captures current approved work into the durable outbox; source changes can require a fresh preview rather than silently executing changed records. Requires a connected QuickBooks company for mutations. Current user/group permissions must include manage_settings, access_account_settings or group_all in addition to route access. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Resume reviewed inbound Bloomerang sync
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/resume-reviewed-inbound-bloomerang-sync

post /integrations/hub/connections/{connection_id}/bloomerang/ongoing-sync/resume
With readiness review enabled, requires a same-connection reviewed_sync_run_id with current complete/scope-compatible evidence, no newer relevant review and freshness within 24 hours. Selects ready object types or the requested subset, adds required donor/donation dependencies, validates cursors and can partially activate ready scopes; group is review/manual-only. A readiness-bound resume enables imports and leaves outgoing sending paused. Legacy rollout resumes saved cursor state without a review. Already-active requests return existing state unless extending partial activation with a reviewed run. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Retry a historical QuickBooks checkpoint
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/retry-a-historical-quickbooks-checkpoint

post /integrations/hub/connections/{connection_id}/quickbooks/historical/runs/{run_id}/events/{event_id}/retry
Retries only retryable failed/needs_review/skipped execution checkpoints belonging to this run/connection. Requires unchanged approved source and a reviewable outbox attempt; an already queued/processing checkpoint fails validation. Dispatches the retry without assuming provider completion. Requires a connected QuickBooks company for mutations. Current user/group permissions must include manage_settings, access_account_settings or group_all in addition to route access. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Review future sending to Bloomerang
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/review-future-sending-to-bloomerang

post /integrations/hub/connections/{connection_id}/bloomerang/ongoing-sync/outbound/preview
Builds a no-send review of approved outgoing mappings inside active inbound scope. Reports open conflicts, existing actionable outgoing work and historical suppression; ready reviews include an encrypted 24-hour token. Does not activate sending, replay history, charge or contact provider write endpoints. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Review HubSpot mapping and import readiness
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/review-hubspot-mapping-and-import-readiness

post /integrations/hub/connections/{connection_id}/hubspot/dry-run
Synchronously discovers metadata if requested or missing, ensures templates, persists mapping/ownership conflicts and predicts sample company/contact outcomes without creating donor/household records or writing provider records. Completion can include errors/conflicts; inspect counters and summary. Default sample metadata size 5; preview page_size defaults to 25 and max_pages defaults to 1, with preview pages capped at 3 even though validation accepts 25. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Review outgoing donations owned by archived donors
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/review-outgoing-donations-owned-by-archived-donors

get /integrations/hub/connections/{connection_id}/outbound-donation-owner-decisions
Returns local payment groups whose outgoing work is waiting for a missing donor mapping and whose current owner is archived. Exposes actual candidate matching, identity/commitment/payment safety blockers, separate keep-local eligibility, current tokens and a potentially undoable prior resolution. Totals can span currencies while the top-level currency comes from the first group; review each group currency. No provider requests are sent. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Review Salesforce mapping readiness
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/review-salesforce-mapping-readiness

post /integrations/hub/connections/{connection_id}/salesforce/dry-run
Synchronously uses existing metadata or discovers it when refresh_metadata is true or no snapshot exists. Ensures templates, checks org/template shape, required object/field permissions and financial/multiple-provider ownership, and records local review events/conflicts. A completed run may include errors/conflicts. sample_size defaults to 10 for metadata discovery; this is mapping review and does not import sample donors or write provider records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Review SAP export readiness
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/review-sap-export-readiness

post /integrations/hub/connections/{connection_id}/sap/dry-run
Synchronously reviews metadata, accounting context, ownership conflicts and up to25 latest donations (default10), plus up to10 commitments when enabled. May persist open ownership conflicts and local templates. Predicted create/update counters and completed review status do not represent SAP writes. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save a program QuickBooks item category
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-a-program-quickbooks-item-category

put /admin/program_item_category/{program_id}
Sets the selected program item-category id. Omitted, null or whitespace-only item_category_id removes the override. The program and integration must belong to this organization. Requires permission: one of manage_programs.



# Save an integration conflict decision
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-an-integration-conflict-decision

post /integrations/hub/conflicts/{conflict_id}/resolve
Behavior depends on conflict type. Ordinary Bloomerang donor conflicts accept hys/provider defaults plus per-field overrides and apply provider values only for conflicted email, first_name, last_name, organization_name, phone, street, city, state, zip or country; unsupported types record status/history only. Inspect resolution_json.applied because a resolved receipt can report skipped/error. Relationship identity decisions keep_separate, same_or_reverse or choose_relationship stage a pending open decision, requiring the current expected_object_mapping_id or expected_stale_mapping_token, and target_hys_object_id for an explicit choice. Recurring schedule decision already_represented_in_hys requires expected_provider_object_id, expected_source_snapshot_token and expected_active_commitment_token from current review; it resolves by preserving existing commitments and payment behavior, followed by verification. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Bloomerang constituent-to-donor mapping
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-bloomerang-constituent-to-donor-mapping

post /integrations/hub/connections/{connection_id}/bloomerang/contact-donor-mapping
Requires an organization donor form and available field pairs. Each canonical provider field may be used once (Name and FullName collide); an enabled relationship-manager custom field must be available and distinct. Requires a mapped field or enabled manager mapping. Saves historical-backfill protections and notification/outgoing suppression, creation/adoption choices and the next approved mapping without syncing. Creation requires outgoing ownership and explicit creation opt-in; omitted creation/manager enablement is false, omitted email-match/backfill choices preserve stored state. Direction follows sync_direction_control: configurable uses requested/current/default direction, locked_bidirectional forces bidirectional, and unavailable preserves current/default direction. Defaults are bidirectional. Returned context/mapping shows effective flags; saving direction and activating ongoing sync are separate. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Bloomerang group tag import
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-bloomerang-group-tag-import

post /integrations/hub/connections/{connection_id}/bloomerang/group-mapping
Defaults enabled to true. Saves provider-owned group/tag membership setup for already mapped constituents, superseding prior group versions. Disabling returns mapping=null. Groups import into Gratona donor tags; this setup does not write Gratona tags back as Bloomerang groups or import records immediately. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Bloomerang household setup
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-bloomerang-household-setup

post /integrations/hub/connections/{connection_id}/bloomerang/household-mapping
Atomically saves the next approved household mapping and mapped-constituents-only membership policy, superseding its previous approved version. Household setup does not create missing donor identities. Direction follows sync_direction_control: configurable uses requested/current/default direction, locked_bidirectional forces bidirectional, and unavailable preserves current/default direction. Defaults are bidirectional. Returned context/mapping shows effective flags; saving direction and activating ongoing sync are separate. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Bloomerang interaction and note settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-bloomerang-interaction-and-note-settings

post /integrations/hub/connections/{connection_id}/bloomerang/interaction-mapping
Either enabled direction requires selected Task, Call, Meeting, Email or Note types. Omitted fields disable both directions and clear selection. Supersedes prior task/interaction/note mappings, creates outbound task/log mappings only when enabled, and creates Note ownership as hys/provider/bidirectional according to enabled directions. Returns first mapping plus all new mappings, without importing records, sending messages or writing provider records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Bloomerang relationship setup
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-bloomerang-relationship-setup

post /integrations/hub/connections/{connection_id}/bloomerang/relationship-mapping
Atomically approves the next constituent-relationship mapping and mapped-constituents-only member policy, superseding its previous version. Saving setup does not create donor/relationship records. Direction follows sync_direction_control: configurable uses requested/current/default direction, locked_bidirectional forces bidirectional, and unavailable preserves current/default direction. Defaults are bidirectional. Returned context/mapping shows effective flags; saving direction and activating ongoing sync are separate. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Bloomerang transaction setup
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-bloomerang-transaction-setup

post /integrations/hub/connections/{connection_id}/bloomerang/donation-mapping
Saves donation direction, fallback, soft-credit and acknowledgement choices with the next approved transaction mapping. Enabling fallback requires an organization program and recipient belonging to it. Each supplied mapped_fields row requires a supported unique source path and non-empty label. Omitted fallback/soft-credit/acknowledgement booleans are false; disabling fallback clears its ids. Setup describes one payment with multiple designation allocations and requires existing donor/target links for future export; no payment/provider transaction is created here. Direction follows sync_direction_control: configurable uses requested/current/default direction, locked_bidirectional forces bidirectional, and unavailable preserves current/default direction. Defaults are bidirectional. Returned context/mapping shows effective flags; saving direction and activating ongoing sync are separate. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save HubSpot activity sync settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-hubspot-activity-sync-settings

post /integrations/hub/connections/{connection_id}/hubspot/activity-mapping
Ensures default mapping templates and stores enabled/types/link-policy/body-visibility choices. Omitted fields reset to disabled, empty types, matched_only and team respectively. This endpoint returns connection settings only and does not sync activities. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save HubSpot company mapping
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-hubspot-company-mapping

post /integrations/hub/connections/{connection_id}/hubspot/company-mapping
Selects household or organization_donor target, saves name-matching preference and approves the next company mapping while superseding previous company targets. source_of_truth defaults to bidirectional; omitted company_match_by_name preserves its stored value. Does not import or send company records. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save HubSpot contact-to-donor fields
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-hubspot-contact-to-donor-fields

post /integrations/hub/connections/{connection_id}/hubspot/contact-donor-mapping
Requires a donor form in this organization and at least one available form-field/property pair from mapping options. Creates and immediately approves the next donor/contact version, superseding its approved predecessor. source_of_truth defaults to provider and allow_email_match preserves its existing value when omitted. Saves connection form settings without running sync. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save HubSpot deal import settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-hubspot-deal-import-settings

post /integrations/hub/connections/{connection_id}/hubspot/deal-mapping
Stores whether deal import is enabled and selected stage ids, then approves a provider-owned deal/donation mapping. Enabling requires a non-empty stage selection. Omitted fields disable import and clear stages. Mapping defaults mark imported records as one-time donations; this request does not import deals. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save HubSpot product and outbound deal settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-hubspot-product-and-outbound-deal-settings

post /integrations/hub/connections/{connection_id}/hubspot/product-mapping
Stores selected program ids and name/description/price/sku recipient field choices, approving the next recipient/product mapping. Product sync or outbound deals require valid organization-owned programs; outbound deals additionally require pipeline and stage ids. Non-empty legacy product_field_mapping also applies to the first selected program. Omitted settings reset to disabled/empty/null; no provider record is sent by this call. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save legacy QuickBooks form assignments
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-legacy-quickbooks-form-assignments

post /admin/quickbooks/donorform
Stores nonempty string donor_form_id as the donor form assignment and program_id as the legacy program assignment. Integer JSON values, blank strings and other payload values are ignored. This operation does not start a sync. Requires permission: one of access_payment_gateways.



# Save QuickBooks accounting attachment settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-accounting-attachment-settings

post /admin/fields_to_attach
Updates only supplied settings, globally or for the selected tenant-owned program. At least one setting is required; null or blank string clears a scalar setting. Nonempty income accounts must be active Income/Other Income; deposit accounts active Bank/Other Current Asset; classes active; revenue items active Service items. Provider validation failures return422 or retryable503. Program overrides retain only applicable desig-<id>/entity-<id> targets; global overrides retain desig-<id> keys only. Requires permission: one of manage_programs.



# Save QuickBooks accounting attachment settings for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-accounting-attachment-settings-for-a-program

post /admin/fields_to_attach/{program_id}
Updates only supplied settings, globally or for the selected tenant-owned program. At least one setting is required; null or blank string clears a scalar setting. Nonempty income accounts must be active Income/Other Income; deposit accounts active Bank/Other Current Asset; classes active; revenue items active Service items. Provider validation failures return422 or retryable503. Program overrides retain only applicable desig-<id>/entity-<id> targets; global overrides retain desig-<id> keys only. Requires permission: one of manage_programs.



# Save QuickBooks customer field mappings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-customer-field-mappings

post /admin/fields_to_sync
Replaces the global mappings or selected program customer mapping with trimmed nonempty string-to-string pairs from the JSON body; program_id is ignored as a body field. Empty sanitized input clears the selected mapping. Does not write provider customers. Requires permission: one of manage_programs.



# Save QuickBooks customer field mappings for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-customer-field-mappings-for-a-program

post /admin/fields_to_sync/{program_id}
Replaces the global mappings or selected program customer mapping with trimmed nonempty string-to-string pairs from the JSON body; program_id is ignored as a body field. Empty sanitized input clears the selected mapping. Does not write provider customers. Requires permission: one of manage_programs.



# Save QuickBooks deletion sync settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-deletion-sync-settings

put /admin/quickbooks/delete-sync-settings
Updates only supplied deletion flags, globally or for one organization program. At least one flag is required. This changes subsequent sync behavior; it does not immediately delete records. Requires permission: one of access_payment_gateways.



# Save QuickBooks duplicate customer policy
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-duplicate-customer-policy

put /admin/quickbooks/customer-sync-settings
Sets whether a newly imported QuickBooks customer can create a duplicate local donor, globally or for one organization program. Requires the boolean flag; this operation does not import customers immediately. Requires permission: one of access_payment_gateways.



# Save QuickBooks recipient class assignments
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-recipient-class-assignments

put /admin/fields_to_attach
Stores use_entity_classes for the selected program and applies each entity_classes pair to the legacy entity-class mapping. Existing mappings omitted from the list are retained. Each pair must contain entity_id and class_id for a recipient and QuickBooks class available to the organization. Requires permission: one of manage_programs.



# Save QuickBooks recipient class assignments for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-recipient-class-assignments-for-a-program

put /admin/fields_to_attach/{program_id}
Stores use_entity_classes for the selected program and applies each entity_classes pair to the legacy entity-class mapping. Existing mappings omitted from the list are retained. Each pair must contain entity_id and class_id for a recipient and QuickBooks class available to the organization. Requires permission: one of manage_programs.



# Save QuickBooks service item field mappings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-service-item-field-mappings

post /admin/program_fields_to_sync
Replaces the global or program-specific item field mapping with trimmed nonempty string-to-string JSON pairs. Sanitized input must not be empty. Does not start a provider sync; requires an existing QuickBooks integration. Requires permission: one of manage_programs.



# Save QuickBooks service item field mappings for a program
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-service-item-field-mappings-for-a-program

post /admin/program_fields_to_sync/{program_id}
Replaces the global or program-specific item field mapping with trimmed nonempty string-to-string JSON pairs. Sanitized input must not be empty. Does not start a provider sync; requires an existing QuickBooks integration. Requires permission: one of manage_programs.



# Save QuickBooks sync direction
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-quickbooks-sync-direction

put /admin/quickbooks/sync-direction
Saves a global direction or an organization program override. Changes sync policy; this operation does not immediately synchronize records. Requires permission: one of access_payment_gateways.



# Save Salesforce donation sync directions
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-salesforce-donation-sync-directions

post /integrations/hub/connections/{connection_id}/salesforce/donation-mapping
A supplied source_of_truth determines directions: hys enables outbound, provider enables inbound, bidirectional enables both. When omitted, derives ownership from the two direction booleans; both omitted/false disable both directions. Supersedes prior donation mappings and returns mapping=null when disabled; otherwise approves the template-specific Opportunity or GiftTransaction mapping. This request does not import, charge or send a gift. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Salesforce donor field mapping
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-salesforce-donor-field-mapping

post /integrations/hub/connections/{connection_id}/salesforce/contact-donor-mapping
Requires an organization donor form and at least one available form/provider field pair. NPSP maps donors to Contact; Nonprofit Cloud maps to Person Account. Saves form/strategy settings, supersedes prior donor Contact/Account versions and immediately approves the new version. source_of_truth defaults to hys. Does not import or send donors. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Salesforce interaction sync settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-salesforce-interaction-sync-settings

post /integrations/hub/connections/{connection_id}/salesforce/interaction-mapping
Stores outbound/inbound enablement and selected Task, Call, Event or EmailMessage types. Either enabled direction requires a non-empty selection. Omitted fields disable both directions and clear the selection. Ensures mapping templates but does not send or import interactions. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Save Salesforce recipient field mapping
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/save-salesforce-recipient-field-mapping

post /integrations/hub/connections/{connection_id}/salesforce/recipient-mapping
Requires a non-root organization program of contribution, number or campaign type with a recipient form and at least one available field pair. NPSP targets Campaign; Nonprofit Cloud targets GiftDesignation. Defaults to hys ownership; explicit inbound enablement upgrades hys to bidirectional, while provider/bidirectional ownership enables inbound automatically. Saves strategy and approves the next mapping, superseding previous recipient targets without syncing. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Search donation fallback recipients
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/search-donation-fallback-recipients

get /integrations/hub/connections/{connection_id}/bloomerang/fallback-designations
Requires an organization-owned contribution/number/campaign program. Returns local non-deleted recipients cached for 60 seconds, default limit 20 maximum 50, ranked by exact numeric id, exact name, prefix then substring. entity_id directly returns that option or an empty array and takes priority over search/limit. Names use configured title fields and stored fallback labels. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Search QuickBooks revenue mapping targets
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/search-quickbooks-revenue-mapping-targets

get /admin/quickbooks/designation-revenue-targets/{program_id}
Searches applicable designations and recipients/campaigns in the selected program, returning label-sorted options up to limit (default20). Nonempty designation_key takes precedence and resolves one desig-<id> or entity-<id>; an unknown or inapplicable key returns an empty array. This lookup uses local organization records. Requires permission: one of access_payment_gateways.



# Search QuickBooks service items
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/search-quickbooks-service-items

get /admin/quickbooks/items/search
Searches active Service items, default limit20. Nonempty item_id takes precedence over search and returns that provider item when found, even when its type differs; unknown ids return an empty data array. Requires a refreshed connected QuickBooks company. Requires permission: one of access_payment_gateways.



# Stage discovered donations for outgoing review
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/stage-discovered-donations-for-outgoing-review

post /integrations/hub/connections/{connection_id}/outbound-discovery/stage
Requires the unchanged discovery review_token and matching object_type/limit. Adds safely discoverable groups as terminal local outgoing-review work, skipping uncheckable rows and deduplicating groups. Does not queue or send provider requests. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Start Dropbox Sign authorization
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/start-dropbox-sign-authorization

get /integrations/dropbox-sign/oauth/connect
Creates a one-time OAuth state for the authenticated organization, valid for900seconds, and returns the provider authorization URL. Opening that URL starts the provider consent flow. Requires permission: one of access_account_settings.



# Store an integration webhook receipt
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/store-an-integration-webhook-receipt

post /integrations/hub/connections/{connection_id}/webhook-events
Stores supplied provider payload/headers after sensitive-key redaction. A supplied verified flag explicitly records an administrative verification decision; when omitted, the registered adapter verifies the stored receipt. This operation records receipt state and does not execute provider processing. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Undo a local gift-owner or keep-local decision
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/undo-a-local-gift-owner-or-keep-local-decision

post /integrations/hub/connections/{connection_id}/outbound-donation-owner-resolutions/{run_id}/undo
Requires a completed matching local reconcile run that has not already been undone. Rechecks gifts, source mappings, controls and related work under lock. Owner undo restores original donors only while records are still waiting and undispatched. Keep-local undo revokes controls/restores safe local work; recorded deferred refunds keep affected gifts waiting for refund reconciliation and disable their retries. No provider requests are sent; changed or processing records reject the whole batch. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Update a Connected Apps connection
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/update-a-connected-apps-connection

patch /integrations/hub/connections/{connection_id}
Updates validated connection state, credential/settings/context fields and returns the redacted detailed projection. Supplied null values for fields using existing-value fallback retain their stored value; this request does not validate provider credentials remotely. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Update QuickBooks Stripe-payout settings
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/update-quickbooks-stripe-payout-settings

put /admin/quickbooks/stripe-payouts/settings
Requires a connected QuickBooks company, active clearing Bank/Other Current Asset, deposit Bank, fee/dispute Expense/Other Expense accounts and an active Service item with an income account for fee recovery. Saves mappings and refreshes integration compatibility. Requires permission: one of access_payment_gateways.



# Upsert an integration object link
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/upsert-an-integration-object-link

post /integrations/hub/connections/{connection_id}/object-mappings
Creates or updates an identity mapping, restoring a matching retired row if needed. An optional field_mapping_id must belong to this connection. QuickBooks metadata is bound to the current company fingerprint. Does not create a provider object. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Verify a recurring-schedule decision
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/verify-a-recurring-schedule-decision

post /integrations/hub/conflicts/{conflict_id}/verify-recurring-schedule
Requires a resolved already_represented_in_hys decision and a completed same-connection dry_run started after review that includes donation objects. Its exact source event must be skipped with matching schedule, source token, commitment token and donor identity. Saves verification evidence; does not create commitments, charges or provider records. Repeating the same verified run returns the stored result. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Verify a WhatsApp staff-link code
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/verify-a-whatsapp-staff-link-code

post /integrations/hub/providers/twilio/link/verify
Verifies this user/workspace five-minute challenge, provisions its private staff channel and activates the connection. A wrong code consumes the challenge; changed setup or an existing link requires recovery. Requires the same current membership, Workspace Agent channel/use and Twilio configuration gates as requesting the code. Requires the integration platform to be enabled globally or by its configured client feature flag (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Verify and apply a staged relationship decision
Source: https://api-docs.helpyousponsor.com/api-reference/integrations/verify-and-apply-a-staged-relationship-decision

post /integrations/hub/conflicts/{conflict_id}/verify-relationship-identity
Requires a saved pending relationship decision and a completed same-connection dry_run started after staging that includes relationship objects. The matching inbound preview event must prove the exact source relationship payload and both donor identities. Rechecks pending fingerprint, mappings and available candidates under lock before applying. keep_separate may create/adopt a forward/reverse relationship pair; choose_relationship links the selected available pair. No provider write or donor merge occurs. Requires the integration platform global/configured client feature gate (normally integration_platform_foundation). Requires permission: one of access_account_settings.



# Append a message and start an agent run
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/append-a-message-and-start-an-agent-run

post /admin/workspace-agent/runs
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. conversation_id must be present: null starts a conversation, an existing UUID requires If-Match with its quoted conversation revision ETag. Only documented input keys and text parts are accepted; caller-authored client/actor/history/tools/state/credentials are rejected. A UUID Idempotency-Key protects exact command replay.202 returns the queued run and event-stream URL, with updated ETag.



# Approve and execute a Tali draft
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/approve-and-execute-a-tali-draft

post /admin/aida/work-items/{workItemId}/approve
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Approval executes the registered action, which can send approved external copy or create internal records. Blocked, terminal or stale drafts must be resolved/refreshed first. Already-executed approval is observational.



# Cancel a workspace-agent run
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/cancel-a-workspace-agent-run

post /admin/workspace-agent/runs/{run}/cancel
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Active runs are marked cancelled, open interrupts are cancelled and workflow control delivery is queued. Already terminal runs return their current resource. client_id/actor_id are prohibited.



# Cancel an agent human-input interrupt
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/cancel-an-agent-human-input-interrupt

post /admin/workspace-agent/interrupts/{interrupt}/cancel
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Requires an open matching expected_version and the intended participant when one is named. Resolution must satisfy the returned response_schema and payload guard. Accepted command updates the interrupt and queues workflow delivery; caller-supplied client_id/actor_id are prohibited.



# Capture a relationship note for Tali
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/capture-a-relationship-note-for-tali

post /admin/aida/capture
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires capture authority and a nonblank trimmed note. Detects or matches the relationship and prepares work for review; relationship_mode new preserves an unmatched relationship instead of assuming an existing donor.



# Defer Tali work
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/defer-tali-work

post /admin/aida/work-items/{workItemId}/defer
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Moves nonterminal work to waiting/deferred until defer_until, or now plus cooldown_days (default three). Due work can return to the review inbox.



# Delete a workspace-agent conversation
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/delete-a-workspace-agent-conversation

delete /admin/workspace-agent/conversations/{conversation}
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Requires If-Match and UUID Idempotency-Key. Marks deletion_pending, cancels active runs, withdraws participants and schedules provider/artifact deletion. Legal hold or stale revision returns409; accepted receipt does not imply downstream deletion has finished.



# Delete relationship memory
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/delete-relationship-memory

delete /admin/aida/relationship-memories/{memoryId}
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Marks durable memory deleted and returns the resulting memory and any linked work item.



# Download a completed donor intelligence export
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/download-a-completed-donor-intelligence-export

get /admin/donor-intelligence/{client_id}/donors/exports/{uploadId}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Rechecks current route/report/source authority. Default response redirects to a verified temporary URL or streams CSV when necessary. resolve returns a URL envelope when available; protected reports can reject resolve with404. Unready/missing artifacts return404.



# Download a completed donor intelligence export
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/download-a-completed-donor-intelligence-export-1

get /admin/wealth-insights/{client_id}/donors/exports/{uploadId}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Rechecks current route/report/source authority. Default response redirects to a verified temporary URL or streams CSV when necessary. resolve returns a URL envelope when available; protected reports can reject resolve with404. Unready/missing artifacts return404.



# Download a conversation JSON Lines export
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/download-a-conversation-json-lines-export

get /admin/workspace-agent/conversations/{conversation}/export
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Streams one JSON object per line: resource_type and resource. Includes manifest, conversation, participant, message, run, event, interrupt, artifact metadata and feedback. Artifact bytes use their separately authorized content URL.



# Download authorized agent artifact content
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/download-authorized-agent-artifact-content

get /admin/workspace-agent/artifacts/{artifact}/content
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Returns decrypted verified artifact bytes with the stored media type and attachment disposition. Retention/state/integrity failures reject the read.



# Edit a Tali review draft
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/edit-a-tali-review-draft

patch /admin/aida/work-items/{workItemId}/draft
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Updates submitted copy and pending approval text. Executed drafts and closed/suppressed work cannot be edited.



# Link Tali work to an existing donor
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/link-tali-work-to-an-existing-donor

post /admin/aida/work-items/{workItemId}/link-donor
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Donor must belong to the organization; already-linked work cannot be relinked through this operation.



# List available workspace agents
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/list-available-workspace-agents

get /admin/workspace-agent/agents
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Materializes the initial agent release if needed and returns active agent choices.



# List conversation messages after a sequence
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/list-conversation-messages-after-a-sequence

get /admin/workspace-agent/conversations/{conversation}/messages
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Only committed messages expose content and reaction details; other rows have empty content. Includes aggregated reactions and whether this user reported a response failure.



# List donor intelligence prospect rows
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/list-donor-intelligence-prospect-rows

get /admin/donor-intelligence/{client_id}/donors
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns latest profile metadata per donor, or donors without a profile for queue no_insights. Sorting applies to numeric estimates with nulls last, then confidence/refresh/name tie-breakers.



# List donor intelligence prospect rows
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/list-donor-intelligence-prospect-rows-1

get /admin/wealth-insights/{client_id}/donors
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns latest profile metadata per donor, or donors without a profile for queue no_insights. Sorting applies to numeric estimates with nulls last, then confidence/refresh/name tie-breakers.



# List my workspace-agent conversations
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/list-my-workspace-agent-conversations

get /admin/workspace-agent/conversations
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Returns recent active-participant conversations ordered by last activity and ID, with an opaque continuation cursor.



# List recent Tali source sweeps
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/list-recent-tali-source-sweeps

get /admin/aida/runs
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Returns the latest ten sweeps and their signal/preview summaries.



# List run events after a sequence
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/list-run-events-after-a-sequence

get /admin/workspace-agent/runs/{run}/trajectory
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Events are ordered by sequence; redacted events retain identity and expose payload.redacted only. meta reports run status and terminal outcome.



# Move a relationship pipeline stage
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/move-a-relationship-pipeline-stage

patch /admin/aida/work-items/{workItemId}/pipeline-stage
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Requires source-backed evidence for the requested stage; stage changes update recommendations and may mark the draft stale.



# Preview or queue bulk donor profile generation
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/preview-or-queue-bulk-donor-profile-generation

post /admin/donor-intelligence/generations/bulk
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Explicit positive donor_ids are deduplicated; when empty, filters select donor IDs. With no effective selection, defaults to organization donors ordered by ID. The configured bulk limit (default100) truncates selection and is reported. dry_run estimates eligibility/capacity without queueing; otherwise queues eligible runs and reports skipped capacity/active donors. Both modes return202.



# Preview or queue bulk donor profile generation
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/preview-or-queue-bulk-donor-profile-generation-1

post /admin/wealth-insights/generations/bulk
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Explicit positive donor_ids are deduplicated; when empty, filters select donor IDs. With no effective selection, defaults to organization donors ordered by ID. The configured bulk limit (default100) truncates selection and is reported. dry_run estimates eligibility/capacity without queueing; otherwise queues eligible runs and reports skipped capacity/active donors. Both modes return202.



# Purchase shared workspace AI capacity
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/purchase-shared-workspace-ai-capacity

post /admin/ai-capacity/top-ups
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Charges the organization saved payment card for the configured top-up and grants credits only after provider success. Reuse idempotency_key to avoid duplicate purchases; omitted keys create a fresh purchase. Disabled purchases, missing payment setup or insufficient billing success return402.



# Queue a donor intelligence CSV export
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/queue-a-donor-intelligence-csv-export

get /admin/donor-intelligence/{client_id}/donors/export
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Starts an asynchronous filtered prospect export. Poll status_url and download only when ready;200 means dispatch succeeded. Failures to prepare/dispatch return500.



# Queue a donor intelligence CSV export
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/queue-a-donor-intelligence-csv-export-1

get /admin/wealth-insights/{client_id}/donors/export
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Starts an asynchronous filtered prospect export. Poll status_url and download only when ready;200 means dispatch succeeded. Failures to prepare/dispatch return500.



# Queue a donor intelligence profile generation
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/queue-a-donor-intelligence-profile-generation

post /admin/donors/{donor_id}/donor-intelligence/generate
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Reserves shared AI capacity and queues generation. If this donor already has an active generation, reuses its status. Poll data.poll_url; completion may be ready, insufficient-data, skipped or failed.202 does not mean the profile has finished.



# Queue a donor intelligence profile generation
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/queue-a-donor-intelligence-profile-generation-1

post /admin/donors/{donor_id}/wealth-insights/generate
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Reserves shared AI capacity and queues generation. If this donor already has an active generation, reuses its status. Poll data.poll_url; completion may be ready, insufficient-data, skipped or failed.202 does not mean the profile has finished.



# Read a human-input interrupt
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-a-human-input-interrupt

get /admin/workspace-agent/interrupts/{interrupt}
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Returns the request and response_schema for constructing a resolution, plus current version and expiry.



# Read a Tali work item
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-a-tali-work-item

get /admin/aida/work-items/{workItemId}
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Returns current work, source evidence, draft, approval, action timeline, outcome and learning.



# Read a workspace-agent conversation
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-a-workspace-agent-conversation

get /admin/workspace-agent/conversations/{conversation}
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Includes active participants, active/latest run and up to sixteen open interrupts for the current participant. Returns ETag for conditional updates.



# Read agent artifact metadata
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-agent-artifact-metadata

get /admin/workspace-agent/artifacts/{artifact}
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Content bytes are returned only by the content URL after current conversation/run authorization.



# Read an agent run
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-an-agent-run

get /admin/workspace-agent/runs/{run}
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Includes lifecycle/dispatch state, provider/model, grounding/safety and per-attempt usage/cost accounting.



# Read bulk donor generation progress
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-bulk-donor-generation-progress

get /admin/donor-intelligence/generations/bulk/{bulk_generation_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns the cached organization bulk receipt with per-donor state and aggregate counts. Unknown or expired bulk IDs return404.



# Read bulk donor generation progress
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-bulk-donor-generation-progress-1

get /admin/wealth-insights/generations/bulk/{bulk_generation_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns the cached organization bulk receipt with per-donor state and aggregate counts. Unknown or expired bulk IDs return404.



# Read donor intelligence adoption over thirty days
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-adoption-over-thirty-days

get /admin/donor-intelligence/{client_id}/usage
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Groups current-privacy profile rows by generating user; top_users contains the ten highest counts.



# Read donor intelligence adoption over thirty days
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-adoption-over-thirty-days-1

get /admin/wealth-insights/{client_id}/usage
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Groups current-privacy profile rows by generating user; top_users contains the ten highest counts.



# Read Donor Intelligence coverage and capacity summary
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-coverage-and-capacity-summary

get /admin/donor-intelligence/{client_id}/summary
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Coverage is the fraction of supporter donors with a current profile. Stale/high-capacity counts use dashboard settings; large workspaces may use a cached summary.



# Read Donor Intelligence coverage and capacity summary
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-coverage-and-capacity-summary-1

get /admin/wealth-insights/{client_id}/summary
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Coverage is the fraction of supporter donors with a current profile. Stale/high-capacity counts use dashboard settings; large workspaces may use a cached summary.



# Read Donor Intelligence dashboard settings
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-dashboard-settings

get /admin/donor-intelligence/{client_id}/settings
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns configured stale and high-capacity thresholds.



# Read Donor Intelligence dashboard settings
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-dashboard-settings-1

get /admin/wealth-insights/{client_id}/settings
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns configured stale and high-capacity thresholds.



# Read donor intelligence export progress
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-export-progress

get /admin/donor-intelligence/{client_id}/donors/exports/{uploadId}/status
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns queued/processing/ready/failed progress; download_url is present when generated bytes are available and current authorization permits them.



# Read donor intelligence export progress
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-intelligence-export-progress-1

get /admin/wealth-insights/{client_id}/donors/exports/{uploadId}/status
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns queued/processing/ready/failed progress; download_url is present when generated bytes are available and current authorization permits them.



# Read donor profile generation status
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-profile-generation-status

get /admin/donors/{donor_id}/donor-intelligence/generations/{generation_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Generation UUID must belong to this tenant and donor. Completed runs include normalized insights and usage; failed/skipped runs include their lifecycle message. Expired cache or unknown generation returns404.



# Read donor profile generation status
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-donor-profile-generation-status-1

get /admin/donors/{donor_id}/wealth-insights/generations/{generation_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Generation UUID must belong to this tenant and donor. Completed runs include normalized insights and usage; failed/skipped runs include their lifecycle message. Expired cache or unknown generation returns404.



# Read my donor intelligence usage status
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-my-donor-intelligence-usage-status

get /admin/donors/{client_id}/donor-intelligence
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Counts distinct donors with current profiles and computes remaining profile runs from the shared AI credit balance. has_insights on the user-status endpoint reflects this user having a stored profile row.



# Read my donor intelligence usage status
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-my-donor-intelligence-usage-status-1

get /admin/donors/{client_id}/wealth-insights
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Counts distinct donors with current profiles and computes remaining profile runs from the shared AI credit balance. has_insights on the user-status endpoint reflects this user having a stored profile row.



# Read shared workspace AI capacity
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-shared-workspace-ai-capacity

get /admin/ai-capacity/summary
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns available/reserved/spent credits, action rates, top-up price, expiry notices and recent ledger entries.



# Read Tali workspace policy settings
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-tali-workspace-policy-settings

get /admin/aida/settings
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Merges current source registry rows with saved settings and includes workflows/action availability and experiment governance.



# Read the latest stored donor intelligence profile
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-the-latest-stored-donor-intelligence-profile

get /admin/donor-intelligence/{client_id}/donors/{donor_id}/latest
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns the raw stored profile with JSON-valued data retained as serialized strings and normalized Markdown. Missing donor or current profile returns404.



# Read the latest stored donor intelligence profile
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-the-latest-stored-donor-intelligence-profile-1

get /admin/wealth-insights/{client_id}/donors/{donor_id}/latest
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns the raw stored profile with JSON-valued data retained as serialized strings and normalized Markdown. Missing donor or current profile returns404.



# Read the latest stored donor intelligence profile
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-the-latest-stored-donor-intelligence-profile-2

get /admin/donors/{client_id}/donor-intelligence/{donor_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns the raw stored profile with JSON-valued data retained as serialized strings and normalized Markdown. Missing donor or current profile returns404.



# Read the latest stored donor intelligence profile
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-the-latest-stored-donor-intelligence-profile-3

get /admin/donors/{client_id}/wealth-insights/{donor_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Returns the raw stored profile with JSON-valued data retained as serialized strings and normalized Markdown. Missing donor or current profile returns404.



# Read the Tali work review workspace
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-the-tali-work-review-workspace

get /admin/aida/workspace
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Returns prioritized open work, review inbox, source sweeps, settings and portfolio/learning context. Restricted sources are redacted; configured demo-workspace setup may materialize initial work.



# Read workspace donor intelligence usage
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/read-workspace-donor-intelligence-usage

get /admin/donors/{client_id}/distinct-usage-insights
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Counts distinct donors with current profiles and computes remaining profile runs from the shared AI credit balance. has_insights on the user-status endpoint reflects this user having a stored profile row.



# Recall approved relationship source evidence
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/recall-approved-relationship-source-evidence

post /admin/aida/recall
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Searches currently allowed source types using operational search and embedding similarity, with database/deterministic fallback when configured. Restricted/sensitive sources are excluded. limit applies per search channel, default five.



# Record a source change on Tali work
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/record-a-source-change-on-tali-work

post /admin/aida/work-items/{workItemId}/source-change
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Adds changed source context and marks affected drafts/review stale so they are refreshed before approval.



# Record feedback for an agent run
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/record-feedback-for-an-agent-run

post /admin/workspace-agent/runs/{run}/feedback
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Event/message targets must belong to this run/conversation. evidence is limited to16000 serialized bytes and payload safety rules. rubric user-failure-report requires a committed unredacted assistant message from this run; server derives failure evidence and deduplicates per run/user.



# Refresh a stale Tali draft
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/refresh-a-stale-tali-draft

post /admin/aida/work-items/{workItemId}/refresh-draft
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Refreshes source/relationship context, rebuilds the latest draft and reopens review under current action permissions.



# Reject Tali work
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/reject-tali-work

post /admin/aida/work-items/{workItemId}/reject
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Closes nonterminal work and rejects any pending approval.



# Rename, archive or restore a conversation
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/rename-archive-or-restore-a-conversation

patch /admin/workspace-agent/conversations/{conversation}
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Requires If-Match and UUID Idempotency-Key, plus at least one of title/status. Empty title normalizes to null. Only active/archived conversations are mutable; revision increments and response includes the new ETag. client_id/actor_id are prohibited.



# Request missing context for Tali work
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/request-missing-context-for-tali-work

post /admin/aida/work-items/{workItemId}/request-context
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Marks work as missing input and by default creates a task for the current/selected owner. due_date defaults to two days ahead; create_task false records the request without a task.



# Resolve an agent human-input interrupt
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/resolve-an-agent-human-input-interrupt

post /admin/workspace-agent/interrupts/{interrupt}/resolve
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. Requires an open matching expected_version and the intended participant when one is named. Resolution must satisfy the returned response_schema and payload guard. Accepted command updates the interrupt and queues workflow delivery; caller-supplied client_id/actor_id are prohibited.



# Resolve an ambiguous Tali relationship
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/resolve-an-ambiguous-tali-relationship

post /admin/aida/work-items/{workItemId}/resolve-match
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Only work needing relationship resolution can be matched. Confirms the relationship name and optional existing donor ID before preparing external copy.



# Run an approved-source work sweep
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/run-an-approved-source-work-sweep

post /admin/aida/runs/retry
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Runs the source sweep immediately, executes permitted policy-bound internal autonomous actions and indexes open recall sources. The201 response contains the completed sweep result, not a queue-only receipt.



# Save an authored donor intelligence profile
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/save-an-authored-donor-intelligence-profile

post /admin/donors/donor-intelligence/{donor_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Requires body client_id matching the current organization. snapshotData, askData and relationshipMapData are serialized JSON strings. Reserves and spends donor-profile AI capacity while persisting the profile; the email-privacy stamp is server-authored.



# Save an authored donor intelligence profile
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/save-an-authored-donor-intelligence-profile-1

post /admin/donors/wealth-insights/{donor_id}
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Requires body client_id matching the current organization. snapshotData, askData and relationshipMapData are serialized JSON strings. Reserves and spends donor-profile AI capacity while persisting the profile; the email-privacy stamp is server-authored.



# Search donor records for a Tali relationship
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/search-donor-records-for-a-tali-relationship

get /admin/aida/relationship-matches
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Returns up to twelve organization donor matches by identity fields. Supply query or q, each at least two characters.



# Stream workspace-agent run events
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/stream-workspace-agent-run-events

get /admin/workspace-agent/runs/{run}/events
Requires the workspace-agent deployment, rollout and feature flag plus a current Tali/Aida access permission. Conversation resources require an active human participant in the same tenant; inaccessible resources are concealed. SSE emits workspace-agent.event with sequence as id, heartbeats, and workspace-agent.stream-end on terminal/suspended runs or the configured delivery-window boundary. Resume with Last-Event-ID (preferred) or after. Every polling batch rechecks current actor authority; revocation/resource loss emits workspace-agent.access-revoked or workspace-agent.resource-unavailable before closing.



# Suppress Tali work
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/suppress-tali-work

post /admin/aida/work-items/{workItemId}/suppress
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Marks nonterminal work suppressed and closed while recording the reviewer reason.



# Transcribe a Tali voice note
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/transcribe-a-tali-voice-note

post /admin/aida/transcribe
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires capture authority. Accepts approved audio/video MIME types and no more than8000000 bytes (also8000KiB upload validator). Returns text without capturing a work item. Unsupported/unconfigured/failed transcription returns422, except an explicitly configured local fallback can return empty text plus fallback_message.



# Translate text for a public organization
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/translate-text-for-a-public-organization

post /frontend/translate/{client_id}
Looks up a tenant-scoped translation by normalized text and target language, or generates and caches one. Successful output returns only the translated text and cache indicator. Uses the organization route context when no authenticated user is present. If an authenticated user is present, their organization must match the route.



# Translate workspace text
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/translate-workspace-text

post /admin/translate
Looks up a tenant-scoped translation by normalized text and target language, or generates and caches one. Successful output returns only the translated text and cache indicator. The organization is derived from the authenticated user. Requires permission: one of groups, admins, new_form, forms, manage_programs, donors_manage, donations, manage_email, email_manager, manage_sms, sms_manager, sms_inbox_view, sms_inbox_reply, sms_inbox_manage, sendblue_manage, mailings_view, mailings_generate, mailings_manage, manage_settings, access_account_settings, access_payment_gateways, tasks_manage, trips_manage, events_manage, events_sponsor_manage, imports_manage, households_manage, notes_manage, reports_manage.



# Update Donor Intelligence dashboard settings
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/update-donor-intelligence-dashboard-settings

put /admin/donor-intelligence/{client_id}/settings
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Requires full-group or manage_settings authority. Submitted nonnull thresholds override the current values.



# Update Donor Intelligence dashboard settings
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/update-donor-intelligence-dashboard-settings-1

put /admin/wealth-insights/{client_id}/settings
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Requires full-group or manage_settings authority. Submitted nonnull thresholds override the current values.



# Update relationship memory
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/update-relationship-memory

patch /admin/aida/relationship-memories/{memoryId}
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_review or full access. Updates only submitted memory fields and records the changed evidence.



# Update Tali workspace policy settings
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/update-tali-workspace-policy-settings

put /admin/aida/settings
Requires the configured Aida workspace feature (aida_workspace by default). View permits aida_view/capture/review/settings_manage or full access; mutation requires the action-specific capture, review or settings permission. All records belong to the current organization. Requires aida_settings_manage or full access. Submitted sources/freshness/notifications/pause replace their stored sections; automation merges. External send always requires approval. Increasing autonomy needs explicit level_change_approval.status approved and cannot exceed the platform routine_internal_autonomy ceiling. Experiments require approved governance before enabled; rejected requests are reflected in returned settings.



# Update workspace donor intelligence subscription metadata
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/update-workspace-donor-intelligence-subscription-metadata

post /admin/donors/{client_id}/donor-intelligence/subscription
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Sets the workspace module to paid using supplied or existing payment/metadata/expiry values. A later annual expiry may grant included-plan renewal credits. This operation changes subscription/capacity state; it does not itself charge a payment card.



# Update workspace donor intelligence subscription metadata
Source: https://api-docs.helpyousponsor.com/api-reference/intelligence/update-workspace-donor-intelligence-subscription-metadata-1

post /admin/donors/{client_id}/wealth-insights/subscription
Requires the donor_intelligence feature and route permissions. Every client_id route is restricted to the authenticated organization, including platform administrators using workspace routes. Stored profiles are filtered against current email-privacy state; obsolete privacy snapshots are concealed. Legacy wealth-insights URLs are equivalent aliases. Sets the workspace module to paid using supplied or existing payment/metadata/expiry values. A later annual expiry may grant included-plan renewal credits. This operation changes subscription/capacity state; it does not itself charge a payment card.



# API Reference
Source: https://api-docs.helpyousponsor.com/api-reference/introduction

Gratona REST API authentication, versions, and endpoint reference

## Authentication

For server-to-server integrations, generate an API key from **Settings → Account Settings → Developer Settings** in the Gratona dashboard. Send the key in the `X-HYS-API-Key` header on protected admin requests:

```sh theme={null}
curl --request GET \
  --url https://api.gratona.com/v1/admin/api_keys \
  --header 'X-HYS-API-Key: hys_your_key_here'
```

Protected admin endpoints also accept Passport access tokens through `Authorization: Bearer <token>`. These are alternative authentication methods; one valid credential is sufficient. Access is limited to the key or token's organization and the user's permissions.

Public endpoints do not require an admin API key. Donor, recipient, and participant portal endpoints have their own sign-in and session requirements. Follow each endpoint's parameters and authentication description; an admin API key does not replace a portal session.

## API Versions

Most operations use `https://api.gratona.com/v1`. The v2 notes API uses `/v2`. Schema discovery, primitives and the newer Zapier operations use `/v3`. Public endpoints mounted outside a version prefix use the root API URL. Each endpoint's generated request example includes its correct base URL.

The continuing `api.helpyousponsor.com` host supports compatibility integrations. The `X-HYS-API-Key` header remains the API-key header on both hosts.

## Available Workflows

The reference includes donors and households, donations and recognition, sponsorships and recipient funding, events, journeys, trips, tasks, fundraising and stewardship, impact stories, communications, reports, integrations, Spaces and Library, and workspace setup.

Feature availability depends on your organization's configuration, subscription, permissions and rollout settings. An endpoint's presence in the reference does not grant access to its feature. Read the endpoint's requirements and preview or approval steps before submitting a change.

## Requests And Responses

Use the method, path, content type, and required fields shown for each operation. Mutations may require a preview token or an idempotency key. A `202 Accepted` response means work was queued; use the documented status endpoint to observe completion. Retired operations may return `410 Gone`.

This reference is generated from controller annotations in the Gratona API repository. Examples describe the API contract; use test data when trying operations that create or change records.


# Activate a journey
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/activate-a-journey

post /admin/journeys/{id}/activate
Validates trigger availability, graph reachability, message content, delays, tasks, branches, goals and notifications before setting active status. Drafts copied from legacy automations remain activation locked. Requires journeys_manage or beta_features; records remain organization scoped.



# Copy a system automation into a journey draft
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/copy-a-system-automation-into-a-journey-draft

post /admin/journeys/system-automations/convert
Creates a draft with copied source email/SMS steps; this leaves legacy delivery configuration in place. Converted legacy triggers are activation locked until migrated to the Journeys runtime. Requires the workspace bridge and conversion capability. Requires journeys_manage or beta_features; records remain organization scoped.



# Create a journey draft
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/create-a-journey-draft

post /admin/journeys
Creates a draft for an available subject type. Event filters must belong to this organization; event triggers require the event-journeys flag. The response omits graph arrays until the journey is fetched or its steps are saved. Requires journeys_manage or beta_features; records remain organization scoped.



# Create a journey message template
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/create-a-journey-message-template

post /admin/journeys/message-templates
Creates an enabled source template in the organization library. Email requires a subject; SMS availability depends on installed messaging support. Embedded story reuse validates permission and review evidence. Requires journeys_manage or group_all.



# Create an event interest follow-up draft
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/create-an-event-interest-follow-up-draft

post /admin/journeys/event-follow-ups/{eventId}
Creates an event-scoped donor journey with a trigger and an empty email step. Add message content before activation. The default repeat policy is each_order, with reentry disabled; event journeys must be enabled.



# Delete a journey
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/delete-a-journey

delete /admin/journeys/{id}
Soft-deletes the journey and exits every active enrollment with exit_reason journey_deleted, clearing its current step and recording an exit log. Requires journeys_manage or beta_features; records remain organization scoped.



# Duplicate a journey into a draft
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/duplicate-a-journey-into-a-draft

post /admin/journeys/{id}/duplicate
Copies settings, trigger, steps and edges into a uniquely named draft and records source_journey_id in settings. The source remains unchanged. Requires journeys_manage or beta_features; records remain organization scoped.



# Get a journey graph
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/get-a-journey-graph

get /admin/journeys/{id}
Returns the journey, its ordered steps and edges, editability, and activation blockers. Sponsorship journeys return 404 when their lifecycle feature is unavailable. Read access requires journeys_view, journeys_manage or beta_features; records remain organization scoped.



# Get a journey message template
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/get-a-journey-message-template

get /admin/journeys/message-templates/{channel}/{id}
Returns the selected organization-owned library template. Email details include designer data, merge tags and rendered previews; SMS details include retained story IDs. Requires journeys_view, journeys_manage or group_all.



# Get journey editor options
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/get-journey-editor-options

get /admin/journeys/options
Returns organization-specific trigger, field, assignee, template and editor catalogs. Event and sponsorship choices follow workspace feature flags; this endpoint additionally checks journeys_view, journeys_manage or group_all.



# Get journey execution statistics
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/get-journey-execution-statistics

get /admin/journeys/{id}/stats
Returns enrollment totals, messages executed, per-step execution/drop-off counts, branch traffic and health alerts. Recovery rate is nullable outside an overdue-commitment journey with a recovery branch; first-engagement timing is nullable before activity exists. Read access requires journeys_view, journeys_manage or beta_features; records remain organization scoped.



# List event follow-up journeys
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/list-event-follow-up-journeys

get /admin/journeys/event-follow-ups/{eventId}
Lists draft, active and paused donor journeys triggered by monthly-giving or sponsorship interest for this event, including journeys configured for all events. Returns 404 when event journeys are disabled.



# List journey enrollments
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/list-journey-enrollments

get /admin/journeys/{id}/enrollments
Returns enrollment state, resolved subject names, current-step summaries and execution logs, newest entry first. Event-backed runs include occurrence metadata. Read access requires journeys_view, journeys_manage or beta_features; records remain organization scoped.



# List journey message templates
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/list-journey-message-templates

get /admin/journeys/message-templates
Returns email/SMS source templates, setup readiness and editor merge contexts. Reading requires journeys_view, journeys_manage or group_all in addition to route permissions.



# List journeys
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/list-journeys

get /admin/journeys
Returns filtered journeys, health indicators, filtered summary counts and starter templates. Default ordering puts journeys needing attention first, followed by lifecycle priority and favorites. Read access requires journeys_view, journeys_manage or beta_features; records remain organization scoped.



# List legacy system automations
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/list-legacy-system-automations

get /admin/journeys/system-automations
Returns configured email/SMS system automations, delivery health and the programs affected by shared sources. Returns 404 when the workspace system-automation bridge is disabled. Read access requires journeys_view, journeys_manage or beta_features; records remain organization scoped.



# Pause a journey
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/pause-a-journey

post /admin/journeys/{id}/pause
Sets the journey to paused and returns its graph and activation checks. Requires journeys_manage or beta_features; records remain organization scoped.



# Provision starter journey templates
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/provision-starter-journey-templates

post /admin/journeys/message-templates/provision
Idempotently creates missing Journeys email/SMS template sets and configured starter templates. Existing source content is preserved. Requires journeys_manage or group_all.



# Replace a draft journey graph
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/replace-a-draft-journey-graph

post /admin/journeys/{id}/steps
Atomically replaces all steps and edges and returns the graph with client_step_id_map. Exactly one trigger is required, and every edge must reference a submitted step. Only drafts can be replaced; handwritten cards require donor-backed subjects, while sponsorship journeys prohibit tag, update_field and handwritten-card steps. Requires journeys_manage or beta_features; records remain organization scoped.



# Update a shared journey message template
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/update-a-shared-journey-message-template

put /admin/journeys/message-templates/{channel}/{id}
Updates the source library template; every journey step still live-linked to it receives the changes. Email designer data is preserved when omitted; enabled is optional. Embedded story evidence is refreshed. Requires journeys_manage or group_all.



# Update journey details
Source: https://api-docs.helpyousponsor.com/api-reference/journeys/update-journey-details

put /admin/journeys/{id}
Updates supplied metadata, trigger configuration and settings. This endpoint preserves omitted properties; replace the graph through the steps endpoint. Event filter ownership and unique name checks still apply. Requires journeys_manage or beta_features; records remain organization scoped.



# Authorize an immutable Library source upload
Source: https://api-docs.helpyousponsor.com/api-reference/library/authorize-an-immutable-library-source-upload

post /admin/workspace-library/upload-admissions
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Reserves one API-proxied admission, without uploading bytes. Requires storage readiness and current document boundary. Both current-version fields must be present and jointly null or populated. File names cannot contain slashes, backslashes or controls. Google Drive-managed sources reject manual uploads.



# Browse folders in an owned Drive account
Source: https://api-docs.helpyousponsor.com/api-reference/library/browse-folders-in-an-owned-drive-account

get /admin/workspace-library/drive/connections/{connection}/folders
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. folder defaults to root; page is the provider continuation token returned as next_page.



# Complete a Google Drive connection
Source: https://api-docs.helpyousponsor.com/api-reference/library/complete-a-google-drive-connection

post /admin/workspace-library/drive/connections/{connection}/complete
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Consumes a matching unexpired connection flow and verifies the connected account identity. An optional session_uri is checked during that verification.



# Correct a current image description and tags
Source: https://api-docs.helpyousponsor.com/api-reference/library/correct-a-current-image-description-and-tags

patch /admin/workspace-library/files/{file}/analysis
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires workspace_library_manage and rollout availability. expected_sha256 must match current bytes and a ready current analyzer result must exist. tags is required but may be empty; editing schedules search reindexing.



# Create a draft story from a Library file
Source: https://api-docs.helpyousponsor.com/api-reference/library/create-a-draft-story-from-a-library-file

post /admin/workspace-library/files/{file}/stories
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Creates an internal, unreviewed story and attaches this file. Requires impact_stories_manage; a matching request_key reuses the draft, while changed content conflicts. Mapped Drive folder program context is inherited. Existing story edits are refused with 409 and must be made in Stories.



# Create a personal Library collection
Source: https://api-docs.helpyousponsor.com/api-reference/library/create-a-personal-library-collection

post /admin/workspace-library/file-collections
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Names must be nonblank and contain no control characters.



# Create canonical Library document metadata
Source: https://api-docs.helpyousponsor.com/api-reference/library/create-canonical-library-document-metadata

post /admin/workspace-library/documents
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Creates a draft with record_version 1 and no source version. Titles are trimmed, nonblank and free of control characters; domain/type/sensitivity keys use lowercase identifiers. Upload source bytes through a separate admission.



# Delete a personal Library collection
Source: https://api-docs.helpyousponsor.com/api-reference/library/delete-a-personal-library-collection

delete /admin/workspace-library/file-collections/{collection}
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Deleting a collection clears its file assignments; files remain available.



# Delete a personal Library filter view
Source: https://api-docs.helpyousponsor.com/api-reference/library/delete-a-personal-library-filter-view

delete /admin/workspace-library/file-views/{viewId}
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Only the current user own view can be deleted.



# Disconnect an owned Drive account
Source: https://api-docs.helpyousponsor.com/api-reference/library/disconnect-an-owned-drive-account

post /admin/workspace-library/drive/connections/{connection}/disconnect
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Disconnects this provider account and withdraws its shared source authority.



# Discover available Library filter fields
Source: https://api-docs.helpyousponsor.com/api-reference/library/discover-available-library-filter-fields

get /admin/workspace-library/file-filter-fields
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Returns field types, selectable options and permitted recipient custom fields. Visibility options follow whether Spaces clearance is enabled; asynchronous linked-record options use the records endpoint.



# Get an unadmitted Drive original URL
Source: https://api-docs.helpyousponsor.com/api-reference/library/get-an-unadmitted-drive-original-url

get /admin/workspace-library/files/{file}/source
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Only drive: prefixed catalog references support this endpoint. Resolves and verifies the provider source before returning its open URL.



# Link a canonical document to a record
Source: https://api-docs.helpyousponsor.com/api-reference/library/link-a-canonical-document-to-a-record

post /admin/workspace-library/documents/{document}/links
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Both current-version boundary fields must be present and either both null or both populated. subject_id is a string; subject and relationship types must be registered and accessible. is_primary must be a JSON boolean. Stale document boundaries or idempotency conflicts return 409.



# List active document links
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-active-document-links

get /admin/workspace-library/documents/{document}/links
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Returns up to fifty active links and the current document record version. Continue using next_after_link_id when has_more is true.



# List canonical Library documents
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-canonical-library-documents

get /admin/workspace-library/documents
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Uses an authority-bound signed cursor. Search matches full-content rows only. Unknown query fields and request bodies are rejected.



# List consent evidence for a recipient
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-consent-evidence-for-a-recipient

get /admin/workspace-library/consent-evidence
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires access to the recipient; returns the newest100 releases including valid, scheduled, expired and revoked states.



# List failed image analyses in a shared root
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-failed-image-analyses-in-a-shared-root

get /admin/workspace-library/drive/roots/{root}/analysis-issues
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Only accessible ready-image files with failed current analysis appear. Returns twenty files per page.



# List immutable source versions
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-immutable-source-versions

get /admin/workspace-library/documents/{document}/versions
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. Returns up to fifty source versions with their latest text projection state; identity fields follow each version content directive. Cursor is encrypted and bound to current authority.



# List my saved Library filter views
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-my-saved-library-filter-views

get /admin/workspace-library/file-views
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Returns personal views ordered by name.



# List record folders containing uploads
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-record-folders-containing-uploads

get /admin/workspace-library/file-record-folders
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Returns twenty-four accessible donor or recipient folders per page ordered by latest attachment. Search may reject overly broad matches rather than return a partial result.



# List saved source excerpts
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-saved-source-excerpts

get /admin/workspace-library/documents/{document}/excerpts
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. Returns up to fifty active excerpts ordered by UUID. Continue using next_after when present.



# List shared Google Drives
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-shared-google-drives

get /admin/workspace-library/drive/connections/{connection}/drives
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Returns provider Drive IDs and names with a continuation token for additional drives.



# List stories using a Library file
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-stories-using-a-library-file

get /admin/workspace-library/files/{file}/stories
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Returns up to fifty newest associated stories, rechecking their program access. Without story access returns an empty list. Continue with next_after even when some rows were concealed.



# List the accessible Library file catalog
Source: https://api-docs.helpyousponsor.com/api-reference/library/list-the-accessible-library-file-catalog

get /admin/workspace-library/files
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Combines native record uploads, canonical Library documents, Drive and supported message/export sources. Content search uses current published analysis; filename search is the default. Source counts may be null while legacy message projection totals are unavailable.



# Map a shared Drive folder to a program
Source: https://api-docs.helpyousponsor.com/api-reference/library/map-a-shared-drive-folder-to-a-program

post /admin/workspace-library/drive/roots/{root}/context
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Support sessions cannot mutate mappings. folder_id must be the root or a discovered current child. program_id must be present and may be null to remove the mapping; current and previous mapped programs must be accessible.



# Preview or download catalog file bytes
Source: https://api-docs.helpyousponsor.com/api-reference/library/preview-or-download-catalog-file-bytes

get /admin/workspace-library/files/{file}/preview
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Streams verified source bytes with private no-store and safe content disposition. thumbnail requests a bounded PNG derivative. Unadmitted Drive items return 409 and should use their source URL. Processing or changed originals also conflict.



# Queue an HTTPS source capture
Source: https://api-docs.helpyousponsor.com/api-reference/library/queue-an-https-source-capture

post /admin/workspace-library/documents/{document}/capture-url
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. Requires manage authority and expected_record_version. Queues capture and returns a capture ID; the source may remain pending or fail. Poll source status for progress. Drive-managed documents cannot be manually replaced.



# Queue analysis for the current Library image
Source: https://api-docs.helpyousponsor.com/api-reference/library/queue-analysis-for-the-current-library-image

post /admin/workspace-library/files/{file}/analysis
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires workspace_library_manage, rollout availability and shared AI/daily capacity. Only verified JPEG/PNG sources within configured size limits qualify. Existing current analysis is reused or retried.202 acknowledges the request; processing and search publication may still be pending.



# Read a catalog file metadata
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-a-catalog-file-metadata

get /admin/workspace-library/files/{file}
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. file is the prefixed catalog identity returned by index, such as upload:123 or document:UUID; source and linked-record authority are rechecked.



# Read canonical document metadata
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-canonical-document-metadata

get /admin/workspace-library/documents/{document}
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Conceals inaccessible documents with 404; no previous list result grants ongoing access.



# Read current file analysis status
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-current-file-analysis-status

get /admin/workspace-library/files/{file}/analysis
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Only admitted document: references with a current source version support analysis. Returns generated/corrected description, search publication and automatic-source status for the current bytes.



# Read current upload and URL-capture status
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-current-upload-and-url-capture-status

get /admin/workspace-library/documents/{document}/source-status
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. upload_available reflects processing readiness and is false for Drive-managed sources. state can be capturing_url, no_source or the latest admission lifecycle state.



# Read Drive folder program mappings
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-drive-folder-program-mappings

get /admin/workspace-library/drive/roots/{root}/context
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Returns the root plus twenty child folders per page and up to twenty accessible program choices. A restricted existing mapping is concealed; replacing it requires access to its prior program.



# Read Drive source connections and sync progress
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-drive-source-connections-and-sync-progress

get /admin/workspace-library/drive
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Lists organization connections, live shared roots, up to fifty actionable file issues, provider configuration and daily image-analysis capacity. analysis_progress is omitted outside the rollout.



# Read extracted document text and a citation range
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-extracted-document-text-and-a-citation-range

get /admin/workspace-library/documents/{document}/projections/{projection}
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. The projection must be ready and match its immutable source. Supply start and end together for an optional byte range no longer than16000 bytes. Range must be within text and cannot split a UTF-8 character. The full text is still returned along with before/quote/after.



# Read file clearance and consent decisions
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-file-clearance-and-consent-decisions

get /admin/workspace-library/files/{file}/clearance
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Shows current version safety signals, reachable audiences and available review actions. Noncurrent version signals read as unknown.



# Read immutable document source bytes
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-immutable-document-source-bytes

get /admin/workspace-library/documents/{document}/versions/{version}/preview
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. Returns the source MIME type or a PNG thumbnail. Unsafe inline types download as attachments. Unsupported thumbnail sources or changed generation/hash evidence return 409; processing availability can return503.



# Read Library organization and storage summary
Source: https://api-docs.helpyousponsor.com/api-reference/library/read-library-organization-and-storage-summary

get /admin/workspace-library/file-organization
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Includes personal collections, AI rollout state and informational storage accounting. Schedules storage reconciliation at most once per fifteen minutes per organization.



# Record recipient media consent evidence
Source: https://api-docs.helpyousponsor.com/api-reference/library/record-recipient-media-consent-evidence

post /admin/workspace-library/consent-evidence
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires media_clearance_manage and recipient access. valid_from defaults to now; expires_at must be later. Evidence permits supporter/public media use according to its scope.



# Redirect edits of existing Library stories
Source: https://api-docs.helpyousponsor.com/api-reference/library/redirect-edits-of-existing-library-stories

patch /admin/workspace-library/files/{file}/stories/{story}
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Creates an internal, unreviewed story and attaches this file. Requires impact_stories_manage; a matching request_key reuses the draft, while changed content conflicts. Mapped Drive folder program context is inherited. Existing story edits are refused with 409 and must be made in Stories.



# Remove a saved source excerpt
Source: https://api-docs.helpyousponsor.com/api-reference/library/remove-a-saved-source-excerpt

delete /admin/workspace-library/documents/{document}/excerpts/{excerpt}
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. Requires document manage authority. Soft-removes a matching excerpt; no matching excerpt also yields 204.



# Remove analysis for the confirmed image bytes
Source: https://api-docs.helpyousponsor.com/api-reference/library/remove-analysis-for-the-confirmed-image-bytes

delete /admin/workspace-library/files/{file}/analysis
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires workspace_library_manage. expected_sha256 guards against replacing another version description. Retires matching descriptions/corrections and schedules removal from search; this remains available when the rollout is disabled.



# Rename a canonical Library document
Source: https://api-docs.helpyousponsor.com/api-reference/library/rename-a-canonical-library-document

patch /admin/workspace-library/documents/{document}
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Requires expected_record_version from the current document. A successful title change increments record_version; an unchanged title returns unchanged. Stale revisions return a409 command-result receipt.



# Rename a personal Library collection
Source: https://api-docs.helpyousponsor.com/api-reference/library/rename-a-personal-library-collection

patch /admin/workspace-library/file-collections/{collection}
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Names must be nonblank and contain no control characters.



# Replace a personal Library filter view
Source: https://api-docs.helpyousponsor.com/api-reference/library/replace-a-personal-library-filter-view

patch /admin/workspace-library/file-views/{viewId}
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires a nonblank name and a nonempty valid filters tree. Maximum 100 views per user. Updating replaces the complete saved definition with submitted supported fields.



# Revoke recipient consent evidence
Source: https://api-docs.helpyousponsor.com/api-reference/library/revoke-recipient-consent-evidence

post /admin/workspace-library/consent-evidence/{evidenceId}/revoke
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires workspace_library_manage or media_clearance_manage and current recipient access. Repeating a revocation returns the existing revoked record.



# Save a personal Library filter view
Source: https://api-docs.helpyousponsor.com/api-reference/library/save-a-personal-library-filter-view

post /admin/workspace-library/file-views
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires a nonblank name and a nonempty valid filters tree. Maximum 100 views per user. Updating replaces the complete saved definition with submitted supported fields.



# Save a verified source excerpt
Source: https://api-docs.helpyousponsor.com/api-reference/library/save-a-verified-source-excerpt

post /admin/workspace-library/documents/{document}/excerpts
Requires current full-content Library document authority; Drive sources additionally recheck provider ownership. Source reads use immutable version and content hashes. Requires document manage authority and a UUID Idempotency-Key. start/end identify UTF-8-safe byte offsets in a ready projection, with end greater than start and range at most 16000 bytes. Replaying the same key/payload returns the same excerpt ID; changed payload conflicts.



# Schedule a shared Drive source retry
Source: https://api-docs.helpyousponsor.com/api-reference/library/schedule-a-shared-drive-source-retry

post /admin/workspace-library/drive/roots/{root}/retry
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Schedules synchronization and resets actionable files when no active/recent sync is running. Existing active work is left queued and still returns scheduled.



# Search accessible records to link a document
Source: https://api-docs.helpyousponsor.com/api-reference/library/search-accessible-records-to-link-a-document

get /admin/workspace-library/documents/{document}/link-records
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Requires document manage authority; offers up to ten accessible donor, recipient or program choices.



# Search or hydrate linked-record filter options
Source: https://api-docs.helpyousponsor.com/api-reference/library/search-or-hydrate-linked-record-filter-options

get /admin/workspace-library/file-filter-records
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Supply search (including an empty value) to search accessible donor, recipient and program options, or supply ids when search is absent. Unavailable hydrated IDs are omitted.



# Set automatic image analysis for a shared root
Source: https://api-docs.helpyousponsor.com/api-reference/library/set-automatic-image-analysis-for-a-shared-root

post /admin/workspace-library/drive/roots/{root}/analysis
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Enabling requires rollout availability and configured analysis; disabling parks queued analyses and releases their capacity reservations.



# Share a Drive folder with the organization
Source: https://api-docs.helpyousponsor.com/api-reference/library/share-a-drive-folder-with-the-organization

post /admin/workspace-library/drive/connections/{connection}/roots
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Explicitly confirms organization sharing and schedules synchronization. analyze_images opts a newly created/restored root into automatic analysis; an already-active root keeps its existing analysis setting.



# Star files or assign a personal collection
Source: https://api-docs.helpyousponsor.com/api-reference/library/star-files-or-assign-a-personal-collection

patch /admin/workspace-library/file-preferences
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Requires a nonempty selection plus starred or collection_id. All files are authorized before any write. A null collection_id clears the assignment.



# Start a Google Drive connection
Source: https://api-docs.helpyousponsor.com/api-reference/library/start-a-google-drive-connection

post /admin/workspace-library/drive/connect
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Returns the redirect URL and state for this user to connect or reconnect their provider account. Complete the flow using the returned connection ID and state.



# Stop sharing a Drive folder
Source: https://api-docs.helpyousponsor.com/api-reference/library/stop-sharing-a-drive-folder

post /admin/workspace-library/drive/roots/{root}/stop
Requires workspace_library_manage and manage_settings under the current role. Connections are owned by the connecting user; provider and current-role authority are rechecked around provider I/O. Marks the root removed, withdraws memberships, invalidates sync generation and pauses queued automatic image analysis.



# Unlink a canonical document from a record
Source: https://api-docs.helpyousponsor.com/api-reference/library/unlink-a-canonical-document-from-a-record

delete /admin/workspace-library/documents/{document}/links/{link}
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Requires the current document boundary and expected_link_record_version. Both current-version boundary fields must be present and jointly null or populated. Returns an immutable unlinked receipt.



# Update file clearance or safety signals
Source: https://api-docs.helpyousponsor.com/api-reference/library/update-file-clearance-or-safety-signals

put /admin/workspace-library/files/{file}/clearance
Uses the current tenant and Library/linked-record permissions. Private preferences and collections belong to the current user. Mutations are unavailable in support sessions. Library managers may narrow visibility. Widening, removing linked-supporter restrictions or weakening safety signals requires media_clearance_manage and access to every associated recipient/program. Consent holds reject widening with 409. Record uploads cannot be reset to not_reviewed and people_detected is not persisted for them.



# Upload the authorized source bytes
Source: https://api-docs.helpyousponsor.com/api-reference/library/upload-the-authorized-source-bytes

put /admin/workspace-library/upload-admissions/{admission}/bytes
Requires current Library authority and tenant ownership. Content directives are full, masked_identifiers or none; masked documents omit protected identity values. Commands accept only their documented JSON keys and reject query-string fields. Required Idempotency-Key is 8-128 URL-safe characters; changed payload under the same key conflicts. Send raw application/octet-stream bytes using the returned upload_path, generation and session headers. Query fields, Content-Encoding and caller-authored checksum/evidence headers are rejected. The response acknowledges immutable byte storage; scan/extraction/commit processing is queued or deferred as indicated by X-Workspace-Library-Processing. Matching replay resolves the saved receipt.



# Get my notification preferences
Source: https://api-docs.helpyousponsor.com/api-reference/notifications/get-my-notification-preferences

get /admin/notification-preferences
Returns the authenticated admin’s category/event switches and optional signed credentials for both the shared workspace feed and personal feed. Credentials are null when subscriber HMAC is unavailable. The response is private and must not be cached. Category/event/channel keys come from this catalog. Requires permission: notification_preferences_self_service.



# Get the legacy notification count
Source: https://api-docs.helpyousponsor.com/api-reference/notifications/get-the-legacy-notification-count

get /notification/count
Compatibility endpoint. The current implementation always returns count0; current notification feeds are provided through the notification preference/subscriber integration. Requires permission: one of account, programs_view, donors_view, donations, manage_settings, access_account_settings, access_payment_gateways.



# List legacy notifications
Source: https://api-docs.helpyousponsor.com/api-reference/notifications/list-legacy-notifications

get /notification/list
Compatibility endpoint. The current implementation always returns an empty array. Requires permission: one of account, programs_view, donors_view, donations, manage_settings, access_account_settings, access_payment_gateways.



# Update my notification preferences
Source: https://api-docs.helpyousponsor.com/api-reference/notifications/update-my-notification-preferences

put /admin/notification-preferences
Saves the authenticated admin’s category/event overrides. Use keys/channels from the catalog; unsupported combinations return422. enabled is required unless reset/default is truthy. Reset deletes the explicit override. Event switches inherit their category unless overridden. Entries are applied in order; a later invalid entry can fail after earlier entries were saved, so validate all keys before submitting. Requires permission: notification_preferences_self_service.



# Add a new recipient during participation intake
Source: https://api-docs.helpyousponsor.com/api-reference/participation/add-a-new-recipient-during-participation-intake

post /admin/programs/{program_id}/participation/sessions/{session_id}/recipients
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure and access to the check’s site/cohort. Creates a donor-hidden recipient, pending current placement and new-entrant observation in a draft check. A usable recipient title field is required; display_name fills the first title field when no submitted title has a value. Required recipient fields and configured intake fields must be filled; field types/options and unique values are checked, including archived duplicates. Organization-wide idempotency key replays within the same check before stale-version/state validation, returning 200 with the original result (entity may be null if no longer available); new intake returns 201. New-request stale lock_version returns 422. Returns recipient identity and the full updated check.



# Add an existing recipient to a draft check
Source: https://api-docs.helpyousponsor.com/api-reference/participation/add-an-existing-recipient-to-a-draft-check

post /admin/programs/{program_id}/participation/sessions/{session_id}/existing-recipients
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure and access to the check’s site/cohort. Requires the current version of a draft check; a stale version returns 422. The active recipient must belong to this program and have no current placement elsewhere. Creates a pending placement when unplaced, then adds a new-entrant observation and increments the check version. If already present, returns the same check after version validation.



# Add newly available recipients to a draft check
Source: https://api-docs.helpyousponsor.com/api-reference/participation/add-newly-available-recipients-to-a-draft-check

post /admin/programs/{program_id}/participation/sessions/{session_id}/new-entrants
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure and access to the check’s site/cohort. Adds recipients whose placement was created since this check began, is active on the check date and matches its location/group, excluding recipients already present. Only draft checks are accepted. A stale version returns 409 when entrants exist; when none remain this is a no-op even with a stale version. Returns the complete updated check.



# Commit a reviewed attendance import
Source: https://api-docs.helpyousponsor.com/api-reference/participation/commit-a-reviewed-attendance-import

post /admin/programs/{program_id}/participation/imports/{participation_import_id}/commit
Requires participation_configure, programs_view and access to this organization’s program, with participation enabled. Queues creation/submission of participation checks, observations and approved provisional recipients/placements. Every blocked/review row must be resolved first. Use the same idempotency key for retries; a completed matching batch returns200, otherwise202 reports queued or resumed processing. A failed partial commit retains its original commit key and resumes the same batch. Poll until completed;202 does not mean evidence has finished importing. Requires permission: one of participation_configure.



# Configure program participation
Source: https://api-docs.helpyousponsor.com/api-reference/participation/configure-program-participation

put /admin/programs/{program_id}/participation/setup
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_configure. Upserts locations, groups and non-overlapping periods; provide period or periods (periods wins if both exist). At most one period may be open. IDs update existing rows; absent IDs match normalized location/group names or period names before creating. Omitted locations/groups remain. Current placements or draft checks prevent deactivation. Required/profile field keys must belong to this program and any assignee must be an active organization user. Returns a fresh overview and increments setup revision; revision conflicts return 422.



# Create a correction draft for a submitted check
Source: https://api-docs.helpyousponsor.com/api-reference/participation/create-a-correction-draft-for-a-submitted-check

post /admin/programs/{program_id}/participation/sessions/{session_id}/corrections
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_submit or participation_configure and access to the check’s site/cohort. Only the latest submitted revision may be corrected and its series must not already have a draft. Clones the roster and evidence into a new draft with revision incremented and new observation IDs; the original stays submitted until correction submission. The organization-wide key replays only the matching source check. Returns 201 when created or 200 for replay. source_note defaults to the original when omitted or null.



# Create or reuse a recipient participation follow-up
Source: https://api-docs.helpyousponsor.com/api-reference/participation/create-or-reuse-a-recipient-participation-follow-up

post /admin/programs/{program_id}/participation/recipients/{entity_id}/follow-up
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure, visible recipient history/placement and access to the supplied check. Requires an active recipient, participation settings and a participation rollup. Manually creates or reuses the open unresolved-enrollment task for this recipient and check period without waiting for configured thresholds. Uses the configured active assignee or the caller, with due date based on follow_up_due_days. Returns 201 for both a new task and reuse.



# Find possible existing recipients for check intake
Source: https://api-docs.helpyousponsor.com/api-reference/participation/find-possible-existing-recipients-for-check-intake

get /admin/programs/{program_id}/participation/sessions/{session_id}/recipient-suggestions
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure and access to the check’s site/cohort. Returns up to eight candidate names from this program, including archived matches and already-added markers. Search considers up to sixty matching custom-field rows and ranks exact names first. Scoped roles can discover unplaced recipients; current placements outside their scope are excluded. This search does not require the check to remain draft; archived matches cannot be attached through existing-recipients.



# Get attendance import review and progress
Source: https://api-docs.helpyousponsor.com/api-reference/participation/get-attendance-import-review-and-progress

get /admin/programs/{program_id}/participation/imports/{participation_import_id}
Requires participation_configure, programs_view and access to this organization’s program, with participation enabled. Returns batch progress, source inspection, recipient field definitions and paged review rows. row_status filters rows; per_page is25,50 or100. Completed/voided batches also include created check summaries. Validation and commit jobs update this receipt asynchronously; no job is started by this read. Requires permission: one of participation_configure.



# List participation and profile exceptions
Source: https://api-docs.helpyousponsor.com/api-reference/participation/list-participation-and-profile-exceptions

get /admin/programs/{program_id}/participation/exceptions
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_view, participation_record, participation_submit or participation_configure. Results follow the caller’s site/cohort scope. Returns up to 500 prioritized recipients with unresolved enrollment or incomplete profiles, plus the uncapped total. Prioritizes sponsored/overdue recipients, then unresolved check count and exception age. Follow-up details are included only when the caller may view that task. No pagination or query filters are applied.



# List participation check history
Source: https://api-docs.helpyousponsor.com/api-reference/participation/list-participation-check-history

get /admin/programs/{program_id}/participation/sessions
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_view, participation_record, participation_submit or participation_configure. Results follow the caller’s site/cohort scope. Returns filtered summaries ordered by scheduled date, revision and ID descending. No filters means all accessible program checks.



# List recent participation imports
Source: https://api-docs.helpyousponsor.com/api-reference/participation/list-recent-participation-imports

get /admin/programs/{program_id}/participation/imports
Requires participation_configure, programs_view and access to this organization’s program, with participation enabled. Returns the most recent25 batches for this program, newest first, without paged source rows. Reading a batch does not run validation or commit imported evidence. Requires permission: one of participation_configure.



# Preview placement reconciliation
Source: https://api-docs.helpyousponsor.com/api-reference/participation/preview-placement-reconciliation

get /admin/programs/{program_id}/participation/placement-bootstrap
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_configure. Matches non-archived recipients without a current placement to active locations/groups using configured recipient fields (or school/site and class/cohort/grade field-name discovery), normalized names and legacy aliases. Requires settings and an open period. Ambiguous, missing and unmapped values are counted and skipped; preview writes nothing.



# Queue attendance import validation
Source: https://api-docs.helpyousponsor.com/api-reference/participation/queue-attendance-import-validation

post /admin/programs/{program_id}/participation/imports/{participation_import_id}/validate
Requires participation_configure, programs_view and access to this organization’s program, with participation enabled. Saves the exact symbol/worksheet mapping and queues a dry run;202 means validation is pending. Map every enabled worksheet only once, and each attendance date/column once per sheet. Selected field keys must belong to this program; the external ID field must be hysCustomID. Processing/completed/voided or partially committed failed batches cannot be remapped. Poll the batch for row review and failure results; expanded-observation limits can fail asynchronously. Requires permission: one of participation_configure.



# Read a participation check and roster
Source: https://api-docs.helpyousponsor.com/api-reference/participation/read-a-participation-check-and-roster

get /admin/programs/{program_id}/participation/sessions/{session_id}
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_view, participation_record, participation_submit or participation_configure. Results follow the caller’s site/cohort scope. Returns the complete current check representation and name-snapshot ordered observations, including lock_version needed by mutations and the count of eligible entrants not yet added.



# Read a recipient participation timeline
Source: https://api-docs.helpyousponsor.com/api-reference/participation/read-a-recipient-participation-timeline

get /admin/programs/{program_id}/participation/recipients/{entity_id}
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_view, participation_record, participation_submit or participation_configure. Results follow the caller’s site/cohort scope. Requires visible placement or submitted/superseded/voided evidence within the caller’s scope for restricted roles. Includes archived recipients, scoped placement history and finalized evidence; draft observations are omitted. Scoped current state is reconstructed from permitted evidence and conceals program-wide follow-ups; unrestricted callers receive the rollup and any viewable open follow-up.



# Read program participation overview
Source: https://api-docs.helpyousponsor.com/api-reference/participation/read-program-participation-overview

get /admin/programs/{program_id}/participation
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_view, participation_record, participation_submit or participation_configure. Results follow the caller’s site/cohort scope. Returns setup, active scoped locations and groups, period schedule, roster/check totals and caller capabilities. Defaults to the open period, otherwise the newest period. Setup details are returned only to configurators; intake options require record capability.



# Reconcile legacy recipient placements
Source: https://api-docs.helpyousponsor.com/api-reference/participation/reconcile-legacy-recipient-placements

post /admin/programs/{program_id}/participation/placement-bootstrap
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_configure. Applies the same matching plan as the preview. Creates pending current placements beginning on the open period start date, skips recipients already placed and skips ambiguous/missing/unmapped values. The response reports committed placement counts; search-reference synchronization is queued separately. Requires settings, source fields and an open period.



# Resolve an imported attendance recipient
Source: https://api-docs.helpyousponsor.com/api-reference/participation/resolve-an-imported-attendance-recipient

patch /admin/programs/{program_id}/participation/imports/{participation_import_id}/rows/{participation_import_row_id}
Requires participation_configure, programs_view and access to this organization’s program, with participation enabled. Only batches in review can be changed. Match selects one of the reviewed candidate IDs and must respect current placement; provisional marks a new recipient for creation at commit, unresolved preserves unresolved evidence, and skip excludes it. Applies the decision to all ready/review/unresolved observations sharing the same source-record fingerprint, then refreshes batch counts. Blocked rows require mapping correction and revalidation. Requires permission: one of participation_configure.



# Start or reuse a participation check
Source: https://api-docs.helpyousponsor.com/api-reference/participation/start-or-reuse-a-participation-check

post /admin/programs/{program_id}/participation/sessions
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure and access to the check’s site/cohort. Requires enabled setup, an open period, an active site/group and a date within that period. Snapshots placements active on the inclusive check date. The idempotency key is organization-wide and must replay matching program, period, location/group, date, type and evidence source. Returns 201 for a new draft or 200 for replay/reuse. Fixed cadence reuses a draft/submitted check in that window; flexible cadence reuses only a draft on the exact date.



# Submit a participation check
Source: https://api-docs.helpyousponsor.com/api-reference/participation/submit-a-participation-check

post /admin/programs/{program_id}/participation/sessions/{session_id}/submit
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_submit or participation_configure and access to the check’s site/cohort. Finalizes a nonempty draft in an open period. Expected rows require an enrollment confirmation; a nonblank partial_reason permits an unchecked expected row to remain unconfirmed. Any expected not_checked row requires partial_reason. Transfer rows also need an active destination site and, if that site has active groups, a destination group; destinations must be in caller scope. Stale versions return 409. Replaying the same submission key for an already submitted check returns200 without another submission; keys cannot be used by another check. Submission applies authoritative evidence and rollups; inclusive ending dates keep current placements active through that organization-local date. Automatic follow-up task creation and search synchronization may continue in queued jobs. Submitting a correction supersedes its previous submitted revision.



# Update draft roster observations together
Source: https://api-docs.helpyousponsor.com/api-reference/participation/update-draft-roster-observations-together

patch /admin/programs/{program_id}/participation/sessions/{session_id}/observations
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure and access to the check’s site/cohort. Only draft checks may be edited. Omitted fields retain existing values. A non-null enrollment confirmation defaults omitted evidence_source to the check primary source; the source must be enabled. confirmed_enrolled requires evidence. transferred/withdrawn/graduated require evidence and effective_on. A transfer destination must be active, belong to this program, differ from the current placement and be within caller scope; its effective date cannot precede placement start. Destination fields are cleared when enrollment_confirmation is explicitly changed away from transferred. A stale lock_version returns 409; success increments it and returns the full check. All rows must belong to this check; the batch is applied atomically.



# Update one draft roster observation
Source: https://api-docs.helpyousponsor.com/api-reference/participation/update-one-draft-roster-observation

patch /admin/programs/{program_id}/participation/sessions/{session_id}/observations/{observation_id}
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_record, participation_submit or participation_configure and access to the check’s site/cohort. Only draft checks may be edited. Omitted fields retain existing values. A non-null enrollment confirmation defaults omitted evidence_source to the check primary source; the source must be enabled. confirmed_enrolled requires evidence. transferred/withdrawn/graduated require evidence and effective_on. A transfer destination must be active, belong to this program, differ from the current placement and be within caller scope; its effective date cannot precede placement start. Destination fields are cleared when enrollment_confirmation is explicitly changed away from transferred. A stale lock_version returns 409; success increments it and returns the full check. 



# Upload an attendance workbook
Source: https://api-docs.helpyousponsor.com/api-reference/participation/upload-an-attendance-workbook

post /admin/programs/{program_id}/participation/imports
Requires participation_configure, programs_view and access to this organization’s program, with participation enabled. Accepts a private CSV/XLSX file up to20MiB and an existing program participation period. Inspects up to12 sample rows per sheet for mapping. Workbook bounds are100 sheets,100000 source rows,512 columns and2000000 expanded cells. A matching organization-wide upload idempotency key returns the original batch with HTTP200; reuse for another program/period returns422. Upload does not create participation checks. Requires permission: one of participation_configure.



# Void a completed attendance import
Source: https://api-docs.helpyousponsor.com/api-reference/participation/void-a-completed-attendance-import

post /admin/programs/{program_id}/participation/imports/{participation_import_id}/void
Requires participation_configure, programs_view and access to this organization’s program, with participation enabled. Atomically voids the batch’s draft/submitted checks in reverse date/ID order, marks committed source rows voided and records the reason. Only a completed batch may be voided; retrying an already voided batch is allowed. Later submitted evidence can block reversal. Historical records remain available for audit. Requires permission: one of participation_configure.



# Void a draft or submitted participation check
Source: https://api-docs.helpyousponsor.com/api-reference/participation/void-a-draft-or-submitted-participation-check

post /admin/programs/{program_id}/participation/sessions/{session_id}/void
Requires the participation feature, programs_view and access to this organization-owned program. Requires participation_submit or participation_configure and access to the check’s site/cohort. Requires the current lock_version and a reason. Refuses superseded/voided checks and submitted checks for which later submitted evidence exists for an affected recipient. Voids the check and reverses its placement effects, restoring applicable prior evidence; draft-created placements are removed. Returns the complete voided check. Stale versions return 409.



# Check Stripe webhook configuration
Source: https://api-docs.helpyousponsor.com/api-reference/payment-gateways/check-stripe-webhook-configuration

post /integrations/stripe/webhook-status
Checks up to100 Stripe webhook endpoints using the provided or saved private key and compares the expected URL after trimming trailing slashes. Reports endpoint readiness and missing required events; wildcard subscriptions satisfy every required event. This does not create or update an endpoint. Requires permission: one of access_account_settings.



# Complete new Stripe account setup
Source: https://api-docs.helpyousponsor.com/api-reference/payment-gateways/complete-new-stripe-account-setup

get /connect/{token}
Rechecks the server-stored, organization-bound setup token and Standard Stripe account. Incomplete details return incomplete; submitted accounts lacking charge capability persist pending/action_required. Ready accounts become the active connection after account-ownership and direct-gateway checks. This performs setup and creates no charge. Requires permission: one of access_payment_gateways.



# Enable supported Stripe webhook events
Source: https://api-docs.helpyousponsor.com/api-reference/payment-gateways/enable-supported-stripe-webhook-events

post /integrations/stripe/webhook-events
Finds the matching existing Stripe endpoint, adds missing supported events without removing existing subscriptions and enables it if disabled. A missing endpoint is reported as HTTP200 missing and is not created. Returns added and remaining missing events after the update. Requires permission: one of access_account_settings.



# Update direct payment gateway credentials
Source: https://api-docs.helpyousponsor.com/api-reference/payment-gateways/update-direct-payment-gateway-credentials

post /payment-gateways/{name}
Updates only stripe, authorize_net, paypal or qpaypro for the current organization. Fields depend on name. Existing gateway IDs are organization/provider scoped. Empty credentials can remove an existing gateway; direct Stripe writes conflict with a managed Stripe connection or active link attempt. PayPal credentials are verified when both keys are nonblank. Authorize.Net can return an empty HTTP200 body after a successful save. This configures gateways and does not charge a donation. Requires permission: one of access_payment_gateways.



# Authorize an existing Stripe account without direct keys
Source: https://api-docs.helpyousponsor.com/api-reference/payments/authorize-an-existing-stripe-account-without-direct-keys

post /stripe-connect/existing-account-onboarding
Starts an expiring OAuth authorization attempt (default15minutes) for the current organization. A new attempt supersedes pending attempts, while a currently processing attempt returns409. It returns an authorization URL; payment setup changes only when the provider callback completes. Requires configured OAuth and no supported direct-key gateway or active Connect gateway. A deauthorized/disconnected/rolled-back connection may reconnect only to its expected account. Requires permission: one of access_payment_gateways.



# Check the unavailable legacy account session
Source: https://api-docs.helpyousponsor.com/api-reference/payments/check-the-unavailable-legacy-account-session

get /account_session
Legacy placeholder endpoint. The current implementation always returns HTTP500 with error=Not available and does not issue an account session token. Requires permission: one of access_payment_gateways.



# Continue a Flutterwave v4 campaign charge
Source: https://api-docs.helpyousponsor.com/api-reference/payments/continue-a-flutterwave-v4-campaign-charge

put /frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{charge_id}/{session_id}
Submits PIN or OTP authorization for a previously initialized campaign charge. The controller validates the Redis charge state against client, program, charge id, and optional session id before sending the normalized authorization payload to Flutterwave. It stores the updated charge state and returns the same charge response shape as initialization.



# Continue a Flutterwave v4 order charge
Source: https://api-docs.helpyousponsor.com/api-reference/payments/continue-a-flutterwave-v4-order-charge

put /frontend/flutterwave-v4/order-charge/{client_id}/{program_id}/{charge_id}/{session_id}
Alias of the campaign charge continuation logic for Redis order checkout. It validates the same route state and authorization payload, then returns the common Flutterwave v4 charge response.



# Create a legacy Flutterwave payment plan checkout
Source: https://api-docs.helpyousponsor.com/api-reference/payments/create-a-legacy-flutterwave-payment-plan-checkout

post /frontend/flutterwave_payment_plan/{client_id}/{program_id}/{session_id}
Creates a legacy Flutterwave Standard payment plan and checkout URL from the Redis saved entity cart. The controller requires a session id, reads `saved_entity_id` and `saved_entity_frequency`, creates payment plans with retry logic, creates a Flutterwave checkout using the first plan id, and returns the provider response with a generated transaction reference. This route is retained for older order/signup flows; newer card flows use the Flutterwave v4 charge endpoints.



# Create the legacy fixed Flutterwave setup charge
Source: https://api-docs.helpyousponsor.com/api-reference/payments/create-the-legacy-fixed-flutterwave-setup-charge

post /flutterwave/payment
Legacy authenticated card-setup transport. The server always submits an actual USD10 card charge with a generated tx_ref and the current organization’s subaccount, ignoring caller amount/currency. Optional authorization is forwarded to the provider. Returns provider success JSON or local400 with the provider message. Requires an existing organization subaccount. Requires permission: one of access_payment_gateways.



# Create the organization Flutterwave subaccount
Source: https://api-docs.helpyousponsor.com/api-reference/payments/create-the-organization-flutterwave-subaccount

post /flutterwave/subaccount
Creates a provider subaccount and, on provider success, stores its subaccount/account IDs and a default Flutterwave gateway for the authenticated organization. The server supplies split_value=0.05 and split_type=percentage; callers cannot override these fields. Returns the updated organization model. A provider rejection or transport exception is a local500 failure. Requires permission: one of access_payment_gateways.



# Delete the organization Flutterwave subaccount
Source: https://api-docs.helpyousponsor.com/api-reference/payments/delete-the-organization-flutterwave-subaccount

delete /flutterwave/subaccount
Requests provider deletion using the current organization’s stored account ID. On provider success, clears the local subaccount/account IDs and records activity. Returns provider JSON under HTTP200; a provider failure leaves those local IDs intact. The handler does not remove existing gateway rows. Requires permission: one of access_payment_gateways.



# Disconnect a Stripe Connect integration
Source: https://api-docs.helpyousponsor.com/api-reference/payments/disconnect-a-stripe-connect-integration

delete /connect
For a managed connection, first attempts restoration of a retained direct gateway; if unavailable, disconnects the managed integration locally and attempts provider deauthorization. For legacy unmanaged Connect, removes the Connect gateway, clears account linkage and creates an empty direct Stripe gateway for later configuration. This removes integration configuration; it does not delete the provider account. Requires permission: one of access_payment_gateways.



# Get connected Stripe readiness
Source: https://api-docs.helpyousponsor.com/api-reference/payments/get-connected-stripe-readiness

get /stripe-connect/status
Reads live readiness for the organization’s configured Stripe Connect account. Returns a filtered summary of enabled charges/payouts and machine-readable requirements; provider descriptions and arbitrary account data are not returned. A local connection is required. Stripe/provider errors return502 without disclosing credentials. Requires permission: one of access_payment_gateways.



# Get payment gateway setup settings
Source: https://api-docs.helpyousponsor.com/api-reference/payments/get-payment-gateway-setup-settings

get /payment-gateways/settings
Returns only organization/gateway setup fields used by payment settings, plus existing-account authentication-refresh availability and new-account country options. A missing gateway is an empty array. Direct Stripe settings are redacted when a refresh is required. Country lookup uses configured countries or cached provider eligibility; an unavailable lookup returns an empty list. Other stored gateway settings can contain credentials and must be handled as sensitive. Requires permission: one of access_payment_gateways.



# Get the organization Flutterwave subaccount
Source: https://api-docs.helpyousponsor.com/api-reference/payments/get-the-organization-flutterwave-subaccount

get /flutterwave/subaccount
Retrieves the provider subaccount using the authenticated organization’s stored account ID. Returns the provider JSON with HTTP200 even when its status indicates a provider-level rejection; inspect status/message. Requires permission: one of access_payment_gateways.



# Get the platform Stripe publishable key
Source: https://api-docs.helpyousponsor.com/api-reference/payments/get-the-platform-stripe-publishable-key

get /account/form
Returns the configured platform publishable key for authenticated payment settings. This is a publishable browser key, not a secret key. The field can be null when no publishable key is configured. Requires permission: one of access_payment_gateways.



# Initialize a Flutterwave v4 campaign charge
Source: https://api-docs.helpyousponsor.com/api-reference/payments/initialize-a-flutterwave-v4-campaign-charge

post /frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{session_id}
Starts the direct-card Flutterwave v4 charge flow for a public campaign donation. The controller creates or refreshes a frontend session, validates card or saved-payment-method input, validates designation items against the client/program, enforces checkout settings such as single-designation mode, creates or reuses a Flutterwave customer/payment method, creates the charge, stores charge state in Redis, and returns the provider charge status plus any next action. Existing donors must verify their checkout session before using saved payment methods.



# Initialize a Flutterwave v4 order charge
Source: https://api-docs.helpyousponsor.com/api-reference/payments/initialize-a-flutterwave-v4-order-charge

post /frontend/flutterwave-v4/order-charge/{client_id}/{program_id}/{session_id}
Starts the direct-card Flutterwave v4 charge flow for the Redis checkout order page. The controller validates email and card or saved-payment-method input, totals saved entity and designation cart values from Redis, adds configured processing fees when requested, creates or reuses Flutterwave customer/payment method records, stores charge state, and returns the common charge response. The session cart must contain at least one saved entity or designation amount.



# List Flutterwave bank branches
Source: https://api-docs.helpyousponsor.com/api-reference/payments/list-flutterwave-bank-branches

get /flutterwave/banks/{id}/branches
Returns the provider’s branch-directory JSON. If the provider HTTP request is unsuccessful, the compatibility response is still HTTP200 with error=Unable to fetch branches and an empty data array.



# List Flutterwave banks for a country
Source: https://api-docs.helpyousponsor.com/api-reference/payments/list-flutterwave-banks-for-a-country

get /flutterwave/banks/{country}
Returns the provider’s bank-directory JSON for the supplied country. A non-success provider HTTP response becomes a local500 error rather than retaining the provider status.



# List Flutterwave setup countries
Source: https://api-docs.helpyousponsor.com/api-reference/payments/list-flutterwave-setup-countries

get /flutterwave/countries
Returns the application’s configured static country-code/name options used for Flutterwave subaccount setup. This list does not independently verify current provider onboarding eligibility.



# Refresh authentication for an existing direct Stripe account
Source: https://api-docs.helpyousponsor.com/api-reference/payments/refresh-authentication-for-an-existing-direct-stripe-account

post /stripe-connect/existing-account-link
Starts an expiring OAuth authorization attempt (default15minutes) for the current organization. A new attempt supersedes pending attempts, while a currently processing attempt returns409. It returns an authorization URL; payment setup changes only when the provider callback completes. Requires rollout availability and one configured direct Standard Stripe secret key. Verifies that account before returning an authorization URL; the connected provider account must match it. Requires permission: one of access_payment_gateways.



# Refresh pending Stripe account readiness
Source: https://api-docs.helpyousponsor.com/api-reference/payments/refresh-pending-stripe-account-readiness

post /stripe-connect/pending-onboarding/refresh
Retrieves a pending/action-required Standard account from Stripe. If charges remain disabled, persists and returns pending/action_required. If charges are enabled, activates the local Connect gateway and returns connected; payouts_enabled is reported independently and may still be false. Conflicting supported direct gateways or cross-organization ownership prevent activation. Requires permission: one of access_payment_gateways.



# Retired legacy signup payment setup
Source: https://api-docs.helpyousponsor.com/api-reference/payments/retired-legacy-signup-payment-setup

get /stripe_connect_details
This unbound public SetupIntent endpoint has been retired. Current workspace onboarding creates a session-bound SetupIntent through `/workspace-onboarding/{public_id}/payment-intent`.



# Retrieve a Flutterwave v4 campaign charge
Source: https://api-docs.helpyousponsor.com/api-reference/payments/retrieve-a-flutterwave-v4-campaign-charge

get /frontend/flutterwave-v4/campaign-charge/{client_id}/{program_id}/{charge_id}/{session_id}
Retrieves the latest provider status for a campaign charge and refreshes the Redis charge state. The controller first validates the charge state against client, program, charge id, and optional session id, then returns the common Flutterwave v4 charge response payload. Public checkout polls this endpoint after redirect, OTP, or 3DS flows.



# Retrieve a Flutterwave v4 campaign charge by checkout reference
Source: https://api-docs.helpyousponsor.com/api-reference/payments/retrieve-a-flutterwave-v4-campaign-charge-by-checkout-reference

get /frontend/flutterwave-v4/campaign-charge-reference/{client_id}/{program_id}/{reference}/{session_id}
Resolves a stored campaign charge from its checkout reference, validates the client, program, session and checkout flow, then delegates to charge retrieval to refresh the provider status. Use after returning from provider authorization when the checkout reference is available.



# Retrieve a Flutterwave v4 order charge
Source: https://api-docs.helpyousponsor.com/api-reference/payments/retrieve-a-flutterwave-v4-order-charge

get /frontend/flutterwave-v4/order-charge/{client_id}/{program_id}/{charge_id}/{session_id}
Alias of the campaign charge retrieval logic for Redis order checkout. It validates client, program, charge id, and optional session id against stored Redis state, retrieves the provider status, updates Redis, and returns the common Flutterwave v4 charge payload.



# Retrieve a Flutterwave v4 order charge by checkout reference
Source: https://api-docs.helpyousponsor.com/api-reference/payments/retrieve-a-flutterwave-v4-order-charge-by-checkout-reference

get /frontend/flutterwave-v4/order-charge-reference/{client_id}/{program_id}/{reference}/{session_id}
Resolves a stored order charge from its checkout reference, validates the client, program, session and checkout flow, then delegates to charge retrieval to refresh the provider status. Use after returning from provider authorization when the checkout reference is available.



# Start new Stripe account onboarding
Source: https://api-docs.helpyousponsor.com/api-reference/payments/start-new-stripe-account-onboarding

post /stripe-connect/onboarding-link
Creates or resumes a Standard Stripe account onboarding flow for the authenticated organization and returns a provider URL. A completed setup returns its dashboard URL with status=connected. Existing direct-key or incompatible connection state returns409. Creation retries reuse a provider idempotency identity; a stale ambiguous creation attempt requires reconciliation. The returned URL does not itself prove that charges or payouts are enabled. Requires permission: one of access_payment_gateways.



# Start Stripe onboarding through the legacy route
Source: https://api-docs.helpyousponsor.com/api-reference/payments/start-stripe-onboarding-through-the-legacy-route

get /stripe/{id}
Creates or resumes a Standard Stripe account onboarding flow for the authenticated organization and returns a provider URL. A completed setup returns its dashboard URL with status=connected. Existing direct-key or incompatible connection state returns409. Creation retries reuse a provider idempotency identity; a stale ambiguous creation attempt requires reconciliation. The returned URL does not itself prove that charges or payouts are enabled. The route id must match the authenticated organization; a mismatch returns404. Requires permission: one of access_payment_gateways.



# Submit Flutterwave charge authorization
Source: https://api-docs.helpyousponsor.com/api-reference/payments/submit-flutterwave-charge-authorization

post /flutterwave/validate
Public compatibility transport forwarding a numeric OTP and provider flw_ref to charge validation. These values authorize the provider’s existing charge attempt. Returns provider JSON under HTTP200 even for a provider-level rejection; inspect status/message. This handler does not create an organization donation record.



# Temporarily restore retained direct Stripe authentication
Source: https://api-docs.helpyousponsor.com/api-reference/payments/temporarily-restore-retained-direct-stripe-authentication

post /stripe-connect/existing-account-link/rollback
Within the configured rollback window (default14days), restores the retained direct gateway for an active/deauthorized managed connection, marks it rolled_back and attempts provider deauthorization. A missing/expired retained gateway returns409. The authentication refresh remains required; this does not delete the provider Stripe account. Requires permission: one of access_payment_gateways.



# Update the organization Flutterwave subaccount
Source: https://api-docs.helpyousponsor.com/api-reference/payments/update-the-organization-flutterwave-subaccount

put /flutterwave/subaccount
Updates the provider subaccount selected from the authenticated organization’s stored account ID. The server supplies split_value=0.05 and split_type=percentage. Records activity on provider success and returns provider JSON under HTTP200; local organization identity is not caller-controlled. Requires permission: one of access_payment_gateways.



# Verify a legacy Flutterwave transaction
Source: https://api-docs.helpyousponsor.com/api-reference/payments/verify-a-legacy-flutterwave-transaction

post /frontend/flutterwave/verify/{client_id}/{program_id}/{session_id}
Passes the request payload to `FlutterwaveService::verifyTransactionByReference()` for the legacy Flutterwave Standard checkout flow. The controller rejects unavailable recipients, then the service requires tx_ref and returns its provider response directly. This route is retained for older order/signup flows.



# Add a donor form to a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/add-a-donor-form-to-a-program

post /admin/program/form/donor



# Add a sponsorship form to a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/add-a-sponsorship-form-to-a-program

post /admin/program/form/sponsorship



# Attach an email set to a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/attach-an-email-set-to-a-program

post /admin/program/emailset



# Attach an SMS template set to a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/attach-an-sms-template-set-to-a-program

post /admin/program/smsset
Sets `programs.smsset_id` on the target program and repairs the default starter templates for the new attachment via `DefaultSmsSetBootstrapService`. Wrapped in a transaction so the program update and starter-template repair commit atomically. Logs an `attach_program_smsset` activity. The SMS set must belong to the caller's client (404 otherwise). Validation: `id required`, `smsset_id required`. Requires permission: `manage_programs`.



# Attach settings to a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/attach-settings-to-a-program

post /admin/program/settings



# Bootstrap data for the program edit form
Source: https://api-docs.helpyousponsor.com/api-reference/programs/bootstrap-data-for-the-program-edit-form

get /admin/edit_program/{program_id}
Returns the target program along with the list of unlinked programs in the caller's client (used to populate the parent picker on the edit form). Requires permission: `manage_programs`.



# Bootstrap data for the sub-program creation form
Source: https://api-docs.helpyousponsor.com/api-reference/programs/bootstrap-data-for-the-sub-program-creation-form

get /admin/add_sub_program
Returns the list of unlinked (root-level) programs for the caller's client, used to populate the parent picker on the 'Add sub-program' admin form. The `parent_id` field echoes the calling client_id (legacy frontend ergonomics). Requires permission: `manage_programs`.



# Build the multi-program donor-frontend URL
Source: https://api-docs.helpyousponsor.com/api-reference/programs/build-the-multi-program-donor-frontend-url

post /admin/multi_program_select
Companion to `multiProgramSelect` — given a base `program_settings` id and a list of additional `program_list` ids, returns the canonical donor-frontend URL that combines them (`/frontend/view_all/{client_id}/{ids-joined-by-hyphen}`). Strips any program that already matches the base settings to avoid duplicates. Validation: `program_settings required`. Requires permission: `manage_programs`.



# Create a child program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/create-a-child-program

post /admin/program



# Create a sub program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/create-a-sub-program

post /admin/program/sub_program



# Discard an empty program setup draft
Source: https://api-docs.helpyousponsor.com/api-reference/programs/discard-an-empty-program-setup-draft

delete /admin/program/{program_id}/setup-draft
Soft-deletes only an empty setup draft: no attached setting/forms/email/SMS modules, descendant/linked programs, or recipient records including archived ones. Program roots cannot be discarded. Removes the discarded program’s access-role references and records activity; established programs require the normal management/removal flow. Requires permission: one of manage_programs.



# Edit a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/edit-a-program

put /admin/program/{program_id}
Updates a program's name, prefix, counter, and optional parent within the authenticated organization. Omitting or emptying the prefix clears it; omitting or emptying the counter resets it to zero. Selecting a parent inherits its recipient form and may clear incompatible settings. Requires permission: `manage_programs`.



# Get campaign program details
Source: https://api-docs.helpyousponsor.com/api-reference/programs/get-campaign-program-details

get /program/{id}/campaign
Deprecated numeric-only compatibility endpoint. Supply client_id during the rollout; requests without tenant context are rejected after 2026-09-21 UTC. See https://github.com/rg-repos/gratona/issues/2520.



# Get details of a specific program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/get-details-of-a-specific-program

get /program/{id}



# Get organization-scoped campaign checkout metadata
Source: https://api-docs.helpyousponsor.com/api-reference/programs/get-organization-scoped-campaign-checkout-metadata

get /frontend/program/{client_id}/{program_id}/campaign
Public campaign/program form metadata scoped by both organization and program. entity_mode=search returns only recipient options and paging metadata; initial returns bounded options with full form/configuration metadata, optionally adding a selected recipient beyond the limit; none omits recipients; options returns all projected options; full (and unknown modes) returns all raw recipient records. The search limit is clamped1–50, default24. trip_id can select a matching trip donor form. Standard donor field and public donation field contracts are returned only when their features/policies permit. Program progress is cached for30seconds. This metadata request does not create a donor or payment.



# Get program settings
Source: https://api-docs.helpyousponsor.com/api-reference/programs/get-program-settings

get /program/{id}/settings



# Get program setup readiness
Source: https://api-docs.helpyousponsor.com/api-reference/programs/get-program-setup-readiness

get /admin/program/{program_id}/setup-state
Returns attached module identifiers and setup steps for the current organization’s program. Required steps include program, settings, donor form and recipient/designation/participant form; enabled email requires usable templates and an attached setting requires a usable payment method. SMS is optional. This read reports readiness without activating or modifying the program. Requires permission: one of programs_view, manage_programs, program-all.



# Get program website launch context
Source: https://api-docs.helpyousponsor.com/api-reference/programs/get-program-website-launch-context

get /admin/program/{program_id}/launch-context
Returns setup/public-page readiness, current website settings, shared-setting information, additional gift routes, public URLs and Elements embed configuration. No setting access returns403; a missing program returns404. A trip program without a real attached trip has no public page or embed configuration. can_manage reports whether launch settings may be changed. Requires permission: one of programs_view, manage_programs, program-all.



# List compatible program setup modules
Source: https://api-docs.helpyousponsor.com/api-reference/programs/list-compatible-program-setup-modules

get /admin/program/setup-options
Returns current-organization settings, donor/recipient forms and email/SMS sets with compatibility, recommendation and preview details. Blocked settings are omitted. Unsupported/blank type becomes null and receives generic recommendations; it does not return422. Form summaries include standardized donor fields when enabled. Recommended IDs are suggestions and do not attach modules. Requires permission: one of programs_view, manage_programs, program-all.



# Manage programs
Source: https://api-docs.helpyousponsor.com/api-reference/programs/manage-programs

get /programs



# Persist a reordered/reparented programs tree
Source: https://api-docs.helpyousponsor.com/api-reference/programs/persist-a-reorderedreparented-programs-tree

post /admin/updatetree
Accepts the full programs tree (typically the output of the admin drag-and-drop reorder UI) and applies it via `Program::mapTree`, then flushes the `programs_menu` cache for the client. Validation: `data required`. Requires permission: `manage_programs`.



# Programs sharing a donor form that allow combined checkout
Source: https://api-docs.helpyousponsor.com/api-reference/programs/programs-sharing-a-donor-form-that-allow-combined-checkout

get /admin/multi_program_select
Returns checkout-capable root programs grouped by donor form. Programs may use different recipient forms, but a generated checkout must use one donor form. Requires permission: `manage_programs`.



# Remove a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/remove-a-program

delete /admin/program/{program_id}



# Rename a program
Source: https://api-docs.helpyousponsor.com/api-reference/programs/rename-a-program

patch /admin/program/{program_id}/name
Updates only the display name of one tenant-scoped program, leaving its hierarchy, settings, forms, and communication templates unchanged. Intended for administrators using the Website & Embed workspace. Requires permission: manage_programs.



# Search program gift-routing recipients
Source: https://api-docs.helpyousponsor.com/api-reference/programs/search-program-gift-routing-recipients

get /admin/program/{program_id}/additional-gift-targets
Returns up to25 recipient/designation target options in this program. Blank search lists by ID. Nonblank search uses title/name lookup through search with a database fallback. The program and its setting must be accessible. These are routing options, not a routing update. Requires permission: one of programs_view, manage_programs, program-all.



# Update a program name and abbreviation
Source: https://api-docs.helpyousponsor.com/api-reference/programs/update-a-program-name-and-abbreviation

patch /admin/program/{program_id}/identity
Updates only the name and abbreviation of one tenant-scoped program. Program hierarchy, settings, forms, communication templates, and readiness-related attachments remain unchanged. Requires permission: manage_programs.



# Update program additional-gift routes
Source: https://api-docs.helpyousponsor.com/api-reference/programs/update-program-additional-gift-routes

patch /admin/program/{program_id}/additional-gift-routes
Requires manage_settings and access to the program setting. Each gift must be available to the program’s donor form and each nonnull target must belong to this program. Null/blank target removes the override. An empty routes array is a no-op. Returns refreshed routing options and records changed-gift activity. Requires permission: one of manage_programs.



# Update program website settings
Source: https://api-docs.helpyousponsor.com/api-reference/programs/update-program-website-settings

patch /admin/program/{program_id}/launch-settings
Requires manage_settings and access to the attached setting. Only supported nested settings keys are accepted. With multiple linked programs, mode defaults to program_copy; mode=direct requires confirm_shared_update=true, otherwise409 returns the linked-program list. No-op writes return200 with save_mode=direct. The response includes fresh launch context. Changing enabled blur configuration queues image regeneration; recipient portal synchronization follows saving. Requires permission: one of manage_programs.



# Add a designation-only gift to checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/add-a-designation-only-gift-to-checkout

post /frontend/checkout_add_designation_only/{client_id}/{hysform_id}/{designation_id}/{currency}/{session_id}
Adds a designation gift amount to the Redis-backed designation-only checkout cart. The controller validates the amount, expects the selected designation id in the request body, sets a default one-time frequency code of `5`, and stores a checkout message for the frontend. This is a public checkout endpoint and relies on the route session id rather than bearer authentication.



# Add a recipient to the public checkout cart
Source: https://api-docs.helpyousponsor.com/api-reference/public/add-a-recipient-to-the-public-checkout-cart

post /frontend/entity/save/{client_id}/{program_id}/{entity_id}
Validates organization-owned public recipient availability and sponsorship amount policy within the requested program scope. Creates a frontend session if absent/expired. Saves amount, frequency and custom-mode selections for three hours and returns the session ID. Input currency punctuation is removed before numeric validation; policy can still reject unavailable fixed levels or frequencies.



# Add a recipient to the public checkout cart
Source: https://api-docs.helpyousponsor.com/api-reference/public/add-a-recipient-to-the-public-checkout-cart-1

post /frontend/entity/save/{client_id}/{program_id}/{entity_id}/{session_id}
Validates organization-owned public recipient availability and sponsorship amount policy within the requested program scope. Creates a frontend session if absent/expired. Saves amount, frequency and custom-mode selections for three hours and returns the session ID. Input currency punctuation is removed before numeric validation; policy can still reject unavailable fixed levels or frequencies.



# Add the configured optional sponsorship to a checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/add-the-configured-optional-sponsorship-to-a-checkout

post /frontend/checkout/offer/{client_id}/{program_id}/{session_id}
Requires the optional offer to resolve to an eligible public recipient sharing the anchor program donor form, plus a live checkout session. Validates amount and a frequency key from the resolved offer. Saves the recipient through normal amount policy checks and marks it in the original cart for later checkout scope. Unavailable offers and expired sessions return 422; no payment is charged here.



# Cancel an iDEAL | Wero checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/cancel-an-ideal---wero-checkout

post /frontend/checkout/ideal/{client_id}/{program_id}/{token}/cancel
Public browser return action, throttled to 30 requests per minute. The random checkout token must belong to the route client and program. Attempts cancellation only while pending. A payment already approved or still uncertain returns processing; it does not claim a cancellation succeeded. A completed checkout returns its existing outcome. checkout_secret controls full result disclosure.



# Change a saved recipient payment frequency
Source: https://api-docs.helpyousponsor.com/api-reference/public/change-a-saved-recipient-payment-frequency

put /frontend/checkout/frequency/{client_id}/{program_id}/{entity_id}/{frequency}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Frequency must be enabled by the recipient program. Fixed-level sponsorship selections revalidate the saved amount for the new frequency. Returns the schedule-change message.



# Change a saved recipient payment frequency
Source: https://api-docs.helpyousponsor.com/api-reference/public/change-a-saved-recipient-payment-frequency-1

put /frontend/checkout/frequency/{client_id}/{program_id}/{entity_id}/{frequency}/{session_id}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Frequency must be enabled by the recipient program. Fixed-level sponsorship selections revalidate the saved amount for the new frequency. Returns the schedule-change message.



# Change a saved recipient sponsorship amount
Source: https://api-docs.helpyousponsor.com/api-reference/public/change-a-saved-recipient-sponsorship-amount

put /frontend/checkout/amount/{client_id}/{program_id}/{entity_id}/{amount}/{currency}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Uses the current cart frequency and custom-amount mode when validating the new amount. The currency path value only formats the message. Returns the order redirect URL.



# Change a saved recipient sponsorship amount
Source: https://api-docs.helpyousponsor.com/api-reference/public/change-a-saved-recipient-sponsorship-amount-1

put /frontend/checkout/amount/{client_id}/{program_id}/{entity_id}/{amount}/{currency}/{session_id}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Uses the current cart frequency and custom-amount mode when validating the new amount. The currency path value only formats the message. Returns the order redirect URL.



# Complete checkout for an already logged-in donor
Source: https://api-docs.helpyousponsor.com/api-reference/public/complete-checkout-for-an-already-logged-in-donor

post /frontend/logged_in_checkout/{client_id}/{program_id}/{entity_id}/{session_id}
Completes a public checkout for a donor already marked logged in in the Redis session. The controller validates amount, payment method, and frequency, clears previous cart state, writes the selected entity and frequency into Redis, requires a saved card when method `3` is used, creates the sponsorship/commitment and donation order, then clears the checkout cart. The Redis session must resolve to a donor belonging to this client; otherwise the endpoint returns 401.



# Complete designation-only checkout for an existing donor
Source: https://api-docs.helpyousponsor.com/api-reference/public/complete-designation-only-checkout-for-an-existing-donor

post /frontend/checkout_login_only/{client_id}/{hysform_id}/{designation_id}/{session_id}
Completes a designation-only checkout using an existing Redis donor session or login credentials. The controller validates login fields, checks for a saved Stripe customer when card checkout is requested, converts the saved designation cart into donations or recurring commitments, clears the cart, and returns a legacy success envelope. This route is public but requires the checkout session id to carry the cart and, in current code, often the selected donor id.



# Confirm an iDEAL | Wero checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/confirm-an-ideal---wero-checkout

post /frontend/checkout/ideal/{client_id}/{program_id}/{token}/complete
Public browser return action, throttled to 30 requests per minute. The random checkout token must belong to the route client and program. Verifies bank/provider evidence and attempts to record the approved gift once. Repeat the same token to poll a processing outcome; a successful HTTP response can still mean processing, requires_action, review or refund progress. Completed results are disclosed according to checkout_secret.



# Create a campaign cart before an optional sponsorship offer
Source: https://api-docs.helpyousponsor.com/api-reference/public/create-a-campaign-cart-before-an-optional-sponsorship-offer

post /frontend/checkout/campaign-offer/{client_id}/{program_id}
Requires a campaign with checkout_offer_enabled. Validates 1–100 distinct visible recipient IDs belonging to that campaign, creates a new cart and saves each selection through normal amount policy checks. If multiple designations are disabled, exactly one selection is allowed. Returns the new session ID; does not charge a payment or add the sponsorship offer itself.



# Create a donor and complete designation-only checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/create-a-donor-and-complete-designation-only-checkout

post /frontend/checkout_signup_only/{client_id}/{hysform_id}/{designation_id}/{session_id}
Creates a donor account from the designation-only checkout form and attempts to convert the Redis cart into donations or recurring commitments. The request body uses fixed login fields plus dynamic public donor fields from the supplied HysForm; conditional display rules can add required custom field validators at runtime. On success the controller creates a donor session, clears the Redis cart, and returns a legacy success envelope.



# Create a public recipient/entity
Source: https://api-docs.helpyousponsor.com/api-reference/public/create-a-public-recipiententity

post /frontend/add_entity/{client_id}/{program_id}/{session_id}
Creates an entity from a public add-recipient form. The controller delegates to `EntityService::createEntity`, which scopes the program by client, validates `sp_num` according to program type, validates optional email format, enforces any unique public field configured on the HysForm, stores remaining request fields in entity `json_fields`, increments the program counter, logs frontend activity, and reloads the entity cache. The route is throttled by `frontend-add-entity` middleware.



# Display titles and files with pagination
Source: https://api-docs.helpyousponsor.com/api-reference/public/display-titles-and-files-with-pagination

get /frontend/view_all/{client_id}/{program_id}/{session_id}



# List entity names for a program
Source: https://api-docs.helpyousponsor.com/api-reference/public/list-entity-names-for-a-program

get /frontend/entities/view/{client_id}/{program_id}/{session_id}
Returns a compact id/name list for entities in a single program. The public frontend uses this lightweight route when it needs recipient choices without the full sponsorship listing payload. The controller scopes by client id and program id, then resolves each entity display name through `Donor::getEntityName()`.



# List paginated public frontend entities
Source: https://api-docs.helpyousponsor.com/api-reference/public/list-paginated-public-frontend-entities

get /frontend/entities/pagination/{client_id}/{program_id}/{session_id}
Alias of `/frontend/entities/all/{client_id}/{program_id}/{session_id?}` used by newer public frontend pages. It executes the same controller logic, query parameters, Redis session behavior, and response shape.



# List public frontend entities
Source: https://api-docs.helpyousponsor.com/api-reference/public/list-public-frontend-entities

get /frontend/entities/all/{client_id}/{program_id}/{session_id}
Returns visible public entities for a program or program tree, with optional search, filter, sort, and pagination controls. The controller creates or refreshes a Redis frontend session, marks the session as paginated, applies program setup and settings checks, and returns processed recipient cards plus public display settings. This endpoint is public and uses the optional session id for cart/login state rather than bearer authentication.



# List public recipients through the legacy page alias
Source: https://api-docs.helpyousponsor.com/api-reference/public/list-public-recipients-through-the-legacy-page-alias

get /frontend/view_pages/{client_id}/{program_id}/{session_id}
Unversioned alias of /frontend/view_all with the same query controls, session behavior, and response.



# List public trip participants
Source: https://api-docs.helpyousponsor.com/api-reference/public/list-public-trip-participants

get /frontend/public/trips/{clientSlugOrId}/{tripSlug}/participants
Returns active participants for a visible public trip. The controller respects trip settings for participant visibility opt-out, participant goals, and donation amount display, and caches the public list using a signature of those settings. Public trip pages use this endpoint to render participant cards and choose the participant entity id for checkout.



# Look up checkout donors by email
Source: https://api-docs.helpyousponsor.com/api-reference/public/look-up-checkout-donors-by-email

post /frontend/checkout/email_lookup/{client_id}/{program_id}
Checks whether a donor email already exists for the client before public checkout continues. The controller validates email, verifies the program belongs to the client, then returns lightweight donor choices for account selection or passwordless verification. The legacy alias `/frontend/checkout_email_lookup/{client_id}/{program_id}` is routed to the same method.



# Look up checkout donors by email (legacy path)
Source: https://api-docs.helpyousponsor.com/api-reference/public/look-up-checkout-donors-by-email-legacy-path

post /frontend/checkout_email_lookup/{client_id}/{program_id}
Legacy alias of `/frontend/checkout/email_lookup/{client_id}/{program_id}`. It executes the same validation, client/program scoping, and donor lookup response.



# Process a campaign checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/process-a-campaign-checkout

post /frontend/checkout/campaign/{client_id}/{program_id}/{session_id}
Completes public campaign, peer-to-peer or trip checkout and creates or reuses the donor record. Existing donor emails require a verified donor session before payment; checkout accepts a single recipient or a designation cart plus optional extra gifts. Payment admission, fixed-level sponsorship selections and public donor-form rules are checked before creating donations or commitments. A future start date can defer charging, and bank accounts awaiting verification produce a pending success state rather than a completed payment.



# Remove a designation-only gift from checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/remove-a-designation-only-gift-from-checkout

post /frontend/checkout_remove_designation_only/{client_id}/{hysform_id}/{designation_id}/{id}/{currency}/{session_id}
Removes one designation from the Redis-backed designation-only checkout cart. The controller deletes the amount and frequency entries for the selected designation id, then stores a donor-facing checkout message. This endpoint is public and uses the route session id to identify the cart.



# Remove a recipient from the saved checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/remove-a-recipient-from-the-saved-checkout

delete /frontend/checkout/entity/{client_id}/{program_id}/{entity_id}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Requires an organization-owned recipient, then removes its amount, frequency and custom-mode entries. redirect_link points to the order if recipient selections remain, otherwise to the public directory. Returns the resulting session ID.



# Remove a recipient from the saved checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/remove-a-recipient-from-the-saved-checkout-1

delete /frontend/checkout/entity/{client_id}/{program_id}/{entity_id}/{session_id}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Requires an organization-owned recipient, then removes its amount, frequency and custom-mode entries. redirect_link points to the order if recipient selections remain, otherwise to the public directory. Returns the resulting session ID.



# Remove an extra designation gift from checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/remove-an-extra-designation-gift-from-checkout

delete /frontend/checkout/designation/{client_id}/{program_id}/{id}/{currency}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Deletes the saved designation amount, frequency and data. currency is used only in the message. Returns 200 if saved recipient selections remain, otherwise 400 with status error and Order not removed even though designation entries have been deleted.



# Remove an extra designation gift from checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/remove-an-extra-designation-gift-from-checkout-1

delete /frontend/checkout/designation/{client_id}/{program_id}/{id}/{currency}/{session_id}
Public Redis cart mutation. A missing or expired session creates a replacement session. Recipient eligibility and amount/frequency policy are rechecked where applicable. Deletes the saved designation amount, frequency and data. currency is used only in the message. Returns 200 if saved recipient selections remain, otherwise 400 with status error and Order not removed even though designation entries have been deleted.



# Request to join a public trip
Source: https://api-docs.helpyousponsor.com/api-reference/public/request-to-join-a-public-trip

post /frontend/public/trips/{clientSlugOrId}/{tripSlug}/request-to-join
Creates a requested trip participant from the public trip page. The controller only accepts active trips with `request_to_join_enabled` set in trip settings, then delegates validation and participant creation to `TripParticipantService::createJoinRequest`. The service requires `email`, may require standardized donor fields or public signup fields configured for the trip donor form, creates or updates a donor, creates a fundraising entity, and stores the participant with `requested` status.



# Restore a saved entity to checkout
Source: https://api-docs.helpyousponsor.com/api-reference/public/restore-a-saved-entity-to-checkout

get /frontend/save_entity
Adds a previously selected entity back into the Redis-backed public checkout cart from query/body parameters. The endpoint validates the required ids, amount, frequency, and sponsorship amount, creates a replacement frontend session when the supplied one is expired, and stores the entity amount and default frequency in Redis. Public checkout uses this legacy route when restoring cart state.



# Retired legacy workspace signup
Source: https://api-docs.helpyousponsor.com/api-reference/public/retired-legacy-workspace-signup

post /signup
The legacy single-request signup endpoint is retired. It does not create an account or process payment; begin again from the Gratona signup page.



# Search public recipients before adding an entity
Source: https://api-docs.helpyousponsor.com/api-reference/public/search-public-recipients-before-adding-an-entity

get /frontend/add_entity/search/{client_id}/{program_id}/{session_id}
Searches visible recipients for the public add-entity flow so donors do not create duplicates. The controller scopes search by client and program, searches visible non-sample entity `json_fields` and numeric ids, optionally includes archived recipients, and returns display names from title fields plus public profile thumbnails. An empty search string returns an empty result set with the current session id.



# Show a designation-only checkout page
Source: https://api-docs.helpyousponsor.com/api-reference/public/show-a-designation-only-checkout-page

get /frontend/orderD/{client_id}/{hysform_id}/{designation_id}/{session_id}
Builds the public checkout payload for a donation page that accepts designations without sponsorship entities. The controller creates or refreshes a Redis frontend session, loads public donor signup fields for the HysForm, filters designations by client and HysForm, computes saved cart totals/frequency text from Redis, and returns checkout settings used by the frontend. This endpoint does not require bearer authentication; the optional session id carries the cart state.



# Show a public peer-to-peer program page
Source: https://api-docs.helpyousponsor.com/api-reference/public/show-a-public-peer-to-peer-program-page

get /frontend/public/peer-to-peer/{clientSlugOrId}/{programSlug}
Returns the public peer-to-peer campaign page for a client and program slug. The endpoint only returns programs whose settings mark them as `peer_to_peer`, then builds recipient cards, donation totals, checkout setting ids, and public display flags from program settings. Public checkout clients use the response to render the campaign listing and decide whether recipients can still accept donations.



# Show a public peer-to-peer recipient profile
Source: https://api-docs.helpyousponsor.com/api-reference/public/show-a-public-peer-to-peer-recipient-profile

get /frontend/public/peer-to-peer/{clientSlugOrId}/{programSlug}/recipients/{recipientSlug}
Returns the public profile for one visible recipient in a peer-to-peer program. The controller resolves the client, validates that the program is a peer-to-peer program, extracts the recipient id from the slug, and returns profile details plus recent donations. Donation amounts and donor display names follow the program privacy settings.



# Show a public trip page
Source: https://api-docs.helpyousponsor.com/api-reference/public/show-a-public-trip-page

get /frontend/public/trips/{clientSlugOrId}/{tripSlug}
Returns public trip metadata for an active or completed trip. The controller resolves the client by id or organization slug, looks up the trip by slug within that client, and hides trips that are not publicly visible. Public trip pages use the response for trip copy, donation settings, checkout setting ids, fund entity information, and the optional request-to-join form.



# Show a public trip participant profile
Source: https://api-docs.helpyousponsor.com/api-reference/public/show-a-public-trip-participant-profile

get /frontend/public/trips/{clientSlugOrId}/{tripSlug}/participants/{participantSlug}
Returns a public profile for one active trip participant. The controller extracts the participant id from the slug, respects the trip visibility opt-out setting, and hides or masks donation totals and donor names according to trip settings. Public checkout pages use the returned `entity_id`, `program_id`, `setting_id`, and `client_id` to donate to the participant.



# Show public add-recipient form configuration
Source: https://api-docs.helpyousponsor.com/api-reference/public/show-public-add-recipient-form-configuration

get /frontend/add_entity/{client_id}/{program_id}/{session_id}
Returns the public field configuration required to add a recipient/entity from a public program page. The controller creates or refreshes a frontend Redis session, loads the program and its HysForm, filters fields to public permissions, and returns program-type settings used by the public add-entity UI. If the program is missing or has no form configured, it returns a legacy 404 error envelope.



# Start bank redirect for a campaign donation
Source: https://api-docs.helpyousponsor.com/api-reference/public/start-bank-redirect-for-a-campaign-donation

post /frontend/checkout/campaign-ideal/{client_id}/{program_id}
Public, throttled to 30 requests per minute. Submit one recipient with amount/donation_amount, or a non-empty designations cart. Amounts must be positive decimals and allowed recurring selections must satisfy each program amount policy. Additional gifts must use designations allowed by the donor form and valid recipient routing. Existing donor emails require the verified checkout session; new donors must satisfy public donor identity and conditional form requirements. Recurring gifts require reusable bank support, while a valid future next date confirms the bank account for later collection. return_path is relative to the client app. A stale supplied policy_revision returns 409; a missing configured donor form returns 400. The method stores validated checkout details for bank-confirmed replay.



# Start bank redirect for a campaign donation
Source: https://api-docs.helpyousponsor.com/api-reference/public/start-bank-redirect-for-a-campaign-donation-1

post /frontend/checkout/campaign-ideal/{client_id}/{program_id}/{session_id}
Public, throttled to 30 requests per minute. Submit one recipient with amount/donation_amount, or a non-empty designations cart. Amounts must be positive decimals and allowed recurring selections must satisfy each program amount policy. Additional gifts must use designations allowed by the donor form and valid recipient routing. Existing donor emails require the verified checkout session; new donors must satisfy public donor identity and conditional form requirements. Recurring gifts require reusable bank support, while a valid future next date confirms the bank account for later collection. return_path is relative to the client app. A stale supplied policy_revision returns 409; a missing configured donor form returns 400. The method stores validated checkout details for bank-confirmed replay.



# Start bank redirect for an existing sponsorship order
Source: https://api-docs.helpyousponsor.com/api-reference/public/start-bank-redirect-for-an-existing-sponsorship-order

post /frontend/checkout/order-ideal/{client_id}/{program_id}/{session_id}
Public, throttled to 30 requests per minute. Requires a live Redis cart; prices an immutable snapshot of its selected recipients/designations and frequencies, including any configured fee consent. signup requires unique signup_username (min 5), unique valid email and required public donor identity/custom profile fields. login requires a donor linked to the checkout session and a verified session compatible with the saved Stripe customer. Recurring orders require recurring bank support. No donation is recorded until bank confirmation; use returned program_id/token to complete or cancel. A supplied stale donor-form policy_revision returns 409.



# Update a designation-only checkout frequency
Source: https://api-docs.helpyousponsor.com/api-reference/public/update-a-designation-only-checkout-frequency

get /frontend/checkout_update_designation_frequency_only/{client_id}/{hysform_id}/{designation_id}/{id}/{frequency}/{session_id}
Updates the Redis checkout cart frequency for a designation-only gift. The public checkout UI calls this when a donor changes a selected designation from one-time to a recurring schedule. If the optional session id is absent or expired, the controller creates a new frontend session before writing the `saved_designation_frequency` hash.



# End the recipient-portal session
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/end-the-recipient-portal-session

get /frontend/recipient-portal/logout/{client_id}/{session_id}
Deletes the Redis session keyed by `{session_id}`. Returns 200 even if the session was already missing — logout is idempotent for the caller.



# Get full message thread (root + replies)
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/get-full-message-thread-root-+-replies

get /frontend/recipient-portal/{client_id}/{session_id}/messages/{message_id}
Returns the message thread root identified by `{message_id}` along with all replies in chronological order, plus a flag indicating whether new replies require admin approval.



# Paginated list of donations to this recipient
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/paginated-list-of-donations-to-this-recipient

get /frontend/recipient-portal/{client_id}/{session_id}/donations
Returns donations (Donation rows where `designation = recipient.entity_id`) targeted at this recipient. Paginated; donations-tab feature must be enabled (else 403).



# Paginated list of donors who support this recipient
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/paginated-list-of-donors-who-support-this-recipient

get /frontend/recipient-portal/{client_id}/{session_id}/donors
Returns donors who have given to this recipient (or are otherwise associated). The response is paginated; the donors-tab feature must be enabled on the client/program (else 403).



# Paginated list of message threads + donor address book
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/paginated-list-of-message-threads-+-donor-address-book

get /frontend/recipient-portal/{client_id}/{session_id}/messages
Returns the recipient's message inbox (sent + received roots), a bounded initial donor address book (`donor_options`), the total number of emailable donors, and a flag indicating whether new messages require admin approval before delivery. More donor options are searched through the donor-options endpoint. Returns 403 when messaging is disabled.



# Profile-edit form schema + current values
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/profile-edit-form-schema-+-current-values

get /frontend/recipient-portal/{client_id}/{session_id}/profile
Returns the schema for the recipient profile edit form (which fields exist, their types, validation hints) plus the recipient's current values, including the optional peer-to-peer profile when the program has P2P enabled. Returns 403 when the client has the profile-edit feature disabled.



# Recipient-portal dashboard
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/recipient-portal-dashboard

get /frontend/recipient-portal/{client_id}/{session_id}
Returns the recipient-portal home/dashboard payload (recipient summary, program/client branding, peer-to-peer fields, feature flags, recent activity). Requires a valid logged-in Redis session — a 401/403 is returned if the session is missing, expired, or not logged in.



# Render the recipient-portal login page
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/render-the-recipient-portal-login-page

get /frontend/recipient-portal/login/{client_id}/{program_id}/{session_id}
Public endpoint that returns client + program branding for the recipient-portal login page. If `session_id` is omitted a fresh Redis-backed session is created and returned (1-hour TTL). The recipient portal does NOT use bearer tokens — it identifies the visitor through the `{session_id}` URL path parameter that is then carried through every subsequent recipient-portal call.



# Reply to an existing message thread
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/reply-to-an-existing-message-thread

post /frontend/recipient-portal/{client_id}/{session_id}/messages/{message_id}/reply
Creates a reply Donoremail row linked to the parent thread root identified by `{message_id}`. Subject is inherited from the parent. Approval gating and attachment handling work the same as `createPortalMessage`.



# Request a recipient-portal verification code by email
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/request-a-recipient-portal-verification-code-by-email

post /frontend/recipient-portal/login/{client_id}/{program_id}/{session_id}
First step of the recipient-portal login flow. Looks up the recipient by tenant-scoped email, issues a six-digit numeric code and magic link for 15 minutes, and invalidates the previous code for that client/program/recipient/email scope. Shared emails return `status=selection_required` so the caller can re-submit with `entity_id`.



# Search donors the recipient is allowed to message
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/search-donors-the-recipient-is-allowed-to-message

get /frontend/recipient-portal/{client_id}/{session_id}/donor-options
Returns a bounded address-book search for the active recipient session. Full-name mode searches visible donor identity prefixes. Restricted privacy modes accept only their visible labels, preventing hidden names or email addresses from influencing the result.



# Send a new message from the recipient to a donor
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/send-a-new-message-from-the-recipient-to-a-donor

post /frontend/recipient-portal/{client_id}/{session_id}/messages
Creates a Donoremail row from the recipient to a donor. When admin approval is required for outgoing recipient mail, the row is saved with `status=pending_approval`; otherwise it's queued for delivery and returned with `status=sent`. Optional attachment is referenced by an S3 storage key (the file must already have been uploaded via the recipient-portal upload endpoint).



# Submit a recipient impact story for staff review
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/submit-a-recipient-impact-story-for-staff-review

post /frontend/recipient-portal/{client_id}/{session_id}/impact-stories
Requires impact_stories enabled and an active logged-in recipient session belonging to this organization. The session resolves the recipient and program; callers cannot supply another record identity. Creates an internal story in ready_for_review with source recipient_portal_submission; submission does not publish it. An invalid/inactive session returns 400/403, missing recipient or disabled feature returns 404.



# Update the recipient's profile fields
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/update-the-recipients-profile-fields

put /frontend/recipient-portal/{client_id}/{session_id}/profile
Saves edits the recipient made in the profile form. The accepted body keys depend on the program — they're driven by the program's HysForm `entity` form fields and (for P2P programs) an optional `peer_to_peer_profile` sub-object containing facebook/twitter/instagram/linkedin and a free-form `bio`. Validation rules come from `getRecipientProfileValidationRules()` plus `getPeerToPeerProfileValidationRules()` when applicable.



# Verify a recipient portal magic link
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/verify-a-recipient-portal-magic-link

get /frontend/recipient-portal/verify_token/{client_id}/{token}
Consumes the current single-use sign-in token for this organization. Missing, expired or mismatched links return 400; inactive/deleted portal users and disabled program access return 403. On success activates the stored recipient session and returns its ID and safe recipient/client/program summaries. This token action requires no bearer token.



# Verify the recipient-portal login code
Source: https://api-docs.helpyousponsor.com/api-reference/recipient-portal/verify-the-recipient-portal-login-code

post /frontend/recipient-portal/verify_code/{client_id}
Second step of the recipient-portal login flow. Validates only the latest six-digit numeric code; five failed well-formed attempts burn the active challenge across source IPs. Success clears challenge state, marks the Redis session `logged_in=true`, and binds it to the recipient entity.



# Count recipient worksheet footer values
Source: https://api-docs.helpyousponsor.com/api-reference/recipients/count-recipient-worksheet-footer-values

post /admin/entities/{program_id}/footer-calculations
Counts blank, filled and unique values across the complete matching recipient program/all-program view. Resolves saved filters and search while discarding pagination/sort; results can be briefly cached. count_empty/count_filled aliases normalize to blank/filled. Unsupported operations are skipped, but sponsor_names explicitly returns422. Program id all or0 selects combined scope. Requires permission: one of manage_programs.



# Filter recipient worksheet rows
Source: https://api-docs.helpyousponsor.com/api-reference/recipients/filter-recipient-worksheet-rows

post /admin/entities/filter/{program_id}
Returns configurable recipient rows for an accessible program or all programs, including title fields and selected custom/system columns. Requires filter even without advanced groups. All-program views can choose recipients/campaigns surface; program preferences and saved views determine defaults. Participation columns require their workflow permission. The result is JSON with total matching length; custom values and dates retain their worksheet display shape. Requires permission: one of manage_programs.



# Preview existing recipient tags before replacement
Source: https://api-docs.helpyousponsor.com/api-reference/recipients/preview-existing-recipient-tags-before-replacement

post /admin/program/entities/tags/replacement-preview
Returns current tags/counts for selected tenant recipients without modifying them. Explicit ids are normalized; active foreign-program/denied recipients cause403 and missing ids are ignored at lookup. entity_ids=all resolves current worksheet selection with search/saved filters in250-row pages; program_id is required for a nonempty all selection. Proposed values.tags is checked for comma-containing array names but does not affect counts. Requires permission: one of manage_programs.



# Queue a recipient worksheet CSV export
Source: https://api-docs.helpyousponsor.com/api-reference/recipients/queue-a-recipient-worksheet-csv-export

post /admin/entities/{program_id}/export
Creates an export artifact, queues CSV generation and records the request in Activity. Applies saved views, current program/surface filters, selected fields/order/labels and participation field access; all or0 exports the combined program context. Returns HTTP200 with queued status, not CSV content. Follow export_id through the export status workflow; the returned status_url is a versionless relative API path. Worker failures/delivery are reported asynchronously. Requires permission: one of programs_view, manage_programs, program-all.



# Read recipient worksheet column preferences
Source: https://api-docs.helpyousponsor.com/api-reference/recipients/read-recipient-worksheet-column-preferences

get /admin/entities/{program_id}/column-preferences
Reads the current actor/organization/program/surface Redis preferences and sanitizes selected columns against current available fields. No saved preference returns empty arrays; saved preferences ensure name is present and append allowed columns missing from stored order. program_id all selects the combined program context; null/undefined string aliases normalize to all. program_surface defaults recipients; campaigns selects the separate campaign preference namespace. Requires permission: one of programs_view, manage_programs, program-all.



# Aggregate progress / KPI roll-up for a program
Source: https://api-docs.helpyousponsor.com/api-reference/reports/aggregate-progress-kpi-roll-up-for-a-program

get /admin/program/{program_id}/progress
Delegates to `ProgramService::programProgress` to compute and return the program's progress dashboard payload (counts, totals, milestone state). Powers the program progress widget on the admin dashboard. Shape is owned by the service. Requires permission: `manage_programs`.



# Calculate pinned report tile values
Source: https://api-docs.helpyousponsor.com/api-reference/reports/calculate-pinned-report-tile-values

get /admin/dashboard/tiles/values
Tiles and preferences belong to the current staff member within the organization. Writes and metric preview require report-management permission and access to the source report. Only metrics eligible for that report can be pinned or calculated.



# Calculate report worksheet totals
Source: https://api-docs.helpyousponsor.com/api-reference/reports/calculate-report-worksheet-totals

post /admin/reports/{id}/worksheet-summary
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Count reports by source
Source: https://api-docs.helpyousponsor.com/api-reference/reports/count-reports-by-source

get /admin/reports/source-counts
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Create a report audience handoff
Source: https://api-docs.helpyousponsor.com/api-reference/reports/create-a-report-audience-handoff

post /admin/reports/{id}/audience
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Delete a saved report
Source: https://api-docs.helpyousponsor.com/api-reference/reports/delete-a-saved-report

delete /admin/reports/{id}
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Download a completed report CSV
Source: https://api-docs.helpyousponsor.com/api-reference/reports/download-a-completed-report-csv

get /admin/reports/exports/{uploadId}
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata. Without resolve, the operation redirects or streams CSV bytes; resolve returns JSON. Artifact access is rechecked before delivery.



# Duplicate a report
Source: https://api-docs.helpyousponsor.com/api-reference/reports/duplicate-a-report

post /admin/reports/{id}/duplicate
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Get a saved report
Source: https://api-docs.helpyousponsor.com/api-reference/reports/get-a-saved-report

get /admin/reports/{id}
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Get report-builder metadata
Source: https://api-docs.helpyousponsor.com/api-reference/reports/get-report-builder-metadata

get /admin/reports/meta
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Get report source fields
Source: https://api-docs.helpyousponsor.com/api-reference/reports/get-report-source-fields

get /admin/reports/fields
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Get saved report insights
Source: https://api-docs.helpyousponsor.com/api-reference/reports/get-saved-report-insights

get /admin/reports/{id}/details
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Get visible report row counts
Source: https://api-docs.helpyousponsor.com/api-reference/reports/get-visible-report-row-counts

get /admin/reports/counts
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Get worksheet field metadata
Source: https://api-docs.helpyousponsor.com/api-reference/reports/get-worksheet-field-metadata

get /admin/worksheet/fields
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# List available report templates
Source: https://api-docs.helpyousponsor.com/api-reference/reports/list-available-report-templates

get /admin/reports/templates
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# List pinned report dashboard tiles
Source: https://api-docs.helpyousponsor.com/api-reference/reports/list-pinned-report-dashboard-tiles

get /admin/dashboard/tiles
Tiles and preferences belong to the current staff member within the organization. Writes and metric preview require report-management permission and access to the source report. Only metrics eligible for that report can be pinned or calculated.



# List saved reports
Source: https://api-docs.helpyousponsor.com/api-reference/reports/list-saved-reports

get /admin/reports
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# List the saved report catalog
Source: https://api-docs.helpyousponsor.com/api-reference/reports/list-the-saved-report-catalog

get /admin/reports/catalog
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Load a dashboard home section
Source: https://api-docs.helpyousponsor.com/api-reference/reports/load-a-dashboard-home-section

get /admin/dashboard/home/sections/{section}
Returns cached, permission-aware dashboard home data. Sections include overview, action_center, executive_snapshot, fundraising_summary, program_summary, trip_summary, wealth_teaser and recent_activity; sections can be omitted or null when unavailable. Mode changes update the organization preference.



# Load dashboard home
Source: https://api-docs.helpyousponsor.com/api-reference/reports/load-dashboard-home

get /admin/dashboard/home
Returns cached, permission-aware dashboard home data. Sections include overview, action_center, executive_snapshot, fundraising_summary, program_summary, trip_summary, wealth_teaser and recent_activity; sections can be omitted or null when unavailable. Mode changes update the organization preference.



# Pin a report dashboard tile
Source: https://api-docs.helpyousponsor.com/api-reference/reports/pin-a-report-dashboard-tile

post /admin/dashboard/tiles
Tiles and preferences belong to the current staff member within the organization. Writes and metric preview require report-management permission and access to the source report. Only metrics eligible for that report can be pinned or calculated.



# Poll a report CSV export
Source: https://api-docs.helpyousponsor.com/api-reference/reports/poll-a-report-csv-export

get /admin/reports/exports/{uploadId}/status
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Preview a report dashboard metric
Source: https://api-docs.helpyousponsor.com/api-reference/reports/preview-a-report-dashboard-metric

post /admin/dashboard/tiles/preview
Tiles and preferences belong to the current staff member within the organization. Writes and metric preview require report-management permission and access to the source report. Only metrics eligible for that report can be pinned or calculated.



# Preview a saved report
Source: https://api-docs.helpyousponsor.com/api-reference/reports/preview-a-saved-report

get /admin/reports/{id}/preview
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Preview an unsaved report definition
Source: https://api-docs.helpyousponsor.com/api-reference/reports/preview-an-unsaved-report-definition

post /admin/reports/preview
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Queue a report run
Source: https://api-docs.helpyousponsor.com/api-reference/reports/queue-a-report-run

post /admin/reports/{id}/run
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata. A successful200 response queues CSV work; poll the returned status URL.



# Queue an export of report rows
Source: https://api-docs.helpyousponsor.com/api-reference/reports/queue-an-export-of-report-rows

post /admin/reports/{id}/export
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata. A successful200 response queues CSV work; poll the returned status URL.



# Read related records for a report row
Source: https://api-docs.helpyousponsor.com/api-reference/reports/read-related-records-for-a-report-row

get /admin/reports/{id}/rows/{recordId}/related
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Read report worksheet rows
Source: https://api-docs.helpyousponsor.com/api-reference/reports/read-report-worksheet-rows

get /admin/reports/{id}/rows
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Remove a pinned report tile
Source: https://api-docs.helpyousponsor.com/api-reference/reports/remove-a-pinned-report-tile

delete /admin/dashboard/tiles/{id}
Tiles and preferences belong to the current staff member within the organization. Writes and metric preview require report-management permission and access to the source report. Only metrics eligible for that report can be pinned or calculated.



# Remove a report schedule
Source: https://api-docs.helpyousponsor.com/api-reference/reports/remove-a-report-schedule

delete /admin/reports/{id}/schedule
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Resolve a report audience token
Source: https://api-docs.helpyousponsor.com/api-reference/reports/resolve-a-report-audience-token

get /admin/reports/audience/{token}
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Save a report definition
Source: https://api-docs.helpyousponsor.com/api-reference/reports/save-a-report-definition

post /admin/reports
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Schedule a report
Source: https://api-docs.helpyousponsor.com/api-reference/reports/schedule-a-report

post /admin/reports/{id}/schedule
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Set the organization dashboard mode
Source: https://api-docs.helpyousponsor.com/api-reference/reports/set-the-organization-dashboard-mode

put /admin/dashboard/mode
Returns cached, permission-aware dashboard home data. Sections include overview, action_center, executive_snapshot, fundraising_summary, program_summary, trip_summary, wealth_teaser and recent_activity; sections can be omitted or null when unavailable. Mode changes update the organization preference.



# Star or unstar a saved report
Source: https://api-docs.helpyousponsor.com/api-reference/reports/star-or-unstar-a-saved-report

patch /admin/reports/{id}/star
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Tag records selected from a report
Source: https://api-docs.helpyousponsor.com/api-reference/reports/tag-records-selected-from-a-report

post /admin/reports/{id}/tag
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Update a pinned report tile
Source: https://api-docs.helpyousponsor.com/api-reference/reports/update-a-pinned-report-tile

patch /admin/dashboard/tiles/{id}
Tiles and preferences belong to the current staff member within the organization. Writes and metric preview require report-management permission and access to the source report. Only metrics eligible for that report can be pinned or calculated.



# Update a report definition
Source: https://api-docs.helpyousponsor.com/api-reference/reports/update-a-report-definition

put /admin/reports/{id}
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Update a report definition
Source: https://api-docs.helpyousponsor.com/api-reference/reports/update-a-report-definition-1

patch /admin/reports/{id}
Reports are scoped to the authenticated organization. Data operations enforce source-context access and reject missing fields or unavailable saved contexts. Mutations, scheduling, audience handoffs and downloads require report-management permission; read operations expose only permitted source fields. Worksheet columns and row values are dynamic and should be interpreted using the returned field metadata.



# Update report dashboard preferences
Source: https://api-docs.helpyousponsor.com/api-reference/reports/update-report-dashboard-preferences

put /admin/dashboard/preferences
Tiles and preferences belong to the current staff member within the organization. Writes and metric preview require report-management permission and access to the source report. Only metrics eligible for that report can be pinned or calculated.



# Get an exposed model schema
Source: https://api-docs.helpyousponsor.com/api-reference/schema/get-an-exposed-model-schema

get /schema/models/{name}
Returns field types, fillable and hidden metadata, casts and known relationships for one exposed model. Scoped API keys require schema:read (or a matching wildcard). The field and relationship maps reflect the deployed database/model definition and contain no record values.



# Get automation API capabilities
Source: https://api-docs.helpyousponsor.com/api-reference/schema/get-automation-api-capabilities

get /schema/capabilities
Returns the V3 API version, discovery availability, tenant metadata, page-size defaults and supported scope catalog. Scoped API keys require schema:read (or a matching wildcard). The catalog identifies supported scope names; caller authorization remains subject to the current credential and workspace permissions.



# List API enums and constants
Source: https://api-docs.helpyousponsor.com/api-reference/schema/list-api-enums-and-constants

get /schema/enums
Returns the frequency, payment_method, donor_type, entity_status and hysform_type lookup maps used by discovery clients. Scoped API keys require schema:read (or a matching wildcard). Values describe the deployed compatibility mappings.



# List exposed data models
Source: https://api-docs.helpyousponsor.com/api-reference/schema/list-exposed-data-models

get /schema/models
Lists the models available for authenticated integration schema discovery. Scoped API keys require schema:read (or a matching wildcard); each item links to the corresponding model schema. This endpoint returns model metadata, not donor or transaction records.



# Check grouped payment reminder readiness
Source: https://api-docs.helpyousponsor.com/api-reference/settings/check-grouped-payment-reminder-readiness

get /admin/settings/{settings_id}/payment-reminder-preflight
Inspects active default payment-reminder email/SMS templates for programs using this setting. Configured channels require an active template containing the grouped reminder placeholder. Missing channels are reported not_configured and do not block readiness. Different template sets generate warnings; due dates, methods, template sets and channels stay separate. This read does not enable reminders or send messages. Requires permission: one of manage_settings.



# Clone a program setting
Source: https://api-docs.helpyousponsor.com/api-reference/settings/clone-a-program-setting

post /admin/settings/{settings_id}/clone
Replicates an accessible setting for the current organization, clears its archive timestamp and assigns a new name. Blank/omitted name becomes Copy of {source name}, truncated to255characters. summary=true omits the full raw setting model from data. Does not attach the new setting to a program. Requires permission: one of manage_settings.



# Get address field labels
Source: https://api-docs.helpyousponsor.com/api-reference/settings/get-address-field-labels

get /geo/address-format/{country_code}
Returns postal and subdivision labels plus whether subdivisions exist. Unknown country codes use Postal Code and State/Province labels with has_subdivisions=false.



# Get organization jurisdiction settings
Source: https://api-docs.helpyousponsor.com/api-reference/settings/get-organization-jurisdiction-settings

get /admin/jurisdiction-profile
Returns the effective statement/receipt profile, current-year preview and country presets. An organization with no saved profile uses the US preset and existing EIN without printing the registration number. Saving replaces configurable values; omitted optional values reset to their preset/default. Fiscal periods use the year in which the period ends. This endpoint configures wording and period metadata; it does not validate tax eligibility. Requires permission: one of manage_settings, access_account_settings.



# Get organization public branding
Source: https://api-docs.helpyousponsor.com/api-reference/settings/get-organization-public-branding

get /admin/public-branding
Returns public identity, default accent and contrast tokens, program override counts, capabilities and a public preview URL. Requires access_account_settings or manage_settings. Colors fall back to indigo600 when no valid organization color exists. Requires permission: one of access_account_settings, manage_settings.



# Get restricted record display settings
Source: https://api-docs.helpyousponsor.com/api-reference/settings/get-restricted-record-display-settings

get /admin/privacy/record-disclosure
Returns workspace defaults, selected levels, program overrides and the visibility ladder. These settings currently apply to restricted record mentions; users with full record access retain full visibility. Requires permission: one of manage_settings.



# List address countries
Source: https://api-docs.helpyousponsor.com/api-reference/settings/list-address-countries

get /geo/countries
Returns ISO3166-1 alpha-2 country codes and localized names, sorted by name.



# List country subdivisions
Source: https://api-docs.helpyousponsor.com/api-reference/settings/list-country-subdivisions

get /geo/subdivisions/{country_code}
Returns top-level ISO3166-2-style subdivision codes and names, sorted by name. An unknown country or one with no subdivisions returns an empty data array. locale is accepted but the subdivision repository currently supplies its own stored names.



# Pin or unpin a navigation item
Source: https://api-docs.helpyousponsor.com/api-reference/settings/pin-or-unpin-a-navigation-item

patch /admin/navigation-preferences/pins
Updates only the authenticated user’s preferences in the current organization. Supply expected_version from the last snapshot; a stale version returns409 with current. Repeating an already-applied operation is a no-op and preserves the version. Pins are limited to6; expanded and collapsed groups to24 each. client_id and user_id must not be submitted. Requires permission: navigation_preferences_self_service.



# Remember an expanded navigation group
Source: https://api-docs.helpyousponsor.com/api-reference/settings/remember-an-expanded-navigation-group

patch /admin/navigation-preferences/expanded-groups
Updates only the authenticated user’s preferences in the current organization. Supply expected_version from the last snapshot; a stale version returns409 with current. Repeating an already-applied operation is a no-op and preserves the version. Pins are limited to6; expanded and collapsed groups to24 each. client_id and user_id must not be submitted. Requires permission: navigation_preferences_self_service.



# Reset program accent overrides
Source: https://api-docs.helpyousponsor.com/api-reference/settings/reset-program-accent-overrides

delete /admin/public-branding/program-color-overrides
Requires manage_settings and access to every affected program setting. Removes the color override from all currently customized program settings. Optional program_ids is an optimistic confirmation of the complete current customized-program list; it does not select a subset. A changed list returns409 before writing. Requires permission: one of manage_settings.



# Update a program privacy override
Source: https://api-docs.helpyousponsor.com/api-reference/settings/update-a-program-privacy-override

put /admin/programs/{program_id}/record-disclosure
Sets or clears a program’s entity level and hide-type flag. A level looser than the workspace entity default is clamped to that default and clamped=true is returned. Submit entity_level=null to use the workspace default. revision compares the program override revision. Enforcement currently applies to mentions. Requires permission: one of manage_settings.



# Update organization jurisdiction settings
Source: https://api-docs.helpyousponsor.com/api-reference/settings/update-organization-jurisdiction-settings

put /admin/jurisdiction-profile
Returns the effective statement/receipt profile, current-year preview and country presets. An organization with no saved profile uses the US preset and existing EIN without printing the registration number. Saving replaces configurable values; omitted optional values reset to their preset/default. Fiscal periods use the year in which the period ends. This endpoint configures wording and period metadata; it does not validate tax eligibility. Requires permission: one of manage_settings, access_account_settings.



# Update organization public branding
Source: https://api-docs.helpyousponsor.com/api-reference/settings/update-organization-public-branding

patch /admin/public-branding
Supply at least one supported field. Public name and logo require access_account_settings; default color permits that permission or manage_settings. The name is trimmed and must retain3characters. A changed logo must be a workspace-uploaded account-logo asset under client-assets/{client_id}/account-logo with an accepted image extension. Custom hex colors require color_level600; preset names/shades must be configured. Requires permission: one of access_account_settings, manage_settings.



# Update restricted record display levels
Source: https://api-docs.helpyousponsor.com/api-reference/settings/update-restricted-record-display-levels

put /admin/privacy/record-disclosure
Partially merges supported record-type levels. Unknown record types and full visibility are rejected. Supply revision to detect concurrent edits; stale revisions return409. No-op writes preserve the revision. Enforcement currently applies to mentions. Requires permission: one of manage_settings.



# Archive a page and its active descendants
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/archive-a-page-and-its-active-descendants

post /admin/pages/{page}/archive
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Changes the accessible page tree under a space lock; concurrent reorganization can return 409.



# Change clearance for files in a space
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/change-clearance-for-files-in-a-space

post /admin/spaces/{type}/{id}/clearance
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Support sessions are read-only. Each file is authorized independently; refused changes are returned as unchanged rows. A successful batch can return a single-use undo token bound to this user and space, valid for sixty seconds.



# Create a page
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/create-a-page

post /admin/pages
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Creates page metadata and its initial empty page-profile document. The parent must be active in the same space and the configured maximum tree depth must be respected.



# List a recipient space supporters
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-a-recipient-space-supporters

get /admin/spaces/recipient/{id}/supporters
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Without donor access the list is empty and meta.restricted is true; the count remains available. prepare_update is present only when the caller can generate mailings and supporters exist.



# List a space media page
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-a-space-media-page

get /admin/spaces/{type}/{id}/media
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Returns accessible files with current public/supporter clearance decisions and consent holds.



# List accessible program spaces
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-accessible-program-spaces

get /admin/spaces
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Returns every visible program with file and story totals, ordered by most recent activity.



# List Drive sources mapped into a space
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-drive-sources-mapped-into-a-space

get /admin/spaces/{type}/{id}/sources
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Only program spaces have mapped folders; other supported space types return an empty list.



# List my page mention notifications
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-my-page-mention-notifications

get /admin/notifications/page-mentions
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Returns the latest fifty delivered notifications addressed to the current user. Page and access-request identity are reauthorized on each read; inaccessible content is replaced by an unavailable message. meta.unread counts unread rows in this returned window.



# List my pinned pages
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-my-pinned-pages

get /admin/pages/pinned
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Returns at most 200 personal pins.



# List recent mention suggestions
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-recent-mention-suggestions

get /admin/mentions/recent
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. The document must occur in an accessible page. Search and recent additionally require edit access to an active page. Read resolution never grants access to the mentioned record. Suggests the page subject followed by up to ten records mentioned by this user in the last thirty days, reauthorized on every request.



# List recently edited pages
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-recently-edited-pages

get /admin/pages/recent
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Returns twenty accessible results per page. The opaque cursor advances through bounded access scans; use it until next_cursor is null.



# List saved page-document versions
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-saved-page-document-versions

get /admin/page-documents/{document}/versions
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Only page-owned documents are supported. Document and owner UUIDs must belong to the authenticated tenant. Returns up to200 snapshots newest first. Labelled saves always snapshot; unlabelled saves are rate limited by the configured snapshot interval.



# List stories in a space
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-stories-in-a-space

get /admin/spaces/{type}/{id}/stories
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Uses current clearance decisions for the blocked filter and reach fields.



# List work needing attention across spaces
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/list-work-needing-attention-across-spaces

get /admin/spaces/needs-you
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Checks the organization and the twelve most recently active program spaces. partial is true when additional program spaces exist; cached for one minute per user and role authority.



# Mark a page mention notification read
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/mark-a-page-mention-notification-read

post /admin/notifications/page-mentions/{notification}/read
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Marks an unread notification owned by this user. The response acknowledges the requested ID even when no unread owned row needed updating.



# Move or reorder a page
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/move-or-reorder-a-page

post /admin/pages/{page}/move
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. parent_uuid must be present and may be null for the root. Parent must be active in the same space; cycles, self-parenting and excessive depth are rejected. position is stored as a decimal string.



# Pin a page for my user
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/pin-a-page-for-my-user

post /admin/pages/{page}/pin
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Only changes the current user personal pin state.



# Read a mention summary card
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-a-mention-summary-card

get /admin/mentions/summary
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. The document must occur in an accessible page. Search and recent additionally require edit access to an active page. Read resolution never grants access to the mentioned record. Below full disclosure only disclosure is returned; detail fields and donation aggregates appear only when the caller may read them.



# Read a revisioned page document
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-a-revisioned-page-document

get /admin/page-documents/{document}
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Only page-owned documents are supported. Document and owner UUIDs must belong to the authenticated tenant. Returns the stored editor tree and current revision, with present edit and HTML capabilities.



# Read a space header
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-a-space-header

get /admin/spaces/{type}/{id}
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. The type must be organization, program or recipient; event, trip and grant spaces are not implemented by this resolver.



# Read a space overview
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-a-space-overview

get /admin/spaces/{type}/{id}/overview
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Returns attention rows, twelve recent media files, five recent stories and up to eight program recipients with recent media but no recent story.



# Read page metadata and breadcrumbs
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-page-metadata-and-breadcrumbs

get /admin/pages/{page}
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Includes can_edit and the accessible page ancestor trail.



# Read the space clearance board
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-the-space-clearance-board

get /admin/spaces/{type}/{id}/clearance-board
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Returns one column per clearance level with its total and up to 24 initial media items.



# Read the subject space page tree
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-the-subject-space-page-tree

get /admin/spaces/{subjectType}/{subjectId}/pages/tree
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Returns up to 5000 page rows in tree ordering with parent UUIDs and personal pin state. archived selects trash instead of active pages.



# Read the workspace page tree
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/read-the-workspace-page-tree

get /admin/pages/tree
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Returns up to 5000 page rows in tree ordering with parent UUIDs and personal pin state. archived selects trash instead of active pages.



# Request access to a mentioned record
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/request-access-to-a-mentioned-record

post /admin/mentions/request-access
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. The document must occur in an accessible page. Search and recent additionally require edit access to an active page. Read resolution never grants access to the mentioned record. The record must occur in the page. Notifies up to fifty current access managers; repeats within 24 hours reuse the request. If already visible, requested is false and already_visible is true. This endpoint does not change permissions.



# Resolve labels for document mentions
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/resolve-labels-for-document-mentions

post /admin/mentions/resolve
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. The document must occur in an accessible page. Search and recent additionally require edit access to an active page. Read resolution never grants access to the mentioned record. Only references actually present in this document/version are disclosed; foreign, missing and unbound refs get unavailable disclosures. Input allows 400 entries before deduplication; at most 200 distinct valid refs are allowed.



# Restore a page-document version
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/restore-a-page-document-version

post /admin/page-documents/{document}/versions/{version}/restore
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Only page-owned documents are supported. Document and owner UUIDs must belong to the authenticated tenant. Writes the chosen snapshot as a new revision through the normal save rules, with a restoration label. base_revision is optional; supply it to detect a concurrent save. Mentions the actor cannot insert are removed and counted.



# Restore a page from trash
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/restore-a-page-from-trash

post /admin/pages/{page}/restore
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Changes the accessible page tree under a space lock; concurrent reorganization can return 409.



# Save a revisioned page document
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/save-a-revisioned-page-document

patch /admin/page-documents/{document}
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Only page-owned documents are supported. Document and owner UUIDs must belong to the authenticated tenant. Requires base_revision to match the current revision. The request envelope is limited to3 MB and the document itself to2 MB, at most 12 nested levels. Root type must be doc; content follows each node allowed children, unique block IDs and profile rules. Newly inserted mentions and Library files are reauthorized. Archived owners reject edits; HTML changes require Manage HTML blocks.



# Search accessible mention choices
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/search-accessible-mention-choices

get /admin/mentions/search
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. The document must occur in an accessible page. Search and recent additionally require edit access to an active page. Read resolution never grants access to the mentioned record. Groups choices by record kind; limit is per group, with at most 50 items overall. Cursor is effective only with a group. A truncated group has more scanned candidates to page through.



# Search page titles and document text
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/search-page-titles-and-document-text

get /admin/pages/search
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Returns twenty accessible results per page. The opaque cursor advances through bounded access scans; use it until next_cursor is null.



# Search programs and recipients for a space
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/search-programs-and-recipients-for-a-space

get /admin/spaces/search
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Matches names among records the caller can open; returns up to ten options.



# Undo a space clearance change
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/undo-a-space-clearance-change

post /admin/spaces/{type}/{id}/clearance/undo
Requires the spaces feature and current access to the organization, program or recipient. File, story and supporter sections additionally follow their own permissions. Consumes the single-use token within sixty seconds. Each file restores only if its current revision still matches the previous batch; per-file refusals remain in the response.



# Unpin a page for my user
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/unpin-a-page-for-my-user

delete /admin/pages/{page}/pin
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Only changes the current user personal pin state.



# Update page metadata
Source: https://api-docs.helpyousponsor.com/api-reference/spaces/update-page-metadata

patch /admin/pages/{page}
Requires the configured page-editor feature (spaces by default) and current subject/page access. Workspace pages use a null subject; subject pages inherit their space access. Edits only submitted title, icon and width fields. Restore an archived page before editing.



# Add a new commitment
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/add-a-new-commitment

post /admin/sponsorships



# Apply a received gift to recipient coverage
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/apply-a-received-gift-to-recipient-coverage

post /admin/donations/{donation_id}/funding
Requires bearer or API-key authentication, current organization scope and access to every selected recipient program. Gift/funding administration also follows the donations/reports permission policy. Only qualified received gifts with retained money in the organization currency can fund recipients. Campaign, peer-to-peer and trip records are excluded. Money-need programs derive whole monthly periods, retain any unused remainder and allow partial first-month coverage; slot programs require an explicit coverage end. Replans under the gift lock and writes all rows atomically, preventing concurrent over-allocation. Any preview problems become 422. Records funding activity and refreshes coverage/search after commit. Repeating this request can allocate more remaining money; it is not an idempotency-key endpoint and does not charge another payment.



# Apply starter lifecycle reasons
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/apply-starter-lifecycle-reasons

post /admin/lifecycle-reason-sets/apply-template
Materializes selected reason contexts, or all contexts when context_keys is omitted/null. Existing nonempty catalogs are preserved; empty catalogs receive starter reasons. Returns all three current standards. Requires the workspace lifecycle feature. Mutation permission is lifecycle_reasons_manage or manage_settings.



# Approve a donor sponsorship change request
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/approve-a-donor-sponsorship-change-request

post /admin/sponsorship-change-requests/{request_id}/approve
Rechecks a still-pending request under billing/row locks and applies exactly its reviewed values. Changed ownership/financial fingerprint, changed management mode or an unavailable schedule leave the request pending. Schedule changes require donation management permission; cancellation honors the role archive restriction. Approval never charges or refunds; cancellation keeps past giving/paid coverage. Requests are scoped to this organization and programs accessible to the reviewer. Snapshot financial details require donation read access.



# Archive a commitment for a donor
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/archive-a-commitment-for-a-donor

post /admin/sponsorships/{donor_entity_id}/archive



# Archive Sponsorships for Donors
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/archive-sponsorships-for-donors

post /admin/sponsorships/archive



# Confirm a donor sponsorship review
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/confirm-a-donor-sponsorship-review

post /frontend/donor/dashboard/sponsorships/{client_id}/{program_id}/{session_id}/{donor_entity_id}/confirm
Consumes the exact review before writing; expired, used, foreign-session or stale reviews cannot be applied. Direct mode updates the future schedule or archives the relationship/commitment through lifecycle; approval mode stores the reviewed values as a pending request. No charge or refund occurs. Recurring-charge and row locks recheck authority/payment state; failed attempts require a fresh review. Uses a logged-in donor session for this organization and a valid portal program/global context; the session TTL refreshes to one hour. Only that donor’s relationships or requests can be accessed.



# Count sponsorship worksheet footer values
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/count-sponsorship-worksheet-footer-values

post /admin/sponsorships/{program_id}/footer-calculations
Counts blank, filled and unique values over all matching permission-scoped sponsorships. Uses the same saved view, allowed programs, scoped search, due/current status and sponsorship date rules as the worksheet. Index aggregates fall back to bounded250-row projections for live/unsupported filters; errors are not converted into a successful zero count. Program id all or0 selects combined scope. Unknown operations are ignored and count aliases normalize. Requires permission: one of manage_programs.



# Create a lifecycle reason
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/create-a-lifecycle-reason

post /admin/lifecycle-reason-sets/{reason_set_id}/reasons
Creates an active workspace reason at the end of the context. A unique stable code is generated from the label; the set catalog version advances. Requires the workspace lifecycle feature. Mutation permission is lifecycle_reasons_manage or manage_settings.



# Donors and Available Entities
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/donors-and-available-entities

get /admin/sponsorships/new
Returns donors and available entities



# Download a finished commitment export
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/download-a-finished-commitment-export

get /admin/sponsorships/exports/{uploadId}
Sponsorship-export counterpart to `downloadDonorExport`. Default behavior issues an HTTP 302 redirect to a short-lived presigned URL. When called with `?resolve=1`, returns the URL as JSON instead. The upload must belong to the caller's client. Requires permission: `manage_programs` or `donors_view`.



# Filter sponsorship worksheet rows
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/filter-sponsorship-worksheet-rows

post /admin/sponsorships/program/filter/{program_id}
Searches joined donor/recipient/commitment rows within permitted effective programs, excluding explicit program denials in all-program views. Applies current/due status, saved filters, scoped query and sponsorship creation-date bounds. Fields and column_order update current header preferences. Responses retain selected tenant form/display values and only selected commitment metrics; use explicit pageIndex/pageSize to bound results. A search index that cannot supply a safe fallback returns503. Requires permission: one of manage_programs.



# Flat list of entities available for commitment picking
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/flat-list-of-entities-available-for-commitment-picking

get /admin/list_available_entities
Returns permission-scoped recipient options for the authenticated client. Tenant and program filters are applied before pagination, and profile fields/uploads are hydrated only for the requested page. Available recipients have status 0 or 2. Each option includes program context, an optional profile image URL (thumbnail preferred, original image used while the thumbnail is unavailable), and up to three configured sponsorship-card fields. Requires permission: `manage_programs`.



# Get a donor sponsorship approval request
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/get-a-donor-sponsorship-approval-request

get /admin/sponsorship-change-requests/{request_id}
Returns immutable reviewed snapshots plus current approval eligibility/blocker. can_approve can be false because the request is resolved, permissions are insufficient, sponsorship state changed, program mode changed, or current payment/action policies block it. Requests are scoped to this organization and programs accessible to the reviewer. Snapshot financial details require donation read access.



# Get Commitment Statistics
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/get-commitment-statistics

get /admin/sponsorships/statistics
Returns active and archived sponsorship relationship counts grouped by program for the authenticated admin's client. The sponsorship table uses these tenant-scoped counts to populate its summary views.



# Get commitments for a specific donor
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/get-commitments-for-a-specific-donor

get /admin/donor/{id}/sponsorships
Returns sponsorships data



# Get Commitments Table Headers
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/get-commitments-table-headers

post /admin/sponsorships/{program_id}/headers
Retrieves data for the sponsored table based on the given program ID, client ID, and filter.



# Get donor sponsorship management options
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/get-donor-sponsorship-management-options

get /frontend/donor/dashboard/sponsorships/{client_id}/{program_id}/{session_id}/{donor_entity_id}
Returns current financial state, effective management mode, available frequencies/date window and action-specific blockers. Requires exactly one matching donor-owned type1 commitment and visible payment details; unsupported relationships return422. Online writes require direct/approval program mode and workspace rollout. A pending request blocks additional changes. Provider subscriptions, nonbilling/zero/nonrecurring commitments, expired schedules or processing payments require staff help; cancellation also requires active donor_cancelled reason with no notes. Schedule changes also block due/past-due/retry payments. Uses a logged-in donor session for this organization and a valid portal program/global context; the session TTL refreshes to one hour. Only that donor’s relationships or requests can be accessed.



# Get sponsorship lifecycle reasons
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/get-sponsorship-lifecycle-reasons

get /admin/sponsorships/lifecycle/options
Returns active workspace reason choices and policies, falling back to starter config when a context is not materialized. Only reassigned is supported for moves.



# List commitment-export jobs currently queued or processing
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-commitment-export-jobs-currently-queued-or-processing

get /admin/sponsorships/exports/active
Sponsorship-export counterpart to `activeDonorExports`. Returns up to 10 sponsorship-export `Upload` rows from the last 24 hours whose status is `queued` or `processing`, enriched with `PdfRenderService::queuedUploadStatus`. Requires permission: `manage_programs` or `donors_view`.



# List donor sponsorship approval requests
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-donor-sponsorship-approval-requests

get /admin/sponsorship-change-requests
Lists pending requests oldest first, or all statuses newest first, with a fixed page limit of100. The cursor encodes the current ordering position; malformed cursors fail validation. Eligibility is evaluated on opening/approval, so list rows do not include can_approve. Requests are scoped to this organization and programs accessible to the reviewer. Snapshot financial details require donation read access.



# List donor sponsorship change requests
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-donor-sponsorship-change-requests

get /frontend/donor/dashboard/sponsorship-requests/{client_id}/{program_id}/{session_id}
Returns at most fifty latest requests across this organization’s programs, newest ID first. Payment snapshots/currency/behavior are null where portal payment visibility is disabled. Request status remains durable history. Uses a logged-in donor session for this organization and a valid portal program/global context; the session TTL refreshes to one hour. Only that donor’s relationships or requests can be accessed.



# List eligible replacement recipients
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-eligible-replacement-recipients

get /admin/sponsorships/{donor_entity_id}/reassignment-options
Searches active visible recipients other than the current target and other active relationships of this donor. Only accessible programs are included. Current program is ordered first, then newest creation/ID, with public featured fields and newest profile thumbnail.



# List every commitment for the active client
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-every-commitment-for-the-active-client

get /admin/all_sponsorships
Returns every `DonorEntity` row for the calling admin's client, augmented with display names for the entity (via `Donor::getEntityName`) and the donor (via `Entity::getDonorName`). Currently scoped via the legacy session `client_id` rather than the bearer token, so callers must have an active admin session even though the route is also bearer-protected. Mirrored at `/admin/all_sponsorships` on both v1/admin and the legacy api.php. Requires permission: `manage_programs`.



# List lifecycle reason standards
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-lifecycle-reason-standards

get /admin/lifecycle-reason-sets
Returns all three reason contexts including inactive reasons. Unmaterialized contexts expose their configured starter reasons with null IDs and version zero; this read does not create catalog rows. can_manage reflects the current role. Requires the workspace lifecycle feature. Mutation permission is lifecycle_reasons_manage or manage_settings.



# List recipient funding allocated from a gift
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-recipient-funding-allocated-from-a-gift

get /admin/donations/{donation_id}/funding
Requires bearer or API-key authentication, current organization scope and access to every selected recipient program. Gift/funding administration also follows the donations/reports permission policy. Returns rows in ID order filtered to recipient programs the caller can access. available is the remaining allocatable retained gift value; amount is the original gift amount. Reversed/released rows remain in history and have zero effective amount.



# List recipients eligible for gift funding
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-recipients-eligible-for-gift-funding

get /admin/recipient-funding/recipients
Requires bearer or API-key authentication, current organization scope and access to every selected recipient program. Gift/funding administration also follows the donations/reports permission policy. Returns active recipients from supported recipient programs with current coverage and sponsor names. unsponsored_only excludes existing live sponsor relationships. The limit is applied before the name search, so filtering can return fewer matches than the requested limit. Legacy programs with no explicit type remain eligible.



# List sponsorship lifecycle history
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/list-sponsorship-lifecycle-history

get /admin/sponsorships/lifecycle/events
Lists append-only events newest effective_at then ID first. Both old and new programs must be accessible; null program IDs remain included. Names may resolve from archived donors/recipients. Delivery state reflects Journey processing.



# Load legacy commitment table metadata
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/load-legacy-commitment-table-metadata

post /admin/show_all_sponsorships
Returns legacy sponsorship-table bootstrap metadata, not sponsorship rows. The payload contains the selected program marker, archive state, counts for a specific permitted program, and a sponsorship-table marker. With program_id=all, it returns the literal all marker and empty counts. Requires permission: manage_programs.



# Poll a single commitment-export job
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/poll-a-single-commitment-export-job

get /admin/sponsorships/exports/{uploadId}/status
Sponsorship-export counterpart to `donorExportStatus`. Returns the current state of one sponsorship-export `Upload` (scoped to the caller's client, 404 otherwise). Requires permission: `manage_programs` or `donors_view`.



# Post Commitments Next
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/post-commitments-next

post /admin/sponsorships/donor
Returns donor details, program details, and other related information



# Preview a sponsorship recipient reassignment
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/preview-a-sponsorship-recipient-reassignment

post /admin/sponsorships/{donor_entity_id}/reassignment-preview
Validates active source/target, target visibility and basic capacity status, plus duplicate donor/recipient relationships. Returns current payment continuity and effective time. The compatibility target_entity_id alias can supply entity_id and omit transition_type; it still needs expected_version for success. expected_version must match; write rechecks detailed capacity and donor state under locks.



# Preview allocation of a received gift to recipients
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/preview-allocation-of-a-received-gift-to-recipients

post /admin/donations/{donation_id}/funding/preview
Requires bearer or API-key authentication, current organization scope and access to every selected recipient program. Gift/funding administration also follows the donations/reports permission policy. Only qualified received gifts with retained money in the organization currency can fund recipients. Campaign, peer-to-peer and trip records are excluded. Money-need programs derive whole monthly periods, retain any unused remainder and allow partial first-month coverage; slot programs require an explicit coverage end. Reads without writing funding rows. Planning problems are returned in a successful 200 response; invalid input or ineligible recipient-program types return 422. No revenue, payment method or commitment is created.



# Preview available fixed sponsorship levels
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/preview-available-fixed-sponsorship-levels

post /admin/sponsorship-amount-preview
Uses supplied configuration only; no program or recipient is changed. Filters configured positive amounts by current funded percentage and remaining capacity. An amount remains available only below its configured threshold (default100); exceeding remaining target requires allow_sponsorship_over_target. funded_percent is rounded to two decimals and can exceed100.



# Queue a CSV export of commitments (async)
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/queue-a-csv-export-of-commitments-async

get /admin/sponsorships/{program_id}/export
Legacy query-string variant. Prefer POST for wide exports so `column_order` and `column_labels` do not exceed URL length limits. Reserves an `Upload` row to back the export, marks it `queued`, then dispatches `ExportSponsorshipsJob`. Returns 200 immediately with the upload id and a `status_url` to poll. The `program_id` may be the literal string `all` to export every sponsorship across the caller's client (file stem becomes `all-sponsorships-export`). Any extra query parameters (filters, column overrides) are forwarded to the job verbatim. Requires permission: `programs_view`, `manage_programs`, or `program-all`.



# Queue a CSV export of commitments (async)
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/queue-a-csv-export-of-commitments-async-1

post /admin/sponsorships/{program_id}/export
Preferred export endpoint for wide sponsorship worksheets. Accepts filters, `column_order`, and `column_labels` in a JSON request body, reserves an `Upload` row, marks it `queued`, and dispatches `ExportSponsorshipsJob`. Labels only rename columns already present in validated `column_order`; they cannot add columns. Requires permission: `programs_view`, `manage_programs`, or `program-all`.



# Read a recipient funding history and current coverage
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/read-a-recipient-funding-history-and-current-coverage

get /admin/program/entities/{id}/funding
Requires bearer or API-key authentication, organization scope and current recipient program access. Includes archived recipients. Returns all row history ordered by coverage end descending, the current/upcoming coverage summary and configured monetary or slot need. Staff funder names are returned alongside their anonymous display preference; that preference controls recipient-facing presentation.



# Reassign a sponsorship recipient
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/reassign-a-sponsorship-recipient

post /admin/sponsorships/{donor_entity_id}/reassign
Moves the donor relationship and linked type1 commitments to a visible available recipient, including another accessible program. Preserves payment amounts/frequency/method/billing anchors; updates designation/funding and recipient availability. Locks block concurrent billing and recheck donor, target capacity and duplicates. The reasoned contract uses expected version plus UUID retry fingerprint; an identical retry returns replayed=true. Presence of target_entity_id selects older controls semantics: entity_id defaults from it, reason/notes/effective-time/version/retry inputs are ignored and a compact sponsorship result is returned. Controls mode requires lifecycle controls and can reject missing reasons when reason selection is required.



# Reject a donor sponsorship change request
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/reject-a-donor-sponsorship-change-request

post /admin/sponsorship-change-requests/{request_id}/reject
Resolves a pending request as rejected and clears its pending hold. Trims review_note to null if blank; the sponsorship/payment schedule are preserved. Requests are scoped to this organization and programs accessible to the reviewer. Snapshot financial details require donation read access.



# Reorder a lifecycle reason catalog
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/reorder-a-lifecycle-reason-catalog

post /admin/lifecycle-reason-sets/{reason_set_id}/reorder
Requires every reason in this context exactly once, including inactive reasons. Saves zero-based order and advances the catalog version. Requires the workspace lifecycle feature. Mutation permission is lifecycle_reasons_manage or manage_settings.



# Restore one archived sponsorship
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/restore-one-archived-sponsorship

post /admin/sponsorships/{donor_entity_id}/restore
Restores one archived donor-to-recipient sponsorship for the authenticated admin's client, restores its commitment schedule, resets failed-payment retries, recalculates recipient sponsorship status, and refreshes table caches. The donor and recipient must both still be active. Requires permission: `manage_programs` and is gated by the `disable_sponsorship_restore` client restriction.



# Restore selected archived sponsorships
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/restore-selected-archived-sponsorships

post /admin/sponsorships/restore
Restores archived sponsorships selected from the authenticated admin's sponsorship table, including selections spanning every filtered result. Each restored commitment has failed-payment retries reset; a supplied next action date updates its schedule, while omission preserves its existing date. Requires permission: `manage_programs` and is gated by the `disable_sponsorship_restore` client restriction.



# Reverse a recipient funding allocation
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/reverse-a-recipient-funding-allocation

post /admin/recipient-funding/{funding_id}/reverse
Requires bearer or API-key authentication, current organization scope and access to every selected recipient program. Gift/funding administration also follows the donations/reports permission policy. Marks the row reversed and retains its history. Repeating reversal is safe. Removes its effective coverage/allocation so retained gift money is available again; does not reverse or refund the underlying donation.



# Review a donor sponsorship change
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/review-a-donor-sponsorship-change

post /frontend/donor/dashboard/sponsorships/{client_id}/{program_id}/{session_id}/{donor_entity_id}/preview
Creates a ten-minute, session-bound one-time review without writing the payment schedule. Only the documented properties are accepted. Change preserves the monthly-equivalent contribution and re-expresses a per-period amount for the selected frequency; cancellation preserves historical payments/paid coverage. The review explains direct application or approval consequences. Online writes require direct/approval program mode and workspace rollout. A pending request blocks additional changes. Provider subscriptions, nonbilling/zero/nonrecurring commitments, expired schedules or processing payments require staff help; cancellation also requires active donor_cancelled reason with no notes. Schedule changes also block due/past-due/retry payments. Uses a logged-in donor session for this organization and a valid portal program/global context; the session TTL refreshes to one hour. Only that donor’s relationships or requests can be accessed.



# Review bulk commitment changes
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/review-bulk-commitment-changes

post /admin/commitments/preview
Resolves explicit, all-program/filtered or complete failed-operation sponsorship selections and projects financial outcomes. Every relationship must have a matching active donor, recipient, commitment and any nonzero program in this organization; inaccessible owned programs fail403. selected_rows is limited to100; all_total/failed_operation can span the full selection and return grouped outcomes with items empty. No commitment is changed or charged. Apply through PATCH /admin/commitments using the returned ten-minute token and identical selection/values.



# Saved commitment-listing reports for the rule editor
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/saved-commitment-listing-reports-for-the-rule-editor

get /admin/fields/options/sponsorships
Returns the `Report` rows for the caller's client that are flagged `sponsorships=1` — i.e. saved column/filter sets that scope the sponsorships listing UI. Used to populate the saved-view picker on the sponsorship-management screens. Requires permission: `manage_programs`.



# Set lifecycle reason selection policy
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/set-lifecycle-reason-selection-policy

patch /admin/lifecycle-reason-sets/{reason_set_id}
Updates the materialized context policy. Making selection required needs at least one active reason; unchanged policy retains the version. Requires the workspace lifecycle feature. Mutation permission is lifecycle_reasons_manage or manage_settings.



# Shorten a recipient funding period
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/shorten-a-recipient-funding-period

post /admin/recipient-funding/{funding_id}/end
Requires bearer or API-key authentication, current organization scope and access to every selected recipient program. Gift/funding administration also follows the donations/reports permission policy. The row must have status funded. ended_on must fall inclusively between its current start and end. Keeps history and the original recorded amount; the effective allocation can decrease to the cost through the new end. Updates activity and coverage after commit; does not refund the gift.



# Show All Sponsorships
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/show-all-sponsorships

get /admin/sponsorships/program/{program_id}
Shows all sponsorships for a given program ID,
     *          with various filtering, sorting, and pagination options.



# Summarize sponsorship lifecycle history
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/summarize-sponsorship-lifecycle-history

get /admin/sponsorships/lifecycle/summary
Uses the same accessible event selection as the history list. Recipient totals count distinct entity_id falling back to from_entity_id, donor totals count distinct donor_id; historical and current program filters match either side.



# Update a lifecycle reason
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/update-a-lifecycle-reason

patch /admin/lifecycle-reasons/{reason_id}
Changes only supplied properties and preserves the stable code and historical event snapshots. The last active reason cannot be deactivated while selection is required. Actual changes advance the set version; no-op edits retain it. Requires the workspace lifecycle feature. Mutation permission is lifecycle_reasons_manage or manage_settings.



# Withdraw a pending sponsorship request
Source: https://api-docs.helpyousponsor.com/api-reference/sponsorships/withdraw-a-pending-sponsorship-request

post /frontend/donor/dashboard/sponsorship-requests/{client_id}/{program_id}/{session_id}/{request_id}/withdraw
Only the donor’s still-pending request can be withdrawn. The request resolves as withdrawn and the pending hold clears; the sponsorship and payment schedule are preserved. Request body must contain no properties. Uses a logged-in donor session for this organization and a valid portal program/global context; the session TTL refreshes to one hour. Only that donor’s relationships or requests can be accessed.



# Change multiple workspace tasks
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/change-multiple-workspace-tasks

post /admin/tasks/bulk
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Check collaboration upload readiness
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/check-collaboration-upload-readiness

get /admin/collaboration/attachment-uploads/readiness
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Clear the last task workspace view
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/clear-the-last-task-workspace-view

delete /admin/view-state/tasks
Preferences belong to the current staff member and require task-view access. Persistence is unavailable in Support Sessions and returns 409. Last-view persistence strips transient search; an interaction UUID makes retries safe but cannot be reused for a different definition.



# Complete a workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/complete-a-workspace-task

post /admin/tasks/{task}/complete
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Create a named task view
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/create-a-named-task-view

post /admin/saved-views/tasks
Named task views are private to the current staff member and gated by tasks_saved_views. Support Sessions cannot persist views. Updates require the previously loaded lock version and return 409 with current_lock_version when another edit intervened.



# Create a record comment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/create-a-record-comment

post /admin/collaboration/{subjectType}/{subjectId}/comments
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Create a workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/create-a-workspace-task

post /admin/tasks
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Delete a collaboration attachment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/delete-a-collaboration-attachment

delete /admin/collaboration/{subjectType}/{subjectId}/attachments/{attachmentId}
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Delete a named task view
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/delete-a-named-task-view

delete /admin/saved-views/tasks/{savedView}
Named task views are private to the current staff member and gated by tasks_saved_views. Support Sessions cannot persist views. Updates require the previously loaded lock version and return 409 with current_lock_version when another edit intervened.



# Delete a record comment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/delete-a-record-comment

delete /admin/collaboration/{subjectType}/{subjectId}/comments/{commentId}
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Delete a staged task attachment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/delete-a-staged-task-attachment

delete /admin/collaboration/attachment-uploads/{attachmentId}
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Delete a workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/delete-a-workspace-task

delete /admin/tasks/{task}
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Download a scanned collaboration attachment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/download-a-scanned-collaboration-attachment

get /admin/collaboration/{subjectType}/{subjectId}/attachments/{attachmentId}/download
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Edit a record comment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/edit-a-record-comment

patch /admin/collaboration/{subjectType}/{subjectId}/comments/{commentId}
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Export workspace tasks to a calendar
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/export-workspace-tasks-to-a-calendar

get /admin/tasks/exports/calendar
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Export workspace tasks to CSV
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/export-workspace-tasks-to-csv

get /admin/tasks/exports/csv
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Find task assignees
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/find-task-assignees

get /admin/tasks/assignees
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Find teammates to mention
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/find-teammates-to-mention

get /admin/collaboration/{subjectType}/{subjectId}/mention-candidates
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Get a workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/get-a-workspace-task

get /admin/tasks/{task}
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Import named task views
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/import-named-task-views

post /admin/saved-views/tasks/import
Named task views are private to the current staff member and gated by tasks_saved_views. Support Sessions cannot persist views. Updates require the previously loaded lock version and return 409 with current_lock_version when another edit intervened.



# List workspace tasks
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/list-workspace-tasks

get /admin/tasks
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Load task workspace view state
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/load-task-workspace-view-state

get /admin/view-state/tasks
Preferences belong to the current staff member and require task-view access. Persistence is unavailable in Support Sessions and returns 409. Last-view persistence strips transient search; an interaction UUID makes retries safe but cannot be reused for a different definition.



# Pin a record comment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/pin-a-record-comment

put /admin/collaboration/{subjectType}/{subjectId}/comments/{commentId}/pin
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Read a record collaboration thread
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/read-a-record-collaboration-thread

get /admin/collaboration/{subjectType}/{subjectId}
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Reopen a workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/reopen-a-workspace-task

post /admin/tasks/{task}/reopen
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Restore a deleted workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/restore-a-deleted-workspace-task

post /admin/tasks/{task_id}/restore
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Retry scanning a collaboration attachment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/retry-scanning-a-collaboration-attachment

post /admin/collaboration/{subjectType}/{subjectId}/attachments/{attachmentId}/retry-scan
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Save the last task workspace view
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/save-the-last-task-workspace-view

put /admin/view-state/tasks
Preferences belong to the current staff member and require task-view access. Persistence is unavailable in Support Sessions and returns 409. Last-view persistence strips transient search; an interaction UUID makes retries safe but cannot be reused for a different definition.



# Search related workspace records
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/search-related-workspace-records

get /admin/tasks/records/search
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Search related workspace records
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/search-related-workspace-records-1

get /admin/tasks/related/search
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Stage an attachment for a new task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/stage-an-attachment-for-a-new-task

post /admin/collaboration/attachment-uploads
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Unpin a record comment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/unpin-a-record-comment

delete /admin/collaboration/{subjectType}/{subjectId}/comments/{commentId}/pin
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Update a named task view
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/update-a-named-task-view

put /admin/saved-views/tasks/{savedView}
Named task views are private to the current staff member and gated by tasks_saved_views. Support Sessions cannot persist views. Updates require the previously loaded lock version and return 409 with current_lock_version when another edit intervened.



# Update a workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/update-a-workspace-task

put /admin/tasks/{task}
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Update a workspace task
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/update-a-workspace-task-1

patch /admin/tasks/{task}
Tasks are scoped to the authenticated organization and accessible related records. Managing task content, deletion or reassignment requires task management access; completion may also be allowed for the assigned staff member. Expected version or updated timestamp protects changes from stale data and returns 422 on conflict. CSV and calendar exports use the same visibility and filter rules; calendar exports include only dated tasks.



# Upload a record collaboration attachment
Source: https://api-docs.helpyousponsor.com/api-reference/tasks/upload-a-record-collaboration-attachment

post /admin/collaboration/{subjectType}/{subjectId}/attachments
Collaboration is feature-gated and scoped to accessible task, donor, recipient, sponsorship or space_page records in the organization. Archived subjects are read-only409; Support Sessions cannot write. Editing comments requires authorship; pinning requires management access. Revisions and request UUIDs protect concurrent edits. Downloads require a safe scan and existing stored bytes.



# Create a new Access role
Source: https://api-docs.helpyousponsor.com/api-reference/team-&-access/create-a-new-access-role

post /admin/groups



# Delete an Access role by ID
Source: https://api-docs.helpyousponsor.com/api-reference/team-&-access/delete-an-access-role-by-id

delete /admin/groups/{group_id}



# Edit a specific Access role
Source: https://api-docs.helpyousponsor.com/api-reference/team-&-access/edit-a-specific-access-role

put /admin/groups/{group_id}



# Get an Access role by ID
Source: https://api-docs.helpyousponsor.com/api-reference/team-&-access/get-an-access-role-by-id

get /admin/groups/{group_id}



# List a donors and  programs
Source: https://api-docs.helpyousponsor.com/api-reference/team-&-access/list-a-donors-and-programs

get /admin/createGroup



# View all Access roles
Source: https://api-docs.helpyousponsor.com/api-reference/team-&-access/view-all-access-roles

get /admin/groups



# Add a participant to the trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/add-a-participant-to-the-trip

post /frontend/participant/trips/{client_id}/{trip_id}/leader/participants/{session_id}
Creates a new `TripParticipant` (and the underlying donor + entity if needed) via `TripParticipantService::addParticipant`. Optionally syncs tags. Promoting the new participant to `leader` requires the leader to additionally hold `promote_leaders`. Requires `manage_participants`. Note: guardian fields are admin-side data; never echo them back on participant-facing endpoints.



# Add a trip budget item
Source: https://api-docs.helpyousponsor.com/api-reference/trips/add-a-trip-budget-item

post /admin/trips/{tripId}/budget-items
Reads or changes budget items under the organization-owned trip. Amount changes also synchronize the fundraising goal when sync_budget_to_goal is enabled.



# Add a trip document
Source: https://api-docs.helpyousponsor.com/api-reference/trips/add-a-trip-document

post /admin/trips/{tripId}/documents
Manages documents under the organization-owned trip. New uploads can use an existing upload_id or a stored upload_key and file_name pair; specific visibility is restricted to selected trip participants. Download records access and returns the resolved storage URL.



# Add a trip participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/add-a-trip-participant

post /admin/trips/{tripId}/participants
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# Apply a task template to a trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/apply-a-task-template-to-a-trip

post /admin/trips/{tripId}/apply-template/{templateId}
Task templates belong to the authenticated organization. Applying a template requires a trip start date, offsets due dates from that date, creates tasks in template order and resolves dependencies from earlier template indexes.



# Apply a task template to the trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/apply-a-task-template-to-the-trip

post /frontend/participant/trips/{client_id}/{trip_id}/leader/apply-template/{template_id}/{session_id}
Instantiates the task template's tasks against this trip — `due_date_offset` resolves to a concrete date relative to `trip.start_date`, and `depends_on_index` resolves to the actual `trip_task_id` of the task created earlier in the loop. Requires `manage_task_templates`. Refuses with 422 if the trip has no `start_date`.



# Approve a task completion
Source: https://api-docs.helpyousponsor.com/api-reference/trips/approve-a-task-completion

post /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/completions/{completion_id}/approve/{session_id}
Marks a `TripTaskCompletion` as `approved` and stamps `approved_at`. Refuses with 400 if it is already approved. Optionally records `admin_notes`. Requires `approve_task_completions`.



# Approve a trip task submission
Source: https://api-docs.helpyousponsor.com/api-reference/trips/approve-a-trip-task-submission

post /admin/trips/{tripId}/tasks/completions/{completionId}/approve
Updates the completion status and administrator notes and invalidates trip analytics. Already approved submissions return 400 when approved again.



# Archive a trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/archive-a-trip

post /admin/trips/{id}/archive
Sets the organization-owned trip status to archived.



# Audited download for a trip document
Source: https://api-docs.helpyousponsor.com/api-reference/trips/audited-download-for-a-trip-document

get /frontend/participant/trips/{client_id}/{trip_id}/documents/{document_id}/download/{session_id}
Returns the S3 object URL for the requested trip document and writes a `trip_documents/download` ActivityLog entry. Honors the same per-participant visibility check as the list endpoint — documents the participant cannot see return 404 to avoid leaking existence.



# Clone a trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/clone-a-trip

post /admin/trips/{id}/clone
Creates a draft copy of a nonsample trip with a unique name. Optional switches control copying budgets, tasks, documents and settings, and whether copied task dates shift with the new start date. Trip creation entitlement applies.



# Create a budget line item
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-budget-line-item

post /frontend/participant/trips/{client_id}/{trip_id}/leader/budget-items/{session_id}
Adds a `TripBudgetItem`. If the trip's `sync_budget_to_goal` setting is on, the trip's `fundraising_goal` is updated to match the new budget total. Requires `manage_budget`.



# Create a fundraising milestone
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-fundraising-milestone

post /frontend/participant/trips/{client_id}/{trip_id}/leader/milestones/{session_id}
Creates a `TripFundraisingMilestone`. At least one of `target_amount` or `target_percent` is required (returns 422 otherwise). Requires `manage_trip`.



# Create a sample trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-sample-trip

post /admin/trips/sample
Creates a seeded demonstration trip with supporting records. This is available only when sample trip creation is enabled; sample trips do not count toward the creation allowance.



# Create a task template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-task-template

post /frontend/participant/trips/{client_id}/{trip_id}/leader/task-templates/{session_id}
Saves a reusable client-level `TripTaskTemplate`. The `tasks` array stores task definitions in template form (no trip_id, no concrete due_date — they use `due_date_offset` and `depends_on_index` instead). Requires `manage_task_templates`.



# Create a trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-trip

post /admin/trips
Creates or edits a trip within the authenticated organization. Name and slug must be unique within the organization; end_date must not precede start_date. Creating a trip also creates its fund entity and required program/form bindings; updating settings may update the shared Trip Participants program.



# Create a trip fundraising milestone
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-trip-fundraising-milestone

post /admin/trips/{tripId}/milestones
Milestones compare trip fundraising progress with an amount or a percentage of the trip goal. At least one target must be nonzero after saving; update validates that condition after persisting the submitted values.



# Create a trip task
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-trip-task

post /admin/trips/{tripId}/tasks
Manages tasks within the organization-owned trip. New tasks inherit reminder defaults when neither reminder input is supplied. Updating a task replaces dependency selections and normalized target tags; omitted dependencies or target tags are cleared. A task with dependents cannot be deleted.



# Create a trip task
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-trip-task-1

post /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/{session_id}
Creates a `TripTask`. If neither `reminders` nor `reminder_days_before` is sent, a default reminder schedule is generated from the trip's `task_reminder_days` setting. Targeting is controlled via `target_role`, `target_minors_only`, `target_guardians_only`, and tag include/exclude lists. Requires `manage_tasks`.



# Create a trip task template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-a-trip-task-template

post /admin/trip-task-templates
Task templates belong to the authenticated organization. Applying a template requires a trip start date, offsets due dates from that date, creates tasks in template order and resolves dependencies from earlier template indexes.



# Create an embedded signature template draft
Source: https://api-docs.helpyousponsor.com/api-reference/trips/create-an-embedded-signature-template-draft

post /admin/trips/{tripId}/esignatures/templates/embedded-draft
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# Delete a budget line item
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-budget-line-item

delete /frontend/participant/trips/{client_id}/{trip_id}/leader/budget-items/{item_id}/{session_id}
Permanently deletes a budget item. Re-syncs `fundraising_goal` if `sync_budget_to_goal` is on. Requires `manage_budget`.



# Delete a fundraising milestone
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-fundraising-milestone

delete /frontend/participant/trips/{client_id}/{trip_id}/leader/milestones/{id}/{session_id}
Permanently deletes a milestone. Requires `manage_trip`.



# Delete a signature template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-signature-template

delete /admin/trips/{tripId}/esignatures/templates/{templateId}
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# Delete a task template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-task-template

delete /frontend/participant/trips/{client_id}/{trip_id}/leader/task-templates/{template_id}/{session_id}
Permanently deletes a task template. Existing trip tasks created from the template are unaffected. Requires `manage_task_templates`.



# Delete a trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-trip

delete /admin/trips/{id}
Soft-deletes the organization-owned trip.



# Delete a trip budget item
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-trip-budget-item

delete /admin/trips/{tripId}/budget-items/{id}
Reads or changes budget items under the organization-owned trip. Amount changes also synchronize the fundraising goal when sync_budget_to_goal is enabled.



# Delete a trip document
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-trip-document

delete /admin/trips/{tripId}/documents/{id}
Manages documents under the organization-owned trip. New uploads can use an existing upload_id or a stored upload_key and file_name pair; specific visibility is restricted to selected trip participants. Download records access and returns the resolved storage URL.



# Delete a trip fundraising milestone
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-trip-fundraising-milestone

delete /admin/trips/{tripId}/milestones/{id}
Milestones compare trip fundraising progress with an amount or a percentage of the trip goal. At least one target must be nonzero after saving; update validates that condition after persisting the submitted values.



# Delete a trip task
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-trip-task

delete /admin/trips/{tripId}/tasks/{taskId}
Manages tasks within the organization-owned trip. New tasks inherit reminder defaults when neither reminder input is supplied. Updating a task replaces dependency selections and normalized target tags; omitted dependencies or target tags are cleared. A task with dependents cannot be deleted.



# Delete a trip task
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-trip-task-1

delete /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/{task_id}/{session_id}
Deletes a task. Refuses with 422 (`Cannot delete task. Other tasks depend on it.`) if any other task depends on it via `depends_on_task_id` or `depends_on_task_ids`. Requires `manage_tasks`.



# Delete a trip task template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/delete-a-trip-task-template

delete /admin/trip-task-templates/{id}
Task templates belong to the authenticated organization. Applying a template requires a trip start date, offsets due dates from that date, creates tasks in template order and resolves dependencies from earlier template indexes.



# Donations targeted at this participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/donations-targeted-at-this-participant

get /frontend/participant/trips/{client_id}/{trip_id}/donations/{session_id}
Returns donations directed at the participant's `entity_id` (using the historical `donation.designation` column). Donor names are normalized for privacy per the trip's `show_donor_names` setting (`full` / `first_initial` / `anonymous`); amounts are nulled when `show_donation_amounts` is false.



# Export trip donations
Source: https://api-docs.helpyousponsor.com/api-reference/trips/export-trip-donations

get /admin/trips/{tripId}/analytics/exports/donations
Returns organization-scoped trip analytics or a CSV download. Analytics refresh queues a background job but returns200; CSV donations include active-participant designations and the trip fund, participant export includes all participant statuses, and task export covers active participants.



# Export trip participants
Source: https://api-docs.helpyousponsor.com/api-reference/trips/export-trip-participants

get /admin/trips/{tripId}/analytics/exports/participants
Returns organization-scoped trip analytics or a CSV download. Analytics refresh queues a background job but returns200; CSV donations include active-participant designations and the trip fund, participant export includes all participant statuses, and task export covers active participants.



# Export trip task progress
Source: https://api-docs.helpyousponsor.com/api-reference/trips/export-trip-task-progress

get /admin/trips/{tripId}/analytics/exports/tasks
Returns organization-scoped trip analytics or a CSV download. Analytics refresh queues a background job but returns200; CSV donations include active-participant designations and the trip fund, participant export includes all participant statuses, and task export covers active participants.



# Get a signed trip document URL
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-a-signed-trip-document-url

get /admin/trips/{tripId}/esignatures/{requestId}/signed-document
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# Get a trip budget item
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-a-trip-budget-item

get /admin/trips/{tripId}/budget-items/{id}
Reads or changes budget items under the organization-owned trip. Amount changes also synchronize the fundraising goal when sync_budget_to_goal is enabled.



# Get a trip communication
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-a-trip-communication

get /admin/trips/{tripId}/messages/{id}
Requires access to trip messages under the authenticated organization and excludes sample trips. Saving a draft does not send it; phone and note channels create manual logs. Sending resolves active matching participants with email addresses and queues email or SMS delivery; SMS also requires at least one valid phone.



# Get a trip document download URL
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-a-trip-document-download-url

get /admin/trips/{tripId}/documents/{id}/download
Manages documents under the organization-owned trip. New uploads can use an existing upload_id or a stored upload_key and file_name pair; specific visibility is restricted to selected trip participants. Download records access and returns the resolved storage URL.



# Get a trip participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-a-trip-participant

get /admin/trips/{tripId}/participants/{id}
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# Get a trip task template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-a-trip-task-template

get /admin/trip-task-templates/{id}
Task templates belong to the authenticated organization. Applying a template requires a trip start date, offsets due dates from that date, creates tasks in template order and resolves dependencies from earlier template indexes.



# Get a trip with setup details
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-a-trip-with-setup-details

get /admin/trips/{id}
Returns the trip profile, program bindings, cover image, budget items, tasks and fundraising totals in the authenticated organization.



# Get an embedded signature template edit URL
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-an-embedded-signature-template-edit-url

get /admin/trips/{tripId}/esignatures/templates/{templateId}/embedded-edit-url
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# Get the public trip URL
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-the-public-trip-url

get /admin/trips/{id}/public-url
Returns the shareable frontend route for an organization-owned trip. Sample trips are not publicly available.



# Get trip analytics
Source: https://api-docs.helpyousponsor.com/api-reference/trips/get-trip-analytics

get /admin/trips/{tripId}/analytics
Returns organization-scoped trip analytics or a CSV download. Analytics refresh queues a background job but returns200; CSV donations include active-participant designations and the trip fund, participant export includes all participant statuses, and task export covers active participants.



# Import trip participants
Source: https://api-docs.helpyousponsor.com/api-reference/trips/import-trip-participants

post /admin/trips/{tripId}/participants/import
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# Initiate a trip participant background check
Source: https://api-docs.helpyousponsor.com/api-reference/trips/initiate-a-trip-participant-background-check

post /admin/trips/{tripId}/participants/{id}/background-checks
Initiates a Checkr invitation for a nonsample trip participant. If another valid check can be reused, the201 response first requests confirmation unless reuse_existing or force_new is provided. Reuse links a new local check record to the prior provider report.



# Invite active trip participants
Source: https://api-docs.helpyousponsor.com/api-reference/trips/invite-active-trip-participants

post /admin/trips/{tripId}/participants/invite
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# List available signature templates
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-available-signature-templates

get /admin/trips/{tripId}/esignatures/templates
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# List fundraising milestones
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-fundraising-milestones

get /frontend/participant/trips/{client_id}/{trip_id}/leader/milestones/{session_id}
Returns the trip's `TripFundraisingMilestone` rows with each milestone's resolved target amount, current `total_raised`, `progress_percent`, and a derived `status` (`reached` / `behind` if past due / `on_track`). Requires `manage_trip`.



# List organization trips
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-organization-trips

get /admin/trips
Lists trips with active-participant counts, fundraising progress, creation entitlement and sample-trip capability. Search matches name or destination; pagination is clamped to 1-100 rows.



# List participant progress for a trip task
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-participant-progress-for-a-trip-task

get /admin/trips/{tripId}/tasks/{taskId}/participants
Returns one row for each active participant and its submission state; incomplete means not_started or submitted.



# List replies to a trip message
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-replies-to-a-trip-message

get /admin/trips/{tripId}/messages/{id}/replies
Requires access to trip messages under the authenticated organization and excludes sample trips. Saving a draft does not send it; phone and note channels create manual logs. Sending resolves active matching participants with email addresses and queues email or SMS delivery; SMS also requires at least one valid phone.



# List task templates for the client
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-task-templates-for-the-client

get /frontend/participant/trips/{client_id}/{trip_id}/leader/task-templates/{session_id}
Returns reusable `TripTaskTemplate` rows for the client (not the trip — templates live at the client level). Each template stores a JSON array of task definitions that `applyTemplate` can instantiate against any trip. Requires `manage_task_templates`.



# List trip budget items
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-budget-items

get /admin/trips/{tripId}/budget-items
Reads or changes budget items under the organization-owned trip. Amount changes also synchronize the fundraising goal when sync_budget_to_goal is enabled.



# List trip budget items
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-budget-items-1

get /frontend/participant/trips/{client_id}/{trip_id}/leader/budget-items/{session_id}
Returns budget line items in `sort_order` plus the total. Requires `manage_budget` permission.



# List trip communications
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-communications

get /admin/trips/{tripId}/messages
Requires access to trip messages under the authenticated organization and excludes sample trips. Saving a draft does not send it; phone and note channels create manual logs. Sending resolves active matching participants with email addresses and queues email or SMS delivery; SMS also requires at least one valid phone.



# List trip documents
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-documents

get /admin/trips/{tripId}/documents
Manages documents under the organization-owned trip. New uploads can use an existing upload_id or a stored upload_key and file_name pair; specific visibility is restricted to selected trip participants. Download records access and returns the resolved storage URL.



# List trip documents the participant can see
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-documents-the-participant-can-see

get /frontend/participant/trips/{client_id}/{trip_id}/documents/{session_id}
Returns trip documents whose visibility includes the authenticated participant — `all_participants` always, `leaders_only` only when the participant has `role=leader`, and `specific` only when the participant id appears in `visible_to_participants`. Each entry carries a downloadable URL and a download endpoint that logs the access.



# List trip fundraising milestones
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-fundraising-milestones

get /admin/trips/{tripId}/milestones
Milestones compare trip fundraising progress with an amount or a percentage of the trip goal. At least one target must be nonzero after saving; update validates that condition after persisting the submitted values.



# List trip participants
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-participants

get /admin/trips/{tripId}/participants
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# List trip signature requests
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-signature-requests

get /admin/trips/{tripId}/esignatures
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# List trip task submissions
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-task-submissions

get /admin/trips/{tripId}/tasks/completions
Returns paginated task submissions for the organization-owned trip with participant, approver and attachment information.



# List trip task templates
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-task-templates

get /admin/trip-task-templates
Task templates belong to the authenticated organization. Applying a template requires a trip start date, offsets due dates from that date, creates tasks in template order and resolves dependencies from earlier template indexes.



# List trip tasks
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-tasks

get /admin/trips/{tripId}/tasks
Manages tasks within the organization-owned trip. New tasks inherit reminder defaults when neither reminder input is supplied. Updating a task replaces dependency selections and normalized target tags; omitted dependencies or target tags are cleared. A task with dependents cannot be deleted.



# List trip tasks assigned to the participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-tasks-assigned-to-the-participant

get /frontend/participant/trips/{client_id}/{trip_id}/tasks/{session_id}
Returns the tasks visible to this participant — the per-trip task list filtered by `TripTask::appliesToParticipant()` (which honors role / minor / guardian / tag targeting). Each entry includes prerequisite/dependency state and the participant's own completion if any.



# List trip tasks for the leader
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trip-tasks-for-the-leader

get /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/{session_id}
Returns all `TripTask` rows for the trip ordered by `sort_order`, each with completion stats (`completion_count` of approved completions, `total_participants`, `completion_percent`), reminder schedule, dependency metadata, and target tag include/exclude lists. Requires `manage_tasks`.



# List trips the donor is an active participant in
Source: https://api-docs.helpyousponsor.com/api-reference/trips/list-trips-the-donor-is-an-active-participant-in

get /frontend/participant/trips/{client_id}/{session_id}
Donor-portal endpoint that returns the trips the authenticated donor is an active `TripParticipant` of. Authentication is via the `{session_id}` URL path parameter, which references a Redis donor session (key contains `donor_id` + `logged_in=true`). Each entry returns a slim trip + per-participant progress snapshot suitable for a dashboard.



# Mark a participant task as complete
Source: https://api-docs.helpyousponsor.com/api-reference/trips/mark-a-participant-task-as-complete

post /frontend/participant/trips/{client_id}/{trip_id}/tasks/{task_id}/complete/{session_id}
Records a `TripTaskCompletion` for the authenticated participant. If the task `requires_approval`, the row is saved with `status=completed` (pending leader review); otherwise it auto-promotes to `status=approved`. Tasks gated by an unsatisfied dependency return 422; already-approved tasks return 400. Trip stat caches are invalidated on save.



# Paginated task completions for the trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/paginated-task-completions-for-the-trip

get /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/completions/{session_id}
Returns `TripTaskCompletion` rows for the trip with task + participant + upload eager-loaded. Supports `?status`, `?task_id`, `?participant_id`, and `?per_page` filters. Requires `view_task_completions`.



# Participant roster with fundraising progress
Source: https://api-docs.helpyousponsor.com/api-reference/trips/participant-roster-with-fundraising-progress

get /frontend/participant/trips/{client_id}/{trip_id}/leader/participants/{session_id}
Returns active trip participants with fundraising progress, role, minor flag, and tags. Requires `manage_participants` permission. Names come from the standardized donor display name resolver.



# Per-task participant completion status
Source: https://api-docs.helpyousponsor.com/api-reference/trips/per-task-participant-completion-status

get /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/{task_id}/participants/{session_id}
For a specific task, lists every active participant with their `task_status` (`not_started`/`submitted`/`approved`/`rejected`) and any submitted upload. Supports an optional `?status=` filter (`incomplete` collapses `not_started` + `submitted`). Requires `view_task_completions` permission.



# Public URL for the trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/public-url-for-the-trip

get /frontend/participant/trips/{client_id}/{trip_id}/leader/public-url/{session_id}
Returns the leader-facing public URL for this trip (`FRONTEND_URL + /trips/{client_id}/{trip.slug}`) plus the relative path. Requires `manage_trip` permission.



# Queue a trip message
Source: https://api-docs.helpyousponsor.com/api-reference/trips/queue-a-trip-message

post /admin/trips/{tripId}/messages/send
Requires access to trip messages under the authenticated organization and excludes sample trips. Saving a draft does not send it; phone and note channels create manual logs. Sending resolves active matching participants with email addresses and queues email or SMS delivery; SMS also requires at least one valid phone.



# Queue trip analytics refresh
Source: https://api-docs.helpyousponsor.com/api-reference/trips/queue-trip-analytics-refresh

post /admin/trips/{tripId}/analytics/reload
Returns organization-scoped trip analytics or a CSV download. Analytics refresh queues a background job but returns200; CSV donations include active-participant designations and the trip fund, participant export includes all participant statuses, and task export covers active participants.



# Read organization trip defaults
Source: https://api-docs.helpyousponsor.com/api-reference/trips/read-organization-trip-defaults

get /admin/trip-settings
Organization-scoped trip defaults used when creating and displaying trips. A fixed_amount goal mode requires a goal amount; other modes clear that amount. Background-check validity is controlled by the Checkr integration.



# Reject a task completion
Source: https://api-docs.helpyousponsor.com/api-reference/trips/reject-a-task-completion

post /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/completions/{completion_id}/reject/{session_id}
Marks a `TripTaskCompletion` as `rejected` and stores the reviewer's `admin_notes` (required). Requires `approve_task_completions`.



# Reject a trip task submission
Source: https://api-docs.helpyousponsor.com/api-reference/trips/reject-a-trip-task-submission

post /admin/trips/{tripId}/tasks/completions/{completionId}/reject
Updates the completion status and administrator notes and invalidates trip analytics. Already approved submissions return 400 when approved again.



# Reorder budget items
Source: https://api-docs.helpyousponsor.com/api-reference/trips/reorder-budget-items

post /frontend/participant/trips/{client_id}/{trip_id}/leader/budget-items/reorder/{session_id}
Bulk-updates `sort_order` on multiple budget items inside a transaction. Returns the full ordered list. Requires `manage_budget`.



# Reorder trip budget items
Source: https://api-docs.helpyousponsor.com/api-reference/trips/reorder-trip-budget-items

post /admin/trips/{tripId}/budget-items/reorder
Reads or changes budget items under the organization-owned trip. Amount changes also synchronize the fundraising goal when sync_budget_to_goal is enabled.



# Resend a trip signature request
Source: https://api-docs.helpyousponsor.com/api-reference/trips/resend-a-trip-signature-request

post /admin/trips/{tripId}/esignatures/{requestId}/resend
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# Restore a trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/restore-a-trip

post /admin/trips/{id}/restore
Restores a soft-deleted trip. If its status was archived, restores it to draft.



# Save a trip communication draft or log
Source: https://api-docs.helpyousponsor.com/api-reference/trips/save-a-trip-communication-draft-or-log

post /admin/trips/{tripId}/messages
Requires access to trip messages under the authenticated organization and excludes sample trips. Saving a draft does not send it; phone and note channels create manual logs. Sending resolves active matching participants with email addresses and queues email or SMS delivery; SMS also requires at least one valid phone.



# Search client donors as a leader
Source: https://api-docs.helpyousponsor.com/api-reference/trips/search-client-donors-as-a-leader

get /frontend/participant/trips/{client_id}/leader/donors/search/{session_id}
Type-ahead lookup over the client's donors (matches email, username, or any custom JSON field). Returns up to 20 results. Requires the requesting donor to be an active leader on at least one trip for the client and to hold the `invite_participants` permission. Empty / single-character queries return an empty list.



# Search donors for trip participation
Source: https://api-docs.helpyousponsor.com/api-reference/trips/search-donors-for-trip-participation

get /admin/donors/search
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# Send a participant signature request
Source: https://api-docs.helpyousponsor.com/api-reference/trips/send-a-participant-signature-request

post /admin/trips/{tripId}/participants/{id}/esignatures
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# Send invitations to participants
Source: https://api-docs.helpyousponsor.com/api-reference/trips/send-invitations-to-participants

post /frontend/participant/trips/{client_id}/{trip_id}/leader/participants/invite/{session_id}
Sends invitation emails to participants — either every active participant on the trip, or only the subset listed in `participant_ids`. Optionally sets an `invite_expires_at` deadline. Individual send failures are silently ignored; the response reports `sent` vs `total`. Requires `invite_participants`.



# Send manual task reminder
Source: https://api-docs.helpyousponsor.com/api-reference/trips/send-manual-task-reminder

post /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/{task_id}/remind/{session_id}
Dispatches the `SendTripTaskRemindersJob` background job which emails every incomplete participant for this task. Returns 200 immediately — actual delivery is async. Requires `send_manual_reminders` permission.



# Send trip signature requests in a batch
Source: https://api-docs.helpyousponsor.com/api-reference/trips/send-trip-signature-requests-in-a-batch

post /admin/trips/{tripId}/esignatures/batch-send
Uses Dropbox Sign for the organization-owned trip; provider actions exclude sample trips. Minor signers may require guardian contact details. Setup failures return 409 and temporary provider failures return 503. Creating a template draft adds it to this trip; deleting a template removes it from required templates across organization trips.



# Trip detail + participant progress
Source: https://api-docs.helpyousponsor.com/api-reference/trips/trip-detail-+-participant-progress

get /frontend/participant/trips/{client_id}/{trip_id}/{session_id}
Returns trip metadata along with the donor's participant record (progress, bio, social links, leader permissions if applicable, and a precomputed public share URL). Resolves trip-level display preferences (`show_donation_amounts`, `show_donor_names`) from `Trip::getSetting()`.



# Trip Leader Console — trip view + effective permissions
Source: https://api-docs.helpyousponsor.com/api-reference/trips/trip-leader-console-—-trip-view-+-effective-permissions

get /frontend/participant/trips/{client_id}/{trip_id}/leader/{session_id}
Authenticates the donor's Redis session and verifies they are an active participant with `role=leader` on this trip. Returns a slim trip summary, the effective `leader_permissions` map (computed from the trip's `settings.leader_permissions` defaults merged with per-participant overrides), and a lean task list. The frontend uses this payload to gate Leader Console features.



# Update a budget line item
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-budget-line-item

put /frontend/participant/trips/{client_id}/{trip_id}/leader/budget-items/{item_id}/{session_id}
Updates a `TripBudgetItem`. Re-syncs the trip's `fundraising_goal` if `sync_budget_to_goal` is on. Requires `manage_budget`.



# Update a fundraising milestone
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-fundraising-milestone

put /frontend/participant/trips/{client_id}/{trip_id}/leader/milestones/{id}/{session_id}
Updates a milestone. Returns 422 if both `target_amount` and `target_percent` end up empty after the update. Requires `manage_trip`.



# Update a task template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-task-template

put /frontend/participant/trips/{client_id}/{trip_id}/leader/task-templates/{template_id}/{session_id}
Updates a client-scoped task template (only `name` and `tasks` are persisted). Requires `manage_task_templates`.



# Update a trip
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip

put /admin/trips/{id}
Creates or edits a trip within the authenticated organization. Name and slug must be unique within the organization; end_date must not precede start_date. Creating a trip also creates its fund entity and required program/form bindings; updating settings may update the shared Trip Participants program.



# Update a trip budget item
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip-budget-item

put /admin/trips/{tripId}/budget-items/{id}
Reads or changes budget items under the organization-owned trip. Amount changes also synchronize the fundraising goal when sync_budget_to_goal is enabled.



# Update a trip document
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip-document

put /admin/trips/{tripId}/documents/{id}
Manages documents under the organization-owned trip. New uploads can use an existing upload_id or a stored upload_key and file_name pair; specific visibility is restricted to selected trip participants. Download records access and returns the resolved storage URL.



# Update a trip fundraising milestone
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip-fundraising-milestone

put /admin/trips/{tripId}/milestones/{id}
Milestones compare trip fundraising progress with an amount or a percentage of the trip goal. At least one target must be nonzero after saving; update validates that condition after persisting the submitted values.



# Update a trip participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip-participant

put /admin/trips/{tripId}/participants/{id}
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# Update a trip task
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip-task

put /admin/trips/{tripId}/tasks/{taskId}
Manages tasks within the organization-owned trip. New tasks inherit reminder defaults when neither reminder input is supplied. Updating a task replaces dependency selections and normalized target tags; omitted dependencies or target tags are cleared. A task with dependents cannot be deleted.



# Update a trip task
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip-task-1

put /frontend/participant/trips/{client_id}/{trip_id}/leader/tasks/{task_id}/{session_id}
Updates an existing `TripTask`. Same field set as `tasksStore`; the `depends_on_task_id` validation also rejects self-dependency. Returns 422 with `Circular dependency detected` if the resolved dependency list contains the task itself. Requires `manage_tasks`.



# Update a trip task template
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-a-trip-task-template

put /admin/trip-task-templates/{id}
Task templates belong to the authenticated organization. Applying a template requires a trip start date, offsets due dates from that date, creates tasks in template order and resolves dependencies from earlier template indexes.



# Update an existing participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-an-existing-participant

put /frontend/participant/trips/{client_id}/{trip_id}/leader/participants/{trip_participant_id}/{session_id}
Updates participant fields (goal, role, status, visibility, bio, social links, minor flag, guardian info, tags). Promoting to `leader` requires the leader to also hold `promote_leaders`. Requires `manage_participants`. Trip public-page cache is invalidated on save.



# Update organization trip defaults
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-organization-trip-defaults

put /admin/trip-settings
Organization-scoped trip defaults used when creating and displaying trips. A fixed_amount goal mode requires a goal amount; other modes clear that amount. Background-check validity is controlled by the Checkr integration.



# Update the participant's public profile
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-the-participants-public-profile

put /frontend/participant/trips/{client_id}/{trip_id}/profile/{session_id}
Updates the donor-facing fields on the `TripParticipant` record (bio, video, social links, public visibility). Photo uploads go through the existing donor upload endpoint, not this one. The `is_public` flag is forced to true when the trip's `allow_participant_visibility_opt_out` setting is false. Cache invalidation runs after save so public participant pages reflect the change immediately.



# Update trip details as leader
Source: https://api-docs.helpyousponsor.com/api-reference/trips/update-trip-details-as-leader

put /frontend/participant/trips/{client_id}/{trip_id}/leader/{session_id}
Updates trip metadata (name, slug, description, dates, goal, status, cover image, settings) when the leader has the `manage_trip` permission. The slug is unique per client; the new name must also be unique per client. Validation rules are enforced verbatim — see request body.



# Withdraw a participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/withdraw-a-participant

delete /frontend/participant/trips/{client_id}/{trip_id}/leader/participants/{trip_participant_id}/{session_id}
Soft-removes the participant by setting `status=withdrawn` (no row deletion). Requires `manage_participants`. Trip public-page cache is invalidated on save.



# Withdraw a trip participant
Source: https://api-docs.helpyousponsor.com/api-reference/trips/withdraw-a-trip-participant

delete /admin/trips/{tripId}/participants/{id}
Uses the authenticated organization and the selected trip to resolve participants. Withdrawal changes status instead of deleting the record. Invitation sends are best effort and exclude sample trips; donor search respects donor-form access.



# User Signup Step One
Source: https://api-docs.helpyousponsor.com/api-reference/user/user-signup-step-one

post /admin/signup/step_one
Handles the first step of user signup, including data validation and user creation.



# User Signup Step Three
Source: https://api-docs.helpyousponsor.com/api-reference/user/user-signup-step-three

post /admin/signup/step_three
Handles the third step of the staged signup flow using a Stripe-hosted payment-method reference. Raw card fields are not accepted.



# User Signup Step Two
Source: https://api-docs.helpyousponsor.com/api-reference/user/user-signup-step-two

post /admin/signup/step_two
Handles the second step of user signup,
     *          including organization creation, user updates, and sending notifications.



# List team profile roles
Source: https://api-docs.helpyousponsor.com/api-reference/users/list-team-profile-roles

get /admin/team-roles
Returns the configured flat, multi-select team-role catalog. These profile labels do not grant permissions and do not define an owner role. Returns404 when team profiles or their required schema are unavailable. Requires permission: one of admins.



# Snooze my team profile reminder
Source: https://api-docs.helpyousponsor.com/api-reference/users/snooze-my-team-profile-reminder

post /admin/team-member-profile/snooze
Snoozes the authenticated member’s profile reminder for the configured period (default30days), sets the current prompt version and returns completion state. Team profiles must be enabled. Support sessions cannot edit profiles. Requires permission: team_member_profile.



# Update my team profile
Source: https://api-docs.helpyousponsor.com/api-reference/users/update-my-team-profile

put /admin/team-member-profile
Updates the authenticated membership’s phone and job title. A nonempty phone must normalize successfully; changing the normalized number clears phone verification. country_code is required when phone is supplied. Does not assign team roles or permissions. Team profiles must be enabled and support sessions cannot edit them. Requires permission: team_member_profile.



# Authorize.Net ARB silent-post receiver
Source: https://api-docs.helpyousponsor.com/api-reference/webhooks/authorizenet-arb-silent-post-receiver

post /silent_post
Inbound ARB (Automated Recurring Billing) silent-post callback from Authorize.Net. Looks up the matching `Commitment` by `arb_subscription_id` (method `5`) and writes a corresponding `Donation` row with the reported amount + Authorize.Net customer/transaction IDs. Quietly returns when no commitment matches (logs a warning). Validation: `x_amount`, `x_subscription_id`, `x_cust_id`, `x_trans_id` all required. Currently mounted inside the auth.api_or_key middleware group — Authorize.Net must be configured to send credentials.



# Mailgun inbound email webhook
Source: https://api-docs.helpyousponsor.com/api-reference/webhooks/mailgun-inbound-email-webhook

post /activities/email-ingest
Receives BCC'd / inbound emails from Mailgun (form-encoded multipart payload — see Mailgun's Routes/Webhooks docs for the full schema). Authenticates via the `?key=` query parameter against `MAILGUN_ROUTE_KEY`. Creates an `Activity` row, uploads any attachments to S3, detects trip-message replies, auto-associates the email with a donor by sender address when possible, and indexes the activity in Meilisearch. Documented as a webhook for reference; integrators do not call this directly.



# Authenticate a direct workspace invitation
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/authenticate-a-direct-workspace-invitation

post /workspace-onboarding/invite/exchange
Exchanges a direct signed invitation for a resumable setup session. Recovery invitations require the email-code flow and return409. A verified mailbox with an existing account receives the existing_account sign-in route with HTTP200. A newly issued session token replaces the previous resume credential.



# Confirm the new workspace organization
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/confirm-the-new-workspace-organization

put /workspace-onboarding/{public_id}/organization
Saves organization and owner details while the session is authenticated or organization_confirmed. Later states reject edits with409. Country is normalized to uppercase; website and US EIN receive additional validation.



# Confirm workspace setup choices
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/confirm-workspace-setup-choices

put /workspace-onboarding/{public_id}/intent
Confirms exactly primary_goal and starting_point from the displayed registered questions, pins the setup definition and resolves the starter profile. Must follow organization confirmation. Repeating identical answers is allowed; changing a confirmed answer returns409. Unsupported choices or extra answer keys currently surface as503; use the choices returned by the session.



# Create the verified workspace and sign in
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/create-the-verified-workspace-and-sign-in

post /workspace-onboarding/{public_id}/finalize
Requires confirmed setup choices and successful payment-method qualification. Atomically creates the organization, owner, pricing assignment and pinned setup profile, with starter recipes and welcome delivery queued. Claims a single authenticated handoff and burns the resume credential before issuing the ordinary admin session. HTTP409 handoff_requires_sign_in means the workspace is ready and the owner should sign in normally. Existing mailbox accounts receive HTTP200 sign-in routing.



# Get a resumable workspace setup session
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/get-a-resumable-workspace-setup-session

get /workspace-onboarding/{public_id}
Returns the authenticated setup state and display-safe questions. Before intent confirmation, primary_goal selects the starting-point question branch. The default session lifetime is24 hours, configurable by the server. Use the session header, rather than an administrator bearer token.



# Get workspace signup entry options
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/get-workspace-signup-entry-options

get /workspace-onboarding/entry
Returns the admission mode for the trusted request host. Brand comes from configured Gratona or Gratona Sponsorships hosts, never browser JSON. Disabled self-service returns guided admission; a host outside the configured allowlist returns404.



# Look up a nonprofit during workspace setup
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/look-up-a-nonprofit-during-workspace-setup

post /workspace-onboarding/{public_id}/organization-lookup
Searches the configured nonprofit directory while the session is authenticated or organization_confirmed. Returns up to eight normalized matches; a disabled or failed provider returns HTTP200 unavailable with an empty results array. Search collapses whitespace and must remain2–100 characters after normalization.



# Prepare workspace card verification
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/prepare-workspace-card-verification

post /workspace-onboarding/{public_id}/payment-intent
Creates or resumes a Stripe customer and card SetupIntent after intent confirmation. This verifies a payment method without charging it or enabling automatic billing. The browser confirms the returned client secret with Stripe and can exchange the payment-return token to resume. An existing mailbox account receives HTTP200 sign-in routing.



# Preview a workspace invitation
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/preview-a-workspace-invitation

get /workspace-onboarding/invite
Returns the organization label, masked mailbox and required authentication mode without authenticating the visitor. Invitation must be signed, unexpired, unclaimed and unrevoked; admission must be enabled.



# Preview organization website suggestions
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/preview-organization-website-suggestions

post /workspace-onboarding/{public_id}/organization-enrichment
Returns optional website-derived brand name, up to five uppercase hex colors and whether a logo was found. Available only before intent confirmation. Suggestions do not update the confirmed organization. A disabled or failed provider returns HTTP200 with status unavailable; successful results are cached per session and website.



# Resume workspace setup after payment verification
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/resume-workspace-setup-after-payment-verification

post /workspace-onboarding/payment-return/exchange
Consumes the short-lived return token issued with a setup intent and rotates the session resume credential atomically. It is bound to the public session, current setup intent and current resume credential, so it cannot be replayed after rotation. Token lifetime is at most15 minutes and never exceeds session expiry.



# Send a public workspace signup code
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/send-a-public-workspace-signup-code

post /workspace-onboarding/self-serve/request-code
Starts or resumes the email-code signup flow for the trusted request host. Admission must be enabled. Returns a generic acknowledgement and masked mailbox without disclosing whether an account exists. Resending replaces the old code; defaults are15 minutes and5 attempts.



# Send a workspace invitation verification code
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/send-a-workspace-invitation-verification-code

post /workspace-onboarding/invite/request-code
Sends a code to the invitation mailbox and returns the pending public session ID and a masked mailbox. A new request supersedes the previous code. Code lifetime and attempt limits are server configured, defaulting to15 minutes and5 attempts.



# Verify a public workspace signup code
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/verify-a-public-workspace-signup-code

post /workspace-onboarding/self-serve/verify-code
Consumes the code for the normalized email and pending public session ID. Issues a resume credential, or returns HTTP200 existing_account sign-in routing after mailbox ownership is verified.



# Verify a workspace invitation code
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/verify-a-workspace-invitation-code

post /workspace-onboarding/invite/verify-code
Consumes the invitation-mailbox code and issues a resume credential, or returns HTTP200 existing_account sign-in routing. Codes are scoped to the invitation session, expire and have a configured attempt limit.



# Verify the workspace payment method
Source: https://api-docs.helpyousponsor.com/api-reference/workspace/verify-the-workspace-payment-method

post /workspace-onboarding/{public_id}/verify-payment
Retrieves the server-bound Stripe SetupIntent and requires matching session metadata, customer, succeeded status and payment method. Cards are required; prepaid cards are rejected with422 and require a fresh setup attempt. Saves the verified default payment method and advances qualification; repeated qualified calls are allowed. Existing mailbox accounts receive HTTP200 sign-in routing.



# Check calculation status for wrapped statistics
Source: https://api-docs.helpyousponsor.com/api-reference/wrapped/check-calculation-status-for-wrapped-statistics

get /admin/wrapped/{year}/status



# Check if a public wrapped report exists
Source: https://api-docs.helpyousponsor.com/api-reference/wrapped/check-if-a-public-wrapped-report-exists

get /wrapped/{year}/public/{token}/exists
Quick check to verify if a shared wrapped report exists and is still public.
     *                  Useful for pre-flight checks before loading the full report.



# Email the wrapped report to the admin
Source: https://api-docs.helpyousponsor.com/api-reference/wrapped/email-the-wrapped-report-to-the-admin

post /admin/wrapped/{year}/email
Sends the year's wrapped report summary to the authenticated admin's email address.
     *                  The email includes key highlights and a link to view the full report.



# Generate or toggle public sharing link for wrapped report
Source: https://api-docs.helpyousponsor.com/api-reference/wrapped/generate-or-toggle-public-sharing-link-for-wrapped-report

post /admin/wrapped/{year}/share
Creates a unique public sharing token for the wrapped report. If sharing is already enabled,
     *                  returns the existing share URL. Include 'disable' parameter to revoke sharing.



# Get organization's year in review
Source: https://api-docs.helpyousponsor.com/api-reference/wrapped/get-organizations-year-in-review

get /admin/wrapped/{year}
Retrieves wrapped statistics for a given year. For large datasets (>10,000 donations),
     *                  the calculation will be performed asynchronously when refresh=true.
     *
     *                  Polling Strategy:
     *                  1. Make initial request with refresh=true
     *                  2. If response is 202, begin polling the status endpoint
     *                  3. Poll /wrapped/{year}/status every 5-10 seconds
     *                  4. When status is 'completed', make another request to this endpoint
     *                  5. Stop polling if status is 'failed' or after 5 minutes
     *
     *                  Example polling implementation:
     *                  ```javascript
     *                  async function getWrappedStats(year, refresh = false) {
     *                    const response = await fetch(`/api/v1/admin/wrapped/${year}?refresh=${refresh}`);
     *
     *                    if (response.status === 202) {
     *                      return pollCalculation(year);
     *                    }
     *
     *                    return response.json();
     *                  }
     *
     *                  async function pollCalculation(year) {
     *                    let attempts = 0;
     *                    const maxAttempts = 60; // 5 minutes at 5-second intervals
     *
     *                    while (attempts < maxAttempts) {
     *                      const status = await fetch(`/api/v1/admin/wrapped/${year}/status`);
     *                      const data = await status.json();
     *
     *                      if (data.status === 'completed') {
     *                        return getWrappedStats(year);
     *                      }

     *                      if (data.status === 'failed') {
     *                        throw new Error(data.error || 'Calculation failed');
     *                      }

     *                      await new Promise(resolve => setTimeout(resolve, 5000));
     *                      attempts++;
     *                    }

     *                    throw new Error('Calculation timed out');
     *                  }
     *                  ```



# Get public wrapped report by share token
Source: https://api-docs.helpyousponsor.com/api-reference/wrapped/get-public-wrapped-report-by-share-token

get /wrapped/{year}/public/{token}
Returns a publicly shared wrapped report. Personal identifiable information (PII) like donor names
     *                  is anonymized. No authentication required but a valid share token is necessary.



# Archive or restore a commitment through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/archive-or-restore-a-commitment-through-zapier

patch /zapier/actions/commitments/{id}/status
Soft-deletes or restores the selected commitment record through commitments.update_status and returns its current archive state. Requires donation management and the primitive scope. To end a linked sponsorship through the full sponsorship lifecycle, use the dedicated cancellation endpoint.



# Cancel a commitment through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/cancel-a-commitment-through-zapier

post /zapier/actions/commitments/{id}/cancel
Ends the linked sponsorship through the canonical lifecycle, or archives a standalone commitment under its billing lock. Requires Zapier sponsorship lifecycle enabled, donation management, current donor/program access and primitives:commitments:cancel (or primitives:*). Reuse the same external_reference for retries of this cancellation occurrence; concurrent billing, changed targets and conflicting replays return409.



# Create a donor through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/create-a-donor-through-zapier

post /zapier/actions/donors
Creates an organization-scoped donor through donors.create. Requires donors_manage, donor-form access and the primitive scope. Duplicate active donor emails return409; a supplied body idempotency_key replays the cached create.



# Create a profile note through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/create-a-profile-note-through-zapier

post /zapier/actions/notes
Creates a permissioned donor or recipient note through notes.create. Send a stable Idempotency-Key header: the primitive requires a key and this transport does not forward a body idempotency_key. Category defaults to uncategorized; requires notes_manage, the target donor/program access and primitive scope.



# Create a recipient through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/create-a-recipient-through-zapier

post /zapier/actions/recipients
Creates a recipient through entities.create, including program counter allocation and configured custom-field processing. Requires manage_programs, program access and the primitive scope. Custom fields declared unique are checked across the program; tag names cannot contain commas.



# Create an externally managed sponsorship
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/create-an-externally-managed-sponsorship

post /zapier/actions/sponsorships
Creates an External Processor method7, non-charging sponsorship with amount expressed per payment period. Requires Zapier sponsorship lifecycle enabled, donation management, donor/program access and primitives:commitments:create_sponsorship (or primitives:*). external_reference identifies a replay-protected recurring record. Do not send payment_method, method, is_non_charging, is_per_period_amount or arb_subscription_id: these fields are prohibited and controlled by this action.



# Get the Zapier compatibility template
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/get-the-zapier-compatibility-template

get /zapier/compat/template
Returns the first template and associated template uploads for the authenticated organization. This read-only compatibility endpoint supports existing Zapier workflows.



# Get Zapier commitment field definitions
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/get-zapier-commitment-field-definitions

get /zapier/triggers/commitments/fields
Returns the union of donor and recipient custom-field definitions used across the organization programs, plus the standardized donor field contract. Integrations can use these definitions to configure custom-field mappings before polling commitments.



# List commitment cancellation events for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/list-commitment-cancellation-events-for-zapier

get /zapier/triggers/commitments/cancelled-feed
Returns immutable archive events in descending ledger-ID order, filtered by the caller current donor-form and program access. Requires Zapier sponsorship lifecycle to be enabled, primitives:commitments:list (or primitives:*) and donation/report read permission. Use cancellation_event_id for event deduplication and commitment_id to match the external recurring record.



# List newly inserted donations for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/list-newly-inserted-donations-for-zapier

get /zapier/triggers/donations/created-feed
Returns positive, qualified donation records in descending immutable donation-ID order so edits to the gift date do not create a new event. The numeric id is both the deduplication key and cursor. created_after and cursor_created_at are retained compatibility inputs: the current query pages by cursor_id rather than filtering by those date fields.



# List updated commitments for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/list-updated-commitments-for-zapier

get /zapier/triggers/commitments/feed
Returns an organization-scoped change feed for polling integrations. Use the event id for update-event deduplication and pass both next_cursor fields for the next page; the underlying numeric record identifier is returned separately. The cursor is descending by updated_at and numeric record id.



# List updated donations for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/list-updated-donations-for-zapier

get /zapier/triggers/donations/feed
Returns an organization-scoped change feed for polling integrations. Use the event id for update-event deduplication and pass both next_cursor fields for the next page; the underlying numeric record identifier is returned separately. The cursor is descending by updated_at and numeric record id.



# List updated donors for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/list-updated-donors-for-zapier

get /zapier/triggers/donors/feed
Returns an organization-scoped change feed for polling integrations. Use the event id for update-event deduplication and pass both next_cursor fields for the next page; the underlying numeric record identifier is returned separately. The cursor is descending by updated_at and numeric record id.



# List updated notes for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/list-updated-notes-for-zapier

get /zapier/triggers/notes/feed
Returns an organization-scoped change feed for polling integrations. Use the event id for update-event deduplication and pass both next_cursor fields for the next page; the underlying numeric record identifier is returned separately. The cursor is descending by updated_at and numeric record id.



# List updated recipients for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/list-updated-recipients-for-zapier

get /zapier/triggers/recipients/feed
Returns an organization-scoped change feed for polling integrations. Use the event id for update-event deduplication and pass both next_cursor fields for the next page; the underlying numeric record identifier is returned separately. The cursor is descending by updated_at and numeric record id.



# Record a donation through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/record-a-donation-through-zapier

post /zapier/actions/donations
Records a donation through donations.create and returns the created record with individual/combined payment amount context. This records the supplied payment outcome without initiating a provider charge. Requires donation management and the relevant donor-form/program access; body idempotency_key supports replay.



# Record an offline commitment payment
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/record-an-offline-commitment-payment

post /zapier/actions/commitments/{id}/offline-payments
Records a settled offline payment against an existing active commitment and advances its payment dates through the canonical donation service. It does not charge a processor. external_reference provides a stable replay identity; conflicting reuse returns409. Requires donation management and donor/program access.



# Record an offline sponsorship payment
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/record-an-offline-sponsorship-payment

post /zapier/actions/sponsorships/{id}/offline-payments
Resolves the sponsorship to exactly one active commitment and records the offline payment through the same replay-protected commitment payment action. No processor charge is initiated. Multiple active commitments return409 and require the caller to use the commitment-specific endpoint.



# Search commitments for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/search-commitments-for-zapier

get /zapier/searches/commitments
An id selects one active or archived commitment; otherwise donor, designation and lifecycle filters list commitments. The response projects the selected primitive result into a data array. An ID lookup that finds no record returns200 with data=[] and count=0.



# Search donations for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/search-donations-for-zapier

get /zapier/searches/donations
An id selects one donation; otherwise donor/date filters list donations. date_to cannot be earlier than date_from. Requires the corresponding donation primitive scope and donation/report read permission. An ID lookup that finds no record returns200 with data=[] and count=0.



# Search donors for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/search-donors-for-zapier

get /zapier/searches/donors
An id selects a single donor; otherwise email/query selects donor search, and an empty search lists donors. Results respect the selected primitive scopes and current donor-form permissions. An ID lookup that finds no record returns200 with data=[] and count=0.



# Search forms for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/search-forms-for-zapier

get /zapier/searches/forms
Reads the forms.list primitive without field definitions, applies a case-insensitive name match to that returned batch, and truncates the result to limit. Matching occurs after the primitive limited catalog is loaded. An ID lookup that finds no record returns200 with data=[] and count=0.



# Search programs for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/search-programs-for-zapier

get /zapier/searches/programs
Searches program names through the programs.list primitive, with the caller scope and program-access permissions applied. An ID lookup that finds no record returns200 with data=[] and count=0.



# Search recipients for Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/search-recipients-for-zapier

get /zapier/searches/recipients
An id selects one recipient; otherwise query and program_id filter the recipient list. Results respect the selected primitive scopes and current program permissions. An ID lookup that finds no record returns200 with data=[] and count=0.



# Test a Zapier connection
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/test-a-zapier-connection

get /zapier/auth/test
Resolves the system.context primitive and returns the connected user, organization and credential scopes. Requires the system context primitive scope (or primitives:*); the current workspace identity is determined by the credential.



# Update a donor through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/update-a-donor-through-zapier

patch /zapier/actions/donors/{id}
Updates the supplied safe profile fields through donors.update. Requires donors_manage, donor-form access and the primitive scope. The returned body is the donor record; duplicate email or stewardship household-impact conflicts may prevent the write.



# Update a recipient through Zapier
Source: https://api-docs.helpyousponsor.com/api-reference/zapier/update-a-recipient-through-zapier

patch /zapier/actions/recipients/{id}
Updates supplied recipient fields through entities.update. Requires manage_programs, program access and the primitive scope. Tags may use the compatibility list/string representation; names containing commas are rejected.



# Import recipient photos
Source: https://api-docs.helpyousponsor.com/guides/importing-recipient-photos

Prepare photo filenames, choose a matching field, validate the files, and import recipient photos in bulk.

Bulk photo import matches each image to one recipient in the selected program. The match comes from the photo's filename and the **Unique Field to Consider** you choose during import.

<Tip>
  Use the Gratona **Entity ID** when possible. Gratona generates this system value for every recipient, and it does not change when profile information is edited.
</Tip>

## Before you upload

1. Open **Imports**, choose **Profile Photos**, and select the recipient program.
2. Choose **Recipients** as the resource, then continue to the photo upload step.
3. In **Unique Field to Consider**, select the field represented in every photo filename. Choose **Entity ID** when it is available in your source files.
4. Decide whether the imported images should become the recipients' profile photos.

You can select multiple photos, choose a folder, or drag a folder into the upload area. The upload screen shows the current file-size and batch-size limits for your workspace.

<Frame>
  <img alt="The photo import field selector showing Entity ID under system fields and the program's recipient fields in a separate group" />
</Frame>

### Choose the matching field

You have two useful choices:

* **Entity ID** is the safest default. Copy the system-generated Gratona ID from the recipient record or an export.
* **A recipient form field** works when your organization already has a stable identifier, such as a recipient number, case number, email address, or username.

The selected field must contain a value for every recipient in the batch, and each value must identify exactly one recipient in the selected program. A field appearing in the selector does not guarantee that its data is unique. Avoid names, dates of birth, gender, or any other field that people can share.

## Name each photo

The filename must contain the selected recipient field's value. The file extension is not part of the match.

For the most predictable result, make the filename just the value:

| Selected field | Recipient's value | Recommended filename |
| - | - | - |
| Gratona Entity ID | `4821` | `4821.jpg` |
| Recipient number | `DO0140540` | `DO0140540.jpg` |
| Email | `john.doe@example.com` | `john.doe@example.com.jpg` |
| Username | `john-smith` | `john-smith.png` |

Descriptive text can appear before or after the value. For example, `recipient_4821_profile.jpg` and `student_DO0140540_profile.png` can match the same values shown above. Spaces, hyphens, and underscores are treated as separators for general identifiers such as recipient numbers, so `ABC-001.jpg` can match a stored value of `ABC 001`.

Even though descriptive text is supported, exact-value filenames are easier to audit. When matching a numeric Entity ID, avoid adding other numbers such as years or sequence numbers to the filename.

<Warning>
  Preserve punctuation in email addresses and usernames. `john-smith.jpg`, `john.smith.jpg`, and `johnsmith.jpg` are different values. The match ignores letter case, but it does not treat those punctuation variants as the same username.
</Warning>

You do not need to add a field label such as `Entity ID` to the filename, and a CSV is not required for a photo import.

## Supported images

Use one of these file types:

* JPG or JPEG
* PNG
* GIF

Each filename must be unique within the selected batch. If two selected files use the same filename, Gratona keeps one and marks the duplicate as rejected before upload.

<Frame>
  <img alt="The photo upload screen showing four accepted files and one rejected duplicate filename" />
</Frame>

## Validate before importing

Gratona validates the batch before attaching any photos. Review the validation results, especially skipped files:

* **No matching record** means the filename does not contain a value found in the selected field for a recipient in this program.
* **Matched multiple records** means the value is not unique enough to identify one recipient.
* **Invalid file type** means the image is not a supported JPG, JPEG, PNG, or GIF.
* **File size exceeds the limit** means the image is larger than the limit displayed on the upload screen.

Only validated files are imported. A skipped file is not attached to any recipient.

<Frame>
  <img alt="Completed photo validation showing three successful matches and one warning for an unmatched Entity ID" />
</Frame>

## Troubleshooting a filename

If a photo does not match:

1. Confirm that you selected the field represented in the filename.
2. Copy the value directly from the recipient record or a recipient export.
3. Rename the file to the exact value plus its extension, such as `4821.jpg`.
4. For email or username fields, restore every period, hyphen, underscore, plus sign, and `@` character.
5. Confirm that the recipient belongs to the program selected for the import.
6. Validate the batch again before importing.

If more than one recipient has the selected value, correct the duplicate data or switch to the Gratona **Entity ID**. Gratona skips ambiguous files instead of guessing which recipient should receive the photo.


# Gratona API Documentation
Source: https://api-docs.helpyousponsor.com/introduction

Integrate donor records, donations, commitments, and fundraising workflows with Gratona.

The Gratona API lets integrations manage donor and recipient records, donations, commitments, programs, and related fundraising workflows.

## Get Started

Generate an API key from **Settings → Account Settings → Developer Settings** in the Gratona dashboard. Send it in the `X-HYS-API-Key` header when calling protected admin endpoints:

```sh theme={null}
curl --request GET \
  --url https://api.gratona.com/v1/admin/api_keys \
  --header 'X-HYS-API-Key: hys_your_key_here'
```

The full key is shown once when created. Give it a descriptive name, store it securely, and revoke it from Developer Settings when it is no longer needed. Passport bearer tokens are also accepted on protected admin endpoints.

Public checkout and portal sign-in endpoints have different authentication requirements. Read the [API reference introduction](/api-reference/introduction) and the individual endpoint before making a request.

## Response Statuses

* `200` or `201`: The request succeeded.
* `202`: Work was accepted for asynchronous processing.
* `401` or `403`: Authentication or access was refused.
* `404`: The requested resource was not available.
* `409`: The request conflicts with the current state; follow the endpoint's retry or recovery instructions.
* `410`: The operation has been retired.
* `422`: Request validation failed.
* `429`: Too many requests; retry according to the response headers.

Each operation documents its request fields, response shape, and applicable statuses.