REST API

REST API 2018-06-22T13:51:30+00:00

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.

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.

POST https://api.bloomerang.co/v1/Keys
{
    Username: "bob.smith@myorganization.org",
    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.

GET https://api.bloomerang.co/v1/Campaign/1234
Content-Type: application/json; charset=utf-8
Authorization: Basic fb2a5d4b-7c2c-11e2-98d3-4ceb426db38d:
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: "frodo@lordoftherings.net"
        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: "frodo@lordoftherings.net",
        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: "bob.smith@example.com"
    },
    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: "bob.smith@example.com",
        IsPrimary: true,
        Id: 601088
    },
    Emails: [
        {
                AccountId: 92344,
                TypeName: "Home",
                Value: "bob.smith@example.com",
                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]"
    },
    CustomValues: {
        "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. String 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. CustomValues 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: "blah@notamatch.com"
}
{
    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]"
	},
        CustomValues: {}
    }
]}

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
Email 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: "bob.smith@example.com"
     },
     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]"
     },
     CustomValues: {
          "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]"
     },
     CustomValues: {
     }
 }

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. CustomValues No

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

NameDescriptionFormatRequiredValid Values
IdThe automatically assigned unique identifier for this recordLongNo
AccountIdThe unique id of the Constituent that the address belongs toStringRequired
TypeNameThe type of addressStringRequiredHome, Work, Vacation
IsPrimaryIs this the primary address for the constituent? Automatically true for the first address added.BooleanNotrue, false
IsBadIs this address flagged as bad/invalid?BooleanNotrue, false
StreetThe 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.StringNo
CityThe city portion of the address. For addresses other than United States, Canada, or Bermuda, this value will be added to the Street attribute.StringNo
StateThe state or province of the address. For addresses other than United States, Canada, or Bermuda, this value will be added to the Street attribute.StringNo
PostalCodeThe ZIP code portion of the address. For addresses other than United States, Canada, or Bermuda, this value will be added to the Street attribute.StringNo
CountryThe country portion of the address.StringNoDefault 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: "joe@notarealdomain.com",
    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: "joe@totallyarealdomain.com"
}
{
    Id: 7845,
    AccounId: 92344,
    IsPrimary: true,
    TypeName: "Home",
    Value: "joe@totallyarealdomain.com"
}

Create a New Email

POST https://api.bloomerang.co/v1/Email

