Skip to main content

Bloomerang Connector (Technical Documentation)

Written by Philippe Trussart

Overview

The Bloomerang connector provides read-only access to Bloomerang CRM data through the Bloomerang v2 API. It retrieves constituent, transaction, interaction, communication, custom field, fundraising, and related reference data.

The connector does not create, update, or delete records in Bloomerang.

All records use:

Id

as the unique key.

Authentication

The connector requires a Bloomerang:

private_key

The key is sent with every request using:

X-API-KEY: {private_key}

The API base URL is:

https://api.bloomerang.co/v2/

The connection test performs:

GET /addresses

and succeeds when Bloomerang returns a successful response. Invalid credentials return a specific authentication error.

API Requests

The connector uses GET requests only. There are no POST, PUT, PATCH, or DELETE operations.

For paginated endpoints, requests follow this pattern:

GET /{endpoint}?skip={offset}&take=50

The page size is fixed at:

50 records

The connector increases skip by 50 until the API indicates that there are fewer than 50 records remaining.

Some reference/custom-field endpoints are marked as non-paginated and are retrieved in a single request.

Sync Behavior

Most Bloomerang tables are fully re-read on every sync.

The main exception is:

interactions

which supports incremental synchronization.

Incremental interaction sync

After the first full load, the connector stores a last_started bookmark.

On subsequent interaction syncs it requests records ordered by:

LastModifiedDate DESC

and processes records from newest to oldest.

Once it encounters a record whose:

AuditTrail.LastModifiedDate

is less than or equal to the previous bookmark, it stops requesting additional records.

The new bookmark is the UTC time at which the current sync started, rather than the timestamp of the last record returned.

First interaction sync

Initial/default bookmark values are recognized as indicating that no real incremental checkpoint exists yet. In that situation, interactions is fully loaded before incremental mode begins.

An interaction stream can also be configured to perform a full re-read instead of using incremental mode.

Schema & Raw API Data

Bloomerang tables use a predefined column mapping rather than dynamically creating columns from each response.

This means newly introduced Bloomerang fields will not automatically become dedicated columns until the connector mapping is updated.

However, every record also contains:

json_record_data

This field preserves the complete original API response object before unmapped fields are removed.

This is useful when:

  • Bloomerang adds a new field that has not yet been formally mapped.

  • A developer needs access to nested API data.

  • A field is needed for troubleshooting or downstream modeling.

Missing mapped fields are returned as NULL rather than causing the record to fail.

Nested Data

Several Bloomerang records contain arrays or objects, including data such as:

  • Audit information

  • Primary contact information

  • Communication restrictions

  • Custom values

  • Transaction designations

  • Membership information

  • Attachments

  • Household members

These values remain structured rather than being fully flattened into separate relational tables or columns.

Consumers may therefore need to parse nested fields or use json_record_data for more detailed analysis.

Deletes

The connector does not explicitly synchronize deletes.

There is:

  • No deletion endpoint.

  • No delete-event feed.

  • No comparison against previous source snapshots to identify missing records.

  • No delete message generated when a Bloomerang record is removed.

Therefore, a record deleted in Bloomerang will not be explicitly communicated as a deletion by this connector.

This applies even to tables that are fully re-read on each execution.

Retries & Rate Limits

The connector automatically retries temporary API failures.

For normal failures:

Retry delay: 30 seconds Maximum retries: 5

HTTP 429 rate-limit responses use a longer exponential delay:

1st retry:  300 seconds 2nd retry:  600 seconds 3rd retry: 1200 seconds 4th retry: 2400 seconds 5th retry: 2400 seconds

The maximum rate-limit delay is 2,400 seconds (40 minutes).

This means large syncs can take considerably longer when the Bloomerang API begins returning rate-limit responses.

Known Limitations & Notable Behavior

  • Most tables are not incremental. They are fully re-read each time the connector runs. Only interactions is explicitly configured for incremental synchronization.

  • Deletes are not propagated. A deleted Bloomerang record does not generate a downstream delete event.

  • Schemas are predefined. Newly added API fields will not automatically appear as dedicated columns, although the original response is preserved in json_record_data.

  • Incremental interaction sync depends on AuditTrail.LastModifiedDate. Records without this value cannot be used to determine the incremental stopping point.

  • Incremental filtering happens while paging rather than through a LastModifiedDate API filter. The connector requests interactions ordered newest-first and continues paging until it reaches the previous bookmark. Large amounts of recently modified interaction data can therefore require many API requests.

  • Pagination is limited to 50 records per request. Large tables may require a substantial number of API calls.

  • Rate limiting can introduce long delays. Repeated 429 responses can result in waits of up to 40 minutes between attempts.

  • All tables use Id as the unique key. Consumers should use this field when joining repeated sync results or identifying the same source record across executions.

Did this answer your question?