<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=2191750074375425&amp;ev=PageView&amp;noscript=1">
Skip to content
More support
Contact us
  • There are no suggestions because the search field is empty.

DonorPerfect Integration

Send donors, donations, pledges, refunds, activities and tags from BetterUnite to DonorPerfect.

Send your donors, donations, pledges, refunds, activities and tags from BetterUnite to DonorPerfect, and bring DonorPerfect constituents into BetterUnite as contacts.

Before you start

Two things need to be in place in DonorPerfect before the integration is useful.

API access. You need a DonorPerfect API key, which you generate yourself under Settings, User Management, API Self Service. If you do not see that screen, your DonorPerfect user does not have rights to it.

The codes you want to use. BetterUnite never creates a code in DonorPerfect. DonorPerfect rejects a code it does not already have rather than adding it, so every general ledger code, solicitation code, campaign code, gift type, thank-you letter code and activity code you plan to map has to exist first, under Settings, Code Maintenance.

Note: the integration writes to your live DonorPerfect database. The DonorPerfect API has no call that deletes a gift, so nothing BetterUnite sends can be removed by BetterUnite afterwards. It is worth reviewing your code mappings before the first sync rather than after it.

Connect your DonorPerfect account

  1. In BetterUnite, go to Settings, then Integrations, and open DonorPerfect.
  2. In DonorPerfect, go to Settings, User Management, API Self Service and generate an API key.
  3. Paste the key into DonorPerfect API key in BetterUnite and click Connect.

A successful connection reports how many constituents the account holds, which is a quick confirmation that the key reached the right database. Test Connection re-checks an existing key at any time.

Generate the key against a DonorPerfect user created for the integration, not against a real person's login. A key generated on a staff member's account stops working the day that account is removed, and the sync then fails silently until someone reconnects it.

The key is a full read and write credential to your entire donor database, so treat it the way you would a password. Disconnect on the same page removes it from BetterUnite. You can also revoke it in DonorPerfect, which has the same effect. Disconnecting stops future syncs; it does not remove anything already written to DonorPerfect, and it does not clear the links between BetterUnite records and the DonorPerfect records they created.

Map your campaigns to DonorPerfect codes

The Sync Transactions tab lists your campaigns in two groups: Available to Sync, which is campaigns with donations still to send, and Fully Synced. The Only campaigns with donations switch hides campaigns that have never taken a gift, which is most of them on a mature account.

Each campaign row has three drop-downs, filled from your own DonorPerfect code lists:

  • General Ledger comes from the GL_CODE list, and sets where the revenue is booked.
  • Solicitation comes from the SOLICIT_CODE list, and records what prompted the gift.
  • Campaign comes from the CAMPAIGN list, and sets the DonorPerfect campaign the gift belongs to.

Change a drop-down and click Save Mapping on that row. Leaving one blank is not an error: the gift falls back to the matching default in Sync Options, and if that is blank too the gift lands in DonorPerfect without that code rather than being rejected.

The View button on a row opens the transactions for that campaign.

Sync options

Sync Options opens a panel covering everything that is not campaign-specific. Click Save Options when you are done.

What syncs

  • Send donations as gifts. On by default. This is the main direction of the integration.
  • Send pledges and their payments. Off by default. See Sync pledges.
  • Itemize multi-line orders as split gifts. Off by default. See DonorPerfect Split Gifts.

Default codes

These apply to any campaign with no mapping of its own.

  • General Ledger. Every gift from a campaign with no general ledger code.
  • Solicitation. Every gift from a campaign with no solicitation code.
  • Sub-solicitation. Every gift. There is no per-campaign sub-solicitation mapping.
  • Campaign. Every gift from a campaign with no campaign code.
  • Gift Type. Every ordinary one-off gift.
  • Gift Type for Recurring Gifts. Instalments of a recurring donation, when set.
  • Thank-you Letter. Every gift BetterUnite creates.

The thank-you letter code is worth setting deliberately. DonorPerfect SmartActions do not fire on records written through the API, so a gift that arrives from BetterUnite will not enter your acknowledgement run on its own. The letter code on the gift is what puts it there.

