4. API Reference
4. API Reference
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 |
| 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 |
