Bloomerang API Documentation

  1. Introduction
  2. Self-Hosted Forms
  3. Bloomerang.js
    1. Required Methods
      1. useKey
      2. useProcessor
    2. Data Methods
      1. Account
        1. individual
        2. organization
        3. organizationName
        4. firstName
        5. middleName
        6. lastName
        7. prefix
        8. suffix
        9. informalName
        10. formalName
        11. envelopeName
        12. recognitionName
    3. Form Submission Methods

Bloomerang API Documentation

This document discusses the different ways to use the Bloomerang API to make online donations. The typical use case for an online donation is to have an online donation page that collects the donor’s personal information, donation information, and payment information. When the form is submitted, a Spreedly iFrame will pop up where donors can enter their credit card information. Spreedly then injects a token into the form. Then the browser submits the token and the rest of the information to Bloomerang’s OnlineDonation endpoint.

Bloomerang will:

  1. Create a new account for the constituent or merge the constituent with an existing constituent that matches the new information.
  2. Use the token to process the credit card or EFT account with the processor (Stripe or BluePay).
  3. Save the donation information in the database.
  4. Send an e-mail to the constituent thanking him or her for the donation.

There are a few different ways to do this depending upon the level of customization desired:

  1. Use Bloomerang’s online donation forms within the application.
  2. Use Bloomerang.js to assemble and submit the data.
  3. Make a submission using another technology to our REST API.

Using Bloomerang’s online donation forms within the application is the recommended way to receive online donations. If you need additional customization beyond what Bloomerang provides, you can switch the form into “Self Hosted” mode and obtain the code for the Bloomerang form, which you can then customize. This is the easiest way, since all the boilerplate code necessary to make a working form will already be included.

Using Bloomerang.js is the second recommended way to receive online donations. This has the added benefit of the developer having full control over everything except how the data is posted to Bloomerang. It also allows the site to benefit from improvements that Bloomerang makes to Bloomerang.js, but any changes Bloomerang makes to our built-in donation forms will not be included. Note that it is the developer’s responsibility to keep their custom forms up to date as Bloomerang.js changes. We will try to introduce new versions of Bloomerang.js for compatibility reasons, but security or other concerns may require breaking changes to existing versions of Bloomerang.js.

Finally, if another technology is required, the Bloomerang REST API is available, but loses out on all of the convenience of Bloomerang.js and any updates that happen. Again, it is the developer’s responsibility to update their software to keep up with any changes to the Bloomerang REST API endpoints.

Bloomerang Self-Hosted Forms

Bloomerang Self-Hosted Forms are the preferred way to add custom forms to Bloomerang. Using Bloomerang’s in-application website integration tools, you can set up a form that comes as close as possible to your desired functionality and then make any further modifications to your form based on your unique needs.

To use Bloomerang’s in-application website integration, go to Settings -> Website Integration. There you can make a new form with options to set the name of the form, the processor it uses (if it is a donation form), a confrmation email to send when the form is submitted, and other options such as custom fields. This removes the need to manually look up IDs when using Bloomerang.js, and assuming no further customization, Bloomerang could keep everything up to date.

If you need to make further customizations to the form, continue to the Preview page. Then, scroll all the way to the bottom of the screen and click the “Self-Host Form” button. This swiches the form into self-hosted mode and gives you access to the form’s source code, including all of the calls it makes to Bloomerang.js. You can then copy and paste the code for the form into your own website, and make any changes you like.

Note that once the form is in self-hosted mode, any changes you make in the Bloomerang editor may not be reflected in the form on your website. This could cause your form to stop working! For example, if you enable CAPTCHAs in Bloomerang and do not add a CAPTCHA to the form itself, any submissions will be rejected.

However, some changes made in the Bloomerang editor will still affect the form’s behavior. For example, if there is no Campaign specified in the form itself, changing the form’s campaign in Bloomerang will cause the new Campaign to be used for any future submissions. Essentially, what is specified in the form builder are the default values, but you can override them in the self-hosted form code if you desire.

Bloomerang.js

Bloomerang.js is the bridge between our in-application advanced code editor and our REST API. It handles all of the technology behind getting a message in the right format to our servers and lets you focus on developing the form itself.

Note that the filename will contain the version of the library you are referencing. For example, you might write your form using Bloomerang-v2.js. This documentation assumes you are using the most current version of Bloomerang.js

Required Methods

