Skip to main content
Sign in

NationBuilder sync

What flows from NationBuilder into Together, how often, and how it lands in the unified donor and donation lists.

The NationBuilder integration is poll-based: Together runs a sync every 15 minutes and pulls everything that changed since the last run. NationBuilder webhooks aren't used because they're not officially supported and are gated to Enterprise NationBuilder plans.

What syncs

Each sync pass pulls four kinds of record:

RecordDirectionMapped fields
PeopleNB -> TogetherFirst name, last name, email, phone, full address. Phone is normalised to Australian format. See Which records sync.
DonationsNB -> TogetherAmount, donation date, payment method, tracking code, NB recipient mapping, donation status, donation type (monetary or in-kind).
Tracking codesNB -> TogetherThe free-text labels NB stamps on donations. Together uses these for jurisdiction classification.
Custom fieldsNB -> TogetherSelected NB custom fields on the person record, including any compliance flags you've set up upstream.

The inbound direction (NB to Together) is always on. Write-back from Together to NB (segment tags and suggested ask amounts) is opt-in and configured at Intelligence > Write-back; it requires the Grow tier and above. Together recognises the donations it has already written back to NationBuilder, so they are never re-imported as duplicates on the next inbound sync.

Gifts your team records by hand write back too. Record the cheque, bank transfer or in-kind gift on the donations list and it appears in NationBuilder within a few minutes - so don't also key it into NationBuilder yourself, or you will have the same gift twice. Together does not check NationBuilder for a matching donation before it writes.

Editing one of those hand-recorded gifts updates the NationBuilder copy as well - the amount, the date, the payment type and the revenue code, sent the moment you save. It is one-way: editing that same gift in NationBuilder does not come back to Together, because the sync deliberately skips gifts Together wrote (see Donation matching), so make the correction here. See Revenue codes when Together writes back for what changing the code does in NationBuilder, which is not the same as what happens when the gift is first sent. If NationBuilder can't be reached, Together still saves your edit and says so on the form, and saving again retries. Only gifts recorded in Together can be edited this way - a donation that came from NationBuilder is edited in NationBuilder.

Voiding one of those gifts marks the NationBuilder copy - it never deletes it. Together does two things in one edit: it cancels the donation, so the row stops showing as succeeded, and it appends [VOIDED IN TOGETHER] with the date to the donation's note so the record says who did what and when. The donation itself stays: deleting a donation in your nation is not something Together will do on your behalf, and it could not be undone.

A cancelled donation shows in NationBuilder as Refunded. That is the nearest label NationBuilder has - there is no "voided" status on a donation, and the status field cannot be set directly - and it does not mean money moved. Nothing is refunded to the donor by voiding a gift in Together; if a real refund is owed, issue it wherever the money was taken. Remove it there yourself if your record-keeping wants it gone. A gift voided before it ever reached NationBuilder is normally never sent, and nothing is marked. The exception is a gift that was mid-send or waiting on a retry when you voided it: Together stops the send, but a copy that had already landed will not be marked, so the dialog tells you to check. Same if NationBuilder can't be reached at the moment you void. Either way the void stands in Together, and there is no retry for a void - remove or annotate that donation in NationBuilder by hand.

Marketing contact preferences write back the same way. When write-back is on, marking a donor as do-not-contact (or a donor opting back in from their receipt) updates that person's contact permissions in NationBuilder - their email_opt_in and do_not_contact fields - so a donor who has asked not to be contacted stays suppressed in your CRM too. The update usually lands within a couple of minutes of the change. In the other direction, Together honours opt-outs it reads from NationBuilder - see Opt-outs from NationBuilder.

NationBuilder donations with an in-kind payment type (for example "In-Kind") are classified as in-kind donations in Together; all others are monetary. The NationBuilder amount is kept as the donation's fair value, so it counts toward compliance like any other donation. See In-kind donations and compliance.

Which records sync

The Records to sync setting on the NationBuilder card at Settings -> Integrations decides which NationBuilder people come into Together. Only an ADMIN can change it.