POST https://api.bloomerang.co/v1/Email
{
    AccountId: 92344,
    TypeName: "Work",
    Value: "joe@wherejoeworks.com"
}
{
    Id: 7849,
    AccounId: 92344,
    IsPrimary: false,     // already had another email that is primary
    TypeName: "Home",
    Value: "joe@totallyarealdomain.com"
}

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. “bob@bloomerang.co”)
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",
            CustomValues: {}
        }
    ],
    Interactions: [
        {
            Date: "6/3/2013",
            Subject: "Major Gift Thank You Letter",
            Notes: "It was a hand-written note",
            Purpose: "Acknowledgement",
            Channel: "Mail",
            CustomValues: {}
        }
    ],
    Donations: [
        {
            Date: "6/1/2013",
            Amount: 3500.0,
            ...
            CustomValues: {}
        },
        {
            Date: "9/1/2013",
            Amount: 1000.0,
            ...
            CustomValues: {
                "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",
    CustomValues: {
        "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",
    CustomValues: {
        "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,
    CustomValues: {}
}

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])
    All of the soft credits attributed to this 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 Yes, if using this method
RoutingNumber Bank routing number. Submit all digits Long Yes, if using this method

 

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 or recurring donation payment 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 or recurring donation payment 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
EndDate The date to end processing the recurring donation. Defaults to null, which means process indefinitely. Date (mm/dd/yyyy) 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 or recurring donation payment 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
RecurringDonationID Automatically assigned ID of the recurring donation. Used when working with recurring donation payments Long No No
SoftCredits All the soft credits attributed to this recurring donation Array[SoftCredit] No Yes
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 Yes, if using this method
RoutingNumber Bank routing number. Submit all digits Long Yes, if using this method
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 or 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 or 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 or recurring donation payment Long No No
NonDeductible Amount of the pledge that is not deductible Decimal No No
Note Note about the recurring donation String No Yes
RecurringDonationID Automatically assigned ID of the recurring donation. Used when working with recurring donation payments 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

NameDescriptionFormatRequiredValid ValuesModifiable
AccountIdDatabase ID of constituentLongYesNo
AcknowledgementStatusIf the pledge has been acknowledgedStringNoYes, No, DoNotAcknowledge *Defaults to NoYes
AmountDollar amount of pledge or pledge paymentDecimalYesNo
AppealNameThe appeal to which the pledge is appliedStringNoYes
BalanceAmount remaining to be paid for pledgeDecimalNoNo
CampaignNameThe campaign to which the pledge is appliedStringNoYes
CustomFieldsAn associative array that maps names of custom fields to an array of applied valuesStringNoYes
DateDate of pledge or pledge paymentDate (mm/dd/yyyy)YesNo
FirstInstallmentDateThe date of the first payment for the pledgeDate (mm/dd/yyyy)YesNo
FrequencyFrequency of pledgeStringYesNo
FundNameThe fund to which the pledge is appliedStringYesYes
IdAutomatically assigned ID of pledge or pledge paymentLongNoNo
InstallmentAmountAmount to be paid for each installmentDecimalYesNo
NonDeductibleAmount of the pledge that is not deductibleDecimalNoYes
NoteNote about the pledgeStringNoYes
PaymentsList of payment IDsArray[Long]NoNo
PledgeIDAutomatically assigned ID of the pledge. Used when working with pledge paymentsLongYesNo
SoftCreditsAll the soft credits attributed to this pledgeArray[SoftCredit]NoYes
StatusThe status of the pledgeStringNoInArrears, InGoodStanding, WrittenOff, FulfilledYes
TributeNameThe pledge is made in this person’s nameStringNoYes
TributeTypeNameThe type of tributeStringNoIn Honor of, In Memory ofYes

Transaction Method Attribute Reference

NameDependent ValuesDescriptionFormatRequiredValid Values
CreditCardPayment method is credit card
IdAutomatically assigned ID for this recordLongNo
NumberCredit card number. Only submit the last four digits.LongYes, if using this method
ExpirationExpiration date of card.Date (mm/dd/yyyy)Yes, if using this method
EftPayment method is electronic funds transfer
IdAutomatically assigned ID for this recordLongNo
AccountTypeType of bank accountStringNoChecking, Savings
AccountNumberBank account number. Only submit last four digits.LongYes, if using this method
RoutingNumberBank routing number. Submit all digitsLongYes, 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

NameDescriptionFormatRequiredValid ValuesModifiable
AccountIdDatabase ID of constituentLongYesNo
AcknowledgementStatusIf the associated pledge has been acknowledgedStringNoYes, No, DoNotAcknowledge *Defaults to NoYes
AmountDollar amount of pledge paymentDecimalYesNo
AppealNameThe appeal to which the associated pledge is appliedStringNoYes
CampaignNameThe campaign to which the associated pledge is appliedStringNoYes
CustomFieldsAn associative array that maps names of custom fields to an array of applied valuesStringNoValues that already exist in the databaseYes
DateDate of pledge paymentDate (mm/dd/yyyy)YesOn or after the pledge date.No
FundNameThe fund to which the associated pledge is appliedStringYesYes
IdAutomatically assigned ID of pledge payment

Long

YesNo
NonDeductibleAmount of the pledge that is not deductibleDecimalNoYes
NoteNote about the pledge paymentStringNoYes
PledgeIdAutomatically assigned ID of the pledge that this payment is associated withLongYesMust be a pledge ID that already exists.No
SoftCreditsAll the soft credits attributed to this pledgeArray[SoftCredit]NoNo
TributeNameThe associated pledge is made in this person’s nameStringNoYes
TributeTypeNameThe type of tributeStringNoIn Honor of, In Memory ofYes

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).

NameDependent ValuesDescriptionFormatRequiredValid Values
CashPayment method is cash
IdAutomatically assigned ID for this recordLongNo
CheckPayment method is check
IdAutomatically assigned ID for this recordLongNo
NumberThe check numberStringYes, if using this method
DateThe date of the checkDate (mm/dd/yyyy)Yes, if using this method
CreditCardPayment method is credit card
IdAutomatically assigned ID for this recordLongNo
NumberCredit card number. Only submit the last four digits.LongYes, if using this method
ExpirationExpiration date on credit cardDate (mm/dd/yyyy)Yes, if using this method
EftPayment method is electronic funds transfer
IdAutomatically assigned ID for this recordLongNo
AccountTypeType of bank accountStringNoChecking, Savings
AccountNumberBank account number. Only submit last four digits.LongYes, if using this method
RoutingNumberBank routing number. Submit all digits.LongYes, if using this method
InKindPayment method is in kind
IdAutomatically assigned ID for this recordLongNo
DescriptionUser-entered description of in-kind donationStringNo
InKindTypeType of in-kind donationStringNoGoods, Services
MarketValueDollar amount for the market value of the in-kind donationDecimalNo
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,
     CustomValues: {}
}

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.",
    CustomValues: {}
}

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.",
    CustomValues: {}
}

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.",
    CustomValues: {}
}

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,
    CustomValues: {}
}

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,
    CustomValues: {}
}

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,
    CustomValues: {}
}

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

