This version of the REST API is now deprecated. If you have an existing integration using this version (created before June 16, 2020), use this documentation for troubleshooting. However, this version will no longer be receiving updates. If you are creating a new integration, use the current 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.
The Bloomerang API is organized around REST. It’s a simple, resource-oriented approach to writing and reading data to and from a Bloomerang database. All you need to get started are your organization’s API keys. This help article describes where you can find these keys. You’ll notice that there are two keys: a Public key and a Private key.
Public Key
This is used for public integration points like an online donation form. This will not allow you to pull any records from your database, but will let you post donations/signups as well as (in the future) pull aggregate data such as a giving thermometer. Most of your database is off-limits using this key since it will likely be viewed in plain text somewhere on a web page.
All public API Keys start with “pub_” so you should be able to easily distinguish this from your private key.
Private Key
Guard this key with your life. This gives you full read/write access to any of your data exposed by any of the endpoints in the API. When writing hosted solutions/integrations this is the key that you will need to capture and supply with each call to authenticate yourself.
API – Key Handshake
One hurdle to integrating with Bloomerang is getting the user’s API key. Most endpoints require the user’s private key, so you’ll need that. You could ask your user to copy/paste their Bloomerang API Key into some field on your side but that doesn’t make for the greatest user experience. After all, most of your users will immediately ask themselves “what is an API?” To make this a bit more seamless, we’ve provided the Keys endpoint so that you can ask the user to enter their Bloomerang Username/Password on your side and then make an API call behind the scenes where we’ll authenticate those credentials for you and return their API keys if all goes well.
IMPORTANT: This should be something you do ONCE for a customer. Have them authenticate themselves and then you should store the API key on your side for future use. The user’s username and password may not be used to authenticate any other endpoints. So aside from the fact that it’s bad practice to store their Bloomerang Username/Password, it won’t do you any good. Just obtain the key and store that.
Sample Request
POST https://api.bloomerang.co/v1/Keys
{
Username: "[email protected]",
Password: "eyeH3@rtTw1light!"
}
{
PublicKey: "pub_2a7d9e94-eede-4d0c-b60d-82220ba6511a",
PrivateKey: "13891375-0310-4444-a659-43a81ba8b041"
}
Once you have your API keys, provide one of them using a process similar to HTTP Basic Auth. You only need to supply your key as the username for the basic auth – you can leave the password side blank (hence the trailing colon in the examples where we supply the key).
Note that this implementation is slightly different from RFC2617. You should not base64-encode the API key. If you’re using a standard REST client, set the Authorization header yourself instead of using that REST client’s built-in authentication framework.
You can search, get, update, and create constituents via the API. A constituent represents a donor, volunteer, or any other individual/organization affiliated with your organization in some way.
Retrieve a Constituent
GET https://api.bloomerang.co/v1/Constituent/{constituent-id}
GET https://api.bloomerang.co/v1/Constituent/1234
{
Type: "Individual"
Status: "Active"
FirstName: "Frodo"
LastName: "Baggins"
Middle: "H"
Prefix: "Mr."
Suffix: "Sr."
FullName: "Frodo H Baggins"
InformalName: "Frodo"
FormalName: "Mr. Baggins"
EnvelopeName: "Mr. Frodo Baggins Sr."
RecognitionName: "Mr. Frodo H Baggins Sr."
JobTitle: "Adventurer"
Employer: "Gandalf"
AccountNumber: 1
Website: "www.lordoftherings.net"
FacebookId: "frodobaggins"
TwitterId: "frodobaggins"
LinkedInId: ""
Gender: "Male"
Birthdate: "2968-09-22T00:00:00"
Address: {
AccountId: 1234
TypeName: "Home"
Street: "123 Main St."
City: "Hobbiton"
State: "New York"
County: ""
PostalCode: "12345"
Country: "United States"
IsPrimary: true
Id: 9332
},
Addresses: [ ... array of Address objects ... ],
PrimaryEmail: {
AccountId: 1234
TypeName: "Home"
Value: "[email protected]"
IsPrimary: true
Id: 9345
},
Emails:[ ... array of Email objects ... ],
PrimaryPhone: {
AccountId: 1234
TypeName: "Home"
Extension: "333"
Number: "(123) 123-5555"
IsPrimary: true
Id: 9349
},
Phones:[ ... array of Phone objects ... ],
EmailInterestType: "All",
AuditTrail: {
CreatedDate: "2016-06-28T14:34:49Z",
CreatedName: "[API]",
LastModifiedDate: "2016-06-28T14:34:49Z",
LastModifiedName: "[API]"
},
CustomFields: {
"Shirt Size": [1]
0: "L"
"Attributes": [3]
0: "Board Member"
1: "Volunteer"
2: "Member"
}
Id: 1234
}
Search For a Constituent
Rather than have you pull your entire database to find a constituent by their name or contact info, we expose the same search facility that the Bloomerang CRM application uses using the “q” query string parameter. You can facilitate paging via the “skip” and “take” parameters which default to 0 and 50 respectively to grab the first 50 matching results.
GET https://api.bloomerang.co/v1/Constituent/?q=Bob+Smith
GET https://api.bloomerang.co/v1/Constituent/?q=Bob+Smith
GET https://api.bloomerang.co/v1/Constituent/?q=Bob+Smith?skip=50
{
Total: 76,
Start: 0,
MaxItems: 50,
Results: [
{ ... account 1 info ... },
{ ... account 2 info ... },
...
{ ... account 50 info ... }
]
}
Update a Constituent
POST https://api.bloomerang.co/v1/Constituent/{constituent-id}
POST https://api.bloomerang.co/v1/Constituent/1234
{
Status: "Inactive",
TwitterId: "theringbearer"
}
{
Id: 1234,
Type: "Individual",
Status: "Inactive",
Prefix: "Mr.",
FirstName: "Frodo",
Middle: "H",
LastName: "Baggins",
Suffix: "Sr.",
FullName: "Frodo H Baggins",
InformalName: "Frodo",
FormalName: "Mr. Baggins",
EnvelopeName: "Mr. Frodo Baggins Sr.",
RecognitionName: "Mr. Frodo H Baggins Sr.",
Website: "www.lordoftherings.net",
FacebookId: "frodobaggins",
TwitterId: "theringbearer",
LinkedInId: "",
Gender: "Male",
Birthdate: "9/22/2968",
Address: {
Id: 9332,
AccountId: 1234,
TypeName: "Home",
Street: "123 Main St.",
City: "Hobbiton",
State: "New York",
PostalCode: "12345",
Country: "United States",
IsBad: false,
IsPrimary: true
},
Addresses: [ ... array of Address objects ... ],
PrimaryEmail: {
Id: 9345,
AccountId: 1234,
TypeName: "Home",
Value: "[email protected]",
IsPrimary: true
},
Emails:[ ... array of Email objects ... ],
PrimaryPhone: {
Id: 9349,
AccountId: 1234,
TypeName: "Home",
Number: "(123) 123-5555",
Extension: "333",
IsPrimary: true
},
Phones:[ ... array of Phone objects ... ],
EmailInterestType: "All"
AuditTrail: {
CreatedDate: "2016-06-28T14:34:49Z",
CreatedName: "[API]",
LastModifiedDate: "2016-06-28T14:34:49Z",
LastModifiedName: "[API]"
},
CustomFields: {
"Shirt Size": [1]
0: "L"
"Attributes": [3]
0: "Board Member"
1: "Volunteer"
2: "Member"
} }
Create a New Constituent
POST https://api.bloomerang.co/v1/Constituent/
We’ll assign an id that you’ll receive in the response. For Individual records, the FirstName and LastName fields are required. For Organization records, the FullName field is required (first and last are only if you want to track a primary contact for the org). Unless otherwise specified, the status will be Active.
POST https://api.bloomerang.co/v1/Constituent/
{
Type: "Individual",
FirstName: "Bob",
LastName: "Smith",
Website: "www.google.com",
Address: {
TypeName: "Home",
Street: "98123 Main St.",
City: "Indianapolis",
State: "Indiana",
PostalCode: "46250"
},
PrimaryEmail: {
TypeName: "Home",
Value: "[email protected]"
},
CustomFields: {
"Shirt Size": ["S"]
}
}
{
Id: 92344,
Type: "Individual",
Status: "Active",
Prefix: "",
FirstName: "Bob",
Middle: "",
LastName: "Smith",
Suffix: "",
InformalName: "Bob",
FormalName: "Bob",
EnvelopeName: "Bob Smith",
RecognitionName: "Bob Smith",
FullName: "Bob Smith",
Website: "www.google.com",
FacebookId: "",
TwitterId: "",
LinkedInId: "",
Address: {
Id: 92345,
AccountId: 92344,
TypeName: "Home",
Street: "98123 Main St.",
City: "Indianapolis",
State: "Indiana",
PostalCode: "46250",
Country: "United States",
IsBad: false,
IsPrimary: true
}
Addresses: [{ ... just the above address ... }],
PrimaryEmail: {
AccountId: 92344,
TypeName: "Home",
Value: "[email protected]",
IsPrimary: true,
Id: 601088
},
Emails: [
{
AccountId: 92344,
TypeName: "Home",
Value: "[email protected]",
IsPrimary: true,
Id: 601088
}
],
PrimaryPhone: null,
Phones: [],
EmailInterestType: "All",
AuditTrail: {
CreatedDate: "2016-06-28T14:34:49Z",
CreatedName: "[API]",
LastModifiedDate: "2016-06-28T14:34:49Z",
LastModifiedName: "[API]"
},
CustomFields: {
"Shirt Size": ["S"]
}
}
Attribute Reference
| Name | Description | Format | Required | Valid Values |
|---|---|---|---|---|
| ID | The automatically assigned unique identifier for the record | Long | No | |
| Type | The type of account | String | Required | Individual, Organization |
| Status | The status of the account | String | No | Active, Inactive, Deceased |
| Prefix | The name prefix or title, such as “Mr.” | String | No | |
| FirstName | The account’s first name. For organizations, this is the first name of the primary contact. | String | Required | |
| Middle | The account’s middle name. For organizations, this is the middle name of the primary contact. | String | No | |
| LastName | The account’s last name. For organizations, this is the last name of the primary contact. | String | Required | |
| Suffix | The name suffix, such as “Jr.” | String | No | |
| FullName | The name of the organization. Does not apply to accounts with Type = Individual. | String | No | |
| FormalName | We will auto-build this for you using name components. | String | No | |
| InformalName | We will auto-build this for you using name components. | String | No | |
| EnvelopeName | We will auto-build this for you using name components. | String | No | |
| RecognitionName | We will auto-build this for you using name components. | String | No | |
| Website | The constituent’s website. | String/URL | No | |
| FacebookID | The URL of the constituent’s Facebook page/profile. | String/URL | No | |
| TwitterID | The constituent’s Twitter handle. | String | No | |
| LinkedInID | The URL for the constituent’s LinkedIn profile. | String/URL | No | |
| Gender | The gender of the constituent | String | No | Male, Female, Other |
| Birthdate | The constituent’s birthdate. | Date | No | mm/dd/yyyy |
| Address | The address marked as Primary on a constituent’s record. | String | No | See API – Address. Addresses other than United States, Canada, or Bermuda use only the Country and Address attributes. See https://www.iso.org/obp/ui/#search for correct country codes. |
| PrimaryPhone | The phone number marked as Primary on a constituent’s record. | No | See API – Phone. Add “+” in front of a non-United States phone number. | |
| PrimaryEmail | The email address marked as Primary on a constituent’s record. | No | See API – Email | |
| Addresses | All of the constituent’s address records. | Array[Address] | No | |
| Phones | All of the constituent’s phone records. | Array[Phone] | No | |
| Emails | All of the constituent’s email addresses. | Array[Email] | No | |
| EmailInterestType | Set which type of emails a constituent is interested in receiving. | String | No | All, Custom, OptedOut. Defaults to All. You cannot set a constituent’s email interests to Custom through the API. |
| AuditTrail | Information about who created or modified a constituent and when. | String | No | Response only. |
| CustomFields | An associative array that maps names of custom fields to an array of applied values. | CustomFields | No |
Use the Duplicate Constituent Search API when you need to determine if a set of data matches an existing account. A classic case is determining if an online donation gets added to an existing account or a new account needs to be created first.
How Duplicate Search Works
When determining a duplicate, the system searches an index of the database to get a list of potential matches. It looks at:
- Full name (for organizations)
- First name (for individuals; includes common nicknames)
- Last name (for individuals)
- Standardized street addresses
- Email addresses
- Last seven digits of phone numbers
For individuals, both first and last names must match.
Second, the system pulls the accounts for the potential matches from the database and determines if each account is a duplicate.
How a Duplicate Is Determined
A potential match is a duplicate when the account IDs match, or when the name matches and one of the following matches:
- Email address
- Standardized street address
- Last seven digits of phone number
Full names for organizations must be identical to match. For individuals’ names to match, these must be identical:
- Last name
- First name, accounting for common nicknames
- Suffix, if both names have suffixes. If only one name has a suffix, the suffix is ignored.
Search for Duplicates
POST https://api.bloomerang.co/v1/Duplicates
POST https://api.bloomerang.co/v1/Duplicates
{
FirstName: "Bob",
LastName: "Smith",
Street: "98123 Main Street",
PhoneNumber: "(317) 5559-090",
Email: "[email protected]"
}
{
Total: 1,
Start: 0,
MaxItems: 500,
Results: [{
Id: 92344,
Type: "Individual",
Status: "Active",
Type: "Individual",
Prefix: "",
FirstName: "Bob",
Middle: "",
LastName: "Smith",
Suffix: "",
InformalName: "Bob",
FormalName: "Bob",
EnvelopeName: "Bob Smith",
RecognitionName: "Bob Smith",
FullName: "Bob Smith",
Website: "www.google.com",
FacebookId: "",
TwitterId: "",
LinkedInId: "",
Address: {
Id: 92345,
AccounId: 92344,
IsPrimary: true,
Type: "Home",
Street: "98123 Main St.",
City: "Indianapolis",
State: "IN",
PostalCode: "46250"
}
Addresses: [{ ... just the above address ... }],
PrimaryEmail: null,
Emails: [],
PrimaryPhone: null,
Phones: [],
EmailInterestType: "All",
AuditTrail: {
CreatedDate: "2016-06-28T14:34:49Z",
CreatedName: "[API]",
LastModifiedDate: "2016-06-28T14:34:49Z",
LastModifiedName: "[API]"
},
CustomFields: {}
}
]}
Attribute Reference
| Name | Description | Format | Required | Valid Values |
|---|---|---|---|---|
| Type | The type of account | String | No | Individual, Organization. Default is Individual. |
| FirstName | Use with Individual accounts only. The account’s first name. | String | Required | |
| LastName | Use with Individual accounts only. The account’s last name. | String | Required | |
| OrganizationName | Use with Organization accounts only. The organization’s complete name. | String | Required | |
| An email address. Compared to all email addresses in account’s profile. | String | No | ||
| PhoneNumber | A phone number. Compared to all phone numbers in account’s profile. | String | No | |
| Street | A street address. Compared to all street addresses in account’s profile. | String | No |
Two constituents may be merged. Organizations cannot be merged, nor can a constituent be merged into an organization.
To merge, the submitted constituent must match the first and last name, plus either phone, email, or address, of an existing constituent. See Duplicate Constituent Search for more details. If no match is found, a new constituent is created.
Merge Two Constituents
POST https://api.bloomerang.co/v1/Merge
POST https://api.bloomerang.co/v1/Merge
{
Type: "Individual",
FirstName: "Bob",
LastName: "Smith",
Address: {
Street: "98123 Main St.",
City: "Indianapolis",
State: "Indiana",
PostalCode: "46250",
},
PrimaryEmail: {
TypeName: "Home",
Value: "[email protected]"
},
PrimaryPhone: {
TypeName: "Home",
Number: "13175559876"
}
}
{
Id: 92344,
Type: "Individual",
Status: "Active",
Prefix: "",
FirstName: "Bob",
Middle: "",
LastName: "Smith",
Suffix: "",
InformalName: "Bob",
FormalName: "Bob",
EnvelopeName: "Bob Smith",
RecognitionName: "Bob Smith",
FullName: "Bob Smith",
Website: "www.google.com",
FacebookId: "",
TwitterId: "",
LinkedInId: "",
Address: {
Id: 92345,
AccountId: 92344,
TypeName: "Home",
Street: "98123 Main St.",
City: "Indianapolis",
State: "Indiana",
PostalCode: "46250"
IsBad: false
IsPrimary: true
}
Addresses: [{ ... just the above address ... }],
PrimaryEmail: null,
Emails: [],
PrimaryPhone: null,
Phones: [],
EmailInterestType: "All",
AuditTrail: {
CreatedDate: "2016-06-28T14:34:49Z",
CreatedName: "[API]",
LastModifiedDate: "2016-06-28T14:34:49Z",
LastModifiedName: "[API]"
},
CustomFields: {
"Shirt Size": ["S"]
}
}
{
Id: 123,
Type: "Individual",
Status: "Active",
Prefix: "",
FirstName: "Bob",
Middle: "",
LastName: "Smith",
Suffix: "",
InformalName: "Bob",
FormalName: "Bob",
EnvelopeName: "Bob Smith",
RecognitionName: "Bob Smith",
FullName: "Bob Smith",
Website: "",
FacebookId: "",
TwitterId: "",
LinkedInId: "",
Address: {
Id: 123,
AccountId: 123,
TypeName: "Home",
Street: "98123 Main St.",
City: "Indianapolis",
State: "Indiana",
PostalCode: "46250"
IsBad: false
IsPrimary: true
}
Addresses: [... array of Address objects ... }],
PrimaryEmail: null,
Emails: [],
PrimaryPhone: null,
Phones: [],
EmailInterestType: "All",
AuditTrail: {
CreatedDate: "2016-06-28T14:34:49Z",
CreatedName: "[API]",
LastModifiedDate: "2016-06-28T14:34:49Z",
LastModifiedName: "[API]"
},
CustomFields: {
}
}
Attribute Reference
| Name | Description | Format | Required | Valid Values |
|---|---|---|---|---|
| ID | The automatically assigned unique identifier for the record | Long | No | |
| Type | The type of account | String | Required | Individual, Organization |
| Status | The status of the account | String | No | Active, Inactive, Deceased |
| Prefix | The name prefix or title, such as “Mr.” | String | No | |
| FirstName | The account’s first name. For organizations, this is the first name of the primary contact. | String | Required | |
| Middle | The account’s middle name. For organizations, this is the middle name of the primary contact. | String | No | |
| LastName | The account’s last name. For organizations, this is the last name of the primary contact. | String | Required | |
| Suffix | The name suffix, such as “Jr.” | String | No | |
| FullName | The name of the organization. Does not apply to accounts with Type = Individual. | String | No | |
| FormalName | We auto-build this for you using name components. | String | No | |
| InformalName | We auto-build this for you using name components. | String | No | |
| EnvelopeName | We auto-build this for you using name components. | String | No | |
| RecognitionName | We auto-build this for you using name components. | String | No | |
| Website | The constituent’s website. | String/URL | No | |
| FacebookID | The URL of the constituent’s Facebook page/profile. | String/URL | No | |
| TwitterID | The constituent’s Twitter handle. | String | No | |
| LinkedInID | The URL for the constituent’s LinkedIn profile. | String/URL | No | |
| Gender | The gender of the constituent | String | No | Male, Female, Other |
| Birthdate | The constituent’s birthdate. | Date | No | mm/dd/yyyy |
| Address | The address marked as Primary on a constituent’s record. | No | See API – Address | |
| PrimaryPhone | The phone number marked as Primary on a constituent’s record. | No | See API – Phone | |
| PrimaryEmail | The email address marked as Primary on a constituent’s record. | No | See API – Email | |
| Addresses | All of the constituent’s address records. | Array[Address] | No | |
| Phones | All of the constituent’s phone records. | Array[Phone] | No | |
| Emails | All of the constituent’s email addresses. | Array[Email] | No | |
| EmailInterestType | Set which type of emails a constituent is interested in receiving. | String | No | All, OptedOut. Defaults to All. Custom is used in the response only. See the EmailInterestType Merging table for merge logic. |
| AuditTrail | Information about who created or modified a constituent and when. | String | No | Response only. |
| CustomFields | An associative array that maps names of custom fields to an array of applied values. | CustomFields | No | |
| OptedInEmail | The constituent’s opt in preference for contact by email. | Boolean | No | If this field is set to false, it overrides the EmailInterestType setting. This field is only used if the request contains an address from a European country. |
| OptedInMail | The constituent’s opt in preference for contact by mail. | Boolean | No | This field is only used if the request contains an address from a European country. |
| OptedInPhone | The constituent’s opt in preference for contact by phone. | Boolean | No | This field is only used if the request contains an address from a European country. |
EmailInterestType Merging
This table illustrates how email interest types are merged using the Merge endpoint. Note: This merge logic is different from the merge logic used in the application.
| Existing Constituent Email Interests | |||
|---|---|---|---|
| Submitted Values | All | Custom | OptedOut |
| All | All | Custom | All |
| OptedOut | OptedOut | OptedOut | OptedOut |
While you can access address records from the Constituents that they belong to, it’s more efficient to access them directly when all you want to do is work with the contact info.
Retrieve an Address
GET https://api.bloomerang.co/v1/Address/{address-id}
GET https://api.bloomerang.co/v1/Address/92345
{
AccountId: 92344
TypeName: "Home"
Street: "98123 Main St."
City: "Indianapolis"
State: "Indiana"
County: ""
PostalCode: "46250"
Country: "United States"
IsPrimary: true
IsBad: false
Id: 92345
}
Update an Address
POST https://api.bloomerang.co/v1/Address/{address-id}
POST https://api.bloomerang.co/v1/Address/92345
{
City: "Columbus",
State: "Ohio"
}
{
AccountId: 92344
TypeName: "Home"
Street: "98123 Main St."
City: "Columbus"
State: "Ohio"
County: ""
PostalCode: "46250"
Country: "United States"
IsPrimary: true
IsBad: false
Id: 92345
}
Create a New Address
POST https://api.bloomerang.co/v1/Address/
POST https://api.bloomerang.co/v1/Address/
{
AccountId: 92344,
IsPrimary: true,
TypeName: "Work",
Street: "5625 N Post Rd",
City: "Indianapolis",
State: "Indiana",
PostalCode: "46216"
}
{
AccountId: 92344
TypeName: "Work"
Street: "5626 N Post Road"
City: "Indianpolis"
State: "Indiana"
County: ""
PostalCode: "12345"
Country: "United States"
IsPrimary: true
IsBad: false
Id: 92348
}
Add an International Address
POST https://api.bloomerang.co/v1/Address/
POST https://api.bloomerang.co/v1/Address/
{
AccountId: 92344,
TypeName: "Work",
Street: "221B Baker St",
City: "London",
PostalCode: "NW1 6XE",
Country: "GB"
}
{
AccountId: 92344
TypeName: "Work"
Street: "221B Baker St\rNW1 6XE London"
City: ""
State: ""
County: ""
PostalCode: ""
Country: "United Kingdom"
Id: 92348
}
Attribute Reference
| Name | Description | Format | Required | Valid Values |
|---|---|---|---|---|
| Id | The automatically assigned unique identifier for this record | Long | No | |
| AccountId | The unique id of the Constituent that the address belongs to | String | Required | |
| TypeName | The type of address | String | Required | Home, Work, Vacation |
| IsPrimary | Is this the primary address for the constituent? Automatically true for the first address added. | Boolean | No | true, false |
| IsBad | Is this address flagged as bad/invalid? | Boolean | No | true, false |
| Street | The street portion of the address. {NewLine} is acceptable for multiline addresses. If the country is not United States, Canada, or Bermuda, use the Street attribute to store the entire address. See http://www.upu.int/en/activities/addressing/postal-addressing-systems-in-member-countries.html for correct address formatting for various countries. | String | No | |
| City | The city portion of the address. For addresses other than United States, Canada, or Bermuda, this value will be added to the Street attribute. | String | No | |
| State | The state or province of the address. For addresses other than United States, Canada, or Bermuda, this value will be added to the Street attribute. | String | No | |
| PostalCode | The ZIP code portion of the address. For addresses other than United States, Canada, or Bermuda, this value will be added to the Street attribute. | String | No | |
| Country | The country portion of the address. | String | No | Default is United States. We recommend using the 2- or 3-digit country code. See https://www.iso.org/obp/ui/#search. The API also accepts country name, but verify the result in the response. |
While you can access email records from the accounts themselves, its more efficient to access the email record directly when all you want to work with is the contact info.
Retrieve an Email
GET https://api.bloomerang.co/v1/Email/{email-id}
GET https://api.bloomerang.co/v1/Email/7845
{
AccountId: 138240,
TypeName: "Work",
Value: "[email protected]",
IsPrimary: true,
IsBad: false,
Id: 177155Id: 7845,
}
Update an Email
POST https://api.bloomerang.co/v1/Email/{email-id}
POST https://api.bloomerang.co/v1/Email/7845
{
Value: "[email protected]"
}
{
Id: 7845,
AccounId: 92344,
IsPrimary: true,
TypeName: "Home",
Value: "[email protected]"
}
Create a New Email
POST https://api.bloomerang.co/v1/Email
POST https://api.bloomerang.co/v1/Email
{
AccountId: 92344,
TypeName: "Work",
Value: "[email protected]"
}
{
Id: 7849,
AccounId: 92344,
IsPrimary: false, // already had another email that is primary
TypeName: "Home",
Value: "[email protected]"
}
Attribute Reference
** Denotes a required field
- Id (long)
The automtaically assigned unique identifier for the record. - AccountId** (long)
The unique identifier of the Constituent record this email belongs to. - TypeName** (string)
“Home” or “Work” - IsPrimary (boolean)
If the constituent has more than one email, is this the primary? This is automatically true for the first email added to a constituent. - Value** (string)
The actual email address (e.g. “[email protected]”)
Although you can access phone number records from the accounts themselves, it’s more efficient to access the phone record directly when all you want to work with is the contact info.
Retrieve a Phone
GET https://api.bloomerang.co/v1/Phone/{phone-id}
GET https://api.bloomerang.co/v1/Phone/5555
{
Id: 5555,
AccounId: 92344,
IsPrimary: true,
TypeName: "Mobile",
Number: "(555) 888-9999",
Extension: ""
}
Update a Phone
POST https://api.bloomerang.co/v1/Phone/{phone-id}
POST https://api.bloomerang.co/v1/Phone/5555
{
Number: "(555) 888-9999"
}
{
Id: 5555,
AccounId: 92344,
IsPrimary: true,
TypeName: "Mobile",
Number: "(555) 888-9999",
Extension: ""
}
Create a New Phone
POST https://api.bloomerang.co/v1/Phone
POST https://api.bloomerang.co/v1/Phone
{
AccountId: 92344,
TypeName: "Work",
Number: "(555) 111-2222",
Extension: "123"
}
{
Id: 7849,
AccounId: 92344,
IsPrimary: false, // already had another phone that is primary
Number: "(555) 111-2222",
Extension: "123"
}
Attribute Reference
| Name | Description | Format | Required | Valid Values |
|---|---|---|---|---|
| Id | The automtaically assigned unique identifier for the record | Long | No | |
| AccountId | The unique identifier of the constituent record that this phone number belongs to | Long | Required | |
| TypeName | The type of phone number | String | Required | Home, Work, Mobile, Fax |
| IsPrimary | If the constituent has more than one phone number, is this the primary? This is automatically true for the first phone added to a constituent | Boolean | No | true, false |
| Number | The phone number. Automatically formatted for North American display style. Add “+” in front of a non-United States phone number | String | No | |
| Extension | The extension for the phone number | String | No |
This allows you to pull all timeline entries (transactions, interactions, notes, etc.) for a given constituent account.
Retrieve a Constituent’s Timeline
GET https://api.bloomerang.co/v1/Timeline/{constituent-id}
GET https://api.bloomerang.co/v1/Timeline/1234
{
Id: 1234,
Notes: [
{
Date: "1/3/2012",
Note: "This is some note from 2012"
},
{
Date: "1/9/2012",
Note: "Here's another note for this person",
CustomFields: {}
}
],
Interactions: [
{
Date: "6/3/2013",
Subject: "Major Gift Thank You Letter",
Notes: "It was a hand-written note",
Purpose: "Acknowledgement",
Channel: "Mail",
CustomFields: {}
}
],
Donations: [
{
Date: "6/1/2013",
Amount: 3500.0,
...
CustomFields: {}
},
{
Date: "9/1/2013",
Amount: 1000.0,
...
CustomFields: {
"Number of Tickets": ["4"]
}
}
],
RecurringDonations: []
}
Pledges: [
{
"Frequency": "Monthly",
//The list of all installments, past and future, for the pledge
"Installments": [
{
"Date": "2015-08-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2015-09-15T00:00:00",
"Amount": 50.000000
},
…
],
//The list of the IDs for all payments made to the pledge
"Payments": [
50254,
50255,
…
],
"Balance": 400.000000,
"Status": "InGoodStanding",
},
"FundName": "Pod Racer Fund"
"CampaignName": "2017 Annual Campaign",
"AppealName": "2017 Boonta Eve Classic Appeal",
"TributeName": "Anakin Skywalker",
"TributeTypeName": "In Honor of",
"AcknowledgementStatus": "Do Not Acknowledge",
"Amount": "600.000000",
"NonDeductible": "100.000000",
"Fund": {
"Name": "Pod Racer Fund",
"IsActive": true,
"Id": 102400
},
"Campaign": {
"Goal": "20000000.000000",
"StartDate": "2015-05-01T00:00:00",
"EndDate": "2025-12-31T00:00:00",
"Name": "Pod Racer Campaign",
"IsActive": true,
"SortIndex": 4,
"Id": 56320
},
"Appeal": {
"Goal": "0.000000",
"Name": "2017 Boonta Eve Classic Appeal",
"IsActive": true,
"SortIndex": 8,
"Id": 57344
},
],
"CustomFields": {},
"AccountId": 60416,
"Date": "2015-07-15T00:00:00",
"Note": "Wishing Anakin all the best!",
"Id": 50253
}
]
PledgePayments: [
{
"PledgeId": 50253, //Pledge to which this payment is assigned
"FundName": "Pod Racer Fund",
"CampaignName": "2017 Annual Campaign",
"AppealName": "2017 Boonta Eve Classic Appeal",
"TributeName": "Shmi Skywalker Lars",
"TributeTypeName": "In Memory of",
"AcknowledgementStatus": "No",
"Amount": "50.000000",
"NonDeductible": "0.000000",
"Fund": {
"Name": "Pod Racer Fund",
"IsActive": true,
"Id": 12288
},
"Campaign": {
"Goal": "0.000000",
"Name": "2017 Annual Campaign",
"IsActive": true,
"SortIndex": 3,
"Id": 13315
},
"Appeal": {
"Goal": "0.000000",
"Name": "2017 Boonta Eve Classic Appeal",
"IsActive": true,
"SortIndex": 10,
"Id": 14346
},
"CreditCard": {
"Number": "************4242",
"Expiration": "2020-01-31T12:00:00",
"Id": 51270
},
],
"CustomFields": {},
"AccountId": 60416,
"Date": "2017-07-15T00:00:00",
"Note": "Credit card payment",
"Id": 50260
}
]
Tasks: [
{
AccountId: 29787,
UserId: 50176,
Status: "Active",
DueDate: "2015-07-23T00:00:00",
CompletedDate: "0001-01-01T00:00:00",
Channel: "Email",
Purpose: "Acknowledgement",
Subject: "Send thank-you note for volunteering",
Note: "We were especially grateful that Sam brought 3 dozen donuts!",
Id: 53249,
InteractionId: 12345
}
]
- Id (long)
- Note (array)
- Interaction (array)
- Donations (array)
- RecurringDonation (array)
- RecurringDonationPayment (array)
- Pledge (array)
- PledgePayment (array)
- Task (array)
Standard one-time transactions. You can get a list of them from the Timeline endpoint for a given constituent. Otherwise you can read/create/update individual instances just like any other record
Retrieve a Donation
GET https://api.bloomerang.co/v1/Donation/{donation-id}
GET https://api.bloomerang.co/v1/Donation/7890
{
Id: 7890,
AccounId: 1234,
EntryType: "Donation",
Date: "1/2/2011",
Amount: 50.0,
NonDeductible: 0.0,
Fund: {
Id: 7123,
Name: "Unrestricted",
...
},
FundName : "Unrestricted",
Campaign : {
Id: 8123,
Name: "Capital",
...
},
CampaignName: "Capital",
Appeal: {
Id: 9123,
Name: "Direct Mail",
...
},
AppealName: "Direct Mail",
AcknowledgementStatus: "No",
Check: {
CheckDate: null,
CheckNumber: "123"
},
CreditCard: null,
Eft: null,
InKind: null,
SoftCredits: [{
Id: 9876,
TransactionId: 7890,
AccountId: 17542, // the soft credit account, not the donor
Amount: 25.0
}]
TributeName: "Martin Luther King, Jr.",
TributeType: "In Memory of",
CustomFields: {
"Giving Level": ["Bronze"]
}
}
Update a Donation
POST https://api.bloomerang.co/v1/Donation/{donation-id}
POST https://api.bloomerang.co/v1/Donation/7890
{
Amount: 100.0,
FundName: "Building",
AcknowledgementStatus: "Yes"
}
{
Id: 7890,
AccounId: 1234,
EntryType: "Donation",
Date: "1/2/2011",
Amount: 100.0,
NonDeductible: 0.0,
Fund: {
Id: 7126,
Name: "Building",
...
},
FundName : "Building",
Campaign : {
Id: 8123,
Name: "Capital",
...
},
CampaignName: "Capital",
Appeal: {
Id: 9123,
Name: "Direct Mail",
...
},
AppealName: "Direct Mail",
AcknowledgementStatus: "Yes",
Check: {
CheckDate: null,
CheckNumber: "123"
},
CreditCard: null,
Eft: null,
InKind: null,
SoftCredits: [{
Id: 9876,
TransactionId: 7890,
AccountId: 17542, // the soft credit account, not the donor
Amount: 25.0
}]
TributeName: "Martin Luther King, Jr.",
TributeType: "In Memory of",
CustomFields: {
"Giving Level": ["Bronze"]
}
}
Create a New Donation
POST https://api.bloomerang.co/v1/Donation
POST https://api.bloomerang.co/v1/Donation
{
AccountId: 1234,
Amount: 25.0,
Date: "2/2/2013",
FundName: "Unrestricted",
AppealName: "Direct Mail",
Check: {
Number: "552"
}
}
{
Id: 483445,
AccounId: 1234,
EntryType: "Donation",
Date: "2/2/2013",
Amount: 25.0,
NonDeductible: 0.0,
Fund: {
Id: 7123,
Name: "Unrestricted",
...
},
FundName : "Unrestricted",
Campaign : null,
CampaignName: null,
Appeal: {
Id: 9123,
Name: "Direct Mail",
...
},
AppealName: "Direct Mail",
AcknowledgementStatus: "No",
Check: {
Number: "552",
Date: null
}
CreditCard: null,
Eft: null,
InKind: null,
SoftCredits: [],
TributeName: null,
TributeType: null,
CustomFields: {}
}
Attribute Reference
** Denotes a required field
- Id (long)
The automatically assigned unique id of the record. - AccountId** (long)
The id of the constituent that the donation belongs to. - EntryType (string)
Read only value: “Donation”. - Date (date)
The date that the donation was made in mm/dd/yyyy format (e.g. “12/24/2012”). - Amount (decimal)
The amount of the donation in USD. - NonDeductible (decimal)
Equal to or less than the amount – this portion of the amount is not tax deductible. - AcknowledgementStatus (string)
“Yes”, “No”, or “DoNotAcknowledge” (default is “No”). - FundName (string)
The display name of the currently applied fund. - CampaignName (string)
The display name of the currently applied campaign. - AppealName (string)
The display name of the currently applied appeal. - SoftCredits (Array[SoftCredit]) *Read Only
All of the soft credits attributed to a donation. - TributeName (string)
The display name of the applied tribute. - TributeType (string)
Either “In Memory of” or “In Honor of”. - CustomFields (Custom Values)
An associative array that maps names of custom fields to an array of applied values.
Transaction Method Attribute Reference
The payment type can be modified only if the payment has not been processed (usually through Stripe, Authorize.Net, or BluePay).
| Name | Dependent Values | Description | Format | Required | Valid Values |
| Cash | Payment method is cash | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Check | Payment method is check | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | The check number | String | Yes, if using this method | ||
| Date | The date of the check | Date (mm/dd/yyyy) |
Yes, if using this method |
||
| CreditCard | Payment method is credit card | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | Credit card number. Only submit the last four digits. | Long | Yes, if using this method | ||
| Expiration | Expiration date of card. | Date (mm/dd/yyyy) | Yes, if using this method | ||
| Eft | Payment method is electronic funds transfer | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| AccountType | Type of bank account | String | No | Checking, Savings | |
| AccountNumber | Bank account number. Only submit last four digits. | Long | No | ||
| RoutingNumber | Bank routing number. Submit all digits | Long | No |
You can use this endpoint to inform Bloomerang of a recurring donation schedule that is processed outside of Bloomerang. You can read/create/update individual instances just like any other record.
Retrieve a Recurring Donation
GET https://api.bloomerang.co/v1/RecurringDonation/{donation-id}
GET https://api.bloomerang.co/v1/RecurringDonation/225282
{
"Frequency": "Monthly",
"Payments": [
225283
],
"FundName": "Building",
"CampaignName": "",
"AppealName": "",
"TributeName": "",
"TributeTypeName": "",
"AcknowledgementStatus": "Yes",
"Amount": "15.000000",
"NonDeductible": "0.000000",
"Fund": {
"Name": "Building",
"IsActive": true,
"SortIndex": 0,
"Id": 12288
},
//"None" appears if the schedule is set to not autoprocess.
"None": {
"Id": 0
},
//"CreditCard" only appears if the schedule's autoprocessing payment method is set to Credit Card.
"CreditCard": {
"Number": "1111",
"Expiration": "2034-11-30T12:00:00",
"Id": 237574
},
//"Eft" only appears if the schedule's autoprocessing payment method is set to EFT.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 237575
},
//"SoftCredits" only appears when the recurring donation has soft credits
"SoftCredits": [],
"IsRefunded": false,
"CustomFields": {},
"CustomFreeformFields": {},
"CustomPickFields": {},
"TrueImpactEnabled": false,
"TrueImpactUsed": false,
"AccountId": 29709,
"Date": "2017-06-13T00:00:00",
"Note": "",
"Id": 225282
}
Update a Recurring Donation
Partial updates are supported. You may not update the Amount. If you want to upgrade the donation, set an end date for the current recurring donation schedule and then create a new schedule with the desired amount.
POST https://api.bloomerang.co/v1/RecurringDonation/{donation-id}
POST https://api.bloomerang.co/v1/RecurringDonation/225282
{
FundName: "Program",
AcknowledgementStatus: "No"
}
{
"Frequency": "Monthly",
"Payments": [
225283
],
"FundName": "Program",
"CampaignName": "",
"AppealName": "",
"TributeName": "",
"TributeTypeName": "",
"AcknowledgementStatus": "No",
"Amount": "15.000000",
"NonDeductible": "0.000000",
"Fund": {
"Name": "Building",
"IsActive": true,
"SortIndex": 0,
"Id": 12288
},
//"None" appears if the schedule is set to not autoprocess.
"None": {
"Id": 0
},
//"CreditCard" only appears if the schedule's autoprocessing payment method is set to Credit Card.
"CreditCard": {
"Number": "1111",
"Expiration": "2034-11-30T12:00:00",
"Id": 237574
},
//"Eft" only appears if the schedule's autoprocessing payment method is set to EFT.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 237575
},
//"SoftCredits" only appears when the recurring donation has soft credits
"SoftCredits": [],
"IsRefunded": false,
"CustomFields": {},
"CustomFreeformFields": {},
"CustomPickFields": {},
"TrueImpactEnabled": false,
"TrueImpactUsed": false,
"AccountId": 29709,
"Date": "2017-06-13T00:00:00",
"Note": "",
"Id": 225282
}
Create a New Recurring Donation
You may not currently use this endpoint to create a recurring donation that will be autoprocessed by Bloomerang. You can create the record, but all payments must be handled manually or created through the RecurringDonationPayment endpoint. To have Bloomerang autoprocess a recurring donation, use a Bloomerang form (see API Documentation).
POST https://api.bloomerang.co/v1/RecurringDonation
POST https://api.bloomerang.co/v1/RecurringDonation
{
"AccountId": 29709,
"Amount": 100,
"Date": "8/15/2017",
"FundName": "Building",
"Frequency": "Monthly",
}
}
{
"Frequency": "Monthly",
"Payments": [],
"FundName": "Building",
"CampaignName": "",
"AppealName": "",
"TributeName": "",
"TributeTypeName": "",
"AcknowledgementStatus": "No",
"Amount": "100",
"NonDeductible": "0",
"Fund": {
"Name": "Building",
"IsActive": true,
"SortIndex": 0,
"Id": 12288
},
"None": {
"Id": 0
},
"SoftCredits": [],
"IsRefunded": false,
"CustomFields": {},
"CustomFreeformFields": {},
"CustomPickFields": {},
"TrueImpactEnabled": false,
"TrueImpactUsed": false,
"AccountId": 29709,
"Date": "2017-08-15T12:00:00",
"Note": "",
"Id": 238594
}
Attribute Reference
| Name | Description | Format | Required | Valid Values | Modifiable |
| AccountId | Database ID of constituent | Long | Required, when creating | No | |
| AcknowledgementStatus | If the recurring donation has been acknowledged | String | No | Yes, No, DoNotAcknowledge *Defaults to No | Yes |
| Amount | Dollar amount of recurring donation | Decimal | Required, when creating | No | |
| AppealName | The appeal to which the recurring donation is applied | String | No | Yes | |
| CampaignName | The campaign to which the recurring donation is applied | String | No | Yes | |
| CustomFields | An associative array that maps names of custom fields to an array of applied values | String | No | Yes | |
| Date | Date of recurring donation | Date (mm/dd/yyyy) | Required, when creating | No | |
| StartDate | The date of the first payment for the recurring donation. Defaults to today’s date. | Date (mm/dd/yyyy) | No | No | |
| SoftCredits | All the soft credits attributed to this recurring donation | Array[SoftCredit] | No | Yes | |
| Frequency | Frequency of recurring donation | String | Required, when creating | No | |
| FundName | The fund to which the recurring donation is applied | String | Required, when creating | Yes | |
| Id | Automatically assigned ID of recurring donation | Long | No | No | |
| NonDeductible | Amount of the recurring donation that is not deductible | Decimal | No | Yes | |
| Note | Note about the recurring donation | String | No | Yes | |
| Payments | List of payment IDs | Array[Long] | No | No | |
| TributeName | The recurring donation is made in this person’s name | String | No | Yes | |
| TributeTypeName | The type of tribute | String | No | In Honor of, In Memory of | Yes |
Transaction Method Attribute Reference
| Name | Dependent Values | Description | Format | Required | Valid Values |
| CreditCard | Payment method is credit card | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | Credit card number. Only submit the last four digits. | Long | Yes, if using this method | ||
| Expiration | Expiration date of card. | Date (mm/dd/yyyy) | Yes, if using this method | ||
| Eft | Payment method is electronic funds transfer | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| AccountType | Type of bank account | String | No | Checking, Savings | |
| AccountNumber | Bank account number. Only submit last four digits. | Long | No | ||
| RoutingNumber | Bank routing number. Submit all digits | Long | No |
Recurring donation payments are payments made to a pre-existing schedule. You can get a list of recurring donation schedules from the Timeline endpoint for a given constituent. You can read/create/update individual instances just like any other record.
Retrieve a Recurring Donation Payment
GET https://api.bloomerang.co/v1/RecurringDonationPayment/{donation-id}
GET https://api.bloomerang.co/v1/RecurringDonationPayment/225283
{
"RecurringDonationId": 225282,
"FundName": "Program",
"CampaignName": "",
"AppealName": "",
"TributeName": "",
"TributeTypeName": "",
"AcknowledgementStatus": "No",
"Amount": "15.000000",
"NonDeductible": "0.000000",
"Fund": {
"Name": "Program",
"IsActive": true,
"SortIndex": 5,
"Id": 188417
},
//"Cash" only appears if the schedule's payment method is set to Cash
"Cash": {
"Id": 237573
},
//"Check" only appears if the schedule's payment method is set to Check
"Check": {
"Number": "1478",
"Date": "2017-07-16T00:00:00",
"Id": 51272
},
//"CreditCard" only appears if the schedule's autoprocessing payment method is set to Credit Card.
"CreditCard": {
"Number": "1111",
"Expiration": "2034-11-30T12:00:00",
"Id": 237574
},
//"Eft" only appears if the schedule's autoprocessing payment method is set to EFT.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 237575
},
//"SoftCredits" only appears if the recurring donation has soft credits applied to it
"SoftCredits": [],
"IsRefunded": false,
"CustomFields": {},
"CustomFreeformFields": {},
"CustomPickFields": {},
"TrueImpactEnabled": false,
"TrueImpactUsed": false,
"AccountId": 29709,
"Date": "2017-06-13T00:00:00",
"Note": "",
"Id": 225283
}
Update a Recurring Donation Payment
POST https://api.bloomerang.co/v1/RecurringDonationPayment/{donation-id}
POST https://api.bloomerang.co/v1/RecurringDonationPayment/7890
{
FundName: "General/Operating",
AcknowledgementStatus: "Yes"
}
{
"RecurringDonationId": 225282,
"FundName": "General/Operating",
"CampaignName": "",
"AppealName": "",
"TributeName": "",
"TributeTypeName": "",
"AcknowledgementStatus": "Yes",
"Amount": "15.000000",
"NonDeductible": "0.000000",
"Fund": {
"Name": "General/Operating",
"IsActive": true,
"SortIndex": 5,
"Id": 188417
},
//"Cash" only appears if the schedule's payment method is set to Cash
"Cash": {
"Id": 237573
},
//"Check" only appears if the schedule's payment method is set to Check
"Check": {
"Number": "1478",
"Date": "2017-07-16T00:00:00",
"Id": 51272
},
//"CreditCard" only appears if the schedule's autoprocessing payment method is set to Credit Card.
"CreditCard": {
"Number": "1111",
"Expiration": "2034-11-30T12:00:00",
"Id": 237574
},
//"Eft" only appears if the schedule's autoprocessing payment method is set to EFT.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 237575
},
//"SoftCredits" only appears if the recurring donation has soft credits applied to it
"SoftCredits": [],
"IsRefunded": false,
"CustomFields": {},
"CustomFreeformFields": {},
"CustomPickFields": {},
"TrueImpactEnabled": false,
"TrueImpactUsed": false,
"AccountId": 29709,
"Date": "2017-06-13T00:00:00",
"Note": "",
"Id": 7890
}
Create a New Recurring Donation Payment
If a payment method is not specified, the payment defaults to the payment method on the schedule. If the schedule’s payment method is “None”, the recurring donation payment’s payment method defaults to “Cash”.
POST https://api.bloomerang.co/v1/RecurringDonationPayment
POST https://api.bloomerang.co/v1/RecurringDonationPayment
{
AccountId: 29709,
RecurringDonationId: 238594,
Date: "8/15/2017"
}
{
"RecurringDonationId": 238594,
"FundName": "Building",
"CampaignName": "",
"AppealName": "",
"TributeName": "",
"TributeTypeName": "",
"AcknowledgementStatus": "No",
"Amount": "100.000000",
"NonDeductible": "0",
"Fund": {
"Name": "Building",
"IsActive": true,
"SortIndex": 0,
"Id": 12288
},
//"Cash" only appears if the schedule's payment method is set to Cash
"Cash": {
"Id": 237573
},
//"Check" only appears if the schedule's payment method is set to Check
"Check": {
"Number": "1478",
"Date": "2017-07-16T00:00:00",
"Id": 51272
},
//"CreditCard" only appears if the schedule's autoprocessing payment method is set to Credit Card.
"CreditCard": {
"Number": "1111",
"Expiration": "2034-11-30T12:00:00",
"Id": 237574
},
//"Eft" only appears if the schedule's autoprocessing payment method is set to EFT.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 237575
},
//"SoftCredits" only appears if the recurring donation has soft credits applied to it
"SoftCredits": [],
"IsRefunded": false,
"CustomFields": {},
"CustomFreeformFields": {},
"CustomPickFields": {},
"TrueImpactEnabled": false,
"TrueImpactUsed": false,
"AccountId": 29709,
"Date": "2017-08-15T12:00:00",
"Note": "",
"Id": 238595
}
Attribute Reference
| Name | Description | Format | Required | Valid Values | Modifiable |
| AccountId | Database ID of constituent | Long | Required | No | |
| AcknowledgementStatus | If the recurring donation has been acknowledged | String | No | Yes, No, DoNotAcknowledge *Defaults to No | Yes |
| Amount | Dollar amount of recurring donation payment | Decimal | No | No | |
| AppealName | The appeal to which the recurring donation is applied | String | No | No | |
| CampaignName | The campaign to which the recurring donation is applied | String | No | No | |
| CustomFields | An associative array that maps names of custom fields to an array of applied values | String | No | Yes | |
| Date | Date of recurring donation payment | Date (mm/dd/yyyy) | Required | No | |
| FundName | The fund to which the recurring donation is applied | String | No | No | |
| Id | Automatically assigned ID of recurring donation payment | Long | No | No | |
| NonDeductible | Amount of the recurring donation payment that is not deductible | Decimal | No | No | |
| Note | Note about the recurring donation | String | No | Yes | |
| RecurringDonationID | Automatically assigned ID of the recurring donation that this payment is associated with | Long | Required, when using POST | No | |
| SoftCredits | All the soft credits attributed to this recurring donation | Array[SoftCredit] | No | No | |
| TributeName | The recurring donation is made in this person’s name | String | No | No | |
| TributeTypeName | The type of tribute | String | No | In Honor of, In Memory of | No |
Transaction Method Attribute Reference
The payment type can be modified only if the payment has not been processed (usually through Stripe, Authorize.Net, or BluePay).
| Name | Dependent Values | Description | Format | Required | Valid Values |
| Cash | Payment method is cash | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Check | Payment method is check | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | The check number | String | Yes, if using this method | ||
| Date | The date of the check | Date (mm/dd/yyyy) |
Yes, if using this method |
||
| CreditCard | Payment method is credit card | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | Credit card number. Only submit the last four digits. | Long | Yes, if using this method | ||
| Expiration | Expiration date of card. | Date (mm/dd/yyyy) | Yes, if using this method | ||
| Eft | Payment method is electronic funds transfer | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| AccountType | Type of bank account | String | No | Checking, Savings | |
| AccountNumber | Bank account number. Only submit last four digits. | Long | Yes, if using this method | ||
| RoutingNumber | Bank routing number. Submit all digits | Long | Yes, if using this method |
Retrieve a Pledge
GET /v1/Pledge/{pledge-id}
GET /v1/Pledge/50253
{
"Frequency": "Monthly",
//The list of all installments, past and future, for the pledge
"Installments": [
{
"Date": "2017-08-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-09-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-10-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-11-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-12-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-01-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-02-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-03-15T00:00:00",
"Amount": 50.000000
}
],
//The list of the IDs for all payments made to the pledge
"Payments": [
50254,
50255,
50256,
50257
],
"Balance": 400.000000,
"Status": "InGoodStanding",
//"Arrears" only appears when the pledge is in arrears
"Arrears": 175.000000,
//"WriteOff" only appears when the pledge is written off
"WriteOff": {
"Date": "2017-07-15T00:00:00",
"Amount": 85.000000,
"Id": 57346
},
"FundName": "Pod Racer Fund"
"CampaignName": "2017 Annual Campaign",
"AppealName": "2017 Boonta Eve Classic Appeal",
"TributeName": "Anakin Skywalker",
"TributeTypeName": "In Honor of",
"AcknowledgementStatus": "Do Not Acknowledge",
"Amount": "600.000000",
"NonDeductible": "100.000000",
"Fund": {
"Name": "Pod Racer Fund",
"IsActive": true,
"Id": 102400
},
"Campaign": {
"Goal": "20000000.000000",
"StartDate": "2017-05-01T00:00:00",
"EndDate": "2025-12-31T00:00:00",
"Name": "Pod Racer Campaign",
"IsActive": true,
"SortIndex": 4,
"Id": 56320
},
"Appeal": {
"Goal": "0.000000",
"Name": "2017 Boonta Eve Classic Appeal",
"IsActive": true,
"SortIndex": 8,
"Id": 57344
},
//"None" appears if the schedule is set to not autoprocess.
"None": {
"Id": 0
},
//"CreditCard" only appears if the schedule's autoprocessing payment method is set to Credit Card.
"CreditCard": {
"Number": "1111",
"Expiration": "2034-11-30T12:00:00",
"Id": 237574
},
//"Eft" only appears if the schedule's autoprocessing payment method is set to EFT.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 237575
},
//"SoftCredits" only appears when the pledge has soft credits
"SoftCredits": [
{
"TransactionId": 50253,
"EntryType": "Soft Credit",
"AccountId": 29781,
"Amount": "300.000000",
"Id": 53253
},
],
"IsRefunded": false,
"CustomFields": {},
"TrueImpactEnabled": false,
"TrueImpactUsed": false,
"AccountId": 60416,
"Date": "2017-07-15T00:00:00",
"Note": "Wishing Anakin all the best!",
"Id": 50253
}
Create a New Pledge
POST /v1/Pledge
You may not currently use this endpoint to create a pledge that will be autoprocessed by Bloomerang. You can create the record, but all payments must be handled manually or created through the PledgePayment endpoint. To have Bloomerang autoprocess a pledge, use a Bloomerang form (see API Documentation).
POST /v1/Pledge
{
"AccountId": 60416,
"Date": "7/16/2017",
"Amount": 500.00,
"Note": "For improvements to Skywalker’s pod racer."
"Frequency": "Monthly",
"InstallmentAmount": 25.00,
"FirstInstallmentDate": "7/15/2017",
"FundName": "Pod Racer Fund",
"AppealName": "2017 Boonta Eve Classic Appeal",
"CampaignName": "2017 Annual Campaign",
"TributeName": "Shmi Skywalker Lars",
"TributeTypeName": "In Memory of",
"AcknowledgementStatus": "Yes",
"NonDeductible": 100.00,
"CustomFields": {}
}
{
"AccountId": 60416,
"Date": "7/16/2017",
"Amount": 500.00,
"Note": "For improvements to Skywalker’s pod racer."
"Frequency": "Monthly",
//The list of all installments, past and future, for the pledge
"Installments": [
{
"Date": "2017-07-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-08-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-09-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-10-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-11-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-12-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-01-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-02-15T00:00:00",
"Amount": 50.000000
}
],
"FundName": "Pod Racer Fund",
"AppealName": "2017 Boonta Eve Classic Appeal",
"CampaignName": "2017 Annual Campaign",
"TributeName": "Shmi Skywalker Lars",
"TributeTypeName": "In Memory of",
"AcknowledgementStatus": "Yes",
"NonDeductible": 100.00,
"None": {
"Id": 0
},
"CustomFields": {},
"Id": 50254
}
Update a Pledge
POST /v1/Pledge/{pledge-id}
After a pledge has been made, you cannot make changes to the schedule, dates, amounts, or assigned pledge ID through the API.
The following attributes can be updated, and none are required.
POST /v1/Pledge/50253
{
"Note": "We hope to see a great race this year!",
"FundName": "Pod Racer Fund",
"AppealName": "2017 Boonta Eve Classic Appeal",
"CampaignName": "2017 Annual Campaign",
"TributeName": "Shmi Skywalker Lars",
"TributeTypeName": "In Memory of",
"AcknowledgementStatus": "No",
"NonDeductible": 150.00,
"CustomFields": {}
}
{
"Frequency": "Monthly",
//The list of all installments, past and future, for the pledge
"Installments": [
{
"Date": "2017-08-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-09-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-10-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-11-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2017-12-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-01-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-02-15T00:00:00",
"Amount": 50.000000
},
{
"Date": "2018-03-15T00:00:00",
"Amount": 50.000000
}
],
//The list of the IDs for all payments made to the pledge
"Payments": [
50254,
50255,
50256,
50257
],
"Balance": 400.000000,
"Status": "InGoodStanding",
//"Arrears" only appears when the pledge is in arrears
"Arrears": 175.000000,
//"WriteOff" only appears when the pledge is written off
"WriteOff": {
"Date": "2017-07-15T00:00:00",
"Amount": 85.000000,
"Id": 57346
},
"FundName": "Pod Racer Fund"
"CampaignName": "2017 Annual Campaign",
"AppealName": "2017 Boonta Eve Classic Appeal",
"TributeName": "Shmi Skywalker Lars",
"TributeTypeName": "In Memory of",
"AcknowledgementStatus": "No",
"Amount": "600.000000",
"NonDeductible": "150.000000",
"Fund": {
"Name": "Pod Racer Fund",
"IsActive": true,
"Id": 102400
},
"Campaign": {
"Goal": "20000000.000000",
"StartDate": "2017-05-01T00:00:00",
"EndDate": "2025-12-31T00:00:00",
"Name": "Pod Racer Campaign",
"IsActive": true,
"SortIndex": 4,
"Id": 56320
},
"Appeal": {
"Goal": "0.000000",
"Name": "2017 Boonta Eve Classic Appeal",
"IsActive": true,
"SortIndex": 8,
"Id": 57344
},
//"None" appears if the schedule is set to not autoprocess.
"None": {
"Id": 0
},
//"CreditCard" only appears if the schedule's autoprocessing payment method is set to Credit Card.
"CreditCard": {
"Number": "1111",
"Expiration": "2034-11-30T12:00:00",
"Id": 237574
},
//"Eft" only appears if the schedule's autoprocessing payment method is set to EFT.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 237575
},
//"SoftCredits" only appears when the pledge has soft credits
"SoftCredits": [
{
"TransactionId": 50253,
"EntryType": "Soft Credit",
"AccountId": 29781,
"Amount": "300.000000",
"Id": 53253
},
],
"CustomFields": {},
"AccountId": 60416,
"Date": "2017-07-15T00:00:00",
"Note": "We hope to see a great race this year!",
"Id": 50253
}
Attribute Reference
| Name | Description | Format | Required | Valid Values | Modifiable |
| AccountId | Database ID of constituent | Long | Yes | No | |
| AcknowledgementStatus | If the pledge has been acknowledged | String | No | Yes, No, DoNotAcknowledge *Defaults to No | Yes |
| Amount | Dollar amount of pledge | Decimal | Yes | No | |
| AppealName | The appeal to which the pledge is applied | String | No | Yes | |
| Balance | Amount remaining to be paid for pledge | Decimal | No | No | |
| CampaignName | The campaign to which the pledge is applied | String | No | Yes | |
| CustomFields | An associative array that maps names of custom fields to an array of applied values | String | No | Yes | |
| Date | Date of pledge | Date (mm/dd/yyyy) | Yes | No | |
| FirstInstallmentDate | The date of the first payment for the pledge | Date (mm/dd/yyyy) | Yes | No | |
| Frequency | Frequency of pledge | String | Yes | No | |
| FundName | The fund to which the pledge is applied | String | Yes | Yes | |
| Id | Automatically assigned ID of pledge | Long | No | No | |
| InstallmentAmount | Amount to be paid for each installment | Decimal | Yes | No | |
| NonDeductible | Amount of the pledge that is not deductible | Decimal | No | Yes | |
| Note | Note about the pledge | String | No | Yes | |
| Payments | List of payment IDs | Array[Long] | No | No | |
| SoftCredits | All the soft credits attributed to this pledge | Array[SoftCredit] | No | Yes | |
| Status | The status of the pledge | String | No | InArrears, InGoodStanding, WrittenOff, Fulfilled | Yes |
| TributeName | The pledge is made in this person’s name | String | No | Yes | |
| TributeTypeName | The type of tribute | String | No | In Honor of, In Memory of | Yes |
Transaction Method Attribute Reference
| Name | Dependent Values | Description | Format | Required | Valid Values |
| CreditCard | Payment method is credit card | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | Credit card number. Only submit the last four digits. | Long | Yes, if using this method | ||
| Expiration | Expiration date of card. | Date (mm/dd/yyyy) | Yes, if using this method | ||
| Eft | Payment method is electronic funds transfer | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| AccountType | Type of bank account | String | No | Checking, Savings | |
| AccountNumber | Bank account number. Only submit last four digits. | Long | Yes, if using this method | ||
| RoutingNumber | Bank routing number. Submit all digits | Long | Yes, if using this method |
Retrieve a Pledge Payment
GET /v1/PledgePayment/{pledge-payment-id}
GET /v1/PledgePayment/50260
{
"PledgeId": 50253, //Pledge to which this payment is assigned
"FundName": "Pod Racer Fund",
"CampaignName": "2017 Annual Campaign",
"AppealName": "2017 Boonta Eve Classic Appeal",
"TributeName": "Shmi Skywalker Lars",
"TributeTypeName": "In Memory of",
"AcknowledgementStatus": "No",
"Amount": "50.000000",
"NonDeductible": "0.000000",
"Fund": {
"Name": "Pod Racer Fund",
"IsActive": true,
"Id": 12288
},
"Campaign": {
"Goal": "0.000000",
"Name": "2017 Annual Campaign",
"IsActive": true,
"SortIndex": 3,
"Id": 13315
},
"Appeal": {
"Goal": "0.000000",
"Name": "2017 Boonta Eve Classic Appeal",
"IsActive": true,
"SortIndex": 10,
"Id": 14346
},
//"Cash" only appears if the pledge payment was made with cash
"Cash": {
"Id": 50000
},
//"CreditCard" only appears if the pledge payment was made by credit card
"CreditCard": {
"Number": "************4242",
"Expiration": "2020-01-31T12:00:00",
"Id": 51270
},
//"Check" only appears if the pledge payment was made by check
"Check": {
"Number": "1478",
"Date": "2017-07-16T00:00:00",
"Id": 51272
},
//"Eft" only appears if the pledge payment was made by electronic funds transfer
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 64512
},
//"InKind" only appears if the pledge payment was made with an in-kind donation
"InKind": {
"Description": "Building Materials",
"InKindType": "Goods",
"MarketValue": "200.000000",
"Id": 40224
},
//"SoftCredits" only appears if the pledge has soft credits applied to it
"SoftCredits": [
{
"TransactionId": 50253,
"EntryType": "Soft Credit",
"AccountId": 29781,
"Amount": "300.000000",
"Id": 53253
}
],
"CustomFields": {},
"AccountId": 60416,
"Date": "2017-07-15T00:00:00",
"Note": "Credit card payment",
"Id": 50260
}
Add a Pledge Payment
POST /v1/PledgePayment
If a payment method is not specified, the payment defaults to the payment method on the schedule. If the schedule’s payment method is “None”, the pledge payment’s payment method defaults to “Cash”.
The first four attributes are required to make a pledge payment. This call does not process the transaction in Bloomerang.
POST /v1/PledgePayment
{
"AccountId": 29791,
"PledgeId": 50236,
"Amount": 100.00,
"Date": "5/1/2017",
"Note": "Thanks for putting on a great race every year!",
"AcknowledgementStatus": "No",
//If no payment type is specified, the default is "Cash".
//Add "Check" only if the pledge payment was made by check
"Check": {
"Number": "1479",
"Date": "2017-07-16T00:00:00",
},
//Add "CreditCard" only if the pledge payment was made by credit card.
"CreditCard": {
"Number": "1234", //We recommend sending only the last four digits of the credit card number
"Expiration": "2020-01-31T00:00:00",
},
//Add "Eft" only if the pledge payment was made by electronic funds transfer.
"Eft": {
"AccountType": "Checking",
"AccountNumber": "6789", //We recommend sending only the last four digits
"RoutingNumber": "123123123",
},
//Add "InKind" to change the pledge payment type to an in-kind donation
"InKind": {
"Description": "Building Materials",
"InKindType": "Goods",
"MarketValue": "200.000000"
},
"CustomFields": {}
}
{
"AccountId": 29791,
"PledgeId": 50236,
"Amount": 100.00,
"Date": "5/1/2017",
"Note": "Thanks for putting on a great race every year!",
"AcknowledgementStatus": "No",
//"Cash" only appears if the pledge payment was made with cash
"Cash": {
"Id": 50001
},
//"CreditCard" only appears if the pledge payment was made by credit card
"CreditCard": {
"Number": "************1234",
"Expiration": "2020-01-31T12:00:00",
"Id": 51271
},
//"Check" only appears if the pledge payment was made by check
"Check": {
"Number": "1479",
"Date": "2017-07-16T00:00:00",
"Id": 51272
},
//"Eft" only appears if the pledge payment was made by electronic funds transfer
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 64513
},
//"InKind" only appears if the pledge payment was made with an in-kind donation
"InKind": {
"Description": "Building Materials",
"InKindType": "Goods",
"MarketValue": "200.000000",
"Id": 40224
},
"CustomFields": {},
"Id": 50261
}
Update a Pledge Payment
POST /v1/PledgePayment/{pledge-payment-id}
After a pledge payment has been made, you cannot make changes to the dates, amounts, associated constituent, or assigned pledge through the API.
The following attributes can be updated, and none are required.
POST /v1/PledgePayment/50261
{
"Note": "We hope to see a great race this year!",
"AcknowledgementStatus": "Yes",
//Add "Cash" to change the pledge payment type to cash
"Cash": {
},
//Add "CreditCard" to change the pledge payment type to credit card
"CreditCard": {
"Number": "************1234",
"Expiration": "2020-01-31T12:00:00",
},
//Add "Check" to change the pledge payment type to check
"Check": {
"Number": "1479",
"Date": "2017-07-16T00:00:00",
},
//Add "Eft" to change the pledge payment type to electronic funds transfer
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
},
//Add "InKind" to change the pledge payment type to an in-kind donation
"InKind": {
"Description": "Building Materials",
"InKindType": "Goods",
"MarketValue": "200.000000"
},
"CustomFields": {}
}
{
"AccountId": 29791,
"PledgeId": 50236,
"Amount": 100.00,
"Date": "5/1/2017",
"Note": "We hope to see a great race this year!",
"AcknowledgementStatus": "Yes",
//"Cash" only appears if the pledge payment was made with cash
"Cash": {
"Id": 50001
},
//"CreditCard" only appears if the pledge payment was made by credit card
"CreditCard": {
"Number": "************1234",
"Expiration": "2020-01-31T12:00:00",
"Id": 51271
},
//"Check" only appears if the pledge payment was made by check
"Check": {
"Number": "1479",
"Date": "2017-07-16T00:00:00",
"Id": 51272
},
//"Eft" only appears if the pledge payment was made by electronic funds transfer
"Eft": {
"AccountType": "Checking",
"AccountNumber": "*****6789",
"RoutingNumber": "123123123",
"Id": 64513
},
//"InKind" only appears if the pledge payment was made with an in-kind donation
"InKind": {
"Description": "Building Materials",
"InKindType": "Goods",
"MarketValue": "200.000000",
"Id": 40224
},
"CustomFields": {},
"Id": 50261
}
Attribute Reference
| Name | Description | Format | Required | Valid Values | Modifiable |
| AccountId | Database ID of constituent | Long | Yes | No | |
| AcknowledgementStatus | If the associated pledge has been acknowledged | String | No | Yes, No, DoNotAcknowledge *Defaults to No | Yes |
| Amount | Dollar amount of pledge payment | Decimal | Yes | No | |
| AppealName | The appeal to which the associated pledge is applied | String | No | Yes | |
| CampaignName | The campaign to which the associated pledge is applied | String | No | Yes | |
| CustomFields | An associative array that maps names of custom fields to an array of applied values | String | No | Values that already exist in the database | Yes |
| Date | Date of pledge payment | Date (mm/dd/yyyy) | Yes | On or after the pledge date. | No |
| FundName | The fund to which the associated pledge is applied | String | Yes | Yes | |
| Id | Automatically assigned ID of pledge payment |
Long |
Yes | No | |
| NonDeductible | Amount of the pledge that is not deductible | Decimal | No | Yes | |
| Note | Note about the pledge payment | String | No | Yes | |
| PledgeId | Automatically assigned ID of the pledge that this payment is associated with | Long | Yes | Must be a pledge ID that already exists. | No |
| SoftCredits | All the soft credits attributed to this pledge | Array[SoftCredit] | No | No | |
| TributeName | The associated pledge is made in this person’s name | String | No | Yes | |
| TributeTypeName | The type of tribute | String | No | In Honor of, In Memory of | Yes |
Transaction Method Attribute Reference
The payment type can be modified only if the payment has not been processed (usually through Stripe , Authorize.Net, or BluePay).
| Name | Dependent Values | Description | Format | Required | Valid Values |
| Cash | Payment method is cash | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Check | Payment method is check | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | The check number | String | Yes, if using this method | ||
| Date | The date of the check | Date (mm/dd/yyyy) | Yes, if using this method | ||
| CreditCard | Payment method is credit card | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Number | Credit card number. Only submit the last four digits. | Long | Yes, if using this method | ||
| Expiration | Expiration date on credit card | Date (mm/dd/yyyy) | Yes, if using this method | ||
| Eft | Payment method is electronic funds transfer | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| AccountType | Type of bank account | String | No | Checking, Savings | |
| AccountNumber | Bank account number. Only submit last four digits. | Long | Yes, if using this method | ||
| RoutingNumber | Bank routing number. Submit all digits. | Long | Yes, if using this method | ||
| InKind | Payment method is in kind | ||||
| Id | Automatically assigned ID for this record | Long | No | ||
| Description | User-entered description of in-kind donation | String | No | ||
| InKindType | Type of in-kind donation | String | No | Goods, Services | |
| MarketValue | Dollar amount for the market value of the in-kind donation | Decimal | No |
This call refunds the full amount of a donation, recurring donation payment, or pledge payment. If the transaction was processed in Bloomerang, the refund endpoint triggers a refund in the payment processor.
Make a Refund
POST https://api.bloomerang.co/v1/Refund
POST https://api.bloomerang.co/v1/Refund
{
TransactionId: 1234,
Reason: "API refund"
}
{
Id: 1234,
AccountId: 4321,
EntryType: "Donation",
Date: "6/16/2016",
Amount: 25.0,
NonDeductible: 0.0,
Fund {
Id: 7123,
Name: "Unrestricted",
...
},
FundName: "Unrestricted",
Campaign: null,
CampaignName: null,
Appeal: {
Id: 9123,
Name: "Direct Mail",
...
},
AppealName: "Direct Mail",
AcknowledgementStatus: "No",
Check: {
Number: "553",
Date: null
}
CreditCard: null,
Eft: null,
InKind: null,
SoftCredits: [],
IsRefunded: true,
TributeName: null,
TributeType: null,
CustomFields: {}
}
Attribute Reference
| Name | Description | Format | Required |
| TransactionId | Unique ID of the transaction being refunded | Long | Required |
| Reason | The reason for refunding the transaction | String | No |
This is our representation of a dated, freeform note about a constituent.
Retrieve a Note
GET https://api.bloomerang.co/v1/Note/{note-id}
GET https://api.bloomerang.co/v1/Note/10245
{
Id: 10245,
AccountId: 92344,
Date: "1/2/2011",
Note: "The day she won the lottery.",
CustomFields: {}
}
Update a Note
POST https://api.bloomerang.co/v1/Note/{note-id}
POST https://api.bloomerang.co/v1/Note/10245
{
Date: "1/2/2013"
}
{
Id: 10245,
AccountId: 92344,
Date: "1/2/2013",
Note: "The day she won the lottery.",
CustomFields: {}
}
Create a New Note
POST https://api.bloomerang.co/v1/Note
{
AccountId: 34948,
Date: "5/5/2013",
Note: "Was in the newspaper for saving kittens from a well."
}
{
Id: 932923,
AccountId: 34948,
Date: "5/5/2013",
Note: "Was in the newspaper for saving kittens from a well.",
CustomFields: {}
}
Attribute Reference
** Denotes a required field
- Id (long)
The automatically assigned unique identifier for the record. - AccountId** (long)
The id of the constituent the interaction belongs to. - Date** (date)
The date of the interaction in mm/dd/yyyy format (e.g. “5/22/2012”) - Note** (string)
The long description of the interaction.
This is our representation of a “touch” between the organization and the constituent in either direction.
Retrieve an Interaction
GET https://api.bloomerang.co/v1/Interaction/{interaction-id}
GET https://api.bloomerang.co/v1/Interaction/10245
{
Id: 10245,
AccountId: 92344,
Date: "1/2/2011",
Subject: "January Newsletter",
Note: "Sent via MailChimp... why didn't we do this through Bloomerang?",
Channel: "MassEmail",
Purpose: "Newsletter",
IsInbound: false,
CustomFields: {}
}
Update an Interaction
POST https://api.bloomerang.co/v1/Interaction/{interaction-id}
POST https://api.bloomerang.co/v1/Interaction/10245
{
Date: "1/2/2013"
}
{
Id: 10245,
AccountId: 92344,
Date: "1/2/2013",
Subject: "January Newsletter",
Note: "Sent via MailChimp... why didn't we do this through Bloomerang?",
Channel: "MassEmail",
Purpose: "Newsletter",
IsInbound: false,
CustomFields: {}
}
Create a New Interaction
POST https://api.bloomerang.co/v1/Interaction
{
AccountId: 34948,
Date: "5/5/2013",
Subject: "Upgrade solicitation",
Note: "Called him and he agreed to double his previous year's giving!",
Channel: "Phone",
Purpose: "Solicitation"
}
{
Id: 932923,
AccountId: 34948,
Date: "5/5/2013",
Subject: "Upgrade solicitation",
Note: "Called him and he agreed to double his previous year's giving!",
Channel: "Phone",
Purpose: "Solicitation",
IsInbound: false,
CustomFields: {}
}
Attribute Reference
** Denotes a required field
- Id (long)
The automatically assigned unique identifier for the record. - AccountId** (long)
The id of the constituent the interaction belongs to. - Date** (date)
The date of the interaction in mm/dd/yyyy format (e.g. “5/22/2012”) - Subject** (string)
The short, one line summary of the interaction. - Note (string)
The long description of the interaction. - Channel (string)
“Email”, “MassEmail”, “Phone”, “Mail”, “InPerson”, “SocialMedia”, “Website”, or “Other”. - Purpose (string)
“Acknowledgement”, “ImpactCultivation”, “Newsletter”, “Receipt”, “Solicitation”, “SpecialEvent”, “VolunteerActivity”, “Welcome”, or “Other”. - IsInbound (boolean)
Was it the constituent reaching out to the organization (e.g. they emailed someone at the organization)?
Update your organization’s to-do list through the Task API.
Retrieve a Task
GET https://api.bloomerang.co/v1/Task/{task id}
GET https://api.bloomerang.co/v1/Task/11112
{
AccountId: 29787,
UserId: 50176,
Status: "Active",
DueDate: "2015-07-23T00:00:00",
CompletedDate: "0001-01-01T00:00:00",
Channel: "Email",
Purpose: "Acknowledgement",
Subject: "Send thank-you note for volunteering",
Note: "We were especially grateful that Sam brought 3 dozen donuts!",
Id: 53249,
InteractionId: 12345
}
The returned CompletedDate value of “0001-01-01T00:00:00” indicates the task is not completed.
Add a Task
POST https://api.bloomerang.co/v1/Task
{
UserId: 50176,
AccountId: 29784,
DueDate: "9/9/2015",
Channel: "MassEmail",
Purpose: "Solicitation",
Status: "Active",
Subject: "Draft the Adopt a Puppy email",
Note: "This email is to support our feeding program for all our puppies. Emphasize
giving levels: Feed a puppy for a week, month, or 3 months."
}
{
UserId: 50176,
AccountId: 29784,
DueDate: "9/9/2015",
Channel: "MassEmail",
Purpose: "Solicitation",
Status: "Active",
Subject: "Draft the Adopt a Puppy email",
Note: "This email is to support our feeding program for all our puppies. Emphasize
giving levels: Feed a puppy for a week, month, or 3 months."
}
Update a Task
POST https://api.bloomerang.co/v1/Task/{task id}
Only include those values that need to be updated. To make a task as completed or archived, both the Status and CompletedDate fields must be included.
POST https://api.bloomerang.co/v1/Task/11113
{
UserId: 50176,
AccountId: 29787,
Status: "Complete",
DueDate: "8/10/2015",
CompletedDate: "7/24/2015",
Channel: "Website",
Purpose: "ImpactCultivation",
Subject: "Update: Post pics of puppy adoption event",
Note: "Instead of posting just puppy pictures, post all pics with puppies and
new caretakers. Credit the adopters if possible",
InteractionId: 54272
}
{
UserId: 50176,
AccountId: 29787,
Status: "Complete",
DueDate: "8/10/2015",
CompletedDate: "7/24/2015",
Channel: "Website",
Purpose: "ImpactCultivation",
Subject: "Update: Post pics of puppy adoption event",
Note: "Instead of posting just puppy pictures, post all pics with puppies and
new caretakers. Credit the adopters if possible",
InteractionId: 54272
}
Reproduce “Save as Interaction”
You can replicate the “Save as Interaction” functionality through the API, following this procedure:
- Create an interaction using the Interaction API. Note the InteractionId value.
- Using the Task API, send an Update using the InteractionId and set the Status to Complete.
Attribute Reference
| Name | Description | Format | Required | Valid Values |
|---|---|---|---|---|
| AccountId | The ID of the constituent associated with the task | Long | No | |
| UserId | The ID of the user who is assigned the task | Long | Yes | |
| Status | Status of the task | String | No | Active, Complete, Archived |
| DueDate | The date the task is due | Date (mm/dd/yyyy format) | Yes | |
| CompletedDate | The date the task was completed | Date (mm/dd/yyyy format) | No | |
| Channel | How the task is to be carried out | String | Yes | Email, InPerson, Mail, MassEmail, Phone, SocialMedia, Website, Other |
| Purpose | The intent behind the task | String | No | Acknowledgement, ImpactCultivation, Newsletter, PledgeReminder, Receipt, Solicitation, SpecialEvent, VolunteerActivity, Welcome, Other |
| Subject | The short, one-line summary of the task | String | Yes | |
| Note | The long description of the task | String | No | |
| Id | The automatically assigned unique identifier for the record | Long | No | |
| InteractionId | The automatically assigned unique identifier for the interaction record associated with the task | Long | No |
This is an attribute on transactions that let you designate what the money is allowed to be used for. Bloomerang comes stocked with 3 funds: “Unrestricted”, “Endowment”, and “Program”. Typically these should align one-to-one with the programs that your organization uses money for.
List All Funds
GET https://api.bloomerang.co/v1/Fund
{
Total: 3,
Start: 0,
MaxItems: 50,
Results: [{
Id: 6541,
Name: "Unrestricted",
IsActive: true,
SortIndex: 0
},
{
Id: 6542,
Name: "Restricted",
IsActive: true,
SortIndex: 1
},
{
Id: 6543,
Name: "Building",
IsActive: true,
SortIndex: 2
}]
}
Retrieve a Fund
GET https://api.bloomerang.co/v1/Fund/{fund-id}
GET https://api.bloomerang.co/v1/Fund/6543
{
Id: 6543,
Name: "Building",
IsActive: true,
SortIndex: 2
}
Update a Fund
Note: You cannot deactivate a fund through the API.
POST https://api.bloomerang.co/v1/Fund/{fund-id}
POST https://api.bloomerang.co/v1/Fund/6543
{
"Name": "Building Fund"
}
{
"Name": "Building Fund",
"IsActive": true,
"Id": 12288
}
Create a New Fund
POST https://api.bloomerang.co/v1/Fund
POST https://api.bloomerang.co/v1/Fund/
{
Name: "Mission Trips"
}
{
Id: 6544,
Name: "Mission Trips",
IsActive: true,
SortIndex: 99999
}
Attribute Reference
** Denotes a required field
- Id (long)
The automatically assigned unique id of the record. - Name** (string)
The display name of the fund. It must be unique across all funds. - IsActive (boolean)
Is available to apply to new donations in the UI. - SortIndex (int)
What order should this fund appear in the list of all funds?
This is an attribute on transactions that describes the long-term marketing campaign that helped to bring this money into the organization. Bloomerang does not come with any campaigns by default.
List All Campaigns
GET https://api.bloomerang.co/v1/Campaign
{
Total: 1,
Start: 0,
MaxItems: 50,
Results: [{
Id: 6541,
Name: "Building",
IsActive: true,
SortIndex: 0,
Goal: 15000.0,
StartDate: "9/1/2013",
EndDate: null
},
{
Id: 6542,
Name: "2013 Capital Campaign",
IsActive: true,
SortIndex: 1,
Goal: 250000.0,
StartDate: null,
EndDate: null
}]
}
Retrieve a Campaign
GET https://api.bloomerang.co/v1/Campaign/{campaign-id}
GET https://api.bloomerang.co/v1/Campaign/13314
{
"Goal": "150000.000000",
"StartDate": "2017-01-01T00:00:00",
"EndDate": "2017-12-31T00:00:00",
"Name": "Building",
"IsActive": true,
"SortIndex": 3,
"Id": 13314
}
Update a Campaign
Note: You cannot deactivate a campaign through the API.
POST https://api.bloomerang.co/v1/Campaign/{campaign-id}
POST https://api.bloomerang.co/v1/Campaign/13314
{
"Goal": 200000
}
{
"Goal": "200000",
"StartDate": "2017-01-01T00:00:00",
"EndDate": "2017-12-31T00:00:00",
"Name": "Building",
"IsActive": true,
"SortIndex": 3,
"Id": 13314
}
Create a New Campaign
POST https://api.bloomerang.co/v1/Campaign
POST https://api.bloomerang.co/v1/Campaign/
{
"Name": "2013 Upgrades for Major Donors",
"Goal": 500000.0
}
{
"Goal": 500000.0,
"Name": "Upgrades for Major Donors",
"IsActive": true,
"SortIndex": 2,
"Id": 6544
}
Attribute Reference
** Denotes a required field
- Id (long)
The automatically assigned unique id of the record. - Name** (string)
The display name of the campaign. It must be unique across all campaigns. - IsActive (boolean)
Is available to apply to new donations in the UI. - SortIndex (int)
What order should this campaign appear in the list of all campaigns? (default is end of the list) - Goal (decimal)
What is the target dollar amount for this campaign? - StartDate (date)
When did this campaign activity begin? (mm/dd/yyyy format like “5/24/2013”) - EndDate (date)
When is this campaign activity over? (mm/dd/yyyy format like “8/24/3013”)
This is an individual piece of marketing that is part of a larger Campaign. This could be a particular letter or a specific event or even something more general like “Unsolicited”.
List All Appeals
GET https://api.bloomerang.co/v1/Appeal
{
Total: 1,
Start: 0,
MaxItems: 50,
Results: [{
Id: 6541,
Name: "Fall 2013 Solicitation",
IsActive: true,
SortIndex: 0,
Goal: 20000.0,
StartDate: "9/1/2013",
EndDate: null
},
{
Id: 6542,
Name: "Unsolicited",
IsActive: true,
SortIndex: 1,
Goal: 0.0,
StartDate: null,
EndDate: null
}]
}
Retrieve a Appeal
GET https://api.bloomerang.co/v1/Appeal/{appeal-id}
GET https://api.bloomerang.co/v1/Appeal/14336
{
"Goal": "0.000000",
"Name": "2017 Spring Direct Mail",
"IsActive": true,
"SortIndex": 4,
"Id": 14336
}
Update a Appeal
Note: You cannot deactivate an appeal through the API.
POST https://api.bloomerang.co/v1/Appeal/{appeal-id}
POST https://api.bloomerang.co/v1/Appeal/14336
{
"Goal": 20000,
"StartDate": "1/1/2017"
}
{
"Goal": "20000",
"StartDate": "2017-01-01T00:00:00",
"Name": "2017 Spring Direct Mail",
"IsActive": true,
"SortIndex": 4,
"Id": 14336
}
Create a New Appeal
POST https://api.bloomerang.co/v1/Appeal
POST https://api.bloomerang.co/v1/Appeal/
{
"Name": "2017 Summer Picnic"
}
{
"Goal": "0",
"Name": "2017 Summer Picnic",
"IsActive": true,
"SortIndex": 15,
"Id": 118784
}
Attribute Reference
** Denotes a required field
- Id (long)
The automatically assigned unique id of the record. - Name** (string)
The display name of the appeal. It must be unique across all appeals. - IsActive (boolean)
Is available to apply to new donations in the UI. - SortIndex (int)
What order should this appeal appear in the list of all appeals? (default is end of the list) - Goal (decimal)
What is the target dollar amount for this appeal? - StartDate (date)
When did this appeal activity begin? (mm/dd/yyyy format like “5/24/2013”) - EndDate (date)
When is this appeal activity over? (mm/dd/yyyy format like “8/24/3013”)
Custom fields and their values are set up within Bloomerang. The types of custom fields are:
- Benevon (a type of Interaction custom field in Bloomerang)
- Constituent
- Interaction
- Note
- Transaction
Use the CustomField API endpoint to get the IDs for custom fields. The endpoint is read-only.
When building forms, submit the IDs instead of the names whenever possible. This prevents a name change from breaking the form.
List All Custom Fields for a Type
GET https://api.bloomerang.co/v1/CustomField/{area}
Replace {area} with a valid value: Benevon, Constituent, Interaction, Note, Transaction. Benevon is available only in Benevon-enabled databases.
GET https://api.bloomerang.co/v1/CustomField/Constituent?isActive=true
[{
"Category": "Clothing Preferences",
"Name": "Shirt Size",
"IsRequired": false,
"IsActive": true,
"DataType": "Text",
"PickType": "PickOne",
"Id": 850
},
{
"Category": "Volunteer Fields",
"Name": "Volunteer Organizer",
"IsRequired": false,
"IsActive": true,
"DataType": "Text",
"PickType": "Freeform",
"Id": 851
},
{
"Category": "Volunteer Fields",
"Name": "Favorite Location",
"IsRequired": false,
"IsActive": true,
"DataType": "Text",
"PickType": "Freeform",
"Id": 852
}]
Parameter Table
| Parameter | Description | Format | Required | Notes |
|---|---|---|---|---|
| isActive | Filters the list to active or inactive custom fields | Boolean | No | true returns active custom fields; false returns inactive custom fields. Default is to return all custom fields |
Custom Field Table
Values are returned based on the SortIndex in Bloomerang.
| Name | Description | Format | Notes |
|---|---|---|---|
| Id | The automatically assigned unique identifier for this record | Number | |
| Category | The user-defined category that the custom field is assigned to | String | |
| Name | The user-defined name of the custom field | String | |
| IsRequired | Whether the custom field must be completed to submit a data-entry screen or form | Boolean | |
| IsActive | Whether the custom field is active | Boolean | |
| DataType | The data type of the custom field values | String | Valid values: Currency, Date, Decimal, Text, Year |
| PickType | How the user enters data into the custom field | String | Valid values: Freeform, PickMultiple, PickOne. You cannot retrieve custom field values if the PickType is Freeform |
Custom fields and their values are set up within Bloomerang. Custom fields belong to an area in Bloomerang:
- Benevon (a type of Interaction custom field in Bloomerang)
- Constituent
- Interaction
- Note
- Transaction
The custom field’s values belong to that custom field.
Use the CustomValue API endpoint to get the IDs for custom field values. The endpoint is read-only.
When building forms, submit the IDs instead of the names whenever possible. This prevents a name change from breaking the form.
Get Custom Field Values
Get all the custom values for a particular custom field.
GET https://api.bloomerang.co/v1/CustomValue/{area}/{customFieldId}
Replace {area} with a valid value: Benevon, Constituent, Interaction, Note, Transaction. Benevon is available only in Benevon-enabled databases.
{customFieldID} is the Id of the custom field. Get this value using the CustomField endpoint.
GET https://api.bloomerang.co/v1/CustomValue/Constituent/850?skip=0&take=25
{
"Start": 0,
"MaxItems": 25,
"Total": 5,
"Results": [{
"FieldId": 850,
"TextValue": "S",
"IsActive": true,
"Id": 870
},
{
"FieldId": 850,
"TextValue": "M",
"IsActive": true,
"Id": 871
},
{
"FieldId": 850,
"TextValue": "L",
"IsActive": true,
"Id": 872
},
{
"FieldId": 850,
"TextValue": "XL",
"IsActive": true,
"Id": 873
},
{
"FieldId": 850,
"TextValue": "XXL",
"IsActive": true,
"Id": 874
}]
}
Parameter Table
| Parameter | Description | Format | Required | Notes |
|---|---|---|---|---|
| skip | Start showing results at this record number. Defaults to 0. If skip is larger than the number of records, an empty array is returned. | Integer | No | |
| take | How many records to return in one page | Integer | No | Accepts 0-500. Default is 500. |
Custom Field Values Documentation
Values are returned based on the SortIndex in Bloomerang.
| Name | Dependent Values | Description | Format | Notes |
|---|---|---|---|---|
| Start | The index of the first record returned. Set by the skip parameter | Number | ||
| MaxItems | The number of results to return in a page. Set by the take parameter | Number | ||
| Total | The number of results in the system | Number | ||
| Results | Top level | Array of custom field values | ||
| FieldId | The automatically assigned unique identifier for this record | Number | ||
| IsActive | Whether the custom field value is active | Boolean | ||
| TextValue | Populated if the custom field’s DataType is Text | String | ||
| DateValue | Populated if the custom field’s DataType is Date or Year | String | If Year, only the year part of the date is relevant | |
| NumberValue | Populated if the custom field’s DataType is Decimal or Currency | Number | Can be set to null | |
| DataType | The data type of the custom field values | String | Valid values: Currency, Date, Decimal, Text, Year | |
| PickType | How the user enters data into the custom field. Freeform fields return a 400 error: “You cannot request values for a freeform field.” | String | Valid values: Freeform, PickMultiple, PickOne |
Custom Field Value Errors
| Code | Description | Notes |
|---|---|---|
| 400 | You cannot request values for a freeform field | The supported PickTypes are Pick Multiple and Pick One |
| 500 | Error | An error from Bloomerang’s end |
You can search and get users via the API. Each person from an organization who needs to access their Bloomerang database needs a user account.
List All Users
GET https://api.bloomerang.co/v1/User
{
“Start”: 0,
“MaxItems”: 2,
“Total”: 2,
“Results”: [
{
“Id”: 12345,
“UserName”: “[email protected]”,
“Name”: “Frodo Baggins”,
“Email”: “[email protected]”,
“Phone”: “123-456-7890”,
“IsActive”: true,
“UserTimeZone”: {
“Id”: “Central Standard Time”,
“UtcOffset”: “-06:00:00”,
“Name”: “Central Standard Time”
}
},
{
“Id”: 12346,
“UserName”: “[email protected]”,
“Name”: “Samwise Gamgee”,
“Email”: “[email protected]”,
“Phone”: “123-456-7890”,
“IsActive”: true,
“UserTimeZone”: {
“Id”: “Central Standard Time”,
“UtcOffset”: “-06:00:00”,
“Name”: “Central Standard Time”
}
}]
}
“Start”: 0,
“MaxItems”: 2,
“Total”: 2,
“Results”: [
{
“Id”: 12345,
“UserName”: “[email protected]”,
“Name”: “Frodo Baggins”,
“Email”: “[email protected]”,
“Phone”: “123-456-7890”,
“IsActive”: true,
“UserTimeZone”: {
“Id”: “Central Standard Time”,
“UtcOffset”: “-06:00:00”,
“Name”: “Central Standard Time”
}
},
{
“Id”: 12346,
“UserName”: “[email protected]”,
“Name”: “Samwise Gamgee”,
“Email”: “[email protected]”,
“Phone”: “123-456-7890”,
“IsActive”: true,
“UserTimeZone”: {
“Id”: “Central Standard Time”,
“UtcOffset”: “-06:00:00”,
“Name”: “Central Standard Time”
}
}]
}
Retrieve a User
GET https://api.bloomerang.co/v1/User/{User-id}
GET https://api.bloomerang.co/v1/User/12345
{
“Id”: 12345,
“UserName”: “[email protected]”,
“Name”: “Frodo Baggins”,
“Email”: “[email protected]”,
“Phone”: “712-234-2300”,
“IsActive”: true,
“UserTimeZone”: {
“Id”: “Central Standard Time”,
“UtcOffset”: “-06:00:00”,
“Name”: “Central Standard Time”
}
}
“Id”: 12345,
“UserName”: “[email protected]”,
“Name”: “Frodo Baggins”,
“Email”: “[email protected]”,
“Phone”: “712-234-2300”,
“IsActive”: true,
“UserTimeZone”: {
“Id”: “Central Standard Time”,
“UtcOffset”: “-06:00:00”,
“Name”: “Central Standard Time”
}
}
Attribute Reference
-
- Id (long)
The automatically assigned unique id of the record. - UserName (string)
The unique identifier of the user. This is unique across all Bloomerang databases. - Name (string)
The display name of the user. - Email (string)
The email address associated with this user account. - Phone (string)
The phone number associated with this user account. - IsActive (boolean)
Is able to log into the database. - UserTimeZone (object)
The time zone selected for this user. It has the following properties:- Id (string)
- UtcOffset (string)
-
Name (string)
- Id (long)