search
Request Demo
Demo
Request a Demo Search

API Documentation

Bloomerang has two ways to get data into the system using an API. They are:

  1. Bloomerang REST API (private key)
  2. Bloomerang.js (public key)

REST API

The REST API is a private key API. It is for server-to-server integrations. These integrations push and pull final data from the Bloomerang database. The private key allows anyone to change any information they want, so you must keep this key secret. Online transaction forms would expose the private key, so you cannot use the REST API with them. To submit donation information with the REST API, you must process the donations and collect any funds yourself. Then you submit the finished data to Bloomerang from your server. For more information on this type of integration, see the REST API documentation.

Looking for REST API v1? It is still available here. If you are starting a new integration, please see the current REST API documentation.

Bloomerang.js

Bloomerang.js uses a public key API. It takes information from a form and submits it to an API endpoint on Bloomerang’s servers. It allows anyone to add donations and interactions to Bloomerang. Only constituent records can be updated, such as with a new address. These characteristics make Bloomerang.js perfect for online forms. For more information about this type of integration, see the Bloomerang.js documentation.

Development Options

You have several options for creating forms, with varying levels of customization:

  • Use Bloomerang’s standard forms within the application.
  • Self-host Bloomerang forms.
  • Use Bloomerang.js to assemble and submit the data.
  • Submit data to the REST API using another technology.

We recommend using Bloomerang’s standard forms within the application. These forms have some customization options, and Bloomerang maintains them.

See Bloomerang’s help articles about creating forms.

For more customization, switch a standard form into self-hosted mode. Get the boilerplate code for the form and customize it. This is the easiest way to get a custom form, but you are responsible for making any future updates. See Bloomerang’s help articles about self-hosted forms.

Bloomerang.js gives you full control over everything except how the data posts to Bloomerang. As we improve Bloomerang.js, you can improve these forms, too. Sometimes changes for security or other concerns may break compatibility with older versions. You are responsible for updating custom forms as Bloomerang.js changes.

Finally, if you need to use another technology, you can use the Bloomerang REST API. The drawbacks are:

  • It is not as convenient as Bloomerang.js.
  • These forms are not updated with improvements to the REST API.
  • You must submit donation information from the server because you are using the organization’s private API key. You cannot submit from the constituent’s browser.
  • The Bloomerang REST API only accepts final data. You are responsible for building any PCI-compliant payment processing.
  • You are responsible for updating your software as the Bloomerang REST API changes.

How to Get Bloomerang IDs

Some functions in the REST API or Bloomerang.js need you to submit an item’s Bloomerang ID. This prevents forms from breaking if a user renames the item in Bloomerang. In general, you should submit IDs rather than names wherever possible.

To find an item’s Bloomerang ID, navigate to that item in Bloomerang.

The ID is the numerical part of the URL. For example, the URL for a constituent custom field might be https://crm.bloomerang.co/Settings/Constituent/CustomField/Edit/12345.

In this case, the Bloomerang ID is 12345.

Transaction Form Workflow

As you develop forms that process transactions, keep this typical workflow in mind:

  1. Constituents enter their personal and donation information and submit the form.
  2. A Spreedly iFrame opens, and constituents enter their credit card information.
  3. Spreedly adds a token to the form.
  4. The browser submits the token and the rest of the information to Bloomerang’s OnlineDonation endpoint.

Then Bloomerang:

  1. Creates a new account for the constituent or updates an existing constituent.
  2. Uses the token to process the credit card or EFT account with the processor (Stripe, Authorize.Net, or BluePay).
  3. Saves the donation information in the database.
  4. Sends a confirmation email to the constituent.

Recommendations for Developing Forms

We have a few recommendations for developing forms using Bloomeang.js or starting from the beginning.

Bloomerang.js

To use Bloomerang.js, we recommend this process:

  1. Create a form within Bloomerang.
  2. Put the form in Self-Hosted mode and copy the generated code.
  3. Tweak the functionality of the form as you desire. See Bloomerang.js for reference.

From the Beginning

If you really want to start from the beginning, here is the general process and some things to remember.

Create the Form in Bloomerang

Bloomerang needs to know about your form. If the form processes donations, it needs to know which processor it should use. Create a form within Bloomerang first.

Include Bloomerang.js in Your Page

Include a <script> tag on your website page that pulls in the newest version of Bloomerang.js. To get the correct version:

  1. Open the form you created.
  2. Put it in Self-Hosted mode.
  3. Copy the URL from the code.

Initialize the Form

Make sure Bloomerang.js is fully loaded. Then call Bloomerang.useKey() to register your form with Bloomerang.js.
If you are developing a transaction form, also call:

Register Bloomerang Event Handlers

Define handlers for the following Bloomerang-fired events.

Bloomerang.Api.OnSubmit

Bloomerang fires this just before the form is submitted. This is where you call all the appropriate data functions to set information for the account, donation, custom fields, and so on. Perform any validation here. If the function returns false, the donation is cancelled.

All Bloomerang forms on the page will fire this event. This is a problem if you have multiple forms on the same page (such as an email sign-up form and a donation form). In this case, you need to do two things:

  • When the form is loaded, define your own OnSubmit function specific to this form.
  • When submitting the form, set Blooomerang.Api.OnSubmit to be your form’s OnSubmit function.

Bloomerang.Api.OnSuccess

Bloomerang fires this when the form is successfully submitted. Here you display whatever thank-you message you want to show the constituents.

Bloomerang.Api.OnError

Bloomerang fires this if there is an error and the submission is not successful. The Message property of the response argument tells you what the problem is. You may display this error message to the constituent or log it for your own purposes. Call Bloomerang.cancelFinancialSubmission() if you want the constituent to be able to retry the submission.

Define Your Submit Handler

Add a submit handler to your form to set everything up before submitting the form using Bloomerang.js.

If you are developing a transaction form, your submit handler must:

Gotchas

Keep these things in mind when developing your form:

  • Wait for Bloomerang.js, Spreedly.js, jQuery, and any other dependencies to load before you enable the form. Otherwise, constituents may see errors and be unable to donate. For this reason, basic Bloomerang forms aren’t shown on the page until everything is ready to go.
  • Multiple forms on the same page can cause problems. For example, each form has its own Bloomerang.Api.OnSubmit handler. However, only the last one is used. If the page must have multiple forms, make sure they don’t interfere with each other when calling functions on Bloomerang.js.

Test Forms

Test your forms thoroughly before putting them on a public site. See Test Forms with Interactions and Test Forms with Transactions.