FAQ

The questions partners ask before their first support ticket — and the ones that would have been a ticket.

Using the partner portal

The Partner Help Center explains how Roster works, what you will build and how to use each screen, without requiring coding knowledge. Start with Find the right screen or Common questions.

For technical setup, use the integration quickstart, webhooks guide and certification guide here in the API docs.

Keys and environments

Why does my key return 401 on the other environment? Each environment accepts only its own key prefix (sk_test_… in the sandbox, sk_live_… in production) and only keys it issued, so a key from the other environment gets the same opaque 401 as an unknown key. See unauthorized.

Can I see a key again? A live key, no: it is shown once at issuance. A sandbox key, usually yes: the workspace owner can copy the current one from the Integration Guide. If the Guide says the key can't be shown again, rotate it once; the new sandbox key stays available there. To replace a key, rotate it from your workspace and update every consumer; do not assume an overlap period with the old key. A revoked key answers 401.

Requests

Is Idempotency-Key really required on every POST? Yes. Keep it stable for the same action, but read the operation-specific replay behavior. A donor session replay does not recover its hosted URL, and a webhook test can run again. See retries.

I keep reading page one of the event feed. Check that you pass next_cursor back as since_cursor on the next poll. next_cursor always comes back when there were events, even on the last page — it is where your next poll resumes. A page with no events can return next_cursor: null: keep the cursor you stored and poll again with it — never overwrite it with null. The feeds page with since_cursor; GET /v1/enrollments pages with cursor. A parameter an operation does not accept is refused with 400, so a wrong name fails instead of re-reading page one.

What does 404 mean? "Not found or not yours." We do not distinguish the two, because confirming that a resource exists would leak it. If you get a 404 you did not expect, check which partner the key belongs to. See not-found.

How many requests can I make? 600 per minute per partner. Every response to a call made with your key says how many are left in RateLimit-Remaining. Past the quota you get 429 with a Retry-After header; wait that long and retry. The gateway in front of the API also has a throttle shared by every partner: its 429 has no Retry-After and no problem body, so back off exponentially. See rate-limited.

Churches and consent

Do I register a church's consent, or tick a box? You send a record: POST /v1/church_consents with what the church accepted — your document, its version, when, how. Identify her by the Roster church_id, or by your own church_reference before she is registered; send that same value as reference when you register her and the two join.

I registered the same church twice. If both requests carried the same reference, they are the same church — the second returns the existing one, even under a different Idempotency-Key. Without a reference, identity comes from the ein, when you send one, and otherwise from the Idempotency-Key. Two of your rows with the same ein are one church; see When the EIN matches a church Roster already has.

How do I stop working with a church? Consent is not withdrawn. Take the Roster button off her site and tell us.

Donors and outcomes

The flow told my page it finished — is the enrollment done? Not necessarily. onComplete is a courtesy, never the result. Trust the webhook and the feed: enrollment.created, then enrollment.activated once payroll is connected. See webhooks.

How do I include paycheck gifts in my reports and existing ChMS integration? Use donation.updated for actual donation amounts, transfer outcomes, returns and refunded totals, and donor.updated for the contact changes donors make in the donor sessions you create. Both are available through signed webhooks and GET /v1/financial_events. Authorized donor name, email, phone and mailing address are included when available. Preserve Roster identifiers and report missing profile data explicitly. See financial integration. Roster supplies the structured data; you keep using your existing ChMS connector. The contract does not expose raw payroll data or donor bank credentials.

Can I refund a donation through the API? Yes, a donation that came through you, in full or in part: POST /v1/refunds, then follow refund.created and refund.updated. Roster asks the donor for the bank account that receives the money. See refunds. A refund is not a bank return: when the bank returns a transfer, you receive donation.updated with status: returned and return_details; reconcile it as described in Interpret progress accurately.

Sandbox and going live

Why did the sandbox flow stop at the payroll screen? Check your scenario setup and the current enrollment state first. The sandbox flow connects the payroll through the payroll provider's window in its test mode: sign in with a test user that window indicates (see Test donors) and save the gift. A script that does not drive that window can activate a pending enrollment with POST /sandbox/simulate/payroll-connected; the flow moves on by itself. See the complete simulation catalog for payroll, deposits, cancellation confirmations and returns. These routes exist only on the test-key stack.

Are the certification checks required for production? No. They are recommended checks; Roster releases production separately, once the commercial agreement is signed. The portal tracks four enrollment scenarios run end to end on sandbox: activation, an amount change, a cancellation, and a broken payroll connection. The recommended checks in Integration Guide update from the feed, never from a checkbox. Follow the certification script, then prove the separate financial integration scenarios before calling a donation/reporting integration ready.