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

iPaaS.com Customer records can be transferred to Blackbaud Raiser's Edge NXT as Constituent records (Add or Update), with all child addresses written through the Add/Update Raiser's Edge NXT Constituent Address FROM iPaaS.com child collection in the same transfer. Outbound Constituent Delete is not supported. The integration supports four collision-handling resolution methods, eight Constituent custom-field data types, and automatic rescheduling on Blackbaud rate-limit and daily-quota responses.

ID Format

Manual Sync ID Format

Enter the iPaaS.com Customer ID — a numeric value identifying the Customer record in iPaaS.com (example: 12094). The integration uses this ID to retrieve the full Customer record (with its child addresses) from iPaaS.com and write it to Raiser's Edge NXT.

External ID Format (saved after sync)

After a successful Add transfer, iPaaS.com records the Raiser's Edge NXT Constituent ID returned by Blackbaud (a numeric value such as 280) as the external-id link on the iPaaS.com Customer record. This is the link that routes subsequent Update transfers to PATCH /constituent/v1/constituents/{id} instead of creating a duplicate. Each child address has its own external-id link recorded against the iPaaS.com child address record using the Blackbaud Address ID returned by the address POST.

Deleted Record Support

Outbound Constituent Delete is not supported. The integration's Constituent.Delete is not implemented for outbound transfers; deletes must be handled directly in Raiser's Edge NXT. Outbound Constituent Address Delete is likewise not supported — addresses are only written as children of a parent Constituent transfer. Outbound Add and Update are the only supported outbound actions.

Custom Field Support

This mapping collection supports writing Constituent custom field values to Raiser's Edge NXT after the Constituent record write completes. Raiser's Edge NXT supports eight custom field data types on Constituent records: Text, Number, Date, Currency, Boolean, Code Table Entry, Constituent ID, and Fuzzy Date. The integration provides one conversion function per data type for use in mapping formulas:

Data Type	Conversion Function	Value Type
Text	`BlackbaudCustomFieldAsText(category, value)`	String
Number	`BlackbaudCustomFieldAsNumber(category, value)`	Numeric
Date	`BlackbaudCustomFieldAsDate(category, value)`	DateTime
Currency	`BlackbaudCustomFieldAsCurrency(category, value)`	Numeric (decimal)
Boolean	`BlackbaudCustomFieldAsBoolean(category, value)`	Boolean (true/false)
Code Table Entry	`BlackbaudCustomFieldAsCodeTableEntry(category, value)`	String (must match an active code table entry name)
Constituent ID	`BlackbaudCustomFieldAsConstituentId(category, value)`	String (Blackbaud Constituent ID)
Fuzzy Date	`BlackbaudCustomFieldAsFuzzyDate(category, day, month, year)`	Three integers (each independently nullable)

For each custom field configured on the transfer, the integration performs the following sequence:

Lists existing categories via GET /constituent/v1/constituents/customfields/categories/details.
If the referenced category does not exist, attempts to create it via POST /customfield/customfieldcategories. Some Blackbaud installations restrict category auto-creation — see Known Limitations.
For an Add, posts each custom field via POST /constituent/v1/constituents/customfields/ with the Constituent ID set as the parent in the request body.
For an Update, lists existing custom fields via GET /constituent/v1/constituents/{id}/customfields, matches by Category, then PATCHes existing entries via PATCH /constituent/v1/constituents/customfields/{id} or POSTs new ones.

Constituent Address custom fields are not supported — Raiser's Edge NXT does not expose custom fields on Constituent Address records via the SKY API.

Naming Convention: Each conversion function's category parameter must match the exact name of the Raiser's Edge NXT custom field category. The iPaaS.com subscription custom field used as the mapping source must also use the same name as the Raiser's Edge NXT category — the integration resolves the category by name, so a mismatch will result in a new category being created (if auto-creation is permitted) or a failure (if it is not). This is the same naming requirement used in the TO iPaaS.com direction for the direct 1:1 Field pattern.

