NOTE: Custom API Implementation is only available for 360MatchPro Enterprise clients. Learn more about 360MatchPro Enterprise here or reach out to your Client Success team member at support@doublethedonation.com for more information.

Custom Implementation

• Step 1. Add our code to your form
• Step 2. Add our code to your confirmation
• Step 3. Test your integration

We've designed 360MatchPro to be easily integrated into any platform, via both a JavaScript API, and a REST interface. The primary piece of information we require is the donor's company information. This is best obtained directly on your donation form, and we provide a simple JavaScript tool to add our streamlined company search into your donation form. If you do not wish or are unable to add our tool to your donation form, skip to Step 2 and set up our plugin on the confirmation page.

Step 1: Adding our streamlined company search plugin to your donation form

Include our CSS and JavaScript somewhere on the page.

<!--Listing 1-->
<script src="https://doublethedonation.com/api/js/ddplugin.js"></script>
<link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet"/>

Insert the following div element in the form where you want our input to appear. Ensure that it is placed within the form tag of your donation form.

<!--Listing 2-->
<script>var DDCONF = {API_KEY: "<360matchpro_public_key>"};</script>
<div id="dd-company-name-input"></div>

Troubleshooting: If the above doesn't work, it's likely that your donation form is dynamically generated with JavaScript. If this is the case, run the following JavaScript instead after your donation form has been inserted into the DOM:

//Listing 3
if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason

  doublethedonation.plugin.load_streamlined_input(); // Loads the search into a DOM element with id="dd-company-name-input"

  // Alternatively, if you create DOM elements dynamically, you could also call it with a DOM element specified:
  var streamlined_search = jQuery("<div id='dd-container'></div>"); // Create the element
  streamlined_search.after("#placeholder"); // Insert it somewhere
  doublethedonation.plugin.load_streamlined_input(streamlined_search[0]); // Load the search with this element
}

Behind the scenes: Our streamlined search widget works by creating the following three hidden inputs in the nearest enclosing form:

1. doublethedonation_status:
• "found": Search was used and company was selected
• "not_found": Search was used but company wasn't found
• "no_interaction": Search wasn't used
2. doublethedonation_company_id: Double the Donation company ID if a company was found (string)
3. doublethedonation_company_name: Double the Donation company name if a company was found (string)

You can record these values into your database for future use, such as querying for company details via our API, or for populating the confirmation page as per the next section.

Sample Form: Below is a sample donation form to showcase the behavior of the streamlined search tools, which is the input field under "Matching Gift Company Name". You can enter a company in the following form to see it working.

Sample Donation Form

Donation UUID (hidden)

Donor Name

Donor Email

Donation Amount

Matching Gift Company Name

Step 2: Adding our donation submission code and plugin on the confirmation page

Note: This step is mandatory regardless of whether you've installed our plugin on your donation form.

Include our CSS and JavaScript somewhere on the page:

<!--Listing 4 (same as Listing 1 above)-->
<script src="https://doublethedonation.com/api/js/ddplugin.js"></script>
<link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet"/>

Pass the donation to our systems via a JavaScript function (doublethedonation.integrations.core.register_donation), filling out the fields with the schema described here. Here's an example submission:

//Listing 5
 if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason
  doublethedonation.integrations.core.register_donation({
    "360matchpro_public_key": "<360matchpro_public_key>",   //Replace this key with your 360MatchPro public key
    "campaign": "EY_2017_Fall",
    "donation_identifier": "I-YE238388",
    "donation_amount": 123.30,
    "donor_first_name": "John",
    "donor_last_name": "Doe",
    "donor_email": "john@example.com",
    "donor_address": {"zip": 30301,         //numeric, but string (eg. "30301", "30101-123") will work
                      "city": "Atlanta",
                      "state": "GA",
                      "address1": "8769 Party Central Drive",
                      "address2": "suite 901",
                      "country" : "US"},   //ISO 3166-1 alpha-2 country code (eg. "US", "CA", "GB")
    "donor_phone": "(123) 456-7890",       //This is an example. Your phone number can be formatted differently.
    "donation_datetime": "2018-12-25T10:15:30-05:00",
    "doublethedonation_company_id": 50,     // only needed if using streamlined search
    "doublethedonation_entered_text": "Home Depot" // only needed if streamlined search used on donation page
  });
 };

