Raiser's Edge NXT to iPaaS.com Constituent Address Standalone Mapping Documentation

Blackbaud Raiser's Edge NXT Constituent Address records can be transferred to iPaaS.com independently of their parent Constituent when an address changes or is deleted on its own. This standalone mapping collection processes address-specific webhook events (Update and Delete only) and writes the changed address to its existing iPaaS.com Customer record. New addresses are not handled here — they are captured through the parent Constituent transfer flow the next time the constituent changes.

ID Format

Manual Sync ID Format

Enter the Raiser's Edge NXT Address ID — the address's own system record ID (example: 67890).

External ID Format (saved after sync)

After a successful transfer, iPaaS.com records the Raiser's Edge NXT Address ID alone (example: 67890) as the external-id link on the iPaaS.com Address record. This is the same value used to identify the address in Blackbaud's webhook payloads (address.change.v1, address.delete.v1), so subsequent standalone address events route to the correct iPaaS.com Address record without any custom reconstruction. The same Address ID is used by the child collection (Add/Update Raiser's Edge NXT Constituent Address TO iPaaS.com) so records stay linked regardless of which collection processed them.

Note for legacy records: Address records created before the May 2026 refactor were stored with the legacy composite external ID ConstituentId|AddressId (e.g., 12345|67890). The integration accepts both the new format (Address ID alone) and the legacy composite format when reading external IDs, so existing legacy records continue to resolve correctly. New transfers always record the Address ID alone.

Deleted Record Support

Inbound Delete is supported for standalone Constituent Address transfers. When an address.delete.v1 webhook event is received from Raiser's Edge NXT, the integration dispatches a Delete transfer to iPaaS.com for the matching address record.

Custom Field Support

Constituent Address custom fields are not supported — Raiser's Edge NXT does not expose custom fields on Constituent Address records via the SKY API. Custom field mappings on this collection would not write to iPaaS.com.

Mapping Collection Status

Status: Enabled
Trigger Events: Address Change, Address Delete (subscribed in the iPaaS.com subscription configuration's Inbound Data Flows section as Blackbaud SKY API webhook subscriptions). Webhooks do not activate automatically — the subscriber must register the relevant webhook subscriptions. Manual Sync is also available.

The following SKY API webhook events trigger transfers through this collection once subscribed:

Webhook Event	Action
`address.change.v1`	Triggers an Update transfer to iPaaS.com
`address.delete.v1`	Triggers a Delete transfer to iPaaS.com

The address.add.v1 event is not subscribed for this collection. Newly created addresses are not processed through this standalone flow — they are captured the next time a constituent.change.v1 event fires for the parent constituent, which processes all addresses through the Add/Update Raiser's Edge NXT Constituent Address TO iPaaS.com child collection.

Duplicate or Conflicting Mappings

This standalone collection operates on the same Constituent Address entity as the following collection:

Add/Update Raiser's Edge NXT Constituent Address TO iPaaS.com: The child collection that transfers addresses as part of a parent Constituent transfer. When a constituent.change.v1 event fires, all addresses (including newly created ones) are processed through the child collection. This standalone collection handles only address-specific changes and deletions that occur independently of the parent.

These two collections are complementary, not conflicting. The child collection handles address transfers that accompany a parent Constituent change (including new addresses); this standalone collection handles address updates and deletions that occur independently. Both collections record the iPaaS.com-side external-id link as the Raiser's Edge NXT Address ID alone, so records stay linked regardless of which collection processed them.

Warning — Unmapped Field Overwrite Risk: The iPaaS.com API uses PUT (full record replace) when updating Customer Address records. The following Address fields are not mapped in the default template mappings for this collection or the child Add/Update Raiser's Edge NXT Constituent Address TO iPaaS.com collection. Any existing values in these fields on the iPaaS.com Address record will be overwritten with empty/null values each time an inbound transfer runs unless additional mappings are added to preserve them:

first_name
last_name
company
phone_number
is_primary_billing
is_primary_shipping

The parent Add/Update Raiser's Edge NXT Constituent TO iPaaS.com collection also does not map the following Customer-level fields, which will be overwritten on the parent record during inbound Constituent transfers:

customer_number
company

If your integration uses any of these fields on the iPaaS.com side, you must take action to preserve their values during inbound updates. The recommended approach is to split the TO iPaaS.com mapping collections into separate Add and Update collections, then use the DestinationValue function in the Update collection's mapping formulas to carry forward the existing iPaaS.com value for each unmapped field. For example, to preserve the existing phone number on an address during an update, add a Dynamic Formula mapping with the source formula DestinationValue.PhoneNumber mapped to the iPaaS.com PhoneNumber field. This retrieves the current value from the iPaaS.com record and writes it back, preventing the PUT from overwriting it with null. Repeat for each field that needs to be preserved. Alternatively, you can add source-side mappings that pull the values from Raiser's Edge NXT, but the DestinationValue approach is simpler when the field values originate from iPaaS.com and do not exist in Raiser's Edge NXT.

Supported Child Collections

This standalone collection has no child collections. It operates on a single Constituent Address record per inbound webhook event.

System Caveats

Raiser's Edge NXT Caveats

Webhook Provisioning Delay: After registering webhook subscriptions, allow 1–2 minutes for them to be provisioned before they take effect in the Raiser's Edge NXT platform.
Address Type Configuration: Address type values in Raiser's Edge NXT are configurable per environment. The Address Type - To iPaaS lookup translation must be updated to match the address types defined in your Raiser's Edge NXT instance.
Multi-Line Address Limit: Raiser's Edge NXT stores address lines as a single multi-line address_lines field. If an address contains more than three lines, only the first three lines will be transferred to iPaaS.com (Address1, Address2, Address3).
New Address Events: The address.add.v1 event is not subscribed for this collection. Newly created addresses are not processed here — they are captured via the parent Constituent transfer flow the next time a constituent.change.v1 event fires for the parent constituent.
Rate Limiting: Blackbaud enforces a per-second rate limit on the SKY API. When the limit is reached while retrieving the Address record, the transfer is automatically rescheduled and resumes after the limit window resets — no subscriber action is required.
Daily Quota Exhaustion: Each Blackbaud Private Application has a daily call quota. When the quota is reached, the transfer is automatically rescheduled to run after the daily quota resets — no subscriber action is required. Permission errors from Raiser's Edge NXT are treated as permanent failures and appear in Dashboard / Integration Monitoring / Error Logs without being rescheduled.

iPaaS.com Caveats

Existing Address Required: This is an Update-only collection. The address record must already exist in iPaaS.com (created by a prior parent Constituent transfer through the child collection) before a standalone update can be applied.
Parent Customer Lookup Required: The CustomerId mapping uses the GetSpaceportIdAsync conversion function to resolve the iPaaS.com Customer record ID from the Raiser's Edge NXT ConstituentId. The parent Constituent must already exist in iPaaS.com (transferred via the Add/Update Raiser's Edge NXT Constituent TO iPaaS.com mapping collection) for the lookup to succeed. If no matching iPaaS.com Customer is found, the standalone address transfer will fail because the iPaaS.com address API requires CustomerId to link the address to its parent Customer.

Setup Requirements

For full setup steps see the Installation Instructions and Connections and Settings articles. The integration-wide setup (Blackbaud Private Application registration, OAuth scope, subscription settings) is documented there and not repeated here.

Integration Flow

When a standalone address webhook event is received from Raiser's Edge NXT, or a Manual Sync is initiated, the integration processes the transfer in the following order:

Webhook receipt and record retrieval. For webhook-driven transfers, the integration acknowledges the webhook event and retrieves the full Address record from the SKY API along with its parent Constituent ID. For Manual Sync, the integration retrieves the full Address record using the supplied Address ID.
Determine action type. Based on the webhook event (or Manual Sync request), classify the transfer as Update or Delete.
Parent Customer lookup. The CustomerId dynamic-formula mapping calls GetSpaceportIdAsync(ConstituentId, "Customer", SpaceportSystemId) to resolve the iPaaS.com internal Customer ID matching the Raiser's Edge NXT ConstituentId. If no match is found (parent Customer not yet transferred), the transfer fails.
Map Address fields. Apply each mapping in this collection to translate the Address record into the iPaaS.com Address shape (Address1/Address2/Address3 split, City, Region, Country, PostalCode, IsPrimaryBilling, Type translation).
Dispatch to iPaaS.com. The translated Address record is dispatched to iPaaS.com with the resolved CustomerId and the Raiser's Edge NXT Address ID as the external ID. iPaaS.com matches the existing Address record by external ID and applies the Update or Delete.

Mappings

Add/Update Raiser's Edge NXT Constituent Address TO iPaaS.com (Standalone)

Description: Processes Constituent Address updates and deletions from Raiser's Edge NXT to iPaaS.com when an address changes independently of its parent Constituent. The CustomerId mapping resolves the parent iPaaS.com Customer record by ConstituentId lookup so the address can be linked correctly.

Mapping Filter: None — all address records received through webhook events or manual sync are processed without additional filtering conditions.

Field Mapping Table

Mapping Type	Source Field (Raiser's Edge NXT)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`return await GetSpaceportIdAsync(ConstituentId, "Customer", SpaceportSystemId);`	CustomerId	Required. Resolves the iPaaS.com Customer record's internal ID for the parent of this standalone address. Calls GetSpaceportIdAsync with the Raiser's Edge NXT ConstituentId, the iPaaS.com table name `"Customer"`, and the iPaaS.com-supplied SpaceportSystemId. Returns the matching iPaaS.com Customer internal ID as a `long`, or null when the ConstituentId is empty or no matching Customer exists. The transfer fails if no matching iPaaS.com Customer is found — typically because the parent Constituent has not yet been transferred via the Add/Update Raiser's Edge NXT Constituent TO iPaaS.com mapping collection.
Dynamic Formula	(Splits AddressLines on `\n` and returns line 1 — see Dynamic Formula Documentation below.)	Address1	Recommended. First line of the address, extracted from the multi-line `address_lines` field. At least Address1 should be populated for a meaningful address record. Returns null if the address has no lines.
Dynamic Formula	(Splits AddressLines on `\n` and returns line 2 — see Dynamic Formula Documentation below.)	Address2	Optional. Second line of the address. Null if the source address has fewer than two lines.
Dynamic Formula	(Splits AddressLines on `\n` and returns line 3 — see Dynamic Formula Documentation below.)	Address3	Optional. Third line of the address. Null if fewer than three lines; lines beyond three are not transferred.
Field	City	City	Recommended. Maps the address city. Important for address validation and completeness.
Field	State	Region	Recommended. Maps the Raiser's Edge NXT address state to iPaaS.com address region. The SKY API field is named `state` but it maps to the iPaaS.com `region` field — both represent the state, province, or region.
Field	Country	Country	Recommended. Maps the address country. Important for proper address formatting and validation.
Field	PostalCode	PostalCode	Recommended. Maps the address postal code. Important for address validation and completeness.
Field	Preferred	IsPrimaryBilling	Recommended. Maps the Raiser's Edge NXT preferred address flag to iPaaS.com `is_primary_billing`. When true, this is the constituent's preferred/primary address. Raiser's Edge NXT uses a single "preferred" flag rather than separate billing/shipping designations.
Static	`"false"`	IsPrimaryShipping	Optional. Defaults shipping to false. Subscribers can override to map Raiser's Edge NXT Preferred to IsPrimaryShipping per their preference.
Lookup Translation	Lookup Translation: Address Type - To iPaaS	Type	Recommended. Translates Raiser's Edge NXT address type to iPaaS.com Customer Address Type (Billing / Shipping / Other). Configuration required: Update the translation values to match the address types defined in your Raiser's Edge NXT environment.

Dynamic Formula Documentation — Address1 / Address2 / Address3

Each Address line mapping uses the same pattern, varying only by the line index:

// Address1
var lines = AddressLines?.Split('\n');
return (lines?.Length ?? 0) > 0 ? lines[0]?.TrimEnd('\r') : null;

// Address2
var lines = AddressLines?.Split('\n');
return (lines?.Length ?? 0) > 1 ? lines[1]?.TrimEnd('\r') : null;

// Address3
var lines = AddressLines?.Split('\n');
return (lines?.Length ?? 0) > 2 ? lines[2]?.TrimEnd('\r') : null;

Raiser's Edge NXT stores all address lines as a single newline-separated string in the SKY API address_lines field. The formulas split on \n and trim any trailing \r to handle CRLF line endings. Lines beyond the third are not transferred.

Lookup Translation Tables

Address Type - To iPaaS — Subscribers must populate this translation collection with mappings from their Raiser's Edge NXT Address Types code table entries to iPaaS.com Customer Address Type values.

Source Value (Raiser's Edge NXT)	Destination Value (iPaaS.com)	Notes
Home	Billing	Primary home address — commonly used as the billing address.
Business	Billing	Business address.
Work	Other	Work address.
Shipping	Shipping	Shipping-specific address.
Vacation	Other	Seasonal or vacation address.
Former Address	Other	Previous address no longer in use.

The table above shows example mappings based on common Raiser's Edge NXT default address types. Your Raiser's Edge NXT environment may have different address types — the Address Types code table is configurable per environment and subscribers may add, rename, or remove entries. Review the active entries in your Address Types code table and update this translation collection in iPaaS.com to match. The same Address Type - To iPaaS translation collection is shared with the Add/Update Raiser's Edge NXT Constituent Address TO iPaaS.com (Child) collection. Any Raiser's Edge NXT address type not listed in the translation collection will not resolve to an iPaaS.com type during transfer.

Error Handling

Errors from this mapping collection appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. For the full catalog of error messages, descriptions, and resolution steps see the Error Messages article.

Testing & Validation

Test Scenarios

Update an address on a Constituent in Raiser's Edge NXT (e.g., change the city or postal code) and verify the address.change.v1 webhook fires, the integration resolves the parent CustomerId, and the matching iPaaS.com Address is updated.
Delete an address from a Constituent in Raiser's Edge NXT and verify the address.delete.v1 webhook fires and the matching iPaaS.com Address is marked deleted.
Manually sync a known address via the iPaaS.com Manual Sync page using the Raiser's Edge NXT Address ID and verify the transfer succeeds.
Verify that updating an address on a Constituent that has not yet been transferred to iPaaS.com produces a clear error message (parent Customer not found) rather than silently failing.
Verify that creating a new address in Raiser's Edge NXT does NOT trigger this standalone collection (no address.add.v1 event subscribed) — instead, confirm the new address appears on the next constituent.change.v1 event for the parent through the child collection.
Verify that the Address Type - To iPaaS lookup translation handles every active address type in the subscriber's Raiser's Edge NXT environment.

Validation Checklist

Webhook subscriptions for address.change.v1 and address.delete.v1 are enabled in the iPaaS.com subscription configuration's Inbound Data Flows section.
The related Add/Update Raiser's Edge NXT Constituent TO iPaaS.com mapping collection is enabled — without it the parent Customer records will not exist in iPaaS.com and CustomerId lookups will fail.
The Address Type - To iPaaS lookup translation is populated with every active address type from the subscriber's Raiser's Edge NXT environment.
The Blackbaud Private Application's OAuth scope grants access to the Address SKY API endpoint.

Additional Notes

Operational Notes

API unavailability: If the Blackbaud SKY API is temporarily unavailable when a standalone address webhook is received, the transfer will fail. An error will appear in Dashboard / Integration Monitoring / Error Logs. The record can be retried by triggering a new address change event or via Manual Sync.
No standalone Add path: New addresses are intentionally routed through the parent Constituent transfer flow (via the child collection) rather than this standalone collection. This avoids duplicating new-address handling logic in two places and ensures new addresses are processed alongside any other changes to the parent Constituent in the same transfer.