1. Start Here

1. Start Here

SIR Giving Partner API Overview

TheUse the SIR Giving Partner API letsto approvedadd partnersSIR rewards to your product. You can create donation links, reward users for actions in your own system, track balances, and receive webhook events when rewards are issued or reversed.

Most teams use one of two paths:

If you want to... Start with Add a donation button or embedded donation flow A publishable key (pk_...) and the donation endpoints Reward users for purchases, volunteering, referrals, or other actions A secret key (sk_...), HMAC signing, and the actions endpoints Listen for reward status changes Webhooks Test before launch Sandbox credentials and a sandbox token pool

What you need before you call the API

You need three things:

A partner account. An API key pair for the environment you are using. A funded token pool if you want to distribute SIR tokenstokens. to their

Creating userscredentials forlets donation,you volunteering,authenticate. advocacy,It does not automatically mean you can issue real rewards. Rewards draw from a token pool, and other prosocial actions; create donation flows; manage campaigns andproduction token pools;pools andrequire receiveSIR eventGiving notifications via webhooks.approval.

Base URLs

Environment	Base URL

Key prefix Sandbox https://devapi.sirgiving.org pk_test_..., sk_test_... Production https://api.sirgiving.org Sandbox https://devapi.sirgiving.orgpk_live_..., sk_live_...

All partner integration endpoints are prefixed withunder /v1/partner/.

Interactive SwaggerAPI UIdocs isare 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 byChoose your backend.first Requirestutorial X-Partner-Key

(sk_...),X-Timestamp,andGoal X-Signature.Use Usedthis I want to make my first signed backend request Authentication & HMAC Signing I want to add a donation button End-to-End Scenarios: Donation widget I want to reward a user for actions,an users,action transactions,End-to-End campaigns,Scenarios: tokenReward pools,a webhooks,user dashboard.

2. BrowserI widgetwant (publishableto keyreceive only)events

Used

Webhooks 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 yourorganization organization,or withdeveloper account in SIR Giving. API keys, token pools, campaigns, users, and webhooks all belong to a statuspartner.

(PENDING_APPROVAL → ACTIVE → optionally SUSPENDED), a tier (Standard / Professional / Enterprise) controlling rate limits, and a set of enabled features.

API key pair

— every

Each key issuance createsreturns:

a

A publishable keykey, (pk_live_...such /as pk_test_...), safe for browsers,browser plususe. aA secret keykey, (sk_live_...such /as sk_test_...), plusfor backend use only. An HMAC signing secret, used to sign server-to-server requests.

The secret key and HMAC secret are shown once. Store them in a separatesecret hmacSecretmanager.

used for request signing.

Token pool

—

A pre-allocatedfunded bucket of 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 tokensallocated to specificyour stakeholders.partner. Reward actions debit this pool. If there is no active pool in the same environment as your API key, action submission can authenticate but still fail during processing.

Action

— the

The unit of reward work you submit.send Includesto actionTypeSIR (DONATION,Giving. VOLUNTEER,For etc.),example: amount,a stakeholders[],purchase, andvolunteer shift, donation, referral, or advocacy event. Actions include an idempotencyKey. Processedso againstretries ado tokennot pool,duplicate optionallyrewards.

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

A user infrom your system,system mirrored oninto ourSIR sideGiving and keyed byusing your stable externalUserId. EachPartner getsusers anreceive account/walletbalances forwhen actions reward them.

Webhook

An outbound event sent from SIR balance.

Giving Webhookto —your outbound HTTP callback we sendserver when eventsimportant occur.things Signedhappen, withsuch as X-SIR-Signatureaction.completed or token_pool.low_balance.

QuickThe startshortest (5path steps)to a working integration

1. GetCreate approved.or Emailreceive partnerships@sirgiving.org with your use case, expected volume, and integration model. We provision a Partner record andsandbox credentials.
2. Receive credentials. You'll get a publishable key (pk_test_...), a secret key (sk_test_...), and an HMAC signing secret. Store the secretsk_... +key and HMAC secret in your backend environment.

Make a vault — they are shown once. Hit a sandbox endpoint. Trysigned GET /v1/partner/users request. If you are building a widget, create a donation link with the pk_... key. If you are issuing rewards, confirm you have an active sandbox token pool. Submit a test action with a unique idempotencyKey. Register a webhook and send a test event. Repeat the same flow in production after your production token pool is approved.

Common confusion

My key works, but actions fail. Why?

Authentication only proves your key is valid. Reward actions also need an active token pool in the same environment.

Can I use a publishable key for server actions?

No. Mutation endpoints such as action submission and webhook registration require a secret key.

Can I use sandbox keys against production?

Do not do this. Use https://test keys with devapi.sirgiving.org with HMAC headers (see Authentication page).

Submit your first action.and POSTlive /v1/partner/actions/submitkeys with anapi.sirgiving.org. idempotency key, action type, amount, and stakeholders. Token distribution happens synchronously. 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.).