Skip to main content

4. API Reference

All paths are relative to:

  • Sandbox: https://devapi.sirgiving.org
  • Production: https://api.sirgiving.org

Auth legend

Label Meaning
JWT User login token from the SIR Giving app
Widget X-Partner-Key: pk_... only
HMAC X-Partner-Key, X-Timestamp, and X-Signature
HMAC, secret key HMAC request with sk_...; publishable keys are rejected

Partner key management

These endpoints are for signed-in users managing their own partner credentials.

Method Path Auth Purpose
POST /v1/partner/keys JWT Create an API key pair
GET /v1/partner/keys JWT List your API keys
GET /v1/partner/keys/partner-info JWT Get your Partner record
GET /v1/partner/keys/:id JWT Get one key record
PATCH /v1/partner/keys/:id JWT Rename, deactivate, or set expiry
DELETE /v1/partner/keys/:id JWT Delete/revoke a key

Partner auth

These endpoints support the partner portal.

Method Path Auth Purpose
POST /v1/partner/auth/login Email/password Login to partner portal
GET /v1/partner/auth/me JWT Get current partner user and publishable key

Widget/config endpoints

Method Path Auth Purpose
GET /v1/partner/config Widget Get partner widget config
GET /v1/partner/organizations/:slug Widget Look up nonprofit details
POST /v1/partner/donations/create-link Widget Create a donation checkout link
GET /v1/partner/donations/status/:partnerDonationId Widget Check donation reward status

Users

Method Path Auth Purpose
GET /v1/partner/users HMAC List partner users
POST /v1/partner/users HMAC, secret key Create a partner user
GET /v1/partner/users/:externalId HMAC Get a user by your external ID
PATCH /v1/partner/users/:externalId HMAC, secret key Update user metadata
GET /v1/partner/users/:externalId/balance HMAC Get user balance
GET /v1/partner/users/:externalId/transactions HMAC Get user action history

Actions

Method Path Auth Purpose
POST /v1/partner/actions/submit HMAC, secret key Submit one reward action
GET /v1/partner/actions HMAC List actions
GET /v1/partner/actions/:id HMAC Get action status/details
POST /v1/partner/actions/:actionId/reverse HMAC, secret key Reverse a completed action
POST /v1/partner/actions/bulk HMAC, secret key Submit up to 100 actions synchronously

GET /v1/partner/actions/bulk/:jobId is deprecated. Bulk actions are processed synchronously and return their result from POST /bulk.

Token pools

Method Path Auth Purpose
GET /v1/partner/token-pools HMAC List allocated token pools
GET /v1/partner/token-pools/:id/balance HMAC Get pool balance
POST /v1/partner/token-pools/request HMAC, secret key Request more allocation
GET /v1/partner/token-pools/requests HMAC List allocation requests

Campaigns

Method Path Auth Purpose
GET /v1/partner/campaigns HMAC List campaigns
GET /v1/partner/campaigns/active HMAC Get active campaign
GET /v1/partner/campaigns/:id HMAC Get campaign details
GET /v1/partner/campaigns/:id/analytics HMAC Get campaign analytics
POST /v1/partner/campaigns HMAC, secret key Create campaign
PATCH /v1/partner/campaigns/:id HMAC, secret key Update campaign

Transactions

Method Path Auth Purpose
GET /v1/partner/transactions HMAC List partner transactions
GET /v1/partner/transactions/:id HMAC Get transaction details

Dashboard

Method Path Auth Purpose
GET /v1/partner/dashboard/summary HMAC Pool, activity, and user summary
GET /v1/partner/dashboard/trends HMAC Daily activity trends
GET /v1/partner/dashboard/top-earners HMAC Top rewarded users
GET /v1/partner/dashboard/webhooks/health HMAC Webhook health
GET /v1/partner/dashboard/api-usage HMAC API usage metrics
GET /v1/partner/dashboard/recent-activity HMAC Recent actions
GET /v1/partner/dashboard/integration-health HMAC Integration health
GET /v1/partner/dashboard/campaigns/:id/analytics HMAC Campaign performance

Webhooks

Method Path Auth Purpose
POST /v1/partner/webhooks HMAC, secret key Register webhook
GET /v1/partner/webhooks HMAC List webhooks
DELETE /v1/partner/webhooks/:id HMAC, secret key Delete webhook
GET /v1/partner/webhooks/:id/deliveries HMAC List deliveries
POST /v1/partner/webhooks/:id/deliveries/:deliveryId/retry HMAC, secret key Retry delivery
POST /v1/partner/webhooks/:id/test HMAC, secret key Send test webhook

No comments to display

Back to top