Skip to main content

Raiser's Edge Connector (Technical Reference)

Written by Philippe Trussart
Updated over 2 weeks ago

Overview

The Raiser’s Edge connector syncs data from Blackbaud Raiser’s Edge NXT (via the SKY API) into your data warehouse.

It pulls:

  • Constituents and their contact info

  • Gifts, funds, campaigns, appeals and packages

  • Opportunities and fundraiser assignments

  • Event records and event participants

  • Key constituent flags via the SKY Query APIs (no-valid-address, solicit codes, etc.)

The connector is read-only and does not write anything back to Raiser’s Edge.

Authentication

The connector uses the SKY API OAuth2 flow:

  • OAuth base URL: https://oauth2.sky.blackbaud.com/

  • API base URL: https://api.sky.blackbaud.com/

You’ll need:

  • A SKY API application configured in Blackbaud’s developer portal

  • Client ID / client secret

  • An access token and refresh token with permissions to the endpoints listed below

Tokens are passed in HTTP headers on each request; the connector handles refreshing when tokens expire.

High-level Sync Strategy

Streams / tables

The connector exposes the following logical tables:

  1. actions

  2. addresses

  3. appeals

  4. appeals_custom_fields

  5. campaigns

  6. constituent_addressee_and_salutation

  7. constituent_codes

  8. constituent_custom_fields

  9. constituent_no_valid_address

  10. constituent_requests_no_email

  11. constituent_solicit_codes

  12. constituents

  13. educations

  14. email_addresses

  15. event_participants

  16. events

  17. fundraiser_assignments

  18. funds

  19. gift_custom_fields

  20. gifts

  21. memberships

  22. notes

  23. online_presences

  24. opportunities

  25. packages

  26. phones

  27. relationships

Each of these tables has a configured set of columns defined in table_endpoint_index inside the connector. This schema is what gets written out during discovery.

Discovery

When you run discover:

  • The connector loops through every configured stream name.

  • It inspects the column definitions and, if there is an id field, marks it as the unique key.

  • It emits the full JSON schema for that table to the catalog.

  • It also writes initial state for each stream:

    • memberships starts at 1754-01-01 00:00:00

    • All other tables start at 0001-01-01 00:00:00

These last_started timestamps are later used as the starting point for incremental syncs.

Incremental vs truncate-and-reload