The following methods are the few setup methods that must be called to have a successful online donation submission. Note that online donation forms created through the application automatically call Bloomerang.useKey and Bloomerang.useProcessor, if necessary.

Bloomerang.useKey(publicKey)

This function sets the public key used to tell Bloomerang who your organization is. You may obtain the public key from the application at https://crm.bloomerang.co/Settings/Database/Edit or by navigating to Settings -> View All Settings -> Organization.

publicKey required A string that begins with “pub_ ”.

Bloomerang.useProcessor(id, type, publicKey, isTestMode, bluePayTPS, restrictBPCredit)

This function sets the processor to which Bloomerang will post the credit card or EFT information.

This is only needed if you are using BluePay as the form processor and also supporting EFT. Otherwise, the credit card processing will be handled through Spreedly.

id required The Bloomerang ID of the processor to use. Can be obtained from Settings -> View All Settings -> Transactions -> Credit Card Processors. Select the processor you want, then the ID is the numerical portion of the URL https://crm.bloomerang.co/Settings/Transaction/CreditCardProcessor/Edit/{id}.
type required “BluePay” is the only valid value
publicKey required The “Account ID” for a BluePay processor. Can be found in the same location as the processor’s Bloomerang ID.
isTestMode optional – defaults to false A boolean value telling whether or not the processor is in test mode.
bluePayTPS required The MD5 hash of the string concatenation of the processor’s BluePay private key and the string “AUTH0ACH”. For example, if the BluePay private key were “1111”, the bluePayTPS would be the MD5 hash of “1111AUTH0ACH”, or “c8fc6dfcf7fd6373a2b0d4154a4cb709”.
restrictBPCredit required A boolean value. Must be true. This is required to ensure that bad guys can’t use the BluePay TPS to authorize credit cards fraudulently.

Data Methods

The following methods set the data on the Bloomerang object model, which will be used to actually send the data to Bloomerang via the form submission methods.

Account

These methods set information on the Account that will be submitted.

Bloomerang.Account.individual()

Sets the account type of the donor to Individual (a person, not an organization).

Bloomerang.Account.organization()

Sets the account type of the donor to Organization (not an individual).

Bloomerang.Account.organizationName(value)

Sets the full name of the organization. Also calls Bloomerang.Account.organization() to set the type of the account to Organization.

value required The full name of the organization

Bloomerang.Account.firstName(value)

Sets the donor’s first name. This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

value required The donor’s first name.

Bloomerang.Account.middleName(value)

Sets the donor’s middle name. This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

value required The donor’s middle name.

Bloomerang.Account.lastName(value)

Sets the donor’s last name. This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

value required The donor’s last name.

Bloomerang.Account.prefix(value)

Sets the donor’s name prefix (Mr., Mrs., Dr., etc.). This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

value required The donor’s name prefix. This must be one of the prefix values recognized by Bloomerang:
Mr, Miss, Ms, Mrs, Master, Rev, Pastor, Fr, Dr, Atty, Prof, Hon, Pres, Coach , Gov, Sir, Rep, Sen, Pvt, Sgt, Maj, Capt, Cmdr, Lt, Col, Gen, Rabbi, Sr

Bloomerang.Account.suffix(value)

Sets the donor’s name suffix (Jr., III, etc.). This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

value required The donor’s name suffix. This must be one of the suffix values recognized by Bloomerang:
Jr, Sr, II, III, IV, V, Esq, PhD, MD, DDS

Bloomerang.Account.informalName(value)

Sets the donor’s informal name. This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

If this is not called, the informal name will default to the donor’s first name.

value required The donor’s informal name

Bloomerang.Account.formalName(value)

Sets the donor’s formal name. This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

If this is not called, the informal name will default to “Prefix LastName”.

value required The donor’s formal name

Bloomerang.Account.envelopeName(value)

Sets the donor’s envelope name (the name that should be printed on mailing labels). This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

If this is not called, the envelope name will default to “Prefix FirstName LastName Suffix”.

value required The donor’s envelope name

Blooemrang.Account.recognitionName(value)

Sets the donor’s recognition name. This does not set the account type to Individual, so if you had previously set the account to be an organization, you first call Bloomerang.Account.individual().

If this is not called, the recognition name will default to “Prefix FirstName MiddleName LastName Suffix”.

value required The donor’s recognition name

Form Submission Methods

These are the methods used to actually send the form submission to Bloomerang.