NameDescriptionFormatRequired Valid Values
AccountIdThe ID of the constituent associated with the taskLongNo
UserIdThe ID of the user who is assigned the taskLongYes
StatusStatus of the taskStringNoActive, Complete, Archived
DueDateThe date the task is dueDate (mm/dd/yyyy format)Yes
CompletedDateThe date the task was completedDate (mm/dd/yyyy format)No
ChannelHow the task is to be carried outStringYesEmail, InPerson, Mail, MassEmail, Phone, SocialMedia, Website, Other
PurposeThe intent behind the taskStringNoAcknowledgement, ImpactCultivation, Newsletter, PledgeReminder, Receipt, Solicitation, SpecialEvent, VolunteerActivity, Welcome, Other
SubjectThe short, one-line summary of the taskStringYes
NoteThe long description of the taskStringNo
IdThe automatically assigned unique identifier for the recordLongNo
InteractionIdThe automatically assigned unique identifier for the interaction record associated with the taskLongNo

 

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

ParameterDescriptionFormatRequiredNotes
skipStart showing results at this record number. Defaults to 0. If skip is larger than the number of records, an empty array is returned.IntegerNo
takeHow many records to return in one pageIntegerNoAccepts 0-500. Default is 500.

Custom Field Values Documentation

Values are returned based on the SortIndex in Bloomerang.

NameDependent ValuesDescriptionFormatNotes
StartThe index of the first record returned. Set by the skip parameterNumber
MaxItemsThe number of results to return in a page. Set by the take parameterNumber
TotalThe number of results in the systemNumber
ResultsTop levelArray of custom field values
FieldIdThe automatically assigned unique identifier for this recordNumber
IsActiveWhether the custom field value is activeBoolean
TextValuePopulated if the custom field’s DataType is TextString
DateValuePopulated if the custom field’s DataType is Date or YearStringIf Year, only the year part of the date is relevant
NumberValuePopulated if the custom field’s DataType is Decimal or CurrencyNumberCan be set to null
DataTypeThe data type of the custom field valuesStringValid values: Currency, Date, Decimal, Text, Year
PickTypeHow the user enters data into the custom field. Freeform fields return a 400 error: “You cannot request values for a freeform field.”StringValid values: Freeform, PickMultiple, PickOne

Custom Field Value Errors

CodeDescriptionNotes
400You cannot request values for a freeform fieldThe supported PickTypes are Pick Multiple and Pick One
500ErrorAn error from Bloomerang’s end