Usage Examples:

Each custom field mapping uses a Dynamic Formula mapping type with a source formula that calls the appropriate conversion function. The formula's category parameter must match the Raiser's Edge NXT custom field category name exactly. Below are examples for each data type:

Text: BlackbaudCustomFieldAsText("Preferred Greeting", "Dear Friend") — writes a string value.
Number: BlackbaudCustomFieldAsNumber("Years as Member", 12) — writes a numeric value.
Date: BlackbaudCustomFieldAsDate("First Gift Date", new DateTime(2024, 5, 14)) — writes a DateTime value. The value can be constructed from an iPaaS.com date field or parsed from a string using DateTime.ParseExact.
Currency: BlackbaudCustomFieldAsCurrency("Lifetime Giving Estimate", 12500.75) — writes a decimal currency value.
Boolean: BlackbaudCustomFieldAsBoolean("Do Not Mail", true) — writes a true/false value.
Code Table Entry: BlackbaudCustomFieldAsCodeTableEntry("Event Interest", "Annual Gala") — writes a string that must match an active entry name in the corresponding Raiser's Edge NXT code table for that category.
Constituent ID: BlackbaudCustomFieldAsConstituentId("Primary Contact", "280") — writes a Blackbaud Constituent ID as a string value. The referenced constituent must exist in Raiser's Edge NXT.
Fuzzy Date: BlackbaudCustomFieldAsFuzzyDate("Approximate Joined", null, 6, 2005) — writes a partial date with independently optional day, month, and year components. Pass null for any unknown component (e.g., null for day when only the month and year are known).

Fuzzy Date special handling: The BlackbaudCustomFieldAsFuzzyDate function differs from the standard Date variant in that it accepts three separate integer components — day, month, and year — each of which may be independently set to null. Use Fuzzy Date when the source data has partial date information (e.g., only a year, or a month and year without a day). The standard BlackbaudCustomFieldAsDate function expects a single DateTime value and is appropriate when the full date is known.

Setup steps for each custom field mapping:

In iPaaS.com, ensure a subscription custom field exists on the Customer collection with the same name as the Raiser's Edge NXT custom field category.
In this mapping collection, add a mapping of type Dynamic Formula.
Set the destination to the corresponding iPaaS.com subscription custom field.
Set the source formula to call the appropriate BlackbaudCustomField* function, passing the category name and the iPaaS.com source field reference.

At transfer time, the integration resolves the category by name, creates it if it does not already exist (and auto-creation is permitted), and writes the value using the data type structure specific to the conversion function used.

Mapping Collection Status