Tributes, activities and tags

Sync schedule

See Sync schedule and job runs.

Sync transactions

Open the Sync Transactions tab, find the campaign, and click Sync on its row. A results panel reports what was sent and lists anything that failed. You can also open a campaign with View and send a single transaction from its row.

What arrives in DonorPerfect

  • Gift date. The donation date, as a date only. DonorPerfect stores no time of day on a gift.
  • Amount. The gross amount of the transaction.
  • General ledger, solicitation, sub-solicitation and campaign codes. The campaign mapping, then the default.
  • Gift type. The default gift type, or the recurring gift type for an instalment.
  • Thank-you letter code. The default thank-you letter.
  • Fair market value. The non-deductible portion of the payment.
  • Gift narrative. The campaign name, then each purchased line with its quantity and amount, then "Given anonymously" if the donor asked to be, then the donation note.
  • Reference. The BetterUnite transaction id.

Do not edit the Reference field on a gift BetterUnite created. It holds the BetterUnite transaction id, and it is how the sync recognizes a gift it has already sent. Change it and a later run can send the same donation a second time.

Fair market value is how a ticket or auction purchase receipts correctly without being split into separate gifts: DonorPerfect works out the deductible amount from it. When BetterUnite has no deductible figure for a transaction, the field is left empty rather than set to zero, because zero asserts that the whole payment is tax deductible.

Transaction statuses

  • Not Sent. Eligible, waiting for a sync.
  • Gift, followed by a number. Sent. The number is the DonorPerfect gift id.
  • Error. DonorPerfect refused it. The reason is on the row.
  • No Sync. Excluded by someone here. It will never be sent.
  • Refunded. The transaction was refunded in BetterUnite.

A transaction that errors is not retried automatically. That is deliberate: a gift DonorPerfect refused usually needs a person to look at the reason, and retrying it every night would bury the same failure in the log instead of surfacing it.

Filtering and excluding

Above the transaction list there is a date box (transactions on or after, defaulting to three months back) and a filter with five choices: Show All Eligible, Show Errors, Show UnSynced, Show All and Show 'Do Not Sync' Transactions.

The gear button next to the filter holds Mark $0 transactions as Do Not Sync, which excludes every zero-value transaction in the current list in one action. Free tickets, comped registrations and fully discounted orders are the usual reason to reach for it.

Each transaction row has its own menu:

  • OK TO SYNC puts an excluded transaction back in the queue.
  • DO NOT SYNC excludes it permanently.
  • Mark as Sync'ed records it as done without sending it. Use this for a gift that is already in DonorPerfect because someone entered it by hand.
  • Reset Sync Status clears the status so the transaction is picked up again. This is how you retry after fixing the cause of an error.
  • Validate contact looks up the donor in DonorPerfect without writing anything, so you can see what a sync would match before running one.

How much a run sends

The DonorPerfect API has no bulk endpoint, so every gift is a separate request. A single run sends at most 250 transactions, and a scheduled run looks back 30 days. If you have a backlog larger than that, run the sync again, or send a campaign at a time from its row.

Sync pledges

Turn on Send pledges and their payments in Sync Options, then use the Sync Pledges tab. It works the same way as the transactions tab, with its own date filter defaulting to twelve months back and the same five-way status filter.

A BetterUnite pledge becomes a DonorPerfect pledge record, and each payment you collect against it goes over as a gift linked to that pledge, which is what keeps the DonorPerfect balance and its reminders correct.

The payment frequency is worked out from the pledge's own schedule in BetterUnite. When the schedule is irregular enough that no standard frequency fits, the pledge is sent with DonorPerfect's unknown frequency rather than with a guess.

A synced pledge is a record, not a billing instruction. DonorPerfect can only charge a pledge whose payment method is stored in their own gateway, and BetterUnite payment methods are not. Pledges you sync keep being billed from BetterUnite exactly as before. Do not set them up to bill in DonorPerfect as well.