Add our plugin and initialize it. If the streamlined search is installed and a company was picked, the plugin will open to the company page. If not, we set up tracking so that we can record what the user selects for the donation:

<!--Listing 6-->
<div id="dd-container"></div> <!-- Container for our plugin, add this where you want it to show -->

<script>
  var DDCONF = {API_KEY: "<360matchpro_public_key>"};
  var dtd_selected_company = 50;   // Initialize this variable to be the doublethedonation_company_id, if a streamlined search is used
  var dtd_selected_company = null; // Use null if you don't use the streamlined search, or if doublethedonation_company_id is null
  if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason
    doublethedonation.plugin.set_donation_identifier( "DONATION_IDENTIFIER" ); // Replace with actual identifier or an empty string
    doublethedonation.plugin.set_donation_campaign( "CAMPAIGN" ); // Replace with actual campaign
    if (dtd_selected_company) {
      doublethedonation.plugin.set_company(dtd_selected_company);
    } else {
      var domain = doublethedonation.integrations.core.strip_domain( "EMAIL_ADDRESS" ) ; // Replace "EMAIL_ADDRESS" with actual email
      doublethedonation.plugin.email_domain( domain ); // Checks for a company based on the email address
    }
  }
</script>

If you do not want, or unable to use JavaScript to pass us the donation information, you may pass it to us via our RESTful API instead.

We use the following data schema for donations, passed to us via JSON as illustrated in Listing 5:

• 360matchpro_public_key (required): This the key used to tie this donation to your 360MatchPro account. It is provided in the setup email.
• campaign (required): Campaigns are arbitrary containers used to group donations. You can add all donations into one campaign, or you can break them out into separate campaigns. Some sample campaigns would be: "FY2016-Fall", "Boston Walkathahon", "EOY_Giving", etc
• donation_identifier (required): This is an identifier that you generate. It can contain spaces and special characters. The donation identifier is used to tie entries in 360MatchPro back to entries in your database or CRM. For example, you could have your own internal identifier for this donation, such as "PI-4819934", and you can use this value as the identifier. If not, you could generate a UUID, and give us that UUID, while also storing it on your backend for future reference.
• donor_email (strongly recommended): The email address associated with the donation. We have built a large database of email domains that correspond with companies, and we use it to identify donations which are matching gift eligible. Emails are also required for manual and automated emails.
• donor_first_name (strongly recommended): This indicates the first name of the donor. This is used in email templates.
• donor_last_name (strongly recommended): This indicates the last name of the donor. This is used in email templates.
• donation_amount (strongly recommended): This is an integer or decimal value describing the dollar amount of the donation. This is used to identify the best matching gift opportunities and used in email templates.
• donation_datetime (optional): Date and time of the donation expressed according to ISO 8601. If a timestamp is not provided, the current date and time will be assigned to the donation. While this field is generally omitted for online transactions, it is particularly useful for uploading donations that aren't in real-time (e.g. offline donations).
• donor_address (optional): This is a JSON object that contains the donor's address. This information is important when the 360MatchPro direct mail option is enabled. For an example, please reference Listing 5 above. The donor_address field is not required. If it is provided, all fields except address2 are required. If the requirements aren't met, the donation will be registered but the donor_address will be omitted.
• donor_phone (optional): The donor's phone number. No requirements for format. Can contain "(", ")", "-", and other characters. (string)
• doublethedonation_company_id (only used if using a streamlined search on the donation form): This is our DTD internal company ID that is passed to you from our plugin on the donation form. You will have to provide it back to us via this field.

Step 3: Testing your custom implementation

Have you completed steps 1 and 2 in the implementation process? It's time to run a test to make sure everything is working perfectly. Refer to our testing documentation here.