Data glossary
This glossary and the portal are generated from the same versioned API contract. Updates become public when that version is published. Each object is described once, with the operations and events where it appears, and each field appears once inside its object. A field that holds another object points to that object's table; inside that table, Required means required whenever the object itself is present.
Required means the field must be present, not that its value is known. Null means no value is supplied; it is different from omitting the field. Conditional requirements name the parent object or event type. In a field name, [] means each item in a list. Sandbox-only operations simulate activity and are unavailable in production. Deprecated fields are kept for existing integrations; the API reference names what replaces them.
The donor may confirm or correct prefilled values. Exported donor profiles exclude birth dates, government identifiers and identity documents. Bank acceptance does not prove final credit at the destination; a fee record does not prove a separate payout to the partner.
See the API reference for request formats and the event catalog for subscriptions.
What you can send us
Every request
| Header | When present | Meaning |
|---|---|---|
| Idempotency-Key | Required on every POST | Identifier you choose for one write request. Reuse it when retrying the same request so the action is not performed twice. |
| Authorization | Required on every call | Proves which partner is making the request. Send Bearer followed by your API key: sk_test_… in the sandbox, sk_live_… in production. |
Path and query parameters
| Parameter | In | Operations | When present | Meaning |
|---|---|---|---|---|
| cursor | query | GET /v1/churches, GET /v1/enrollments | Optional | Marker returned by the previous page; send it to continue the same list. |
| id | path | GET /v1/churches/{id}, POST /v1/churches/{id}/bank-account, POST /v1/churches/{id}/payout-schedule, POST /v1/churches/{id}/verification | Required | Church id (ch_...). |
| church_id | query | GET /v1/flow-settings, GET /v1/enrollments/{id} | Optional | Church identifier used to select the church’s records or appearance settings. |
| id | path | GET /v1/donor_sessions/{id} | Required | Identifier of the donor session this request concerns. |
| church_id | query | GET /v1/enrollments | Required | Church identifier used to select the church’s records or appearance settings. |
| id | path | GET /v1/enrollments/{id} | Required | Identifier of the recurring giving arrangement this request concerns. |
| donation_id | query | GET /v1/refunds | Required | Identifier of the individual donation whose refunds you want to read. |
| id | path | GET /v1/refunds/{id}, POST /v1/refunds/{id}/cancel | Required | Refund id, as returned by POST /v1/refunds. |
| since_cursor | query | GET /v1/financial_events, GET /v1/events | Optional | Marker returned by your previous event page; send it to continue reading changes without starting again. |
| type | query | GET /v1/events | Optional | Only return notices of this exact event type. |
| id | path | POST /v1/webhook_endpoints/{id}/test, GET /v1/webhook_endpoints/{id}/deliveries, DELETE /v1/webhook_endpoints/{id} | Required | Webhook endpoint id (we_...). |
ChurchInput
Appears in: POST /v1/churches (request body); churches in POST /v1/churches/import (request body).
| Field | When present | Meaning |
|---|---|---|
| name | Required | Name of the church displayed to people. |
| reference | Optional | Your reference for this record, used to match it with your own system. |
| ein | Optional | The church’s nine-digit US tax identification number (EIN). |
| bank_account | Optional | Church bank account to receive payments. Its numbers are supplied only in the request. Ignored when another platform registered the church first. See BankAccountInput. |
| payout_schedule | Optional | When the church receives payouts: daily (the default, every weekday cutoff) or weekly (the next Monday after each deposit, or the next business day when Monday is a bank holiday). The money waits in the donor's account until then. Allowed values: daily, weekly. |
BankAccountInput
Appears in: bank_account in ChurchInput; POST /v1/churches/{id}/bank-account (request body).
| Field | When present | Meaning |
|---|---|---|
| routing_number | Required | Nine-digit number identifying the US bank (ABA routing number). |
| account_number | Required | Number identifying the church’s account at its bank. Roster does not return the full number. |
| legal_name | Optional | Legal name of the account holder; used when checking ownership. |
Import churches in batch — POST /v1/churches/import
| Field | When present | Meaning |
|---|---|---|
| churches | Required | List of churches registered through your platform. See ChurchInput. |
Set when the church receives its payouts — POST /v1/churches/{id}/payout-schedule
| Field | When present | Meaning |
|---|---|---|
| payout_schedule | Required | When the church receives payouts: daily (the default, every weekday cutoff) or weekly (the next Monday after each deposit, or the next business day when Monday is a bank holiday). The money waits in the donor's account until then. Allowed values: daily, weekly. |
Submit legal details for an existing church — POST /v1/churches/{id}/verification
| Field | When present | Meaning |
|---|---|---|
| ein | Required | The church’s nine-digit US tax identification number (EIN). |
| account_holder_type | Required | Confirms the receiving account is held by the church as an organization. An account in a person's name cannot receive payouts and gets 400. Allowed values: organization. |
| address_type | Required | Confirms the church has a street address. A post office box alone is not accepted and gets 400. Allowed values: street. |
| incorporation_date | Required | Date the organization was legally formed, written as YYYY-MM-DD. |
| representative_name | Required | Full name of the person representing the church. |
ChurchConsentInput
Appears in: POST /v1/church_consents (request body).
| Field | When present | Meaning |
|---|---|---|
| church_id | Optional | Roster identifier of the church this record belongs to. |
| church_reference | Optional | Your church identifier, usable before a Roster church identifier exists. |
| document | Required | Name you give the agreement or permission the church accepted. |
| version | Required | Version of the agreement the church accepted. |
| accepted_at | Required | Date and time the church accepted the agreement; cannot be in the future. |
| method | Required | How the church accepted the agreement: terms of service, signed addendum, an in-product opt-in or another method. Allowed values: terms_of_service, signed_addendum, in_product_optin, other. |
| reference | Optional | Your reference for this record, used to match it with your own system. |
FlowSettingsInput
Appears in: PUT /v1/flow-settings (request body).
| Field | When present | Meaning |
|---|---|---|
| expected_version | Required | The version of the settings you read. If someone saved since then, the save is refused with the current settings. |
| church_id | Optional | Church whose own appearance you save. Omit it to save the partner default. |
| button_label | Optional | Text on the button in your own website that opens the donor flow. Required without church_id. With church_id, omit it to use the partner default. |
| brand_color | Optional; may be null | Main brand color, written as a hash sign followed by six hexadecimal digits. Without church_id, omitting it (or sending null) removes the saved color and the donor flow uses its standard look. With church_id, omitting it uses the partner default. |
| display_name | Optional | Name of your platform shown to the donor. |
| support_contact | Optional | Support email address shown to the donor. |
| logo_url | Optional | HTTPS address of the logo image you host. Today the donor flow shows it only on the amount screen, and donor sessions you create start after that screen. |
| cta_label | Optional | Text on the continue button inside the Roster donor flow. Today the donor flow shows it only on the amount screen, and donor sessions you create start after that screen. |
| manage_url | Optional | HTTPS address of the page in your account area where donors change or cancel their gift. Emails to donors who came through you link there. |
| customization | Required | Appearance settings and declaration of donor fields your platform intends to prefill. Always sent; with church_id it can be empty, and what it omits comes from the partner default. |
| customization.customize_churches | Optional | Whether individual churches may override the partner appearance. Churches without their own settings use the partner defaults. Required without church_id. Not saved for a church; only the partner default turns church overrides on. |
| customization.collected_fields | Optional | Names of donor fields your platform intends to prefill. This list contains no personal values; those are sent when opening each donor session. Required without church_id. With church_id, omit it to use the partner list. |
| customization.css | Optional | Allowed appearance properties for Roster-controlled screens. Provider screens keep their own restrictions; arbitrary CSS selectors and remote resources are not accepted. Required without church_id. With church_id, properties you omit use the partner value. |
| customization.css.background_color | Optional | Background color of the Roster donor flow. |
| customization.css.text_color | Optional | Color of the main text. |
| customization.css.button_color | Optional | Background color of action buttons. |
| customization.css.button_text_color | Optional | Color of text inside action buttons. |
| customization.css.input_background | Optional | Background color of fields where the donor types. |
| customization.css.input_text_color | Optional | Color of text the donor types. |
| customization.css.border_color | Optional | Color of borders around controls. |
| customization.css.modal_width | Optional | Width of the donor-flow window, from 280 to 640 pixels. |
| customization.css.border_radius | Optional | Rounding of the window’s corners, from 0 to 32 pixels. |
| customization.css.button_radius | Optional | Rounding of button corners, from 0 to 32 pixels. |
| customization.css.input_radius | Optional | Rounding of input-field corners, from 0 to 32 pixels. |
| customization.css.font_size | Optional | Text size, from 14 to 24 pixels. |
| customization.css.padding | Optional | Space inside the window’s edges, from 0 to 48 pixels. |
| customization.css.gap | Optional | Space between elements, from 0 to 48 pixels. |
| customization.css.line_height | Optional | Space between text lines, from 1.2 to 2 times the text size. |
| customization.css.font_family | Optional | Typeface to use on Roster-controlled screens; choose one of the supported names. Allowed values: Inter, Arial, Georgia, system-ui, sans-serif, serif. |
AllowedOriginsInput
Appears in: PUT /v1/allowed_origins (request body).
| Field | When present | Meaning |
|---|---|---|
| origins | Required | Websites where your pages open the Roster donor flow, written as an HTTPS address with no path. |
| expected_origins | Optional | The list of sites you read before changing it; if someone changed it meanwhile, the save is refused instead of overwriting. |
DonorSessionInput
Appears in: POST /v1/donor_sessions (request body).
| Field | When present | Meaning |
|---|---|---|
| church_id | Required | Roster identifier of the church this record belongs to. |
| donor_phone | Optional | Donor phone number, including country code, to prefill the flow (for example +12025550100, a sandbox test number). The donor confirms it. |
| mode | Required | How the recurring gift is calculated: pct is a percentage; fixed is a fixed dollar amount. Allowed values: pct, fixed. |
| value | Required | Giving amount for the selected mode: a percentage for pct, or US dollars for fixed. |
| reference | Optional | Your platform's identifier for this donor, returned in the session and in the enrollment it creates. Letters, digits, '.', '_', ':' and '-', up to 64 characters; never an email address, phone number or name. |
| fund | Optional | Fund or designation for this gift in your platform, such as General Fund, up to 60 characters. Returned in the session and in the enrollment it creates. It does not change where money goes. |
| funds | Optional | How the donor split this gift among funds of the same church: your fund identifier, an optional name, and a percent (adding up to 100) or, for a fixed gift, an amount in dollars (adding up to the gift). Every donation then reports each fund's amount. It does not change where money goes. |
| funds[].id | Required when funds is provided and an item exists in funds | Your platform's identifier for the fund. Letters, digits, '.', '_', ':' and '-', up to 64 characters. |
| funds[].name | Optional | Name of the fund shown to the donor, such as Building Fund, up to 60 characters. |
| funds[].percent | Optional | Share of the gift for this fund, greater than 0 and at most 100, with at most two decimal places, like 33.33. Send percent or amount for every fund, not both. |
| funds[].amount | Optional | US dollars per paycheck for this fund, greater than 0 with at most two decimal places, like 12.50. Only with mode fixed; the amounts add up exactly to the gift value. |
| donor | Optional | Information your platform already knows and sends to prefill the donor flow. The donor confirms or corrects it. The raw session prefill is not returned by session reads. Authorized confirmed profile fields can later be sent in donor and donation updates; birth date and identity documents are excluded. See DonorPrefill. |
DonorPrefill
Appears in: donor in DonorSessionInput.
| Field | When present | Meaning |
|---|---|---|
| given_name | Optional | Donor’s first name. |
| family_name | Optional | Donor’s last name. |
| date_of_birth | Optional | Birth date supplied to prefill the identity step, written as YYYY-MM-DD; an empty or blank value is treated as absent. It is not included in the donor profile exported to partners. |
ManageSessionInput
Appears in: POST /v1/manage_sessions (request body).
| Field | When present | Meaning |
|---|---|---|
| enrollment_id | Required | Identifier of the recurring gift the donor will change or cancel. |
| church_id | Optional | Roster identifier of the church this record belongs to. |
| donor_phone | Optional | Donor phone number, including country code (for example +12025550100). Today the manage flow does not fill it in; the donor types it and confirms it with a code. |
RefundInput
Appears in: POST /v1/refunds (request body).
| Field | When present | Meaning |
|---|---|---|
| donation_id | Required | Identifier of the individual donation to return to the donor. |
| amount_minor | Optional | Amount to return to the donor, in US cents; 2500 means US$25.00. Leave it out to return everything not yet returned. |
| reason | Required | Why the donation is returned: duplicate, requested_by_donor or other. Allowed values: duplicate, requested_by_donor, other. |
| cancel_recurrence | Required | Whether to also cancel the donor's recurring gift. Required; true cancels it, false keeps it. |
| metadata | Optional | Your own labels for the refund, such as a support ticket number, returned exactly as sent. Up to 50 keys. |
WebhookEndpointInput
Appears in: POST /v1/webhook_endpoints (request body).
| Field | When present | Meaning |
|---|---|---|
| url | Required | HTTPS address where Roster sends notices, on the standard port and with a public host name. IP addresses, a username or password in the address and internal names are refused. At most 3 active endpoints per partner. |
| event_types | Required | Kinds of notices this address is subscribed to receive. |
Simulate a payroll deposit (sandbox only) — POST /sandbox/simulate/deposit
| Field | When present | Meaning |
|---|---|---|
| church_id | Required | Roster identifier of the church this record belongs to. |
| enrollment_id | Optional | Recurring giving arrangement whose donor account receives the test deposit; Roster finds the account. |
| account_ref | Optional | Reference to the simulated bank account that will receive the test deposit. |
| amount | Required | Amount of the test deposit in US dollars; 25.50 means US$25.50. The sandbox accepts up to US$1,000,000.00. |
| trace | Optional | Your reference for this simulated bank transaction; Roster scopes it to your account before sending it. |
Simulate payroll connection (sandbox only) — POST /sandbox/simulate/payroll-connected
| Field | When present | Meaning |
|---|---|---|
| enrollment_id | Required | Identifier of the recurring giving arrangement; links its individual donations over time. |
| church_id | Required | Roster identifier of the church this record belongs to. |
Simulate the payroll vendor confirming the deduction removal (sandbox only) — POST /sandbox/simulate/payroll-disconnected
| Field | When present | Meaning |
|---|---|---|
| enrollment_id | Required | Identifier of the recurring giving arrangement; links its individual donations over time. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| outcome | Optional | Payroll provider result to simulate. success confirms the deduction was removed; error simulates the provider failing to remove it. Defaults to success. Allowed values: success, error. |
Simulate the payroll connection breaking (sandbox only) — POST /sandbox/simulate/connection-broken
| Field | When present | Meaning |
|---|---|---|
| enrollment_id | Required | Identifier of the recurring giving arrangement; links its individual donations over time. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| status | Optional | Payroll-connection state to simulate in the sandbox. Allowed values: user_action_required, unavailable, customer_disabled, degraded, active. |
Simulate the bank confirming an account closure (sandbox only) — POST /sandbox/simulate/account-closure
| Field | When present | Meaning |
|---|---|---|
| enrollment_id | Required | Identifier of the recurring giving arrangement; links its individual donations over time. |
| church_id | Required | Roster identifier of the church this record belongs to. |
Simulate the bank returning a settled gift days later (sandbox only) — POST /sandbox/simulate/late-return
| Field | When present | Meaning |
|---|---|---|
| church_id | Required | Roster identifier of the church this record belongs to. |
| occurrence_id | Required | Identifier of the individual donation being simulated. |
| return_code | Required | Bank code explaining a returned transfer, such as R03 for an account that could not be located. |
| leg | Optional | Which part of the transfer is being returned: church payment or fees. Allowed values: church, fee. |
| after_days | Optional | Number of days after transfer execution before the simulated return is due. The simulation is refused if that time has not passed. |
Simulate a KYC outcome (sandbox only) — POST /sandbox/simulate/kyc
| Field | When present | Meaning |
|---|---|---|
| enrollment_id | Optional | Roster identifier of the enrollment whose donor the identity result applies to. |
| donor_id | Optional | Roster identifier of the donor. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| outcome | Optional | Identity-verification result to simulate. passed lets the donor continue; review and failed both keep the donor on the in-review screen, and with failed no account is prepared. Defaults to passed. Allowed values: passed, review, failed. |
Simulate the donor's bank returning a refund (sandbox only) — POST /sandbox/simulate/refund-returned
| Field | When present | Meaning |
|---|---|---|
| refund_id | Required | Identifier of the refund the simulated donor's bank sends back. |
| return_code | Optional | Bank code explaining a returned transfer, such as R03 for an account that could not be located. |
What you can receive from us
Church
Appears in: POST /v1/churches → 200, 201; church in ImportItemResult; GET /v1/churches/{id} → 200.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Roster identifier of the church. |
| name | Required | Name of the church displayed to people. |
| created_at | Required | Date and time this record was created, in UTC. |
| reference | Optional | Your reference for this record, used to match it with your own system. |
| linked | Optional | Indicates the church was already registered and your platform was linked to its existing record. Allowed values: existing_church. |
| consents | Optional | Records of agreements the church accepted. Returned when reading a single church. See ChurchConsent. |
| payout_ready | Optional | Whether the church meets the church-level requirements to receive payments. Each donation still has its own checks and timing. |
| receiving_account_verified | Optional | Whether the current receiving account has been verified and its payment destination registered. |
| bank_verification | Optional | Result of checking the church’s receiving bank account, returned when the church is created or imported with an account. Not returned when reading the church later, nor when another platform registered the church first; the account you sent is then ignored. See BankVerification. |
| payout_schedule | Optional | When the church receives payouts: daily (the default, every weekday cutoff) or weekly (the next Monday after each deposit, or the next business day when Monday is a bank holiday). The money waits in the donor's account until then. Allowed values: daily, weekly. |
ChurchConsent
Appears in: consents in Church; POST /v1/church_consents → 200, 201.
| Field | When present | Meaning |
|---|---|---|
| church_id | Optional | Roster identifier of the church this record belongs to. |
| church_reference | Optional | Your church identifier, usable before a Roster church identifier exists. |
| document | Required | Name you give the agreement or permission the church accepted. |
| version | Required | Version of the agreement the church accepted. |
| accepted_at | Required | Date and time the church accepted the agreement; cannot be in the future. |
| method | Required | How the church accepted the agreement: terms of service, signed addendum, an in-product opt-in or another method. Allowed values: terms_of_service, signed_addendum, in_product_optin, other. |
| reference | Optional | Your reference for this record, used to match it with your own system. |
| received_at | Required | Date and time Roster received this record, in UTC. |
BankVerification
Appears in: bank_verification in Church; bank_verification in POST /v1/churches/{id}/bank-account → 200.
| Field | When present | Meaning |
|---|---|---|
| status | Required | Result of checking ownership of the receiving account: verified, already_verified, in_review, rejected or pending (recorded without a check, production only for now). Verification alone does not mean a particular donation is ready for payment. Allowed values: verified, in_review, rejected, already_verified, pending. |
| account_mask | Required | Last four digits of the bank account, so you can recognize it without exposing the full number. |
| institution_name | Required; may be null | Name of the bank, or null when unavailable. |
List churches — GET /v1/churches → 200
| Field | When present | Meaning |
|---|---|---|
| churches | Required | List of churches registered through your platform. See ChurchListItem. |
| next_cursor | Optional | Marker for requesting the next page of churches. When it is absent, you have every church. |
ChurchListItem
Appears in: churches in GET /v1/churches → 200.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Roster identifier of the church. |
| name | Required | Name of the church displayed to people. |
| reference | Optional | Your reference for this record, used to match it with your own system. |
| created_at | Required | Date and time this record was created, in UTC. |
| payout_ready | Required | Whether the church meets the church-level requirements to receive payments. Each donation still has its own checks and timing. |
Import churches in batch — POST /v1/churches/import → 200
| Field | When present | Meaning |
|---|---|---|
| results | Required | Result for each church sent in the import, in the same order. See ImportItemResult. |
ImportItemResult
Appears in: results in POST /v1/churches/import → 200.
| Field | When present | Meaning |
|---|---|---|
| index | Required | Position of the church in your import list, starting at 0. |
| status | Required | Created means a new import item succeeded; replayed means its earlier result was reused; rejected means this item could not be accepted. Allowed values: created, replayed, rejected. |
| church | Optional | Church record returned for a successful import item. See Church. |
| detail | Optional | Explanation of the result or problem, without repeating private values from your request. |
Register or replace the church's settlement account — POST /v1/churches/{id}/bank-account → 200
| Field | When present | Meaning |
|---|---|---|
| church_id | Required | Roster identifier of the church this record belongs to. |
| bank_verification | Required | Result of checking the church’s receiving bank account. See BankVerification. |
Set when the church receives its payouts — POST /v1/churches/{id}/payout-schedule → 200
| Field | When present | Meaning |
|---|---|---|
| church_id | Required | Roster identifier of the church this record belongs to. |
| payout_schedule | Required | When the church receives payouts: daily (the default, every weekday cutoff) or weekly (the next Monday after each deposit, or the next business day when Monday is a bank holiday). The money waits in the donor's account until then. Allowed values: daily, weekly. |
Submit legal details for an existing church — POST /v1/churches/{id}/verification → 202
| Field | When present | Meaning |
|---|---|---|
| status | Required | accepted means Roster queued the submission. It is not an approval and does not make the church ready for payouts. Allowed values: accepted. |
| request_id | Required | Reference of this legal-details submission. It stays the same when you repeat the same submission; give it to Roster support to locate it. |
FlowSettingsResponse
Appears in: GET /v1/flow-settings → 200; PUT /v1/flow-settings → 200.
| Field | When present | Meaning |
|---|---|---|
| version | Required | Version of the saved settings, to send back as expected_version when you save. Zero before the first save. |
| settings | Required; may be null | Saved donor-flow settings in the same shape the save request uses. Null means no settings have been saved. |
| settings.button_label | Optional | Text on the button in your own website that opens the donor flow. Required without church_id. With church_id, omit it to use the partner default. |
| settings.brand_color | Optional; may be null | Main brand color, written as a hash sign followed by six hexadecimal digits. Without church_id, omitting it (or sending null) removes the saved color and the donor flow uses its standard look. With church_id, omitting it uses the partner default. |
| settings.display_name | Optional | Name of your platform shown to the donor. |
| settings.support_contact | Optional | Support email address shown to the donor. |
| settings.logo_url | Optional | HTTPS address of the logo image you host. Today the donor flow shows it only on the amount screen, and donor sessions you create start after that screen. |
| settings.cta_label | Optional | Text on the continue button inside the Roster donor flow. Today the donor flow shows it only on the amount screen, and donor sessions you create start after that screen. |
| settings.manage_url | Optional | HTTPS address of the page in your account area where donors change or cancel their gift. Emails to donors who came through you link there. |
| settings.customization | Optional | Appearance settings and declaration of donor fields your platform intends to prefill. Always sent; with church_id it can be empty, and what it omits comes from the partner default. |
| settings.customization.customize_churches | Optional | Whether individual churches may override the partner appearance. Churches without their own settings use the partner defaults. Required without church_id. Not saved for a church; only the partner default turns church overrides on. |
| settings.customization.collected_fields | Optional | Names of donor fields your platform intends to prefill. This list contains no personal values; those are sent when opening each donor session. Required without church_id. With church_id, omit it to use the partner list. |
| settings.customization.css | Optional | Allowed appearance properties for Roster-controlled screens. Provider screens keep their own restrictions; arbitrary CSS selectors and remote resources are not accepted. Required without church_id. With church_id, properties you omit use the partner value. |
| settings.customization.css.background_color | Optional | Background color of the Roster donor flow. |
| settings.customization.css.text_color | Optional | Color of the main text. |
| settings.customization.css.button_color | Optional | Background color of action buttons. |
| settings.customization.css.button_text_color | Optional | Color of text inside action buttons. |
| settings.customization.css.input_background | Optional | Background color of fields where the donor types. |
| settings.customization.css.input_text_color | Optional | Color of text the donor types. |
| settings.customization.css.border_color | Optional | Color of borders around controls. |
| settings.customization.css.modal_width | Optional | Width of the donor-flow window, from 280 to 640 pixels. |
| settings.customization.css.border_radius | Optional | Rounding of the window’s corners, from 0 to 32 pixels. |
| settings.customization.css.button_radius | Optional | Rounding of button corners, from 0 to 32 pixels. |
| settings.customization.css.input_radius | Optional | Rounding of input-field corners, from 0 to 32 pixels. |
| settings.customization.css.font_size | Optional | Text size, from 14 to 24 pixels. |
| settings.customization.css.padding | Optional | Space inside the window’s edges, from 0 to 48 pixels. |
| settings.customization.css.gap | Optional | Space between elements, from 0 to 48 pixels. |
| settings.customization.css.line_height | Optional | Space between text lines, from 1.2 to 2 times the text size. |
| settings.customization.css.font_family | Optional | Typeface to use on Roster-controlled screens; choose one of the supported names. Allowed values: Inter, Arial, Georgia, system-ui, sans-serif, serif. |
| church_settings | Optional; may be null | Only for a church. The settings the church itself stores, on top of the partner default. Null means the church uses the partner default as is. Same fields as settings. |
| removed | Optional | Only in the response to a save. Saved properties the save took away, named by their path in the request body. Empty when nothing was removed. |
| skin | Required; may be null; deprecated | Saved appearance settings. Null means no settings have been saved. Same fields as settings, with camelCase names. |
AllowedOrigins
Appears in: GET /v1/allowed_origins → 200; PUT /v1/allowed_origins → 200.
| Field | When present | Meaning |
|---|---|---|
| origins | Required | Websites where your pages open the Roster donor flow, written as an HTTPS address with no path. |
DonorSession
Appears in: POST /v1/donor_sessions → 200, 201; GET /v1/donor_sessions/{id} → 200.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Identifier of this visit to the donor flow, not a donor identifier. |
| url | Optional | One-time link that opens the donor flow. Returned only at creation; its token expires after 30 minutes. |
| status | Required | Progress of this donor session. The current service reports created, opened, completed and expired. Other declared states are reserved and are not currently produced. Allowed values: created, opened, in_progress, completed, expired, abandoned, failed. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| mode | Required | How the recurring gift is calculated: pct is a percentage; fixed is a fixed dollar amount. Allowed values: pct, fixed. |
| value | Required | Giving amount for the selected mode: a percentage for pct, or US dollars for fixed. |
| expires_at | Required | Date and time the link or session stops being valid, in UTC. |
| reference | Optional | Your platform's identifier for the donor, as you sent it when creating the session. |
| fund | Optional | Fund or designation for the gift in your platform, as you sent it when creating the session. It does not change where money goes. |
| funds | Optional | How the donor split the gift among funds of the same church, as you sent it when creating the session: your fund identifier, the name, and the percent or the amount. It does not change where money goes. |
| funds[].id | Required when funds is provided and an item exists in funds | Your platform's identifier for the fund. Letters, digits, '.', '_', ':' and '-', up to 64 characters. |
| funds[].name | Optional | Name of the fund shown to the donor, such as Building Fund, up to 60 characters. |
| funds[].percent | Optional | Share of the gift for this fund, when the split was sent in percents. A fund has percent or amount, never both. |
| funds[].amount | Optional | US dollars per paycheck for this fund, as you sent it, when the split was sent in dollars for a fixed gift. A fund has percent or amount, never both. |
| enrollment_id | Optional | Identifier of the recurring gift this donor session created. Present once the session is completed. |
| donor | Optional; may be null | Verified donor of a completed session. Returned only where financial integration is enabled, which today is the sandbox; production returns null. Birth date, government identifiers, documents and bank details are not included. Null when unavailable. See IntegrationDonor. |
IntegrationDonor
Appears in: donor in DonorSession; donor in DonationSnapshot; payload.donor in FinancialEvent; payload.donor of donor.updated.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Roster identifier of the donor. |
| given_name | Required | Donor’s first name. An empty string means it is not available. |
| family_name | Required | Donor’s last name. An empty string means it is not available. |
| Required; may be null | Donor’s email address, or null when unavailable. | |
| phone | Required; may be null | Donor’s confirmed phone number, or null when unavailable. |
| updated_at | Required; may be null | Date and time this information last changed, in UTC. |
| address | Required | Donor’s mailing address. |
| address.line1 | Required | Street address, including any apartment or unit information supplied. An empty string means it is not available. |
| address.city | Required | City in the mailing address. An empty string means it is not available. |
| address.state | Required | Two-letter US state abbreviation, such as FL. An empty string means it is not available. |
| address.postal_code | Required | US ZIP code, with an optional four-digit extension. An empty string means it is not available. |
ManageSession
Appears in: POST /v1/manage_sessions → 200, 201.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Identifier of this visit to the manage flow, not a donor identifier. |
| url | Optional | One-time link that opens the manage flow. Returned only at creation; its token expires after 30 minutes. |
| status | Required | Whether the donor has opened the manage link. Allowed values: created, opened. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| enrollment_id | Required | Identifier of the recurring gift the donor will change or cancel. |
| expires_at | Required | Date and time the link or session stops being valid, in UTC. |
List enrollments of a church — GET /v1/enrollments → 200
| Field | When present | Meaning |
|---|---|---|
| enrollments | Required | List of recurring giving arrangements. One donor can have more than one arrangement. See Enrollment. |
| next_cursor | Optional | Marker for requesting the next page without starting again. No marker means there is no next page. |
Enrollment
Appears in: enrollments in GET /v1/enrollments → 200; GET /v1/enrollments/{id} → 200.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Identifier of this recurring giving arrangement. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| status | Required | Current state of the recurring giving arrangement. Active means it is enabled; it does not prove a donation was received. Allowed values: pending, active, paused, cancel_pending, cancelled, terminated, abandoned. |
| mode | Optional | How the recurring gift is calculated: pct is a percentage; fixed is a fixed dollar amount. Allowed values: pct, fixed. |
| value | Optional | Giving amount for the selected mode: a percentage for pct, or US dollars for fixed. |
| created_at | Optional | Date and time this record was created, in UTC. |
| updated_at | Optional | Date and time this information last changed, in UTC. |
| reference | Optional | Your platform's identifier for the donor, as you sent it when creating the session. |
| fund | Optional | Fund or designation for the gift in your platform, as you sent it when creating the session. It does not change where money goes. |
| funds | Optional | How the donor split the gift among funds of the same church, as you sent it when creating the session: your fund identifier, the name, and the percent or the amount. It does not change where money goes. |
| funds[].id | Required when funds is provided and an item exists in funds | Your platform's identifier for the fund. Letters, digits, '.', '_', ':' and '-', up to 64 characters. |
| funds[].name | Optional | Name of the fund shown to the donor, such as Building Fund, up to 60 characters. |
| funds[].percent | Optional | Share of the gift for this fund, when the split was sent in percents. A fund has percent or amount, never both. |
| funds[].amount | Optional | US dollars per paycheck for this fund, as you sent it, when the split was sent in dollars for a fixed gift. A fund has percent or amount, never both. |
Refund
Appears in: POST /v1/refunds → 200, 201; refunds in GET /v1/refunds → 200; GET /v1/refunds/{id} → 200; POST /v1/refunds/{id}/cancel → 200; payload in FinancialEvent; POST /sandbox/simulate/refund-returned → 200; payload of refund.created; payload of refund.updated.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Roster identifier of the refund. |
| object | Required | Kind of record; always refund. |
| donation_id | Required | Identifier of the individual donation this refund returns. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| amount_minor | Required | Amount returned to the donor, in US cents; 2500 means US$25.00. |
| currency | Required | Currency of the amount; USD means US dollars. |
| funds | Required; may be null | How much of the refund comes out of each fund of the donation's split, in US cents. Null when the donation has no split. |
| funds[].id | Required when funds is provided and an item exists in funds | Your platform's identifier for the fund. Letters, digits, '.', '_', ':' and '-', up to 64 characters. |
| funds[].amount_minor | Required when funds is provided and an item exists in funds | Part of this refund taken from the fund, in US cents; 2500 means US$25.00. |
| status | Required | Where the refund is: pending (on its way), requires_action (waiting for the donor's bank account), succeeded (received by the donor's bank), failed or canceled. Allowed values: pending, requires_action, succeeded, failed, canceled. |
| pending_reason | Required; may be null | What a pending refund waits for: in_review, awaiting_approval or processing (sent to the donor's bank). Null when the refund is not pending. |
| reason | Required | Why the donation is returned: duplicate, requested_by_donor, other, or after_cancellation for money Roster returns on its own because it arrived after the recurring gift was cancelled. Allowed values: duplicate, requested_by_donor, other, after_cancellation. |
| failure_reason | Required; may be null | Why a failed refund ended: not_refundable (Roster handles the donation directly) or bank_error. Null when the refund did not fail. |
| cancel_recurrence | Required | Whether the refund request also cancelled the donor's recurring gift. |
| metadata | Required; may be null | Your own labels for the refund, returned exactly as sent. Null when none were sent. |
| created_at | Required | Date and time the refund was created, in UTC. |
| updated_at | Required | Date and time this information last changed, in UTC. |
List the refunds of a donation — GET /v1/refunds → 200
| Field | When present | Meaning |
|---|---|---|
| refunds | Required | The refunds of the donation, oldest first. Empty when the donation has none. See Refund. |
Reconcile identified donations and bank outcomes — GET /v1/financial_events → 200
| Field | When present | Meaning |
|---|---|---|
| events | Required | List of notices about changes. A notice can contain several fields. See FinancialEvent. |
| next_cursor | Required; may be null | Resume point for your next poll. Store it with the page; an empty page means you are caught up, and a null value never replaces a stored marker. |
FinancialEvent
Appears in: events in GET /v1/financial_events → 200; webhook deliveries.
| Field | When present | Meaning |
|---|---|---|
| event_id | Required | Unique identifier of this notice. If it arrives again with the same identifier, do not count it as a new change. |
| event_id | Required when this response variant is used | Unique identifier of this notice. If it arrives again with the same identifier, do not count it as a new change. |
| event_type | Required | Kind of change reported by this notice. |
| event_type | Required when this response variant is used | Kind of change reported by this notice: refund.created when the refund is created, refund.updated on every later change. Allowed values: refund.created, refund.updated. |
| sequence | Required | Position of this notice in the partner’s financial history; used when reading changes in order. |
| sequence | Required when this response variant is used | Position of this notice in the partner’s financial history; used when reading changes in order. |
| occurred_at | Required | Date and time the reported change happened, in UTC. |
| occurred_at | Required when this response variant is used | Date and time the reported change happened, in UTC. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| church_id | Required when this response variant is used | Roster identifier of the church this record belongs to. |
| livemode | Required | Whether this notice comes from production (true) or from the sandbox (false). When one receiver gets notices from both, use it to keep test notices out of your real records. |
| livemode | Required when this response variant is used | Whether this notice comes from production (true) or from the sandbox (false). When one receiver gets notices from both, use it to keep test notices out of your real records. |
| entity_id | Required when this response variant is used | Identifier of the refund described by this notice. |
| entity_id | Required when event_type is donation.updated | Identifier of the individual donation described by this notice. |
| entity_id | Required when event_type is donor.updated | Identifier of the donor described by this notice. |
| payload | Required when this response variant is used | The whole refund, as GET /v1/refunds/{id} returns it at the moment of the change. See Refund. |
| payload | Required when event_type is donation.updated | Fields describing the change. The contents depend on the kind of notice. See DonationSnapshot. |
| payload | Required when event_type is donor.updated | Fields describing the change. The contents depend on the kind of notice. |
| payload.donor | Required when event_type is donor.updated | Authorized donor profile. An unknown email, phone or update time is null, and an unknown name or address line is an empty string. Government identifiers, birth date and documents are not exported. See IntegrationDonor. |
| payload.church_id | Required when event_type is donor.updated | Roster identifier of the church this record belongs to. |
| payload.revision | Required when event_type is donor.updated | Version of this record. Your software compares versions as text to avoid replacing newer data with an older notice. |
DonationSnapshot
Appears in: payload in FinancialEvent; payload of donation.updated.
| Field | When present | Meaning |
|---|---|---|
| revision | Required | Version of this record. Your software compares versions as text to avoid replacing newer data with an older notice. |
| id | Required | Identifier of this individual donation, not the recurring arrangement. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| enrollment_id | Required; may be null | Identifier of the recurring giving arrangement; links its individual donations over time. |
| donor_id | Required; may be null | Roster identifier of the donor. |
| method | Required | Donation method; paycheck means giving from payroll. |
| currency | Required | Currency of the amount; USD means US dollars. |
| amount_minor | Required; may be null | Actual donation deposit in US cents, before bank fees; 2500 means US$25.00. Never an expected future donation. Null means unknown. |
| status | Required | Current recorded stage of this donation. transfer_submitted means sent to the bank; transfer_accepted means accepted by the bank, not proof of final credit at the destination. confirmed is reserved until a bank-confirmation producer is connected. Returns can still occur. reversed means the whole donation was refunded to the donor; a partial refund does not change the status. Allowed values: received, in_review, pending_transfer, transfer_submitted, transfer_accepted, confirmed, returned, failed, reversed. |
| received_at | Required; may be null | When the donation deposit was received, in UTC; null means unknown. |
| updated_at | Required | Date and time this information last changed, in UTC. |
| residual_minor | Required; may be null | Recorded amount left for the donor, in US cents; null means unknown. |
| transfers | Required | Every recorded part of the payment across all attempts, including the church amount, fees and any refund recovery, with their recorded statuses. A returned part stays listed as returned; if it is sent again, the new transfer appears as another entry. |
| transfers[].role | Required when an item exists in transfers | Which part of the payment this is: church amount or fees. A fee entry does not prove a separate payment to the partner. Allowed values: church, fee. |
| transfers[].amount_minor | Required when an item exists in transfers; may be null | Amount of this part of the transfer, in US cents; 2500 means US$25.00. Null means unknown. |
| transfers[].reference | Required when an item exists in transfers; may be null | Bank reference identifying this transfer, or null when unavailable. |
| transfers[].status | Required when an item exists in transfers | Recorded stage of this part of the transfer. submitted means the instruction was sent to the bank; accepted means the bank reported it as executed, which does not prove final credit at the destination; returned means the bank returned it; unknown means the bank record does not say what happened to this part. Allowed values: submitted, accepted, returned, unknown. |
| return_details | Required; may be null | Details of a returned transfer, or null when no return is recorded. |
| return_details.role | Required when return_details is provided; may be null | Which part of the payment was returned: church or fee. Null means unknown. |
| return_details.code | Required when return_details is provided; may be null | Bank code explaining why a transfer was returned. |
| return_details.amount_minor | Required when return_details is provided; may be null | Amount returned for this part of the transfer, in US cents; 2500 means US$25.00. Null means unknown. |
| return_details.reference | Required when return_details is provided; may be null | Bank reference identifying this transfer, or null when unavailable. |
| return_details.occurred_at | Required when return_details is provided | Date and time the reported change happened, in UTC. |
| donor | Required; may be null | Authorized donor profile, or null when no profile can be supplied. In a supplied profile, an unknown email, phone or update time is null, and an unknown name or address line is an empty string. Government identifiers, birth date and documents are not exported. See IntegrationDonor. |
| donor_data_status | Required | Whether authorized donor profile data is available in this update. Allowed values: available, unavailable. |
| refunded_minor | Required | Total already returned to the donor from this donation, in US cents; 2500 means US$25.00. Counts only refunds the donor's bank received; 0 when nothing was returned. |
| funds | Optional | The amount of this donation for each fund of the gift's split, in US cents. Each amount is the donation in proportion to the fund's percent or amount, rounded so the amounts add up exactly to amount_minor: the cents left by rounding go to the funds with the largest remainders, and a tie goes to the fund listed first. A split in dollars reports exactly those dollars when the donation equals the gift. Absent when the gift has no split. Every fund is paid to the same church bank account. |
| funds[].id | Required when funds is provided and an item exists in funds | Your platform's identifier for the fund. Letters, digits, '.', '_', ':' and '-', up to 64 characters. |
| funds[].name | Optional | Name of the fund shown to the donor, such as Building Fund, up to 60 characters. |
| funds[].percent | Optional | Share of the gift for this fund, when the split was sent in percents. A fund has percent or amount, never both. |
| funds[].amount | Optional | US dollars per paycheck for this fund, as you sent it, when the split was sent in dollars for a fixed gift. A fund has percent or amount, never both. |
| funds[].amount_minor | Required when funds is provided and an item exists in funds; may be null | Amount of this donation for this fund, in US cents; 2500 means US$25.00. Null when the donation amount is unknown. |
| funds[].refunded_minor | Optional | Total already returned to the donor from this fund, in US cents, counting only refunds the donor's bank received. Never more than the fund's amount; the funds add up to the donation's refunded_minor. |
Read the activity event feed — GET /v1/events → 200
| Field | When present | Meaning |
|---|---|---|
| events | Required | List of notices about changes. A notice can contain several fields. See Event. |
| next_cursor | Required; may be null | Resume point for your next poll. Store it with the page; an empty page means you are caught up, and a null value never replaces a stored marker. |
Event
Appears in: events in GET /v1/events → 200; webhook deliveries.
| Field | When present | Meaning |
|---|---|---|
| event_id | Required | Unique identifier of this notice. If it arrives again with the same identifier, do not count it as a new change. |
| event_type | Required | Kind of change reported by this notice. Allowed values: partner_session.created, partner_session.opened, partner_session.completed, partner_session.expired, church.created, church.onboarded, enrollment.created, enrollment.activated, enrollment.updated, enrollment.paused, enrollment.resumed, enrollment.cancel_requested, enrollment.cancelled, enrollment.terminated, enrollment.onboarding_expired. |
| occurred_at | Required | Date and time the reported change happened, in UTC. |
| church_id | Required | Roster identifier of the church this record belongs to. |
| entity_id | Required | Identifier of the record that changed; the enrollment for enrollment notices, the donor session for donor session notices and the church for church notices. |
| livemode | Required | Whether this notice comes from production (true) or from the sandbox (false). When one receiver gets notices from both, use it to keep test notices out of your real records. |
| payload | Required | Fields describing the change. The contents depend on the kind of notice. |
WebhookEndpoint
Appears in: POST /v1/webhook_endpoints → 200, 201.
| Field | When present | Meaning |
|---|---|---|
| id | Required | Identifier of the registered receiving address. |
| url | Required | HTTPS address where Roster sends notices for this endpoint. |
| event_types | Required | Kinds of notices this address is subscribed to receive. |
| status | Required | Whether this receiving address is active or has been removed. Allowed values: active, deleted. |
| created_at | Required | Date and time this record was created, in UTC. |
| secret | Optional | Secret used to verify that a notice came from Roster. Returned only when the receiving address is created; save it securely. |
List active webhook endpoints — GET /v1/webhook_endpoints → 200
| Field | When present | Meaning |
|---|---|---|
| endpoints | Required | Addresses registered to receive automatic notices from Roster. |
| endpoints[].id | Required when an item exists in endpoints | Identifier of the registered receiving address. |
| endpoints[].url | Required when an item exists in endpoints | HTTPS address where Roster sends notices for this endpoint. |
| endpoints[].event_types | Required when an item exists in endpoints | Kinds of notices this address is subscribed to receive. |
| endpoints[].status | Required when an item exists in endpoints | Only active endpoints are listed. Allowed values: active. |
| endpoints[].created_at | Required when an item exists in endpoints | Date and time this record was created, in UTC. |
Send a test delivery — POST /v1/webhook_endpoints/{id}/test → 200
| Field | When present | Meaning |
|---|---|---|
| delivered | Required | Whether your receiving address answered successfully. This does not prove your software finished processing the notice. |
| status_code | Required; may be null | Response number returned by the receiving service; 200–299 means it acknowledged receipt. Null means no response number was recorded, which also happens when the address answered with a redirect. |
| reason | Required; may be null | Plain-language reason the test delivery failed, such as a redirect, a timeout, a refused connection or a response outside 200–299. Null when delivered is true. |
List recent deliveries — GET /v1/webhook_endpoints/{id}/deliveries → 200
| Field | When present | Meaning |
|---|---|---|
| health | Required | Summary of the last 50 delivery attempts to this address, based on the failures in a row up to the latest attempt and on how many of the 50 failed. |
| health.status | Required | broken means the latest 3 attempts failed, or 25 or more of the last 50 failed; degraded means the latest attempt failed, or 5 or more of the last 50 failed; healthy means neither; unknown means there is no attempt yet. Allowed values: healthy, degraded, broken, unknown. |
| health.consecutive_failures | Required | Failed attempts in a row, counted back from the latest attempt. 0 means the latest attempt was delivered or there is no attempt yet. |
| health.delivered | Required | Number of delivered attempts among the last 50. |
| health.failed | Required | Number of failed attempts among the last 50. |
| health.last_success_at | Required; may be null | Date and time of the latest delivered attempt among the last 50, in UTC. Null when none of them was delivered. |
| health.last_attempt_at | Required; may be null | Date and time of the latest attempt, delivered or not, in UTC. Null when there is no attempt yet. |
| deliveries | Required | Recorded attempts to send notices. Retrying one notice produces another attempt. See WebhookDelivery. |
WebhookDelivery
Appears in: deliveries in GET /v1/webhook_endpoints/{id}/deliveries → 200.
| Field | When present | Meaning |
|---|---|---|
| event_id | Required | Unique identifier of this notice. If it arrives again with the same identifier, do not count it as a new change. |
| event_type | Required | Kind of change reported by this notice. |
| attempted_at | Required | When this attempt ended (your endpoint answered or the call failed), in UTC. |
| outcome | Required | Delivered means the receiver acknowledged this attempt; failed means it did not. A later retry has its own attempt record. Allowed values: delivered, failed. |
| status_code | Required; may be null | Response number returned by the receiving service; 200–299 means it acknowledged receipt. Null means no response number was recorded, which also happens when the address answered with a redirect. |
List the sandbox test values (sandbox only) — GET /sandbox/fixtures → 200
| Field | When present | Meaning |
|---|---|---|
| test_donors | Required | Values for sandbox test donors in the hosted flow. |
| test_donors.phone_numbers | Required | Range of sandbox test phone numbers a test donor can use. Every sandbox account shares them. See SandboxRange. |
| test_donors.verification_code | Required | Code that verifies any sandbox test phone number; no text message is sent. |
| test_donors.identity_review_numbers | Required | Range of sandbox test phone numbers whose identity check is held in review. See SandboxRange. |
| test_donors.birth_date_rule | Required | Rule for the date of birth a sandbox test donor enters. |
| test_churches | Required | Values for sandbox test churches. |
| test_churches.verified_eins | Required | Range of sandbox EINs that verify a test church within seconds. See SandboxRange. |
| test_churches.manual_check_eins | Required | Range of sandbox EINs that hold a test church for a manual check. See SandboxRange. |
| test_churches.incorporation_date_rule | Required | Rule for the incorporation date of a sandbox test church. |
| test_churches.routing_number | Required | Valid routing number to use for sandbox test churches. |
| test_churches.account_number_endings | Required | Receiving-account result for each ending of a sandbox test account number. |
| test_refund_destination | Required | Test bank login a sandbox test donor uses to add the account that receives a refund. |
| test_refund_destination.username | Required | Username of the sandbox test bank login. |
| test_refund_destination.passcode | Required | Password of the sandbox test bank login; a public test value that works only in the sandbox. |
| test_refund_destination.rule | Required | How and when a sandbox test donor uses the test bank login. |
| documentation | Required | Address of the guide that explains the sandbox test values. |
SandboxRange (sandbox only)
Appears in: test_donors.phone_numbers in GET /sandbox/fixtures → 200; test_donors.identity_review_numbers in GET /sandbox/fixtures → 200; test_churches.verified_eins in GET /sandbox/fixtures → 200; test_churches.manual_check_eins in GET /sandbox/fixtures → 200.
| Field | When present | Meaning |
|---|---|---|
| from | Required | First value of a range of sandbox test values. |
| to | Required | Last value of a range of sandbox test values, included. |
Simulate a payroll deposit (sandbox only) — POST /sandbox/simulate/deposit → 202
| Field | When present | Meaning |
|---|---|---|
| status_code | Required | Response number returned by the receiving service; 200–299 means it acknowledged receipt. |
| simulated | Required | Details of the simulated notice sent to the sandbox. Acceptance does not prove all later processing has finished. |
| simulated.event_type | Required | Kind of change reported by this notice. |
| simulated.trace | Required | Reference the simulated bank used for this deposit; when you sent a trace, its form scoped to your account. |
| simulated.bank_ts | Required | Date and time reported by the simulated bank, in UTC. |
| eligible_at | Optional | When the test donation's processing window ends, 120 minutes after the bank timestamp, in UTC. From then on a settlement run can pick it up. |
| next_run_at | Optional | The earliest weekday 4:00 p.m. America/New_York settlement run that can pick up the test donation, in UTC. That run still checks the enrollment and the church. |
Simulate payroll connection (sandbox only) — POST /sandbox/simulate/payroll-connected → 202
| Field | When present | Meaning |
|---|---|---|
| status_code | Required | Response number returned by the receiving service; 200–299 means it acknowledged receipt. |
| expected_event | Required; may be null | The public event this simulation leads to — wait for it on your webhook and feed. enrollment.activated for a pending enrollment; null for a reconnection, because only the donor's own Resume emits enrollment.resumed. |
Simulate the payroll vendor confirming the deduction removal (sandbox only) — POST /sandbox/simulate/payroll-disconnected → 202
| Field | When present | Meaning |
|---|---|---|
| status_code | Required | Response number returned by the receiving service; 200–299 means it acknowledged receipt. |
| expected_event | Required; may be null | The public event this simulation leads to — wait for it on your webhook and feed. enrollment.cancelled for outcome success; null for error, which keeps the cancellation pending. |
Simulate the payroll connection breaking (sandbox only) — POST /sandbox/simulate/connection-broken → 202
| Field | When present | Meaning |
|---|---|---|
| status_code | Required | Response number returned by the receiving service; 200–299 means it acknowledged receipt. |
| expected_event | Required; may be null | The public event this simulation leads to — wait for it on your webhook and feed. enrollment.paused for the three breaking statuses; null for degraded and active, which deliberately emit nothing. |
Simulate the bank confirming an account closure (sandbox only) — POST /sandbox/simulate/account-closure → 202
| Field | When present | Meaning |
|---|---|---|
| status_code | Required | Response number returned by the receiving service; 200–299 means it acknowledged receipt. |
| simulated | Required | Details of the simulated notice sent to the sandbox. Acceptance does not prove all later processing has finished. |
| simulated.event_type | Required | Kind of change reported by this notice. Allowed values: account.closed. |
| simulated.trace | Required | Reference used to identify this simulated bank transaction. |
| simulated.bank_ts | Required | Date and time reported by the simulated bank, in UTC. |
Simulate the bank returning a settled gift days later (sandbox only) — POST /sandbox/simulate/late-return → 202
| Field | When present | Meaning |
|---|---|---|
| status_code | Required | Response number returned by the receiving service; 200–299 means it acknowledged receipt. |
| simulated | Required | Details of the simulated notice sent to the sandbox. Acceptance does not prove all later processing has finished. |
| simulated.event_type | Required | Kind of change reported by this notice. Allowed values: ach.transfer.returned. |
| simulated.trace | Required | Reference used to identify this simulated bank transaction. |
| simulated.bank_ts | Required | Date and time reported by the simulated bank, in UTC. |
| simulated.leg | Required | Which part of the transfer is being returned: church payment or fees. Allowed values: church, fee. |
| simulated.return_code | Required | Bank code explaining a returned transfer, such as R03 for an account that could not be located. |
Simulate a KYC outcome (sandbox only) — POST /sandbox/simulate/kyc → 202
| Field | When present | Meaning |
|---|---|---|
| status_code | Required | Response number returned by the receiving service; 200–299 means it acknowledged receipt. |
| simulated | Required | The outcome Roster's identity check received, as a code: ACCEPT for passed, REVIEW for review, REJECT for failed. Acceptance does not prove all later processing has finished. Allowed values: ACCEPT, REVIEW, REJECT. |
Problem
Appears in: every API error response.
| Field | When present | Meaning |
|---|---|---|
| type | Required | Address identifying the kind of API error. |
| title | Required | Short name of the API error. |
| detail | Required | Explanation of the result or problem, without repeating private values from your request. |
| request_id | Required | Reference you can give Roster support to locate this request. |
Webhook headers
Appears in: Event delivery to your endpoint; Test delivery to your endpoint.
| Header | When present | Meaning |
|---|---|---|
| Roster-Signature | Required | Signature sent with each webhook. Your software checks it with the endpoint secret to confirm the sender and detect changes to the message. |
| Roster-Webhook-Endpoint | Required | Identifier of the endpoint the webhook was sent to. It lets your software tell apart two endpoints on the same address and pick the secret that checks the signature. |
Event payload fields
| Field | Events | When present | Meaning |
|---|---|---|---|
| payload.donor | donor.updated | Required | Authorized donor profile. An unknown email, phone or update time is null, and an unknown name or address line is an empty string. Government identifiers, birth date and documents are not exported. See IntegrationDonor. |
| payload.church_id | donor.updated | Required | Roster identifier of the church this record belongs to. |
| payload.revision | donor.updated | Required | Version of this record. Your software compares versions as text to avoid replacing newer data with an older notice. |
| payload | donation.updated | Required | Fields describing the change. The contents depend on the kind of notice. See DonationSnapshot. |
| payload | refund.created, refund.updated | Required | Fields describing the change. The contents depend on the kind of notice. See Refund. |
| payload.donor_session_id | partner_session.created, partner_session.opened, partner_session.completed, partner_session.expired | Optional | Identifier of the donor’s visit to the giving flow. |
| payload.partner_id | partner_session.created | Optional | Identifier of the partner platform this session belongs to. |
| payload.church_id | partner_session.created, church.created, church.onboarded, enrollment.created | Optional | Roster identifier of the church this record belongs to. |
| payload.enrollment_id | partner_session.completed | Optional | Identifier of the recurring gift the donor created in this visit. |
| payload.name | church.created | Optional | Name of the church displayed to people. |
| payload.enrollment_id | enrollment.created | Optional | Identifier of the recurring giving arrangement; links its individual donations over time. |
| payload.mode | enrollment.created, enrollment.updated | Optional | How the recurring gift is calculated: pct is a percentage; fixed is a fixed dollar amount. Allowed values: pct, fixed. |
| payload.value | enrollment.created, enrollment.updated | Optional | Giving amount for the selected mode: a percentage for pct, or US dollars for fixed. |
| payload.reference | enrollment.created | Optional | Your platform's identifier for the donor, as you sent it when creating the session. |
| payload.fund | enrollment.created | Optional | Fund or designation for the gift in your platform, as you sent it when creating the session. It does not change where money goes. |
| payload.funds | enrollment.created | Optional | How the donor split the gift among funds of the same church, as you sent it when creating the session: your fund identifier, the name, and the percent or the amount. It does not change where money goes. |
| payload.funds[].id | enrollment.created | Optional | Your platform's identifier for the fund. Letters, digits, '.', '_', ':' and '-', up to 64 characters. |
| payload.funds[].name | enrollment.created | Optional | Name of the fund shown to the donor, such as Building Fund, up to 60 characters. |
| payload.funds[].percent | enrollment.created | Optional | Share of the gift for this fund, when the split was sent in percents. A fund has percent or amount, never both. |
| payload.funds[].amount | enrollment.created | Optional | US dollars per paycheck for this fund, as you sent it, when the split was sent in dollars for a fixed gift. A fund has percent or amount, never both. |
| payload.expected_amount | enrollment.activated | Optional; may be null | Expected amount of a future payroll gift in US dollars. This is an estimate, not money received. null for a percentage gift — Roster never sees the paycheck, so there is no dollar amount to expect; treat it as unknown, never as zero. |
| payload.expected_cycle | enrollment.activated | Optional | Estimated date and time, in UTC, of the first payroll cycle after activation, used to anticipate the next donation. Set once at activation and not updated afterwards. |
| payload.reason | enrollment.paused | Optional | Code for why giving paused; not a free-form explanation. donor_requested: the donor paused giving until resume_at. payroll_connection_broken: the paycheck connection stopped working; no resumption is scheduled. transfer_confirmation_overdue: the donor has not confirmed, through the link Roster emailed, that transfers may go out. Absent when Roster paused giving on its side. Allowed values: donor_requested, payroll_connection_broken, transfer_confirmation_overdue. |
| payload.resume_at | enrollment.paused | Optional | Planned date and time to resume giving, in UTC, when a resumption is scheduled. |
| payload.resumed_from | enrollment.resumed | Optional | What made giving resume. donor: the donor resumed it. schedule: the planned resume_at of the pause arrived. transfer_confirmation: the donor confirmed, through the link Roster emailed, that transfers may go out. Allowed values: donor, schedule, transfer_confirmation. |
| payload.cancellation_business_days | enrollment.cancelled | Optional | Number of business days recorded for the cancellation to take effect. |
| payload.effective_at | enrollment.cancelled | Optional | Calendar date the cancellation takes effect, written as YYYY-MM-DD in the America/New_York time zone. |
| payload.reason | enrollment.terminated | Optional | Code for how the enrollment ended, sent only for the codes listed here. connection_lost: the paycheck connection stopped and was not restored in time. Allowed values: connection_lost. |
| payload.reason | enrollment.onboarding_expired | Optional | Code for why the enrollment closed. onboarding_ttl: setup was not finished within the allowed time. Allowed values: onboarding_ttl. |
Test delivery to your endpoint (webhook.test)
| Field | When present | Meaning |
|---|---|---|
| event_id | Required | Unique identifier of this notice. If it arrives again with the same identifier, do not count it as a new change. |
| event_type | Required | Kind of change reported by this notice. |
| occurred_at | Required | Date and time the reported change happened, in UTC. |
| livemode | Required | Whether this test was sent from production (true) or from the sandbox (false), as on every notice. |
| payload | Required | Fields describing the change. The contents depend on the kind of notice. |
| payload.message | Optional | Text identifying this as a connection test, not a real donation. |