In a scheduled run, pledges are sent before donations. A payment can only link to its parent pledge once that pledge exists, and a payment sent first arrives as an ordinary gift and stays one.

Recurring donations

BetterUnite does not create recurring gift schedules in DonorPerfect. Each instalment arrives as an ordinary gift on the date it was collected.

Set Gift Type for Recurring Gifts in Sync Options to a gift type of your own, and every instalment is marked with it, so DonorPerfect can report recurring revenue separately. Leave it blank and instalments arrive indistinguishable from one-off gifts, which is a working configuration, just a less useful one.

Keeping the schedule in one place is deliberate. Two systems both holding a recurring schedule is two systems that can both decide to charge someone.

Tributes

With Record dedications as tributes on, a donation made in someone's memory or honor creates a matching DonorPerfect tribute and attaches the gift to it.

A tribute with the same name is reused rather than duplicated, so a second gift in the same person's memory joins the first. The In Memory Of and In Honor Of type ids differ from one DonorPerfect system to the next, so BetterUnite reads yours from the account when you connect.

This is off by default because a tribute is a lasting record in DonorPerfect with a life beyond the gift that created it, and starting to create them is a decision worth making on purpose.

How contacts are matched

Before a gift can be sent, its donor has to be matched to a DonorPerfect constituent. BetterUnite works down this ladder and stops at the first rung that answers:

  1. Already linked. The contact has been matched to a constituent before, so that link is used again.
  2. Email address. An exact email match wins outright. If DonorPerfect holds more than one constituent with that address, the oldest record is used.
  3. Name, only when it is unambiguous. A single matching name is used. Two or more, and BetterUnite moves on rather than guessing. Organizations are matched on the organization name of a DonorPerfect organization record, not on a last name.
  4. Create. A new constituent is created with the contact's name, address, phone numbers, email and postal mail preference.

BetterUnite prefers creating a duplicate over making a wrong match. A duplicate is something your staff can merge in DonorPerfect in a few seconds. A wrong match blends two people's giving histories, and unpicking that is a much longer afternoon.

Use Validate contact on a transaction row to see which rung a donor lands on before you sync anything. If you want fewer new constituents created, make sure your BetterUnite contacts carry the same email addresses as your DonorPerfect records.

Sync schedule and job runs

In Sync Options, switch on Enable Sync Schedule and choose the times you want it to run. Times are in your organization's time zone.

Each scheduled run works in this order:

  1. Pledges, so their payments have a parent to link to
  2. Donations
  3. Refunds
  4. Activities

A scheduled run only does the things you have switched on. Turning off donation sync, for example, also stops refunds being mirrored, since a refund is an adjustment to a gift BetterUnite sent.

The Sync Job Runs tab lists every run with the time it was scheduled, the time it actually executed, whether it succeeded, and the error if it did not. This is the first place to look when you expected something to arrive overnight and it did not.

Troubleshooting

A code drop-down is empty

The list is read from DonorPerfect every time the page loads, so an empty one means DonorPerfect returned no active codes for that field. Add the codes under Settings, Code Maintenance in DonorPerfect, then reload the BetterUnite page. Use the Show only filter on that screen to find the right list, for example Activity / Contact Screen for activity codes.

If every list is empty and a warning appears at the top of the page, the key itself is the problem. Run Test Connection.

A transaction shows Error

The reason DonorPerfect gave is on the row. The common ones are a code that no longer exists in Code Maintenance and a required field with nothing in it. Fix the cause, then use Reset Sync Status on the row to put it back in the queue.

The same gift is in DonorPerfect twice

Check whether the Reference field on the first gift was edited or cleared. That field is how the sync recognizes its own work. Mark the BetterUnite transaction as Do Not Sync and delete the duplicate in DonorPerfect by hand.

A donor keeps getting created again

The contact's email address in BetterUnite does not match the one on the DonorPerfect constituent, and the name is either different or not unique. Add the email to the DonorPerfect record, or merge the duplicates there, and later gifts will find the right constituent.

Related articles