Back

Bloomerang API Essential Guide

Aug 16, 20246 minute read

What type of API does Bloomerang provide?

Based on the search results provided, Bloomerang offers a REST API. Here are the key points:

REST API

  • Bloomerang has a REST API for server-to-server integrations.
  • The REST API uses a private key for authentication and allows pushing and pulling data from the Bloomerang database.
  • There are two versions of the REST API:
    • The current REST API (recommended for new integrations)
    • REST API v1 (deprecated but still available for existing integrations)

Key Considerations

  • The REST API is intended for server-to-server integrations, not for client-side use.
  • The private API key must be kept secret, as it allows full access to change data.
  • Bloomerang also offers a public key API called Bloomerang.js for client-side integrations like online forms.

Best Practices

  • Use the current REST API version for new integrations.
  • Keep the private API key secure and do not expose it in client-side code.
  • For online forms and client-side integrations, consider using Bloomerang.js instead of the REST API.

In summary, Bloomerang primarily offers a REST API for server-side integrations, with additional options like Bloomerang.js for client-side use cases. The REST API is the main type of API provided by Bloomerang for data integration purposes.

Does the Bloomerang API have webhooks?

Based on the search results provided, it does not appear that the official Bloomerang API offers webhooks. The search results focus primarily on Bloomerang's REST API capabilities and other features, but do not mention webhooks specifically. Here are the key points:

API Capabilities

  1. Bloomerang offers two main ways to interact with their system via API:

    • Bloomerang.js: A public key API for submitting form data to Bloomerang's servers.
    • REST API: A private key API for server-to-server integrations.
  2. The REST API allows for pushing and pulling final data from the Bloomerang database.

  3. The API documentation covers various endpoints for managing constituents, donations, interactions, and other data within Bloomerang.

Key Considerations

  • The REST API requires a private key, which must be kept secure.
  • OAuth registration is recommended for more secure third-party access to data via the REST API.
  • The API allows for operations like creating, updating, and retrieving various types of records (e.g., constituents, donations, interactions).

Conclusion

While Bloomerang offers robust API capabilities for integrating with their system, there is no mention of webhook functionality in the provided search results. The focus appears to be on RESTful API interactions rather than event-based webhooks. If webhooks are a critical requirement for your integration needs, you may need to explore alternative solutions or contact Bloomerang directly for the most up-to-date information on their API capabilities.

Rate Limits and other limitations

Unfortunately, I could not find any specific information about API rate limits for the Bloomerang API in the provided search results. The search results contain general information about Bloomerang's API offerings and documentation, but do not mention rate limits. Without more specific information from Bloomerang's official documentation, I cannot provide details on their API rate limits.

To get accurate information about Bloomerang's API rate limits, I would recommend:

  1. Checking Bloomerang's official API documentation for any published rate limit information.

  2. Contacting Bloomerang's support or developer relations team directly to inquire about their current API rate limit policies.

  3. Reviewing any developer agreements or terms of service for the Bloomerang API, which may contain rate limit details.

  4. Testing the API with gradually increasing request volumes to determine if and when rate limiting occurs.

API rate limits are an important consideration when integrating with any service, so obtaining this information directly from Bloomerang would be advisable before building any high-volume integrations. Without official documentation, the actual limits may change without notice, so relying on published information from Bloomerang is the best approach.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Bloomerang API:

Current REST API

The most recent version of the Bloomerang API is the current REST API. This is the recommended version for creating new connections with Bloomerang.

Deprecated REST API v1

The REST API v1 is now deprecated. While it is still available for existing integrations created before June 16, 2020, it is no longer receiving updates.

Key Points to Consider

  1. If you are creating a new integration with Bloomerang, it is recommended to use the current REST API.

  2. The current REST API documentation can be found on the Bloomerang website, which includes a Swagger UI for exploring the API.

  3. Bloomerang also offers a public key API called Bloomerang.js, which is designed for online forms and allows adding donations and interactions to Bloomerang.

  4. The REST API is a private key API intended for server-to-server integrations. It requires keeping the private key secret and is not suitable for online transaction forms.

Best Practices

  1. Always use the most recent version of the API (current REST API) for new integrations.

  2. Keep private keys secret when using the REST API for server-to-server integrations.

  3. For online forms and public-facing integrations, consider using Bloomerang.js instead of the REST API.

  4. Regularly check the Bloomerang changelog for updates and new features related to the API.

In summary, the most recent version of the Bloomerang API is the current REST API, which is recommended for all new integrations. The older REST API v1 is deprecated but still available for existing integrations.

How to get a Bloomerang developer account and API Keys?

Generate API Keys

  1. Log in to your Bloomerang account as an Administrator User.

  2. Click on the profile icon at the top right of the page.

  3. Select "Edit My User".

  4. In the "API Keys 2.0" section, click "Generate".

  5. Enter a name for the API key in the "Name" field.

  6. Click "Generate" to create the new API key.

Key Points to Consider

  • Private API keys are handled at the user level in the database.
  • You can generate multiple API keys if needed.
  • API keys are specific to each Administrator User and can only be accessed while logged into your own user account.
  • Deactivating a User Account with active API keys will also deactivate any associated keys.

Best Practices

  1. Keep your API key secret: The private key allows anyone to change any information they want, so it's crucial to keep it secure.

  2. Choose the appropriate integration method:

    • For server-to-server integrations, use the REST API with a private key.
    • For online forms that need to be submitted from a user's browser, use Bloomerang.js instead.
  3. Consider OAuth for third-party access: If you need to allow a third party to access your data via the REST API, OAuth registration is a more secure solution than sharing your private key.

  4. Stay updated: Be prepared to update your integration as the Bloomerang API changes.

  5. Test thoroughly: Before deploying your integration, test it thoroughly using Bloomerang's test forms.

What can you do with the Bloomerang API?

Based on the search results provided, here is a list of data models that can be interacted with using the Bloomerang API, along with what is possible for each:

Constituent (Account)

  • Create new constituent records
  • Update existing constituent records
  • Set personal information like name, gender, birthdate, etc.
  • Set contact information like phone numbers, email addresses, physical addresses
  • Set organizational information for organization accounts
  • Add custom fields

Donation

  • Create one-time donations
  • Set donation amount, date, fund, campaign, appeal
  • Add notes and custom fields
  • Process credit card or EFT payments
  • Handle split payments across multiple designations

Recurring Donation

  • Create recurring donation schedules
  • Set frequency (weekly, monthly, quarterly, yearly)
  • Set start date, amount, fund, campaign, appeal
  • Process initial payment

Interaction

  • Create new interactions
  • Set interaction date, subject, notes, channel, purpose
  • Mark as inbound or outbound
  • Add custom fields

Transaction

  • Create transactions that can be split into multiple designations
  • Designations can be donations, pledges, pledge payments, recurring donations, etc.

Custom Fields

  • Retrieve custom field definitions for constituents, interactions, transactions, etc.
  • Set values for custom fields when creating/updating records

Users

  • Retrieve user account information
  • Search for users

Campaigns

  • Retrieve campaign definitions

Funds

  • Retrieve fund definitions

Other

  • Authenticate and retrieve API keys
  • Submit forms and donations via Bloomerang.js frontend library

Key points:

  • The REST API provides more comprehensive access but requires server-side implementation
  • Bloomerang.js provides an easier frontend implementation for donations and interactions
  • Custom fields and values can be retrieved and set on various record types
  • Split transactions and payments are supported

The API allows for creating, retrieving, and updating most core data models in Bloomerang, with a focus on constituent management, donations, and interactions.