The change applies from the next scheduled sync; saving it starts nothing on the spot. On a large nation the first pass through every supporter runs over several syncs, picking up where the last one stopped.

"All records" takes effect once Together enables it for your organisation, and the card says so until then. Until it is enabled, only donors sync, whichever option is saved.

Switching back to Donors only removes nobody. Supporters already brought in stay in Together, and their opt-outs keep being honoured. Switch to All records again later and Together works through your NationBuilder list again from the start, so nobody who joined in the meantime is missed; supporters already in Together are not duplicated.

Supporters who have never given are left off the Donors list by default, so the list you work from stays your givers. Pick Everyone in the dropdown beside the search box to see them; see Add a donor manually.

Sync cadence

The sync watermark is the most recent update timestamp Together has seen on a NB record. A long pause in syncs (e.g., disconnected for a week) means the next sync covers everything that changed in that window, not just the most recent records.

Donor matching

When a NB person record arrives, Together looks for an existing donor by:

  1. NB person ID first (stored as an external ID on the Together donor record).
  2. Email match if the NB person ID isn't on file.
  3. Name + phone fuzzy match as a last resort.

If a match is found, the existing donor is updated. If not, a new donor is created with the Individual donor type. The email match ignores case. Together never auto-merges across donor types or across mismatched names; ambiguous cases land in the duplicate queue at Donors -> Duplicates.

Under All records, a supporter NationBuilder has no donation for works differently when their email matches a donor already in Together. Together honours their opt-outs on that donor and does nothing else: it does not connect the two records, copy the supporter's name, phone or address onto the donor, or add a second donor. A sign-up form is not proof that the person filling it in owns that email address, and the address is what a disclosure return prints. If they are the same person, their next NationBuilder donation connects the records as usual.

Opt-outs from NationBuilder

Together reads a supporter's NationBuilder record the first time it syncs one of their donations, and again whenever an admin presses Sync from NationBuilder on the donor's page. Together is also switching on, in stages, a regular re-read of every supporter it already holds, so an opt-out someone sets in NationBuilder later reaches Together without waiting for their next donation. Each time, it honours what the record says about contact:

This only ever stops contact. Opting a supporter back in to email in NationBuilder does not clear a do-not-contact in Together - the donor can opt back in from their receipt, or your team can clear the flag on the donor page. Together also never replaces a do-not-contact your team or the donor set in Together, and it does not write these opt-outs back to NationBuilder, which already has them.

Donation matching

NB donations sync with an external donation ID so a single NB donation is never imported twice. Edits to NB donations (amount corrected, date adjusted, tracking code added) flow through on the next sync.

Refunded or cancelled NB donations show up with a refund flag (or are removed); Together's compliance logic excludes them from active aggregates and, where the change drops the donor back below the disclosure threshold, automatically supersedes (or, for an already-filed return, flags for amendment) any outstanding disclosure obligations.

A gift Together pushed is edited in Together

Together owns the gifts it wrote into NationBuilder, and that ownership runs one way by design. Edit such a gift in Together - the amount, the date, the payment type, the revenue code, or void it - and the change is pushed to the NationBuilder copy within a few minutes (Editing a hand-recorded gift).

Edit the NationBuilder copy instead and the change stays in NationBuilder. Every later sync skips those donations, which is what stops each one re-importing as a second gift and counting twice toward caps and disclosure thresholds, so nothing on the row is read back - a tracking code you correct there included. Neither system flags the disagreement: Together keeps showing the original, NationBuilder shows your edit. Make the correction in Together. Donations that came from NationBuilder work the opposite way: edit those upstream and the next sync brings the change in.

Donations deleted in NationBuilder

A donation deleted in NationBuilder (as opposed to cancelled or refunded) does not disappear from Together automatically. The scheduled sync only pulls updates, and a deleted donation leaves nothing behind upstream for the sync to act on, so the gift keeps counting toward the donor's cap and disclosure totals until you reconcile it.

