Roster Partner API

The Roster Partner API lets a platform partner import its churches, open hosted donor sessions, read enrollment status, and reconcile through an event feed plus signed outbound webhooks.

Conventions (apply to every endpoint)

• Authentication — every /v1/* and /sandbox/* request needs Authorization: Bearer sk_test_... (sandbox) or Bearer sk_live_... (production). Test keys only exist on the sandbox stack. A malformed, unknown, or wrong-mode key always gets the same opaque 401.
• Idempotency — the Idempotency-Key header (1–255 visible chars) is required on every POST. Replaying a POST with the same key returns the same resource with 200 instead of creating a duplicate.
• Errors — RFC 7807 application/problem+json: {type, title, detail, request_id}. Include request_id when contacting support.
• Rate limiting — per API key at the gateway; expect 429 with Retry-After.
• Pagination — cursor-based (since_cursor / next_cursor) on the event feed. Cursors are opaque; never construct one.
• No PII — enrollments and events are field-allowlisted projections. The partner surface never exposes donor phone numbers, bank data, or payroll amounts.

Certification flow (sandbox, self-service)

1. Import churches (POST /v1/churches/import).
2. Open a donor_session and complete the hosted flow with a seed donor.
3. Simulate payroll connection (POST /sandbox/simulate/payroll-connected) and receive enrollment.activated on your webhook endpoint.
4. Cross-check the same event on the pull feed (GET /v1/events).