Skip to main content

1. Overview & Quick Start

Partner API Overview

The SIR Giving Partner API lets approved partners distribute SIR tokens to their users for donation, volunteering, advocacy, and other prosocial actions; create donation flows; manage campaigns and token pools; and receive event notifications via webhooks.

Base URLs

Environment URL
Production https://api.sirgiving.org
Sandbox https://devapi.sirgiving.org

All partner endpoints are prefixed with /v1/partner/. Interactive Swagger UI is available at /partner-api on each host.

Two API surfaces

The Partner API has two authentication models matching two integration patterns:

1. Server-to-server (HMAC + secret key)

Used by your backend. Requires X-Partner-Key (sk_...), X-Timestamp, and X-Signature. Used for actions, users, transactions, campaigns, token pools, webhooks, dashboard.

2. Browser widget (publishable key only)

Used by JavaScript running in your customer's browser. Requires only X-Partner-Key (pk_...). Used for donation links, organization lookup, partner config.

Key concepts

  • Partner — your organization, with a status (PENDING_APPROVAL → ACTIVE → optionally SUSPENDED), a tier (Standard / Professional / Enterprise) controlling rate limits, and a set of enabled features.
  • API key pair — every key issuance creates a publishable key (pk_live_... / pk_test_...) safe for browsers, plus a secret key (sk_live_... / sk_test_...) plus a separate hmacSecret used for request signing.
  • Token pool — pre-allocated SIR tokens you draw from when distributing rewards. Pools have balance, restrictions (vesting, expiration), and optional auto-refill.
  • Campaign — a configurable distribution rule (multiplier, splits, tiers, schedule, budget) that controls how an action's amount becomes SIR tokens to specific stakeholders.
  • Action — the unit of work you submit. Includes actionType (DONATION, VOLUNTEER, etc.), amount, stakeholders[], and an idempotencyKey. Processed against a token pool, optionally through a campaign.
  • Stakeholder — a participant in an action (DONOR, VOLUNTEER, ORGANIZATION, REFERRER, etc.) identified by stakeholderTypeCode. Each stakeholder receives tokens per the campaign's split rules.
  • Partner user — a user in your system, mirrored on our side and keyed by your externalUserId. Each gets an account/wallet for SIR balance.
  • Webhook — outbound HTTP callback we send when events occur. Signed with X-SIR-Signature.

Quick start (5 steps)

  1. Get approved. Email partnerships@sirgiving.org with your use case, expected volume, and integration model. We provision a Partner record and credentials.
  2. Receive credentials. You'll get a publishable key (pk_test_...), a secret key (sk_test_...), and an HMAC signing secret. Store the secret + HMAC in a vault — they are shown once.
  3. Hit a sandbox endpoint. Try GET /v1/partner/users against https://devapi.sirgiving.org with HMAC headers (see Authentication page).
  4. Submit your first action. POST /v1/partner/actions/submit with an idempotency key, action type, amount, and stakeholders. Token distribution happens synchronously.
  5. Register a webhook. POST /v1/partner/webhooks with your URL and event types. We'll start delivering events.

What you can build

  • Donation widgets — embed a donation flow on your site that creates Stripe / Every.org links and rewards donors with SIR tokens.
  • Volunteer / advocacy reward programs — issue SIR tokens to users for completing real-world actions tracked in your system.
  • Loyalty integrations — convert your customers' purchases into SIR rewards, redeemable through SIR's marketplace.
  • Custom dashboards — pull dashboard summary, top earners, trends, webhook health, and API usage to power partner-side analytics.

Where to next

  • Onboarding & Partnership — the approval process, account setup, and what you need to provide.
  • Authentication & HMAC Signing — full signing recipe with code samples.
  • API Reference — every endpoint, every parameter.
  • Webhooks — event types, signing verification, retry behavior.
  • End-to-End Scenarios — worked examples (donation flow, volunteer payout, refund, etc.).
Back to top