Introduction

The Roster Partner API lets your platform offer payroll-deduction giving to the churches you serve. You import your churches, hand each donor a hosted enrollment link, and follow the results through webhooks and an event feed — Roster coordinates the donor flow and payroll connection, and instructs the bank that moves funds. Enrollment status and money received are separate outcomes.

Environments

Environment	Base URL	Keys
Sandbox	https://api.sandbox.rostergiving.com	sk_test_...
Production	https://api.rostergiving.com (opens when Roster releases your production workspace)	sk_live_...

Test keys only exist in the sandbox; live keys only in production. A live key is shown once at issuance — store it in your secret manager. The workspace owner can copy the current sandbox key again from the Integration Guide.

Conventions

• Authentication — Authorization: Bearer sk_... on every request. Authentication failures are always an opaque 401.
• Idempotency — the Idempotency-Key header is required on every POST. Keep a stable key for each action; the same key with a different body gets 409 and nothing runs. Replay semantics differ by operation. See errors and retries before automating retries.
• Errors — RFC 7807 application/problem+json with type, title, detail, and request_id. Include request_id when contacting support. Errors from the gateway in front of the API are plain JSON instead; see API errors.
• Donor data — financial updates include authorized identity and contact fields for your reporting and existing ChMS integrations. Activity events retain their narrower projection. See financial integration. Keep personal data and API keys out of URLs and logs.

The integration in one paragraph

Import churches (POST /v1/churches/import), then for each donor create a session (POST /v1/donor_sessions) and open the returned url on your page with roster.js, as a pop-up or embedded — a Roster-hosted flow where the donor verifies their phone, consents, and connects payroll. You observe outcomes on your webhook endpoint (enrollment.created, enrollment.activated, …) and reconcile with GET /v1/events. Follow actual donations and donor contact updates through GET /v1/financial_events, donation.updated and donor.updated to feed your own reports and ChMS connector, and return a donation to the donor with a refund. The end of the flow on your page is a courtesy, never the result: trust the webhook and the feed, not the end of the flow.

Start with your first sandbox request, then follow the import guide, donor handoff and event reconciliation. Use sandbox certification to prove lifecycle behavior before the production readiness checks.