Status: Enabled
Trigger Events: Customer Add, Customer Update (subscribed in the iPaaS.com subscription configuration's Outbound Data Flows section — automatic transfers will not occur until enabled). Manual Sync is also available.

Duplicate or Conflicting Mappings

This mapping transfers Customers from iPaaS.com to Raiser's Edge NXT. The following mapping collections operate on Constituent records in the opposite direction:

Add/Update Raiser's Edge NXT Constituent TO iPaaS.com: Transfers Constituents from Raiser's Edge NXT to iPaaS.com (driven by SKY API webhook events).
Add/Update Raiser's Edge NXT Constituent Address TO iPaaS.com: Transfers Constituent Addresses from Raiser's Edge NXT to iPaaS.com.

Before enabling this workflow alongside the inbound "To iPaaS.com" collections, review and customize your mapping collection filters to prevent circular updates. Define which system is the source of truth for Constituent data — if both directions are active with default mappings, changes may propagate back and forth between systems.

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

customer_number
company
addresses.first_name
addresses.last_name
addresses.company
addresses.phone_number
addresses.is_primary_billing
addresses.is_primary_shipping

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 collection 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 Customer Number during an update, add a Dynamic Formula mapping with the source formula DestinationValue.CustomerNumber mapped to the iPaaS.com CustomerNumber 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.

Collision Handling

Collision handling runs only on the outbound Constituent Create path — Update transfers already carry a stored Raiser's Edge NXT Constituent ID link and skip duplicate detection. Before POSTing a new Constituent, the integration searches Raiser's Edge NXT for an existing matching record and, when exactly one match is found, applies the subscriber's configured Resolution Method instead of creating a duplicate. Collision handling is configured per subscriber on this mapping collection in the iPaaS.com subscriber portal. This collection is currently configured with the Update and Link resolution method.

The integration calls GET /constituent/v1/constituents/search once per active match field, in order, until a match is found or all fields are exhausted. Match fields are configurable per subscriber; the default order is:

Order	Match Field	Behavior
1	lookup_id	Exact match; inactive constituents are included.
2	email_address	Exact match; inactive constituents are included.
3	name (opt-in, excluded by default)	Strict match only. Blackbaud's default phonetic matching is explicitly disabled on this search call.

Search outcomes:

Zero results across all match fields: no collision — standard Create proceeds.
More than one result on any match field: ambiguous — no auto-link is recorded and the transfer falls through to standard Create. The subscriber resolves any subsequent Raiser's Edge NXT rejection manually.
Exactly one result: the configured Resolution Method is applied.

When a single unambiguous match is found, the integration applies the subscriber's configured Resolution Method:

Method	Behavior
Error	No action by the integration. The transfer is allowed to pass through; Raiser's Edge NXT handles any duplicate rejection itself. No link is recorded.
Remap and Link	The matched Constituent is linked to the iPaaS.com Customer for future transfers, and the mappings are re-run against the matched record.
Update and Link	The matched Constituent is linked to the iPaaS.com Customer for future transfers, and the iPaaS.com data is pushed into the matched record. (This collection's configured method.)
Update and No Link	The iPaaS.com data is pushed into the matched record, but no link is recorded — subsequent transfers will run collision detection again.

When a match is found and the Resolution Method is not Error, the integration runs Address Pairing before applying the resolution. Each address on the iPaaS.com Customer is compared against existing addresses on the matched Raiser's Edge NXT Constituent using a weighted likeness score from 0.00 to 1.00. The match threshold is 0.70 — addresses scoring at or above 0.70 are paired with the existing Raiser's Edge NXT address and PATCHed using its AddressId; addresses scoring below 0.70 are treated as new and POSTed as fresh address records. Address pairing runs only during collision handling on Constituent Create.

Supported Child Collections

Add/Update Raiser's Edge NXT Constituent Address FROM iPaaS.com: Writes all addresses associated with the parent Constituent. New addresses are POSTed and the returned Blackbaud address ID is recorded as a per-address link on the iPaaS.com child address record; existing addresses are PATCHed using the stored link. This prevents duplicate addresses on repeated updates.

System Caveats

Raiser's Edge NXT Caveats

Custom Field Category Auto-Creation: Some Blackbaud installations restrict creation of custom field categories via the SKY API. When auto-creation is rejected, the integration logs a clear error to iPaaS.com Dashboard / Integration Monitoring / Error Logs and the category must be created manually in Raiser's Edge NXT before the mapping will succeed.
No Address Custom Fields: Raiser's Edge NXT does not expose custom fields on Constituent Address records via the SKY API. Custom field mappings on the child Address collection are not supported.
Code Table Values Must Exist and Be Active: Email Type, Phone Type, and Address Type values written by this mapping must exist and be active in the subscriber's Raiser's Edge NXT code tables. Missing or inactive values are rejected by the SKY API.
Rate Limiting: Blackbaud enforces a per-second rate limit on the SKY API. When the limit is reached, 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 (for example, an inactive credential or a missing scope) are treated as permanent failures and appear in Dashboard / Integration Monitoring / Error Logs without being rescheduled.

iPaaS.com Caveats

The Phone_Number mapping uses the iPaaSCustomerGetPrimaryPhone conversion function, which reads from the iPaaS.com Customer's Addresses collection. When the Customer has no addresses or none of the addresses have a phone number, no phone object is sent to Raiser's Edge NXT.
Field references in dynamic formulas use PascalCase (e.g., Addresses, Company, IsPrimaryBilling) — this is required by the iPaaS.com mapping formula engine.

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 Customer transfer is dispatched from iPaaS.com to this mapping collection, the integration writes records to Raiser's Edge NXT via the Blackbaud SKY API in the following order:

Determine Add vs Update. If the iPaaS.com Customer has a stored Raiser's Edge NXT Constituent ID link, route to Update. Otherwise route to Add.
Collision detection (Add path only). Search Raiser's Edge NXT for an existing matching Constituent using the configured match fields in order. On a single unambiguous match, run Address Pairing then apply the configured Resolution Method. On zero matches or ambiguous results, fall through to standard Create.
Constituent write. Add via POST /constituent/v1/constituents, or Update via PATCH /constituent/v1/constituents/{id} using the stored Blackbaud Constituent ID link.
Child Address writes. For each address on the iPaaS.com Customer:
- On Constituent Add, every child address is POSTed to /constituent/v1/addresses. The Blackbaud address ID returned by each POST is captured onto the address object and included in the response payload returned to iPaaS.com, which records the external-id link on its own child address record.
- On Constituent Update, each child address is routed by the presence of an existing AddressId on the inbound payload — addresses with no AddressId are POSTed to /constituent/v1/addresses (and the new AddressId is returned to iPaaS.com for linkage); addresses with an existing AddressId are PATCHed to /constituent/v1/addresses/{AddressId}.
Custom Field writes. When configured (see Custom Field Support), each custom field is written after the Constituent record write completes. Categories are created on-demand if the Blackbaud installation permits.
Response back to iPaaS.com. The integration returns the Constituent payload including all child addresses with their captured AddressIds so iPaaS.com can record the external-id links.

Mappings

Add/Update Raiser's Edge NXT Constituent FROM iPaaS.com

Description: Writes Constituent records (Add or Update) to Raiser's Edge NXT via the Blackbaud SKY API. Adds POST to /constituent/v1/constituents; Updates PATCH to /constituent/v1/constituents/{id} using the stored Blackbaud Constituent ID link.

Mapping Filter: None — all Customer records dispatched from iPaaS.com for this collection are processed without additional filtering conditions.

Field Mapping Table

Mapping Type	Source Field (iPaaS.com)	Destination Field (Raiser's Edge NXT)	Description
Dynamic Formula	`return string.IsNullOrWhiteSpace(Company) ? "Individual" : "Organization";`	Type	Required. Determines the constituent type based on the iPaaS.com Customer Company field — empty/whitespace produces Individual, otherwise Organization. Allowed values: Individual, Organization. The constituent type controls which other fields are valid — `first` and `last` apply to Individuals only, `name` applies to Organizations only. The `Company` reference uses PascalCase as required by the iPaaS.com mapping formula engine.
Field	FirstName	First	Recommended. Maps the iPaaS.com Customer first name to Raiser's Edge NXT `first`. Individual constituents only — ignored for Organizations. Character limit: 50.
Field	LastName	Last	Required for Individual constituents. The SKY API rejects Individual constituent creation when `last` is missing. Character limit: 100. Ensure iPaaS.com Customer records have a last name populated before syncing Individuals.
Field	EmailAddress	Email_Address	Recommended. Maps the iPaaS.com Customer email address to the Raiser's Edge NXT constituent email. Part of the constituent's email object — when an email address is provided, the SKY API also requires an email type (set by the Email_Type mapping).
Static	`"true"`	Email_Primary	Recommended. Defaults the email to primary for all constituents transferred from iPaaS.com. Marks the email as the constituent's primary email address in Raiser's Edge NXT.
Static	`"PersonalEmail"`	Email_Type	Recommended. Defaults the email type to PersonalEmail. The SKY API requires an email type when an email address is provided. The value must exist and be active in the subscriber's Email Types code table. Subscribers can override to Email, Business, etc.
Dynamic Formula	`return iPaaSCustomerGetPrimaryPhone(Addresses);`	Phone_Number	Optional. Retrieves the phone number from the iPaaS.com Customer's primary address via the iPaaSCustomerGetPrimaryPhone conversion function. Priority order: (1) address marked primary billing, (2) address marked primary shipping, (3) first address in the collection. Returns null when no address has a phone — in which case no phone is sent to Raiser's Edge NXT. The function does not make an API call; it inspects the data already supplied by iPaaS.com in the transfer payload. The `Addresses` reference uses PascalCase.
Static	`"true"`	Phone_Primary	Optional. Defaults the phone to primary for all constituents. When Phone_Number returns null, the SKY API ignores the primary flag because no phone object is sent.
Static	`"Mobile"`	Phone_Type	Optional. Defaults the phone type to Mobile. The SKY API requires a phone type when a phone number is provided. The value must exist and be active in the subscriber's Phone Types code table. Subscribers can override to Home, Business, etc.

Add/Update Raiser's Edge NXT Constituent Address FROM iPaaS.com

Description: Writes Constituent Address records as children of the parent Constituent transfer — addresses are never written standalone in the outbound direction. New addresses POST to /constituent/v1/addresses and the returned Blackbaud address ID is stored as a per-address linkage; existing addresses PATCH to /constituent/v1/addresses/{AddressId} using the stored link.

Mapping Filter: None — all addresses on the parent Customer are processed without additional filtering conditions.

Field Mapping Table

Mapping Type	Source Field (iPaaS.com)	Destination Field (Raiser's Edge NXT)	Description
Lookup Translation	Lookup Translation: Address Type - From iPaaS	Type	Required. Translates the iPaaS.com address type to a Raiser's Edge NXT address type. Configuration required: Update the translation values to match the address types defined in your Raiser's Edge NXT environment. The translated value must exist and be active in the subscriber's Address Types code table; missing or inactive values are rejected by the SKY API.
Dynamic Formula	(Concatenates Address1/Address2/Address3 with newlines, omitting empty lines — see Dynamic Formula Documentation below.)	AddressLines	Recommended. Concatenates the iPaaS.com address lines into a single newline-separated string for the Raiser's Edge NXT `address_lines` field. Empty or whitespace-only lines are excluded. Character limit: 150 in the SKY API. The `Address1`/`Address2`/`Address3` references use PascalCase.
Field	City	City	Recommended. Maps the iPaaS.com address city to Raiser's Edge NXT `city`. Character limit: 50. Do not use in combination with `suburb` — the SKY API treats city and suburb as mutually exclusive.
Field	Country	Country	Recommended. Maps the iPaaS.com address country to Raiser's Edge NXT `country`. The SKY API accepts the country's ID, name, or abbreviation.
Field	PostalCode	PostalCode	Recommended. Maps the iPaaS.com address postal code to Raiser's Edge NXT `postal_code`. Character limit: 12.
Dynamic Formula	`return IsPrimaryBilling \\|\\| IsPrimaryShipping;`	Preferred	Recommended. Sets the Raiser's Edge NXT `preferred` address flag to true when the iPaaS.com address is marked primary billing or primary shipping. Raiser's Edge NXT uses a single "preferred" flag rather than separate billing/shipping designations. The `IsPrimaryBilling` and `IsPrimaryShipping` references use PascalCase.
Field	Region	State	Recommended. Maps the iPaaS.com address region to Raiser's Edge NXT `state`. The iPaaS.com field is named `region` but it maps to the SKY API `state` field — both represent the state, province, or region of the address.

Dynamic Formula Documentation — AddressLines

var lines = new System.Collections.Generic.List<string>();
if (!string.IsNullOrWhiteSpace(Address1)) lines.Add(Address1);
if (!string.IsNullOrWhiteSpace(Address2)) lines.Add(Address2);
if (!string.IsNullOrWhiteSpace(Address3)) lines.Add(Address3);
return string.Join("\n", lines);

Lookup Translation Tables

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

Source Value (iPaaS.com)	Destination Value (Raiser's Edge NXT)	Notes
[TODO: Document the source iPaaS.com address types]	[TODO: Document the destination RENXT address types per subscriber's code table]	Configurable per subscriber — values must exist and be active in the Raiser's Edge NXT Address Types code table.

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

Create a new iPaaS.com Customer with a Company value populated. Dispatch the outbound transfer and verify that the Constituent is created in Raiser's Edge NXT with type Organization and the company name populated.
Create a new iPaaS.com Customer with no Company value and both First and Last names populated. Dispatch the outbound transfer and verify that the Constituent is created with type Individual and the names populated.
Update an existing iPaaS.com Customer (one with an existing Raiser's Edge NXT external-id link) — change the email address — and verify the transfer routes to PATCH and the email is updated in Raiser's Edge NXT without creating a duplicate Constituent.
Add a new address to an iPaaS.com Customer that has already been transferred. Re-dispatch the Customer and verify the new address is POSTed to Raiser's Edge NXT and the returned AddressId is captured back onto the iPaaS.com child address record.
Update an existing address on an iPaaS.com Customer and verify the address is PATCHed (not POSTed again) to its existing Raiser's Edge NXT address using the stored AddressId.
Manually sync a Customer using the iPaaS.com Customer ID via the iPaaS.com Manual Sync page and verify the transfer succeeds end-to-end.
Configure a Customer whose email matches an existing Raiser's Edge NXT Constituent. With the collection's Update and Link Resolution Method, verify that collision handling links the iPaaS.com Customer to the matched Constituent and updates the matched record rather than creating a duplicate.
Configure a Customer whose email matches multiple existing Raiser's Edge NXT Constituents. Verify the collision is treated as ambiguous (no auto-link) and the transfer either falls through to standard Create or is rejected by the SKY API.

Validation Checklist

Outbound Data Flows subscriptions for Customer Add and Customer Update are enabled in the iPaaS.com subscriber portal.
The Address Type - From iPaaS lookup translation is populated with values that exist and are active in the subscriber's Raiser's Edge NXT Address Types code table.
iPaaS.com Customer records have a last name populated for all Individuals before syncing.
Mapping filters on this collection and on the inbound TO iPaaS.com collections are configured to prevent circular updates between systems.
Subscribers using custom field mappings have verified whether their Blackbaud installation permits category auto-creation, and have created any required categories manually if not.

Additional Notes

Out of Scope

The following are explicitly out of scope for this integration and are not handled by this mapping collection:

Other Blackbaud objects: Gifts, Donations, Campaigns, Funds, Appeals, Events, Memberships, Transactions, Opportunities, and any other Blackbaud objects not listed in the integration's Supported Data Flows are not transferred by this collection.
Outbound Constituent Delete: Only Add and Update are supported in the outbound direction.
Standalone outbound address writes: Addresses are only written as children of a parent Constituent transfer.
Collision handling on Constituent Update: Collision handling runs only on outbound Constituent create, not on updates or address-only transfers.
Custom fields on Constituent Address: Not exposed by the Raiser's Edge NXT API.
Public Application OAuth registrations: A Blackbaud Private Application registration is required for this integration.

Operational Notes

Repeated Daily Quota Exhaustion: The integration reschedules individual transfers after a quota-exhaustion response, but it does not manage or upgrade the underlying Blackbaud SKY API daily quota. Subscribers whose Private Application repeatedly exhausts its daily quota should contact Blackbaud about a quota tier upgrade — this is an operational concern outside the integration's scope.