To reconcile, open the donor's record and click Sync from NationBuilder in the Record management panel (ADMIN). This re-checks that donor's full current NationBuilder donation history, removes any Together-side donation that is no longer present upstream, and recalculates their compliance totals. If NationBuilder no longer has the record a gift came from - it was merged into another record, or removed, which is also what makes a write-back fail with "First name can't be blank" - that gift stays in Together and the button tells you how many were left in place. NationBuilder can no longer say whether those gifts still exist, so Together will not remove them on your behalf. If you know one of them was really deleted in NationBuilder, remove it yourself from its detail dialog (see Read the donations list) - which is also how you delete any single donation. Either way, the removal affects Together only; NationBuilder is not changed.

Tracking-code ingestion

NB stores a tracking code (free text) on each donation. Together ingests this as-is. Each code appears in your library at Settings -> Compliance -> Revenue codes where you assign it to a jurisdiction (Federal, Victoria, or Unregulated); see Set up revenue codes.

Donations without a tracking code retain the empty value and count as Unregulated. To have them count toward a jurisdiction, attach a tracking code upstream in NationBuilder and assign that code a jurisdiction.

Revenue codes when Together writes back

This applies when write-back is enabled (Grow tier and above). Together also sends its own donations - from donation forms, checkout links, recommendation sets, and gifts your team records by hand on the donations list - back into NationBuilder so they sit alongside the rest of your giving. The donation's revenue code goes with it, but only if NationBuilder already has a tracking code with that exact name. Together matches by name; it does not create new tracking codes in your NationBuilder. If there's no matching code, the donation still writes back - just without one.

This matters for codes that exist only in Together - for example, a code applied to a donation inside Together that was never created in NationBuilder. That code won't appear on the donation in NationBuilder until you create a tracking code with the same name there. Until then the donation lands in NationBuilder untagged, even though it's classified correctly inside Together.

There is one way to fix that without leaving Together, and it is why the two behaviours differ. Changing a code on an existing donation does create the tracking code in NationBuilder if it isn't there - whether you use Change revenue code on a donation from a form, a link or a recommendation set, or edit the code on a gift your team recorded by hand. Correcting a code is a deliberate act on one donation, so dropping the attribution silently would re-apply the very mis-tagging you were fixing. The bulk write-back of new donations stays match-only, so a typo in a code can never scatter new tracking codes through your nation.

When a donation does not sync

NationBuilder can refuse a donation Together sends it. Two places tell you which gift, and why.

On Settings -> Integrations -> CRM, the Donation write-back panel lists every failed write-back from the last seven days under Failed write-backs - the donor, the amount, the date and NationBuilder's own message, with the donor's name linking straight to the gift. When you've dealt with the cause, Retry N failed re-queues all of them; the next sync picks them up within a few minutes.

On the donor's record, a gift that didn't reach NationBuilder is marked Not synced to NationBuilder in the giving history, and opening it shows NationBuilder's reason in the detail dialog. Everyone in your organisation can see this.

The message is NationBuilder's wording, passed through unchanged, so what it describes is not always the gift itself - some messages name a field on the supporter record. Together shows it as written rather than interpreting it. Where the repair is in NationBuilder, make it there and then retry from the panel.

One cause repairs itself: if NationBuilder merged the supporter's record into another one, Together follows the merge on the next gift for that supporter - it finds the record NationBuilder kept, checks that one of the supporter's earlier gifts really did move to it, points the supporter at it, and sends the gift there. You do not need to do anything. Together stops and leaves the gift unsent, with the reason on the panel, whenever it cannot be sure: when no earlier gift confirms the record it found, when nobody in NationBuilder holds that supporter's email address, or when following the merge would mean deciding which of two supporters in Together is the real one. It never guesses, because a wrong guess would combine two different people's records.

What doesn't sync

Disconnecting

Disconnecting via Settings -> Integrations -> CRM preserves all historical NB-sourced donors and donations in Together; only future syncing stops. Reconnect later to resume; Together back-fills the gap on the first post-reconnect sync.

What to do next