Create an active API Keys 2.0 key for a Bloomerang administrator and paste it again. Empty keys are rejected before Gratona contacts Bloomerang.
Connect Bloomerang
Updated 3 weeks ago
Connect Bloomerang in Connected Apps, finish your mappings, preview the matches, then click Turn on record sync. Adding the API key alone does not start syncing.
For connection health and reconnect, use Connected Apps.
Gratona.
What to know before you set up
These six ideas explain how Bloomerang works in Gratona. Read them once before you map fields or turn sync on.
Connecting is not the same as syncing
When you paste your Bloomerang API key, Gratona only saves the connection. Nothing moves yet.
Sync starts only after you finish mapping, review matches, and click Turn on record sync.
Gratona remembers the linked person first
After a Bloomerang constituent is linked to a Gratona donor, that saved link is the main identity. Email is only a helper the first time, when no link exists yet.
If more than one donor could match the same email, Gratona creates a conflict for you to review. It does not pick one automatically.
Direction and "sync on" are different settings
Sync flow chooses which way updates can move. Turning sync on is a separate step.
Two-way sync (default): updates can move both ways
Gratona updates Bloomerang: Gratona sends changes to Bloomerang only
Bloomerang updates Gratona: Bloomerang sends changes into Gratona only
Choosing a direction does not turn sync on.
Every gift needs a clear destination
Map Gratona programs and designations to Bloomerang funds, campaigns, or appeals so each gift knows where to go.
If Gratona cannot tell which destination owns a gift, it creates a conflict instead of guessing. A fallback recipient is only for gifts with no matching map—not for unclear maps.
Past gifts and live sync are different jobs
Load history first. Turn on day-to-day sync second.
To bring in past Bloomerang data:
Connect Bloomerang and finish your donor, destination, and gift mappings.
Use the approved migration path at Data & Imports → Imports for the controlled historical load.
In the Bloomerang setup, turn on Historical backfill safeguards when you import history from the connection. That option preserves populated donor and household details, records imported gifts with External Processor, and keeps migration activity out of donor communications.
Use Import from Bloomerang or import reviewed changes for the history load while safeguards are on. Do not click Turn on record sync yet if you are still loading and reconciling the past.
To run day-to-day sync after history is in place:
Finish sync setup, choose when Gratona should start checking for changes, and review donor and household matches.
Click Turn on record sync only when you want ongoing updates going forward.
Live sync watches for new and changed records after that starting point. It is not the bulk history load. Historical imports can also hold back outbound sync and donor notices while old records are created, and they do not charge cards through a live payment gateway.
Conflicts protect your data
When identity, gift routing, or related gift details are unclear, Gratona stops and marks a conflict. That is intentional. Open the conflict, fix the mapping or match, then continue.
Before you start
Get a Bloomerang administrator API key and decide where donors and gifts should land in Gratona.
In Bloomerang, open My Profile, API Keys and create an active API Keys 2.0 key for an administrator.
In Gratona, make sure you can open Settings → Connected Apps.
Choose the donor form that should receive Bloomerang people.
Choose the programs or designations that should receive Bloomerang gifts.
Turn off any Zapier Zaps or other tools that already update the same donors, gifts, groups, or designations. Gratona does not find or disable those for you.
The connection belongs to your whole workspace. Another admin with Connected Apps access can finish setup after the key is saved. You can replace the key with another administrator key only if it belongs to the same Bloomerang database.
Gratona stores the key securely on the server. Most organizations connect with an API key. Sign-in with OAuth is only for approved partner setups.
Connect Bloomerang
Add Bloomerang in Connected Apps and paste your API key.
Open Settings → Connected Apps.
Click Add provider.
Choose Bloomerang.
Click Add provider on the Bloomerang card.
Paste the key into Paste a Bloomerang API Keys 2.0 key.
Finish the connection. You may see Bloomerang added to Connected Apps. or Bloomerang connected successfully.
If the card already says Already added, open that card and click Manage. Do not add Bloomerang a second time.
If Bloomerang rejects the key, create a new active API Keys 2.0 key for an administrator and try again.
Check the connection
Open the Bloomerang card, click Manage, and confirm the connection looks healthy before you map data.
Check connection status and health status
Click Refresh status to run a health check
Open Sync History to see later runs
Open conflicts when a record needs review
Before the first import or send, Sync History shows No sync runs yet.
Choose the sync direction
If you see Sync flow, pick the direction before you rely on ongoing updates.
Two-way sync — default; both systems can send supported updates
Gratona updates Bloomerang — only Gratona sends changes to Bloomerang
Bloomerang updates Gratona — only Bloomerang sends changes into Gratona
This setting does not start sync. You still need Turn on record sync.
Map donors
On the Donors tab, choose the form, match fields, and save.
Open Bloomerang and go to Donors.
Choose the Donor form.
Match Gratona donor fields to Bloomerang constituent fields, including the field that stores the Bloomerang person ID for the saved link.
Turn on Match existing donors by email only if you want first-time email matching when no saved link exists.
Click Save donor setup.
If field names look out of date, click Refresh Bloomerang fields.
Fields appear in groups:
System fields — built-in Gratona fields, including Email
Standard donor fields — when the form uses standardized fields
Custom donor fields — fields from your selected form
Map system Email to Bloomerang Primary email. A second Email row appears only if your form also has a custom field named Email.
Default matches usually cover email, first name, last name, organization name, phone, and address.
How matching works:
If a Bloomerang person is already linked to a donor, Gratona uses that link.
If there is no link yet, optional email matching looks for the same primary email on the selected form.
If more than one donor could match, Gratona creates a conflict instead of updating someone automatically.
Bloomerang Status is copied to the donor. Gratona treats Active and Deceased as active statuses and Archived as archived. A deceased donor can show as deceased on the profile.
Map households and relationships
Household and relationship setup is included so family and related-contact structure can sync with donors.
Household defaults cover id, name, head, and members. Relationship defaults cover the two people and each role name.
Choose a donor form before you import donors, households, or relationships.
Import Bloomerang groups as tags
On donor setup, you can turn on Import Bloomerang groups as donor tags.
When a linked donor belongs to a Bloomerang group, Gratona can add a matching donor tag. Tags stay in Gratona. They are not written back as Bloomerang groups.
This only imports groups that already exist in Bloomerang. Gratona does not create a Child Sponsor group or field from active sponsorships.
If a group name conflicts, resolve the conflict before group membership can sync.
Map programs and gift destinations
On Recipients, tell Gratona which Bloomerang fund, campaign, or appeal belongs to which program or designation.
Open the Recipients tab.
Choose Bloomerang fund, Bloomerang campaign, or Bloomerang appeal.
Pick the Bloomerang item and the Gratona destination.
Optionally choose a Specific Gratona designation (optional).
Click Add Bloomerang program mapping.
Add as many rows as you need. The table shows Bloomerang target and Gratona destination. If you have not added any yet, you see No program or designation mappings yet.
More than one Gratona destination can share the same Bloomerang target when you send gifts out. When a gift comes in from Bloomerang to a shared target, Gratona needs a more specific mapping. If it still cannot tell which destination owns the gift, it creates a conflict.
Set a Fallback recipient only for gifts that have no matching map.
Map donations and soft credits
On donations setup, match gift fields, set a fallback if needed, and choose whether soft credits are included.
Open the donations setup.
Match donation fields as needed.
If some gifts will not match a map, set a Fallback recipient. Choose the program first, then the recipient.
Optionally turn on Include soft credit details. Soft credits sync only when the related donor is already linked.
Click Save donation setup.
Before you import Bloomerang gifts, either set a fallback recipient or map at least one fund, campaign, or appeal.
Default gift fields include transaction id, transaction number, account, amount, date, note, designations, soft credits, and refunds.
For split payments, each part needs its own valid Bloomerang destination, a positive amount, and parts that add up to the full payment. If that is not true, Gratona stops and creates a conflict. Older payments are grouped only when Gratona already has reliable group information.
Recurring schedules and pledge principals are commitments, not completed gifts. Import them as non-charging External Processor commitments. Completed gift transactions can still come through as gifts.
Preview, then import
Preview first. A preview does not create or change donors, households, gifts, payment methods, or messages.
Choose Records to review if asked.
Click Review record matches, Review changes, or Review recent changes when sync is paused.
Check the preview. You may still see history of what was reviewed.
When the preview looks right, click Import reviewed changes or Import from Bloomerang.
You may see Import from Bloomerang queued.
If you are loading old Bloomerang gifts, turn on Historical backfill safeguards and use the migration path first. Keep record sync off until history is loaded and checked. Then use Finish sync setup and Turn on record sync for ongoing updates only.
Turn on record sync
When mapping and preview look right, start ongoing sync.
Confirm the donor form, field maps, starting point, and conflict handling are ready.
Click Turn on record sync.
Open Sync History after the first runs to confirm activity.
Click Send Gratona updates when you need to push pending Gratona changes, if your direction allows it.
When sync turns on, Gratona saves its place for households, donors, donations, soft credits, refunds, notes, tasks, and interactions. Pending sends that were waiting before activation are held back so they do not mix into the new starting point.
After that:
Bloomerang changes are checked about every five minutes
Bloomerang groups are checked once a day
There are no Bloomerang webhooks for this connection
Gratona-to-Bloomerang updates go out when sync is on and the direction allows it
Pause or resume sync
Click Pause record sync to stop automatic updates without wiping your setup.
While paused:
Automatic imports from Bloomerang and automatic sends to Bloomerang stop
Your mappings and saved place stay in place
You can still review recent Bloomerang changes without moving records
New Gratona changes made while paused are not saved to send later
Sends that were already waiting are held back
Click Resume record sync to continue from the saved place. Resume does not restart from the beginning of history.
If resume says required saved positions are missing, click Reset sync setup, then review and turn sync on again. Use reset only when you mean to clear the current ongoing-sync setup.
Read Sync History
Sync History shows what moved, which records changed, and when each run happened.
Each run can show:
Status, type, time, direction, and what started the run
Counts for created, updated, skipped, failed, conflicted, and retried
More detail and field changes when those are available
Times use your admin time zone. Routine healthy connection checks stay hidden. Older runs may not show before-and-after field comparisons.
You will not see raw Bloomerang payloads, API keys, or low-level technical errors here. Those stay in server logs. Conflict rows mean Gratona held the record for review instead of guessing.
What can sync
These are the main Bloomerang areas and where they land in Gratona:
In Bloomerang | In Gratona |
|---|---|
Constituent | Donor |
Household | Household |
Relationship | Related contact |
Group membership | Donor tag, when import is enabled (into Gratona only) |
Transaction | Donation or gift |
Soft credit | Soft credit, when included |
Refund | Donation refund |
Fund, campaign, appeal, designation | Program and designation maps |
Note, interaction, task, tribute | Supported synced activity |
Reconnect or disconnect
Reconnect when the key needs updating. Disconnect when you want Gratona to stop new Bloomerang work.
Reconnect
Open the Bloomerang card in Connected Apps.
Enter a new active API Keys 2.0 key, or leave the field blank to reuse the stored key when that option is available.
Finish reconnect. You may see Bloomerang reconnected successfully or Bloomerang reconnected with the stored API key.
One connection stays tied to one Bloomerang database. To link a different database, remove the connection and add Bloomerang again.
Disconnect
Open the Bloomerang provider.
Click Disconnect.
Confirm in Disconnect provider.
Disconnect stops new sync work. Reconnect turns record sync back on from the saved place. Pause first if you want sync to stay off after reconnect. A record already in progress may still finish.
After disconnect, reconnect or use Remove from Connected Apps.
Fix common problems
Bloomerang rejects the API key
Donors or households will not import
Choose a donor form, finish donor field mapping, and click Save donor setup before you import donors, households, or relationships.
Gifts will not import
Set a fallback recipient, or map at least one Bloomerang fund, campaign, or appeal, then save donation setup.
Record sync is on, but nothing is moving
Check that the connection is connected, sync is not paused, and Sync History is not full of failed runs. Sends stay off while sync is inactive. Also turn off overlapping Zapier or other automation that updates the same records.
A record is marked conflicted
Open the conflict. Fix the unclear donor match, gift destination, group name, or missing link. Gratona keeps the conflict on purpose so it does not overwrite the wrong record.
I cannot reconnect after changing Bloomerang databases
Remove the old connection, then add Bloomerang again with a key from the new database.
Sync History is empty or will not load
Empty history is normal before the first import or send. If loading fails, click Try again.
Resume fails after a pause
Resume continues from the saved place. If that place is missing, use Reset sync setup, then review and turn sync on again.
Frequently asked questions
Short answers to the questions teams ask most during Bloomerang setup.
How do I connect Bloomerang?
In Bloomerang, create an active API Keys 2.0 key under My Profile, API Keys for an administrator. In Gratona, open Connected Apps, add Bloomerang, and paste the key. Gratona stores the key on the server.
Does connecting start sync right away?
No. After you connect, map fields, review matches, choose your starting point, and click Turn on record sync.
Can another admin finish setup?
Yes. The connection belongs to the workspace. Any admin with Connected Apps access can continue. You can also replace the key with another administrator key from the same Bloomerang database.
Can I preview without changing data?
Yes. Review and preview do not create or update donors, households, gifts, payment methods, or messages. You may still see a history entry for what was reviewed.
Which way can data move?
Where the control appears, choose Two-way sync, Gratona updates Bloomerang, or Bloomerang updates Gratona. Picking a direction does not turn sync on.
How are Bloomerang people matched to donors?
Gratona uses the saved link first. If there is no link yet, optional exact primary-email matching can help on the selected donor form. If more than one donor could match, Gratona creates a conflict. Email is a helper, not the permanent identity.
How do Bloomerang groups work?
When Import Bloomerang groups as donor tags is on, existing group membership can become donor tags on already linked donors. Tags do not go back to Bloomerang. Gratona does not create a Child Sponsor group from sponsorships.
How should programs and designations map?
Map each program or designation to a Bloomerang fund, and add a campaign or appeal when you need them. Shared targets are fine when sending gifts out. Incoming gifts to a shared target need a clearer map, or Gratona creates a conflict. Fallback is only for gifts with no map.
What happens with split payments?
Each part of the payment needs a valid Bloomerang destination, a positive amount, and parts that add up to the full payment. If not, Gratona stops and creates a conflict instead of sending a partial guess.
Do soft credits sync?
Yes, when you turn on Include soft credit details and the related donor is already linked. Soft credits do not force a special donor-advised-fund structure. For how soft credits work inside Gratona, see the Soft Credit guide.
How should we bring in historical Bloomerang data?
Connect and map first. Load history through Data & Imports → Imports and, in Bloomerang setup, turn on Historical backfill safeguards before Import from Bloomerang. That keeps populated donor and household details, records gifts with External Processor, avoids live card charges, and keeps migration activity out of donor communications. Leave Turn on record sync for after history is loaded and checked. See How do I import data into my account?.
Are recurring schedules or pledges imported as gifts?
No. Those are commitments, not completed gifts. Import recurring schedules as non-charging External Processor commitments. Completed gift transactions can still import as gifts. Moving the underlying commitments needs a separate approved migration path.
How often does sync run?
Bloomerang records are checked about every five minutes. Groups are checked daily. This connection does not use Bloomerang webhooks. Gratona sends updates when sync is on and the direction allows it.
What does pause do?
Pause stops automatic imports and sends, keeps your mappings and saved place, holds back waiting sends, and does not queue new Gratona changes made while paused. Resume continues from the saved place.
What will I see in Sync History?
Runs, direction, status, counts, outcomes, and field changes when available. You will not see raw payloads, credentials, or low-level technical errors.
Will Gratona turn off my Zapier Zaps?
No. Before you turn sync on, turn off any Zap that updates the same donors, gifts, groups, or designations.
Why do I see Email twice when mapping donors?
System Email is the built-in donor email. Map it to Bloomerang Primary email. A second Email appears only if your donor form also has a custom Email field.
Can one Bloomerang field map to two Gratona fields?
No. Each Bloomerang constituent field can be used once. Remove the duplicate and save again.
What does this integration not do automatically?
It does not create Child Sponsor groups from sponsorships, enforce a donor-advised-fund legal structure, combine or split spouse names, detect overlapping Zapier workflows, or turn recurring schedules or pledge principals into completed gifts.
Related articles
Was this helpful?
Was this helpful?