Your first sandbox request

Start with a read-only request, then create one synthetic church. You need a partner workspace and its sandbox key. The workspace owner copies the key from the portal's Integration Guide. If the Guide says the key can't be shown again, the owner rotates it once from API keys; the new sandbox key then stays available in the Guide. Keep it in your server's secret manager, never in browser code or your repository.

1. Check access

Set ROSTER_KEY in your local environment using your secret manager. The examples assume it contains your sk_test_… key.

export ROSTER_BASE_URL=https://api.sandbox.rostergiving.com
curl --fail-with-body "$ROSTER_BASE_URL/v1/churches" \
  -H "Authorization: Bearer $ROSTER_KEY"

A 200 response contains a churches array; an empty array is a successful first request. A 401 means the key is missing, revoked, invalid, or belongs to another environment. A 404 for a particular resource can also mean it belongs to another partner.

2. Create a test church

curl --fail-with-body -X POST "$ROSTER_BASE_URL/v1/churches" \
  -H "Authorization: Bearer $ROSTER_KEY" \
  -H "Idempotency-Key: tutorial-church-001" \
  -H "Content-Type: application/json" \
  --data '{"name":"Integration Test Church","reference":"integration-test-001"}'

Save the returned church id alongside integration-test-001 in your system. The first creation returns 201; repeating this request returns the existing church with 200. Use a new reference for a different church. Do not put a name, phone number, bank account, or other personal information in a URL or idempotency key.

Creating a church is a registration step. It does not prove that the church's bank account is verified or ready to receive funds. Donors can start paycheck giving only after Roster verifies the church's legal setup and receiving account; see When a church is ready for donors.

3. Choose the next milestone

Goal	Guide	Evidence to keep
Register your church directory	Import churches	Every source reference mapped to an ID or an actionable row error
Start donor enrollment	Donor sessions	Session ID, hosted handoff and enrollment event
Keep your system in sync	Events and Webhooks	Durable cursor, deduplication and verified signature
Integrate with an AI coding agent	Connect an AI client	A successful read with your own sandbox key
Prove lifecycle behavior	Sandbox certification	Four scenarios observed in your integration

The API Reference supplies the exact request and response schemas. Use synthetic churches and test donors: a number from +1 202-555-0100 to +1 202-555-0189 with code 000000 passes; 0190 to 0199 are held in identity review on purpose. Never use a real donor's details.

Introduction

Import churches