There are two main sync patterns:

  1. Standard API endpoints
    For most tables (e.g., constituents, gifts, addresses, etc.), the connector calls the corresponding SKY API “list” endpoints (like constituent/v1/constituents) and uses date fields such as date_modified or date_added to advance the state watermark.

  2. Query-based tables (SKY Query API)
    For these four logical tables:

    • constituent_solicit_codes

    • constituent_addressee_and_salutation

    • constituent_no_valid_address

    • constituent_requests_no_email

    the connector uses the SKY Query API instead of standard list endpoints:

    • It discovers the numeric query type ID from query/querytypes.

    • It looks up node IDs and field IDs for each configured column (node and fieldName in the config).

    • It then runs a query instance and streams the results.

    For query-based tables, every sync is a truncate-and-reload:

    $this->singer->writeTableAction($table, 'truncate');
    ``` :contentReference[oaicite:11]{index=11}  

    However, the query itself usually filters on **“Constituent Date Last Changed”** (`date_modified` column) so you can still think of it as time-bounded by that date in practice.

Deceased / inactive flags

Several tables include configuration flags:

  • has_deceased on constituents

  • has_inactive on:

    • constituents

    • addresses

    • email_addresses

    • online_presences

    • campaigns

    • appeals

    • packages

    • funds

    • opportunities

    • events

The connector uses these flags to include or exclude deceased or inactive records via the corresponding query parameters in SKY API calls.

Custom sync methods

Two tables are not simple list calls; they use custom logic:

  • fundraiser_assignments

    • Endpoint: fundraising/fundraisers/types

    • Method: syncFundraiserAssignments (walks assignment data across funds, campaigns, and appeals).

  • event_participants

    • Endpoint: event/eventlist

    • Method: syncEventParticipants

    • For each event, the connector calls the participants endpoint and flattens the participant data into the event_participants table.

Because these are composed from multiple underlying calls, they behave more like snapshot tables (data refreshed on each run) instead of purely incremental feeds.

Timeouts and retries

  • Default HTTP timeout: 600 seconds.

  • The connector keeps an internal timeout counter and will log/handle timeouts gracefully (exact retry behavior is implemented in the shared HTTP helper).

In practice, for very large datasets we recommend shorter sync windows (e.g., smaller date ranges or more frequent runs) to avoid long-running queries.

Deletes

The connector does not implement incremental deletes:

  • If a record is deleted in Raiser’s Edge, it will not be explicitly deleted from your warehouse by this connector.

  • To reflect deletes, you will need:

    • Either a downstream soft-delete strategy, or

    • Periodic full reloads (truncate & re-sync) of specific tables.

Supported Tables and Endpoints

Below is a reference of each logical table, what it represents, and how it’s populated.

Constituent-centric tables

constituents

  • Description: Core constituent profile records (individuals and organizations).

  • Endpoint: constituent/v1/constituents

  • Includes fields like: name parts, lookup ID, marital status, age, birthdate, deceased flag and date, fundraiser status, online presence, email and phone info, etc.

  • Special: has_deceased, has_inactive flags used to include/exclude filtered segments.

addresses

  • Description: Postal addresses for constituents.

  • Endpoint: constituent/v1/constituents/{id}/addresses (via endpoint_call = addresses).

  • Includes: formatted address, address lines, city, state, postal code, country, seasonal dates, do-not-mail, inactive, start/end dates, etc.

email_addresses

  • Description: Email addresses per constituent.

  • Endpoint: constituent/v1/constituents/{id}/emailaddresses

  • Includes: address, do-not-email flag, primary flag, inactive, timestamps.

phones

  • Description: Phone numbers per constituent.

  • Endpoint: constituent/v1/constituents/{id}/phones

  • Includes: number, type, do-not-call flag, primary flag, inactive, timestamps.

online_presences

  • Description: Online presence / social handles for each constituent.

  • Endpoint: constituent/v1/constituents/{id}/onlinepresences

  • Includes: address (e.g., URL or handle), type, primary, inactive, timestamps.

memberships

  • Description: Membership records associated with constituents.

  • Endpoint: constituent/v1/constituents/{id}/memberships

  • Includes: category, program, standing, subcategory, membership dates, dues (JSON), member list (JSON).

  • Initial state: older “start” date than other tables (1754-01-01).

educations

  • Description: Education history for constituents.

  • Endpoint: constituent/v1/constituents/{id}/educations

  • Includes: school, campus, degrees, majors/minors, class year, GPA, status, dates entered/left/graduated, etc.

actions

  • Description: Interactions/actions (meetings, calls, tasks) tied to constituents and opportunities.

  • Endpoint: constituent/v1/constituents/{id}/actions

  • Includes: dates, description, status, direction, start/end times, outcome, priority, associated opportunity, and fundraiser assignments (JSON list).

notes

  • Description: General notes recorded on constituents.

  • Endpoint: constituent/v1/constituents/{id}/notes

relationships

  • Description: Relationships between constituents (spouse, business, organization contact, etc.).

  • Endpoint: constituent/v1/constituents/{id}/relationships

  • Includes: relation ID, reciprocal relationship, organization contact flags, spouse flag, position, dates, comments.

constituent_custom_fields

  • Description: Custom fields stored on constituents.

  • Endpoint: constituent/v1/constituents/customfields

  • Includes: category, value, date, comments, parent ID, type.

constituent_codes

  • Description: Constituent code assignments (e.g. “Board Member”, “Alumnus”).

  • Endpoint: constituent/v1/constituents/constituentcodes

  • Includes: description, start/end dates, inactive flag, sequence, etc.

Fundraising structure

campaigns

  • Description: Campaign records.

  • Endpoint: fundraising/v1/campaigns

  • Includes: category, description, lookup ID, start/end dates, goals, inactive flag.

appeals

  • Description: Appeal records under campaigns.

  • Endpoint: fundraising/v1/appeals

packages

  • Description: Packages (segments/mailings) under appeals.

  • Endpoint: fundraising/v1/packages

funds

  • Description: Fund records (program/fund designations).

  • Endpoint: fundraising/v1/funds

Gifts & opportunities

gifts

  • Description: Gift/pledge records including splits, acknowledgements, and recurring schedules.

  • Endpoint: gift/v1/gifts

  • Includes: amount, balance, batch, post status, gift code and type, gift splits, soft credits, fundraisers, receipts, schedules, and various status fields.

gift_custom_fields

  • Description: Custom fields on gifts.

  • Endpoint: gift/v1/gifts/customfields

opportunities

  • Description: Major gift or opportunity records.

  • Endpoint: opportunity/v1/opportunities

  • Includes: ask amount/date, expected and funded amounts/dates, campaign, fund, purpose, status, linked gifts, fundraisers, deadline, etc.

fundraiser_assignments

  • Description: Assignments of fundraisers to constituents, campaigns, appeals, and funds (goals and time periods).

  • Endpoint: fundraising/v1/fundraisers/types (with custom walker method).

Events

events

  • Description: Event header records.

  • Endpoint: event/v1/eventlist

  • Includes: lookup ID, name, start/end dates and times, capacity, attendance stats, revenue, goal, percent of goal, category, etc.

event_participants

  • Description: Participants for each event, flattened into a single table.

  • Endpoint: Derived from event/v1/eventlist via syncEventParticipants.

  • Includes: contact/constituent identifiers, name components, contact flags (do not call/email), participation level, RSVP and invitation status, seat info, membership and registration details, donations and revenue attributed to the participant.

Query-based helper tables

These tables are powered by the SKY Query API and are always fully refreshed:

constituent_solicit_codes

  • Query type: Constituent

  • Columns:

    • constituent_id (from Constituent Information → Constituent ID)

    • solicit_code (from Solicit Codes → Solicit Code Description)

    • date_modified (from Constituent Information → Constituent Date Last Changed)

constituent_addressee_and_salutation

  • Query type: Constituent

  • Columns:

    • constituent_id

    • primary_addressee

    • primary_salutation

    • date_modified (also using Constituent Date Last Changed).

constituent_no_valid_address

  • Query type: Constituent

  • Columns:

    • constituent_id

    • no_valid_address (boolean, “No Valid Addresses?”).

constituent_requests_no_email

  • Query type: Constituent

  • Columns:

    • constituent_id

    • requests_no_email (boolean, “Requests No Email?”).

These helper tables make it easier to create downstream segments such as “valid mailing addresses only” or “no email requests” without reproducing the SKY Query definitions.

Operational Considerations & Known Limitations

  1. No hard deletes

    • Records deleted in Raiser’s Edge are not automatically removed from your warehouse data.

    • Plan periodic full reloads or use soft-delete logic downstream if you need to detect removals.

  2. Query-based tables are truncate-and-reload

    • constituent_solicit_codes, constituent_addressee_and_salutation, constituent_no_valid_address, and constituent_requests_no_email are always fully refreshed.

    • On very large databases, this can be relatively heavy; schedule these less frequently if needed.

  3. Large datasets and timeouts

    • The connector uses a 600-second HTTP timeout. Long-running queries on very large tenants can hit this limit.

    • If you frequently see timeouts, consider:

      • Running syncs more frequently (smaller deltas)

      • Disabling rarely used streams

      • Splitting jobs by stream.

  4. Membership baseline date

    • Memberships use a different start watermark (1754-01-01) which effectively pulls all historical memberships on first run.

  5. Typographical quirks in field names

    • Some field names reflect the exact SKY objects and may include spelling inconsistencies (for example, memebers in the memberships stream, or online_presense in constituents).

    • Do not “correct” these names when building SQL; use them exactly as they appear in the schema.

  6. API permissions

    • Access to some streams (e.g., gifts, opportunities, query endpoints) depends on the scopes granted to your SKY API app and user.

    • If a stream returns errors, verify that your app and user have appropriate permissions in Blackbaud.

Did this answer your question?