Introduction
The new Aegis API integration steps away from transferring files between RaiseDonors and Aegis and is now pushing data directly through Aegis's API. The integration happens in real-time so you can expect to see data flow into the batch process as it happens.
To enable this integration, log into RaiseDonors, and head over to the integrations page and click the Aegis API icon.
Below is a summary of each configuration option, explaining the purpose, and use-case. Required fields are indicated in the setup page.
If an integration fails for any reason, you can be alerted by subscribing to the error notification list (see configuration setting below). You may also reference the integration dashboard for a list and status of all integration issues.
Please note that the Aegis Integration Checklist is also a good place to start to ensure the integration is correctly configured.
Navigate this guide
Authentication
Username
This is the email address used to log into Aegis CRM. You can use your own email address or you can setup a specific/new user in Aegis solely for the API integration.
Password
This is the associated password with the email address supplied, to authenticate and log into Aegis CRM.
Context
You'll need to contact your account representative at Aegis and ask them for your "context key". This is a 32 digit alphanumeric key.
URL
This is the API endpoint to communicate with Aegis's API. Your account representative can provide this information to you.
Default Values
Batch Category
This must exist in Aegis.
This is the category to be used as items are placed in the batch. (i.e. Online Giving, Web)
Batch Type
This is the type to be used as items are placed in the batch. (i.e. RaiseDonors, Online Transactions)
Warehouse ID
This must exist in Aegis.
For inventory items, the system needs to know which Warehouse ID to use when creating product orders.
Channel
This must exist in Aegis.
This is the channel to be used when submitting information into batches.
Pledge Program Name
This must exist in Aegis.
When donors create recurring schedules in RaiseDonors, those schedules live at the gateway (Authorize.net or Stripe). The gateway is responsible for charging the payment token on file at the appropriate scheduled time. RaiseDonors creates a pledge in Aegis CRM, indicating that the donor will be giving future donations. For this to happen, you need to supply the pledge program name to be used. Typical values would be "Recurring", "Monthly", etc.
Media Program Name
If your organization is using media codes with donation forms, RaiseDonors can include the selected media outlet with the integration. For media codes to be placed alongside donations and orders, the media program name needs to be supplied here as a default value. Typical values would be "Radio", "Television", "Web", etc.
Example:
in Aegis, Media program name = Radio. Media code = 88.9FM.
In RaiseDonors, Media code = 88.9FM, Name = "WAY FM, 88.9".
The key is that the Aegis Media Code matches exactly to the RaiseDonors Media Code.
Note: It is possible to leave the Media Program Name empty for this setting. Doing so will still send the media program name.
Default Project Code
This must exist in Aegis. Use the Project "ID", not the Project "name".
Since there is no bidirectional sync of project codes between RaiseDonors and Aegis, the project codes must be supplied in RaiseDonors exactly as they are in Aegis. If a project is provided which does not exist in RaiseDonors, the default project code will be used instead. Please use the Project "code" and not the Project "ID".
Default Appeal Code
This must exist in Aegis. Use the Appeal "Id", not the Appeal "name".
Every donation page in RaiseDonors can be configured with an appeal code. The appeal code configured in the page can be overwritten via url parameters. This value is not required in RaiseDonors, but Aegis requires every incoming transaction to be associated with a valid appeal code. In the situation where a transaction is being sent to Aegis without an appeal code, the system will insert the value you provide here—ensuring every transaction has an appeal code. Note: if the appeal code supplied from RaiseDonors is invalid, this default appeal code will be used instead.
Default Origin Source Code
This must exist in Aegis. Use the Origin Source "Name", not the Origin Source "id".
When creating pages in RaiseDonors, the page can be configured with an origin source code. The origin source code configured in the page can be overwritten through URL parameters. This value is not required in RaiseDonors, but Aegis requires every incoming transaction to be associated with a valid origin source code.
In a situation where a transaction is being sent to Aegis without an origin source code, the system will insert the value provided here—ensuring every transaction has an origin source code.
Note: if the origin source code supplied from RaiseDonors is invalid, this default origin source code will be used instead.
Shipping Method
When a donation has an associated product, the integration will create an order. For the order to be fulfilled, Aegis requires a shipping method to be supplied. The integration will use the shipping method you select here when sending data to Aegis.
State ISO Code
When sending address information to Aegis, state names from the USA can be configured to be sent as two-letter abbreviations (ie: TX) or as full name text (ie: Texas).
Tip: it is recommended to use the two-letter abbreviation (ie: ISO2).
Country ISO Code
When sending address information to Aegis, country names can be configured to be sent as any one of the following:
- ISO3 - 3 digit code (ie: USA)
- ISO2 - 2 digit code (ie: US)
- Full name (ie: United States of America)
Tip: it is recommended to use ISO2.
Default Payment Type
A Default Payment Type must exist in Aegis. Reference the getting started guide for instructions on where to locate this value.
Default Payment Type for Credit Card
When a transaction is made via credit card, the integration will send the selected value to Aegis as the payment type.
Default Payment Type for Recurring Credit Card Charges
When an iteration of a recurring schedule is made via credit card, the integration will send the selected value to Aegis as the payment type.
Default Payment Type for E-Check
When a transaction is made via E-Check, the integration will send the selected value to Aegis as the payment type.
Default Payment Type for Recurring E-Check Charges
When an iteration of a recurring schedule is made via E-Check, the integration will send the selected value to Aegis as the payment type.
Recorded By
Aegis allows you to configure who is recording the transaction in Aegis from RaiseDonors. Supply the name here.
In Honor/Memory Of — Project Code
This must exist in Aegis. Use the Project "Id", not the Project "name".
When a donation is placed which includes In Honor/Memory Of information, Aegis requires this attribute information to be associated with a specific project code. Supply the correct project code here.
Attribute names
RaiseDonors will attach various attributes to the partner and transaction objects. The attribute names can be customized to your specifications as needed. Each attribute is provided below for reference.
Gift Aid Requested by Name
Allows you to specify the attribute name when the donor has indicated they have requested Gift Aid. The value of this attribute will be True/False.
Recommended value: RD.GiftAidRequested
Media Outlet Name
Allows you to specify the attribute name when the donor has selected a media outlet. The value of this attribute will be the media outlet value.
Recommended value: RD.MediaOutletName
In Honor Of Name
Allows you to specify the attribute name when the donor has indicated the donation is in honor of someone. The integration will take the provided value (ie: "In_Honor_Of") with 11 variations.
- {Provided In Honor Name} + "_First_Name"
Ex: In_Honor_Of_First_Name - {Provided In Honor Name} + "_Last_Name"
Ex: In_Honor_Of_Last_Name - {Provided In Honor Name} + "_Personalized_Note"
Ex: In_Honor_Of_Personalized_Note - {Provided In Honor Name} + "_Summary"
Ex: In_Honor_Of_Summary- First_Name
- Last_Name
- _Suffix
- _Postal_Address_Line
- _Postal_City
- _Postal_Country
- _Postal_Postal
- _Summary
- _OccasionOrName
- _Personalized_Note
- _DeliveryMethod
In Honor of Product SKU
To properly send In Honor of information to Aegis, it must be associated with a product SKU. Provide the product SKU so that the information is placed into Aegis properly.
In Memory Of Name
Allows you to specify the attribute name when the donor has indicated the donation is in memory of someone. The integration will take the provided value (ie: "In_Memory_Of") with 11 variations.
- {Provided In Memory Name} + "_First_Name"
Ex: In_Memory_Of_First_Name - {Provided In Memory Name} + "_Last_Name"
Ex: In_Memory_Of_Last_Name - {Provided In Memory Name} + "_Personalized_Note"
Ex: In_Memory_Of_Personalized_Note - {Provided In Memory Name} + "_Summary"
Ex: In_Memory_Of_Summary
In Memory of Product SKU
To properly send In Memory of information to Aegis, it must be associated with a product SKU. Provide the product SKU so that the information is placed into Aegis properly.
RaiseDonors Donation ID Name
Allows you to specify the attribute name for the Donation ID from RaiseDonors. The value of this attribute will be the ID of the donation from RaiseDonors.
Recommended value: RD.Donation.Id
RaiseDonors Donation Comment Name
Allows you to specify the attribute name for the donation comment from RaiseDonors. The value of this attribute will be the comment (if supplied) from the donation.
Recommended value: RD.Donation.Comment
RaiseDonors Donor ID Name
Allows you to specify the attribute name for the Donor ID from RaiseDonors. The value of this attribute will be the ID of the donor from RaiseDonors.
Recommended value: RD.Donor.Id
System Name
Allows you to specify the attribute name for the system where this transaction originated from. The value of this attribute will be "RaiseDonors".
Recommended value: System
Currency Name
Allows you to specify the attribute name for the currency used to place this donation. The value of this attribute will be the three digit currency code, ex: GBP, HKD, AUD, CAD, etc.
Note: Us Dollar ($) is assumed to be the default and this attribute will not be included for USD donations.
Recommended value: RD.Currency
Refund
If a transaction is refunded through RaiseDonors, the integration will push along an attribute with information about the refund to the transaction. Please provide the name of this attribute for when Refunds take place.
Recommended value: RD.RefundNotes
Options
How to match incoming transactions with existing partners?
When RaiseDonors sends transaction information to Aegis CRM, the API requires that we include a valid Partner ID. This means the integration will first query Aegis CRM and attempt to match the contact information from the donation with an existing donor in Aegis.
How should this business logic be configured to determine when a match occurs?
- Email
Solely use the email address from the donation to locate a partner in Aegis. - First Name & Last Name
Use the supplied first and last name to locate a partner in Aegis. - Email & Last Name
Use the supplied email address and last name to locate a partner in Aegis. - Email & First Name & Last Name
Use the supplied email address, first name, and last name to locate a partner in Aegis. - Email & Last Name & Zip Code
Use the supplied email address, last name, and the zip code to locate a partner in Aegis. - Email & First Name & Last Name & Zip Code
Use the supplied email address, first name, last name, and zip code to locate a partner in Aegis.
Tip: it is recommended to use "Email & Last name & Zip Code" for best results.
How should multiple matches be handled?
When configuring how RaiseDonors should find partners in Aegis for an incoming donation, it's possible that the business rules return more than one result.
In this instance, what should the integration do?
- Use the Oldest Record
The integration can choose the oldest partner being returned in the list, and attach the transaction to this partner. The oldest partner is calculated by comparing the date created property on each partner being returned. - Use the Newest Record
Similar in concept to "use oldest record", except this will use the newest partner (per the data created property). - Create New Account
When multiple records are returned, this setting would create a new partner by using all of the information supplied in the donation. You can then leverage Aegis' CRM tools to identify and merge duplicate partner records.
Tip: it is recommended to "Use the Oldest Record" setting for best results.
Partner QC Check?
When a partner is created or edited, you can configure the integration to require a QC check inside Aegis, before the changes are submitted. Setting these values to false (for add and/or edit), will require manual review before saving permanently in Aegis.
Include rich meta information about donations
When a transaction is submitted to a batch in Aegis, RaiseDonors can include a wealth of additional information into the transaction comments field. This would include data points such as, recurring schedule information, authorization #, transaction id, the page they gave through, payment summary information, google UTM codes, IP Address, etc.
Update Primary Billing Address
When a transaction is submitted to a batch in Aegis, the transaction can be configured to instruct Aegis CRM to update the partner's billing information on file with the newly supplied information on the transaction. This could be identical information or it could be different information.
Update Primary Email Address
When a transaction is submitted to a batch in Aegis, the transaction can be configured to instruct Aegis CRM to update the partner's email information on file with the newly supplied information on the transaction. This could be identical information or it could be different information.
Include Test Transactions?
The integration has the option to include test donation data when integrating with Aegis CRM.
Include Refunded Donations?
In the event an admin from RaiseDonors refunds a donation, would you like this refund to be pushed into Aegis CRM? The transaction will be supplied to Aegis CRM with a negative amount to indicate the refund.
Include Declined Recurring Donation Instances?
If a recurring schedule attempts a charge which results in a decline, would you like the declined transaction to be sent to Aegis CRM? The transaction sent to Aegis CRM will have the amount set to zero. Please proceed with caution when enabling this setting as it may create large quantities of data.
Debug Mode Enabled?
If you are experiencing difficulty with the Aegis CRM integration, you can turn on debug mode. Doing so will log additional information about each API request/response to Aegis and attach the log data to the corresponding donation.
Do Quality Pre-Check?
If RaiseDonors sends a code that doesn't exist in Aegis, it can cause an error. This pre-check will ensure all data fields have matching values in Aegis. In the even a field doesn't match, the system will use the associated default value provided in the configuration settings.
The following data fields are monitored:
- Appeal code
- Origin source code
- Transaction.Gift.ProjectCode
Notifications
Error Notifications
If any error or unexpected exception occurs while communicating with Aegis API, you can supply one or multiple email addresses to be notified. This notification will be sent via email and contain all of the relevant information needed to troubleshoot the issue.
Notify if Quality Pre-Check Fails
If the data integrity check fails, the system can send a brief email to the error notification list, explaining which donation and which data element is failing data integrity with Aegis. This feature will only send an email if the "Do Quality Pre-Check" feature is enabled.