API & webhooks

Find it: Settings → API keys / Webhooks · Who can use it: Org Admins on Growth or Enterprise plans (technical/integration audience).

What you'll see

Two areas under Settings: API keys (create and manage the credentials your code uses) and Webhooks (subscribe an endpoint of yours to events as they happen). This page is the orientation. The full technical reference — every endpoint, pagination, filtering, error formats, and a machine-readable OpenAPI spec — lives at /docs/api. The API base URL is https://thankfirst.com/api/v1.

How to create an API key

1. Go to Settings → API keys and create a key.
2. Choose its scopes — read and/or write, per resource: donors, gifts, interactions, campaigns. A read-only key can't write; grant only what the integration needs.
3. Copy the key. It is shown once, at creation — store it somewhere safe (a secrets manager), because you can't retrieve it again.
4. Send it as a bearer token on every request (Authorization: Bearer tf_live_…).

Each key is bound to exactly one organization and can never read another tenant's data. Keys are rate-limited (per key), and every call is audit-logged.

How to rotate or revoke a key

• Rotate issues a new secret while the old one keeps working for a 24-hour grace window, so you can roll it out without downtime — then the old secret stops.
• Revoke kills a key immediately. Use it if a key is exposed.

How to subscribe a webhook

1. Go to Settings → Webhooks and add an https endpoint you control.
2. Choose the events to receive: gift.created, donor.created, donor.updated, pledge.created, task.completed, donation.processed.
3. Save. ThankFirst signs every payload with an HMAC signature using a per-endpoint secret — verify the signature on your side before trusting a delivery.
4. Watch the delivery log: every attempt is visible, with a redeliver button. Failed deliveries are retried with backoff; a permanently failing one lands in a dead-letter state you can retry later. Nothing is ever silently dropped.

Guardrails that matter to a nonprofit

The API is not a back door — writes uphold the exact same rules as the app:

• OK-to-ask is enforced. Logging an ask via the API respects the OK-to-ask engine. A blocked ask is rejected, not queued — there is no override path.
• Strict field allowlist on donor updates. Computed fields, deceased status, and primary-email changes are rejected with a clear error — never silently ignored.
• Consent is one-way. You can suppress a donor via the API; you can never re-enable contact through it. Relaxing consent is a human-only action.
• Alias-aware email matching. Creating a donor with an email that already exists (as a primary or an alias) resolves to that donor, so you don't create duplicates.
• Gifts follow the manual-gift path. API-created gifts do not auto-issue a receipt.

Good to know

• Zapier is the no-code path for the long tail — spreadsheets, Slack, Gmail, form tools — built on these same API keys and webhooks. Reach for it when you don't want to write code.
• Because guardrails run server-side, an integration can't do anything a careful admin couldn't; it just can't be tricked into breaking the rules.
• See /docs/api for endpoints, pagination, filtering, and error formats. This guide orients you; that reference is the source of truth.

See Also

• Settings