REST API

The BBIS REST API provides access to several key components of data retrieval. This API is commonly used in conjunction with the Advanced Donation Form. The API defaults to returning JSON, but will also return XML based on the accept header. See the Developer Guide for more information.

CodeTable/{Id}GET

Description

Returns the active code table entries for the specified code table Id ordered as configured in the CRM.

If the provided code table Id is valid, then this will return the active code table entries for the specified code table. The entries will be ordered as configured in the CRM.

Parameters
Id (GUID) Required Id of a code table.
Response
404 Not Found No code table was found by the specified Id.
200 OK Array of Code Table Entry Returns an array of code table entries. 
[
  {
    "Description": "Mr.",
    "Id": "aa784eae-4649-43ce-bf5a-0d2fccb01807"
  },
  {
    "Description": "Mrs.",
    "Id": "ca590da0-2884-4c90-86ef-a349d6ea6b09"
  }
]

Consent/{Id}GET

Description

Returns the object of the consent with consent options associated with a specified consent partId.

If the provided consent partId is valid, then this will return the object for the specified consent. The entries will be as configured in the CRM.

Parameters
Id (Integer) Required Id of the consent part.
Response
404 Not Found No consent part was found by the specified Id.
200 OK Object Returns a consent object. 
{
    "ConsentPartId": 000,
    "Title": "Consent Title",
    "ConsentStatement": "Please let us know how we should contact you in the future.",
    "PrivacyPolicy": null,
    "SolicitCodes": [
        {
            "SolicitCodeID": "fc17b935-5aa9-458b-804f-885f4e9d1e68",
            "ConsentPreferenceCode": 0,
            "IsRequired": false,
            "Sequence": 1,
            "Caption": "Do not phone",
            "ConsentCode": 0
        },
        {
            "SolicitCodeID": "393295e5-e70c-4e82-b105-c19a90b11bf0",
            "ConsentPreferenceCode": 0,
            "IsRequired": false,
            "Sequence": 4,
            "Caption": "Consent Solicit Codes:",
            "ConsentCode": 3
        },
        {
            "SolicitCodeID": "216c4bd4-0cb6-4e1d-85da-6da56642f834",
            "ConsentPreferenceCode": 0,
            "IsRequired": false,
            "Sequence": 7,
            "Caption": "Autumn mailing only",
            "ConsentCode": 0
        }
    ],
    "PrivacyPolicyText": null,
    "hdnCRMConsentSolicitCode": "41c43d63-7ea5-42e7-bbf4-032b0d72c2f5",
    "hdnCRMSolicitCode": "0aa0aa03-53ab-4dc6-b294-8ba6c02d9ad3"
}

DonationEditor/{PartId}GET

Description

Get the information that is configured on ADF Part to open checkout popup.

Parameters
PartId (Integer) Required Id of a donation form part.
Response
200 OK Object Return an object containing editor information. 
{
"MerchantAccountID":"00000000-0000-0000-0000-000000000000",
"UseMasterPass":true,
"UseVisaPass":true,
"UseApplePay":true,
"PrimaryFontColor":"#000000",
"SecondaryFontColor":"#000000",
"FontType":"roboto",
"MACheckoutSupported":true,
"DataKey":"00000000-0000-0000-0000-000000000000",
"RecaptchRequired":false
}
400 Bad Request Error[]

ADFCheckout/CreatePOST

Description

If the payment checkout pop up is configured on ADF and we click on donate button, after the checkout is loaded on the page, the donation transaction is added in the database and the state will be "pending".

Post Body
Donor (Object) Required Information about the donor of the gift. Donor and all attributes related to the donor (ex: Donor.Title) should be excluded if the donation form uses a Payment 2.0 part.
Donor.Title (String)
Donor.FirstName (String)
Donor.LastName (String) Required
Donor.EmailAddress (String) Required
Donor.Phone (String)
Donor.Address () Required Address information about the donor.
Donor.Address.StreetAddress (String) Required
Donor.Address.City (String) Required
Donor.Address.State (String) Required
Donor.Address.Country (String) Required In order for Blackbaud Secure Payments to pre-populate international billing addresses, this value should be the full country description specified in CRM.
Donor.Address.PostalCode (String) Required
Donor.OrganizationName (String) Required if Gift.IsCorporate is true. This field is not valid if the part is configured to use a Payment 2.0 page.
Gift () Required Information about the donation gift.
Gift.IsAnonymous (Boolean) Indicates that the gift is being made anonymously.
Gift.FinderNumber (Long)
Gift.SourceCode (String)
Gift.PaymentMethod (PaymentMethod ENUM) Required Indicates the method of payment to be used for the gift. Possible values:
  • CreditCard (0)
  • BillMeLater (1)
  • DirectDebit (2)
Gift.Comments (String)
Gift.CreateGiftAidDeclaration (Boolean) Indicates whether the gift aid is applied to the donation.
Gift.Designations (Array) Required Array of designation objects for the gift.
Gift.Designations.Amount (Decimal) Required The numeric amount of the designation. The currency is dictated by the merchant account specified.
Gift.Designations.DesignationId (GUID) Required Id of a designation to which the amount should be allocated.
Gift.Attributes (Array) Array of revenue attributes to be added to the gift.
Gift.Attributes.AttributeId (GUID) Required Id of revenue attribute. The only supported attribute data types are text, number, date, currency, yes/no, and code table. Only one per record attribute types are supported, except for code table attributes which support multiple entries per record. Any individual attribute id can only be supplied once for a donation.
Gift.Attributes.Value (String) Required Value of the attribute. For code table values, the name of the code table entry should be used. For Multiple code table entries, use a single attribute with the names semicolon delimited in the value field.
Gift.Recurrence.DayOfWeek (DayOfWeek ENUM) DayOfWeek value is required for weekly recurrences. Field is invalid for any frequency other than weekly. Possible values:
  • Sunday (0)
  • Monday (1)
  • Tuesday (2)
  • Wednesday (3)
  • Thursday (4)
  • Friday (5)
  • Saturday (6)
Gift.Recurrence.DayOfMonth (Integer) DayOfMonth value is required for non-weekly recurrences. Field is invalid for weekly frequency. Valid values: 1-31. Months with less than 31 days will default to the last day of the month is DayOfMonth is higher than number of days in the month.
Gift.Recurrence.Month (Integer) Month value is required for annual recurrences. Field is invalid for any frequency other than annually. Valid values: 1-12; Jan-Dec.
Gift.Recurrence.Frequency (RecurrenceFrequency ENUM) Required Designates the recurrence frequency. "Weekly" cannot be used with pledge installments. Possible values:
  • Weekly (1)
  • Monthly (2)
  • Quarterly (3)
  • Annually (4)
  • Every4Weeks (7)
Gift.Recurrence.StartDate (Date) Required Start date for recurrence. Must start on or after today's date.
Gift.Recurrence.EndDate (Date) Optional end date for recurrence. Must end after start date.
Gift.PledgeInstallment.InstallmentAmount (Date) An installment amount is required for a pledge or pledge installment payment.
Gift.PledgeInstallment.NumberOfInstallments (Date) The number of installments is required for a pledge installment payment.
Gift.Tribute.TributeID (GUID) Optional Tribute ID to map to. Must match Tribute ID from backoffice.
Gift.Tribute.TributeDefinition.FirstName (String) First name for new tribute definition.
Gift.Tribute.TributeDefinition.LastName (String) Required Last name for new tribute definition.
Gift.Tribute.TributeDefinition.Type (String) Required Tribute type to map to in backoffice. Must match existing tribute type.
Gift.Tribute.TributeDefinition.Description (String) Required Description for new tribute definition.
Gift.Tribute.Acknowledgee.FirstName (String) First name for tribute acknowledgee.
Gift.Tribute.Acknowledgee.LastName (String) Required Last name for tribute acknowledgee.
Gift.Tribute.Acknowledgee.Country (String) Required Country for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.AddressLines (String) Required Address lines for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.City (String) Required City for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.State (String) Required State for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.PostalCode (String) Required Postal code for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.Phone (String) Phone number for tribute acknowledgee.
Gift.Tribute.Acknowledgee.Email (String) Email address for tribute acknowledgee.
Gift.IsCorporate (Boolean) Indicates that the gift is given on behalf of a company. When true, the Corporate merge fields are displayed as opposed to the Individual merge fields. Cannot process if Donation Form is using a Payment 2.0 Part.
Origin () Required Information about the origin of the transaction.
Origin.AppealId (GUID) Id of an appeal to associate with the donation.
Origin.PageId (Integer) Id of the BBIS page hosting the donation form.
Origin.PageName (String) Required Name of the web page hosting the donation form.
BBSPReturnUri (String) The Uri that Blackbaud secured payment should redirect to after completing the payment. Required for credit card transactions. Exclude if Donation Form is using a Payment 2.0 Part.
BBSPTemplateSitePageId (Integer) Id of the BBIS page that should be used as the page template in Blackbaud secured payment. This page must contain certain BBSP-integrated part types for the page template to be usable, such as the Advanced Donation Form. Exclude if Donation Form is using a Payment 2.0 Part.
MerchantAccountId (GUID) Required Id of the merchant account that should be used to process the donation. Exclude if Donation Form is using a Payment 2.0 Part. 
{
"Id": "00000000-0000-0000-0000-000000000000"
}
Response
200 OK CreateDonationReply Returns a CreateDonationReply object containing information about the created donation and optionally a Uri for completing payment of the donation with Blackbaud secured payment. A location header is also returned containing a Uri of the new donation object. If the part is configured to use a Payment 2.0 page, the reply will contain a URI to the selected payment page instead of a secure payment URI.
400 Bad Request Error[] A validation error was found with the post data or an error occurred in the processing. Returns an array of Errror objects. Possible Errors:
  • RecordNotFound (106)
  • RequiredFieldMissing (101)
  • InvalidFieldSupplied (102)
  • ValueBelowMinimum (103)
  • ValueExceedsMaximum (104)
  • ValueNotAllowed (105)
  • ExceedsMaximumLength (107)
 
[
	{
		"ErrorCode":101,
		"Field":"Donor.LastName",
		"Message":null
	},
	{
		"ErrorCode":103,
		"Field":"Gift.Designations.Amount",
		"Message":"A designation's amount should be greater than 0."
	}
]

ADFCheckout/CompletePOST

Description

When the payment is completed by the checkout pop up then the previously added donation transaction will be marked as complete in the database, which were added at the time when pop up was loaded first time.

Post Body
Donor (Object) Required Information about the donor of the gift. Donor and all attributes related to the donor (ex: Donor.Title) should be excluded if the donation form uses a Payment 2.0 part.
Donor.Title (String)
Donor.FirstName (String)
Donor.LastName (String) Required
Donor.EmailAddress (String) Required
Donor.Phone (String)
Donor.Address () Required Address information about the donor.
Donor.Address.StreetAddress (String) Required
Donor.Address.City (String) Required
Donor.Address.State (String) Required
Donor.Address.Country (String) Required In order for Blackbaud Secure Payments to pre-populate international billing addresses, this value should be the full country description specified in CRM.
Donor.Address.PostalCode (String) Required
Donor.OrganizationName (String) Required if Gift.IsCorporate is true. This field is not valid if the part is configured to use a Payment 2.0 page.
Gift () Required Information about the donation gift.
Gift.IsAnonymous (Boolean) Indicates that the gift is being made anonymously.
Gift.FinderNumber (Long)
Gift.SourceCode (String)
Gift.PaymentMethod (PaymentMethod ENUM) Required Indicates the method of payment to be used for the gift. Possible values:
  • CreditCard (0)
  • BillMeLater (1)
  • DirectDebit (2)
Gift.Comments (String)
Gift.CreateGiftAidDeclaration (Boolean) Indicates whether the gift aid is applied to the donation.
Gift.Designations (Array) Required Array of designation objects for the gift.
Gift.Designations.Amount (Decimal) Required The numeric amount of the designation. The currency is dictated by the merchant account specified.
Gift.Designations.DesignationId (GUID) Required Id of a designation to which the amount should be allocated.
Gift.Attributes (Array) Array of revenue attributes to be added to the gift.
Gift.Attributes.AttributeId (GUID) Required Id of revenue attribute. The only supported attribute data types are text, number, date, currency, yes/no, and code table. Only one per record attribute types are supported, except for code table attributes which support multiple entries per record. Any individual attribute id can only be supplied once for a donation.
Gift.Attributes.Value (String) Required Value of the attribute. For code table values, the name of the code table entry should be used. For Multiple code table entries, use a single attribute with the names semicolon delimited in the value field.
Gift.Recurrence.DayOfWeek (DayOfWeek ENUM) DayOfWeek value is required for weekly recurrences. Field is invalid for any frequency other than weekly. Possible values:
  • Sunday (0)
  • Monday (1)
  • Tuesday (2)
  • Wednesday (3)
  • Thursday (4)
  • Friday (5)
  • Saturday (6)
Gift.Recurrence.DayOfMonth (Integer) DayOfMonth value is required for non-weekly recurrences. Field is invalid for weekly frequency. Valid values: 1-31. Months with less than 31 days will default to the last day of the month is DayOfMonth is higher than number of days in the month.
Gift.Recurrence.Month (Integer) Month value is required for annual recurrences. Field is invalid for any frequency other than annually. Valid values: 1-12; Jan-Dec.
Gift.Recurrence.Frequency (RecurrenceFrequency ENUM) Required Designates the recurrence frequency. "Weekly" cannot be used with pledge installments. Possible values:
  • Weekly (1)
  • Monthly (2)
  • Quarterly (3)
  • Annually (4)
  • Every4Weeks (7)
Gift.Recurrence.StartDate (Date) Required Start date for recurrence. Must start on or after today's date.
Gift.Recurrence.EndDate (Date) Optional end date for recurrence. Must end after start date.
Gift.PledgeInstallment.InstallmentAmount (Date) An installment amount is required for a pledge or pledge installment payment.
Gift.PledgeInstallment.NumberOfInstallments (Date) The number of installments is required for a pledge installment payment.
Gift.Tribute.TributeID (GUID) Optional Tribute ID to map to. Must match Tribute ID from backoffice.
Gift.Tribute.TributeDefinition.FirstName (String) First name for new tribute definition.
Gift.Tribute.TributeDefinition.LastName (String) Required Last name for new tribute definition.
Gift.Tribute.TributeDefinition.Type (String) Required Tribute type to map to in backoffice. Must match existing tribute type.
Gift.Tribute.TributeDefinition.Description (String) Required Description for new tribute definition.
Gift.Tribute.Acknowledgee.FirstName (String) First name for tribute acknowledgee.
Gift.Tribute.Acknowledgee.LastName (String) Required Last name for tribute acknowledgee.
Gift.Tribute.Acknowledgee.Country (String) Required Country for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.AddressLines (String) Required Address lines for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.City (String) Required City for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.State (String) Required State for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.PostalCode (String) Required Postal code for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.Phone (String) Phone number for tribute acknowledgee.
Gift.Tribute.Acknowledgee.Email (String) Email address for tribute acknowledgee.
Gift.IsCorporate (Boolean) Indicates that the gift is given on behalf of a company. When true, the Corporate merge fields are displayed as opposed to the Individual merge fields. Cannot process if Donation Form is using a Payment 2.0 Part.
Origin () Required Information about the origin of the transaction.
Origin.AppealId (GUID) Id of an appeal to associate with the donation.
Origin.PageId (Integer) Id of the BBIS page hosting the donation form.
Origin.PageName (String) Required Name of the web page hosting the donation form.
BBSPReturnUri (String) The Uri that Blackbaud secured payment should redirect to after completing the payment. Required for credit card transactions. Exclude if Donation Form is using a Payment 2.0 Part.
BBSPTemplateSitePageId (Integer) Id of the BBIS page that should be used as the page template in Blackbaud secured payment. This page must contain certain BBSP-integrated part types for the page template to be usable, such as the Advanced Donation Form. Exclude if Donation Form is using a Payment 2.0 Part.
MerchantAccountId (GUID) Required Id of the merchant account that should be used to process the donation. Exclude if Donation Form is using a Payment 2.0 Part. 
{
"Id": "3439a5c7-9977-4f9c-ba11-fadfb8144d35"
}
Response
200 OK CreateDonationReply Returns a CreateDonationReply object containing information about the created donation and optionally a Uri for completing payment of the donation with Blackbaud secured payment. A location header is also returned containing a Uri of the new donation object. If the part is configured to use a Payment 2.0 page, the reply will contain a URI to the selected payment page instead of a secure payment URI.
400 Bad Request Error[] A validation error was found with the post data or an error occurred in the processing. Returns an array of Errror objects. Possible Errors:
  • RecordNotFound (106)
  • RequiredFieldMissing (101)
  • InvalidFieldSupplied (102)
  • ValueBelowMinimum (103)
  • ValueExceedsMaximum (104)
  • ValueNotAllowed (105)
  • ExceedsMaximumLength (107)
 
[
	{
		"ErrorCode":101,
		"Field":"Donor.LastName",
		"Message":null
	},
	{
		"ErrorCode":103,
		"Field":"Gift.Designations.Amount",
		"Message":"A designation's amount should be greater than 0."
	}
]

ADFCheckout/DeletePOST

Description

When we close the checkout pop up the previously saved transaction deletes from CMSTransactionState table.

Post Body
Id () Required Transaction Id 
{
"Id": "3439a5c7-9977-4f9c-ba11-fadfb8144d35"
}
Response
200 OK HttpResponseMessage Returns a HttpResponseMessage object containing information about the public key.
400 Bad Request Error[] A validation error was found with the post data or an error occurred in the processing. Returns an array of Errror objects. Possible Errors:
  • RecordNotFound (106)
  • RequiredFieldMissing (101)
  • InvalidFieldSupplied (102)
  • ValueBelowMinimum (103)
  • ValueExceedsMaximum (104)
  • ValueNotAllowed (105)
  • ExceedsMaximumLength (107)
 
[
	{
		"ErrorCode":101,
		"Field":"Donor.LastName",
		"Message":null
	}
]

CountryGET

Description

Returns a list of all active countries alphabetized by their description.

Will return information about all active countries alphabetized by their description.

Response
200 OK Array of Countries Returns an array country objects 
[
  { 
    "Id": "2C3F57A7-65DE-4D55-89EF-7857E6EDD53C",
    "Abbreviation": "CA",
    "Description": "Canada",
	"ISO":"CA",
	"AddressFormat":"afCANADA"
  },
  {
    "Id": "B4837D3E-36F6-42F4-8049-CC2A2B108F9E",
    "Abbreviation": "US",
    "Description": "United States",
	"ISO":"US",
	"AddressFormat":"afUNITED_STATES"
  }
]

Country/{Id}GET

Description

Returns information about a specific country.

If the provided country Id is valid, then this will return information about the country.

Parameters
Id (GUID) Required Id of a country.
Response
404 Not Found No country was found by the specified Id.
200 OK Country Returns a country object 
{
  "Id": "B4837D3E-36F6-42F4-8049-CC2A2B108F9E",
  "Abbreviation": "US",
  "Description": "United States",
  "ISO":"US",
  "AddressFormat":"afUNITED_STATES"
}

Country/{Id}/StateGET

Description

Returns a list of states associated with a country, alphabetized by their description.

If the provided country Id is valid, then this will return a list of state objects for each state associated with the country. The states will be returned alphabetized description.

Parameters
Id (GUID) Required Id of a country.
Response
404 Not Found No country was found by the specified Id.
200 OK Array of States Returns an array of state objects for the given country alphabetized by their description. 
[
  {
    "Id": "ba9b5958-b1d0-43ed-ba37-5e7c0eddfc78",
    "Abbreviation": "RI",
    "Description": "Rhode Island",
	"ISO":"RI"
  },
  {
    "Id": "70BF9733-5D24-46F4-A40C-61F6D2765575", 
    "Abbreviation": "SC",
    "Description": "South Carolina",
	"ISO":"SC"
  }
]

Country/{Id}/AddressCaptionsGET

Description

Returns the captions for Address Lines, City, State, and Postcode.

If the provided country Id is valid, then this will return the captions for address lines, city, state, and postcode.

Parameters
Id (GUID) Required Id of a country.
Response
404 Not Found No country was found by the specified Id.
200 OK Address Captions Returns an AddressCaptions object containing the labels for Address Lines, City, State, and Postcode. 
{
  "AddressLines": "Address",
  "City": "City",
  "PostCode": "Zip",
  "State": "State"
}

{PartId}/Donation/{Id}GET

Description

Gets the donation object of the specified Id if the user has appropriate access.

Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database.

Parameters
PartId (Integer) Required Id of a donation form part.
Id (GUID) Required Id of a donation.
Response
403 Forbidden User does not have access to the specified donation.
404 Not Found No donation was found by the specified Id.
200 OK Donation Returns a Donation object containing information about the requested donation Id. 
{
    "Donor": {
        "Address": {
            "City": "Columbia",
            "Country": "United States",
            "PostalCode": "29212",
            "State": "SC",
            "StreetAddress": "123 Main St."
        },
        "EmailAddress": "john.doe@blackbaud.com",
        "FirstName": "John",
        "LastName": "Doe",
        "Phone": "555-555-5555",
        "Title": "Mr."
    },
    "Gift": {
        "Designations": [
            {
                "Amount": 5,
                "DesignationId": "3439a5c7-9977-4f9c-ba11-fadfb8144d35"
            }
        ],
        "FinderNumber": 0,
        "SourceCode": "Sample Source Code",
        "IsAnonymous": false,
        "PaymentMethod": 1,
        "Comments": "Gift comments here.",
        "CreateGiftAidDeclaration": false,
        "Attributes": [
            {
                "AttributeId": "BD18B3FD-B382-4183-A415-8F84B1E0E411",
                "Value": "Volunteer;Member;Alumni"
            },
            {
                "AttributeId": "3607C77D-19DC-4EE0-A0CD-A352762A8EF0",
                "Value": "1985"
            }
        ],
        "Recurrence": {
            "DayOfMonth": 26,
            "DayOfWeek": null,
            "EndDate": null,
            "Frequency": 2,
            "Month": null,
            "StartDate": "Date(1337227200000-0400)"
        },
        "Tribute": {
            "Acknowledgee": {
                "AddressLines": "123 Sunset ln.",
                "City": "Charleston",
                "Country": "USA",
                "Email": "email@address.com",
                "FirstName": "Jane",
                "LastName": "Doe",
                "Phone": "123-123-1234",
                "PostalCode": "29482",
                "State": "SC"
            },
            "TributeDefinition": {
                "Description": "New tribute",
                "FirstName": "John",
                "LastName": "Hancock",
                "Type": "Tribute"
            },
            "TributeId": null
        }
    },
    "Id": "853f96be-bf08-4828-aefa-326a06e48d31",
    "Origin": {
        "AppealId": "C3B20FD8-6A81-451E-BF78-D195E82B4CBF",
        "PageId": 784,
        "PageName": "Sample Page"
    },
    "TransactionStatus": 1
}

{PartId}/Donation/ValidateDonationRequestPOST

Description

When we use the checkout pop up on the ADF then the request must be validated before opening the pop up.

Parameters
PartId (Integer) Required Id of a donation form part.
Response
200 OK Boolean Returns true if successfully validated.
400 Bad Request Error[]

{PartId}/Donation/CreatePOST

Description

Attempts to create a donation from the posted object.

Validates the fields in the posted CreateDonationRequest. If valid, creates a donation transaction and saves it to the database. Stores the Id of the new donation in session so the user has permissions for the donation instance. If the payment type is credit card, communicates with Blackbaud secured payment to set up a check out URI and adds that URI to the return object. For credit card payment, the donation is saved in a Pending state. For payments not using a credit card, the donation is saved in a Completed state and an acknowledgement email is sent.

Parameters
PartId (Integer) Required Id of a donation form part.
Post Body
Donor () Required Information about the donor of the gift. Donor and all attributes related to the donor (ex: Donor.Title) should be excluded if the donation form uses a Payment 2.0 part.
Donor.Title (String)
Donor.FirstName (String)
Donor.LastName (String) Required
Donor.EmailAddress (String) Required
Donor.Phone (String)
Donor.Address () Required Address information about the donor.
Donor.Address.StreetAddress (String) Required
Donor.Address.City (String) Required
Donor.Address.State (String) Required
Donor.Address.Country (String) Required In order for Blackbaud Secure Payments to pre-populate international billing addresses, this value should be the full country description specified in CRM.
Donor.Address.PostalCode (String) Required
Donor.OrganizationName (String) Required if Gift.IsCorporate is true. This field is not valid if the part is configured to use a Payment 2.0 page.
Gift () Required Information about the donation gift.
Gift.IsAnonymous (Boolean) Indicates that the gift is being made anonymously.
Gift.FinderNumber (Long)
Gift.SourceCode (String)
Gift.PaymentMethod (PaymentMethod ENUM) Required Indicates the method of payment to be used for the gift. Possible values:
  • CreditCard (0)
  • BillMeLater (1)
  • DirectDebit (2)
Gift.Comments (String)
Gift.CreateGiftAidDeclaration (Boolean) Indicates whether the gift aid is applied to the donation.
Gift.Designations (Array) Required Array of designation objects for the gift.
Gift.Designations.Amount (Decimal) Required The numeric amount of the designation. The currency is dictated by the merchant account specified.
Gift.Designations.DesignationId (GUID) Required Id of a designation to which the amount should be allocated.
Gift.Attributes (Array) Array of revenue attributes to be added to the gift.
Gift.Attributes.AttributeId (GUID) Required Id of revenue attribute. The only supported attribute data types are text, number, date, currency, yes/no, and code table. Only one per record attribute types are supported, except for code table attributes which support multiple entries per record. Any individual attribute id can only be supplied once for a donation.
Gift.Attributes.Value (String) Required Value of the attribute. For code table values, the name of the code table entry should be used. For Multiple code table entries, use a single attribute with the names semicolon delimited in the value field.
Gift.Recurrence.DayOfWeek (DayOfWeek ENUM) DayOfWeek value is required for weekly recurrences. Field is invalid for any frequency other than weekly. Possible values:
  • Sunday (0)
  • Monday (1)
  • Tuesday (2)
  • Wednesday (3)
  • Thursday (4)
  • Friday (5)
  • Saturday (6)
Gift.Recurrence.DayOfMonth (Integer) DayOfMonth value is required for non-weekly recurrences. Field is invalid for weekly frequency. Valid values: 1-31. Months with less than 31 days will default to the last day of the month is DayOfMonth is higher than number of days in the month.
Gift.Recurrence.Month (Integer) Month value is required for annual recurrences. Field is invalid for any frequency other than annually. Valid values: 1-12; Jan-Dec.
Gift.Recurrence.Frequency (RecurrenceFrequency ENUM) Required Designates the recurrence frequency. Possible values:
  • Weekly (1)
  • Monthly (2)
  • Quarterly (3)
  • Annually (4)
  • Every4Weeks (7)
Gift.Recurrence.StartDate (Date) Required Start date for recurrence. Must start on or after today's date.
Gift.Recurrence.EndDate (Date) Optional end date for recurrence. Must end after start date.
Gift.Tribute.TributeID (GUID) Optional Tribute ID to map to. Must match Tribute ID from backoffice.
Gift.Tribute.TributeDefinition.FirstName (String) First name for new tribute definition.
Gift.Tribute.TributeDefinition.LastName (String) Required Last name for new tribute definition.
Gift.Tribute.TributeDefinition.Type (String) Required Tribute type to map to in backoffice. Must match existing tribute type.
Gift.Tribute.TributeDefinition.Description (String) Required Description for new tribute definition.
Gift.Tribute.Acknowledgee.FirstName (String) First name for tribute acknowledgee.
Gift.Tribute.Acknowledgee.LastName (String) Required Last name for tribute acknowledgee.
Gift.Tribute.Acknowledgee.Country (String) Required Country for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.AddressLines (String) Required Address lines for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.City (String) Required City for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.State (String) Required State for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.PostalCode (String) Required Postal code for tribute acknowledgee address.
Gift.Tribute.Acknowledgee.Phone (String) Phone number for tribute acknowledgee.
Gift.Tribute.Acknowledgee.Email (String) Email address for tribute acknowledgee.
Gift.IsCorporate (Boolean) Indicates that the gift is given on behalf of a company. When true, the Corporate merge fields are displayed as opposed to the Individual merge fields. Cannot process if Donation Form is using a Payment 2.0 Part.
Origin () Required Information about the origin of the transaction.
Origin.AppealId (GUID) Id of an appeal to associate with the donation.
Origin.PageId (Integer) Id of the BBIS page hosting the donation form.
Origin.PageName (String) Required Name of the web page hosting the donation form.
BBSPReturnUri (String) The Uri that Blackbaud secured payment should redirect to after completing the payment. Required for credit card transactions. Exclude if Donation Form is using a Payment 2.0 Part.
BBSPTemplateSitePageId (Integer) Id of the BBIS page that should be used as the page template in Blackbaud secured payment. This page must contain certain BBSP-integrated part types for the page template to be usable, such as the Advanced Donation Form. Exclude if Donation Form is using a Payment 2.0 Part.
MerchantAccountId (GUID) Required Id of the merchant account that should be used to process the donation. Exclude if Donation Form is using a Payment 2.0 Part. 
{
    "Donor": {
        "Address": {
            "City": "Columbia",
            "Country": "United States",
            "PostalCode": "29212",
            "State": "SC",
            "StreetAddress": "123 Main St."
        },
        "EmailAddress": "john.doe@blackbaud.com",
        "FirstName": "John",
        "LastName": "Doe",
        "Phone": "555-555-5555",
        "Title": "Mr."
    },
    "Gift": {
        "Designations": [
            {
                "Amount": 5,
                "DesignationId": "3439a5c7-9977-4f9c-ba11-fadfb8144d35"
            }
        ],
        "FinderNumber": 0,
        "IsAnonymous": false,
        "PaymentMethod": 1,
        "Comments": "Gift comments here.",
        "CreateGiftAidDeclaration": false,
        "Attributes": [
            {
                "AttributeId": "BD18B3FD-B382-4183-A415-8F84B1E0E411",
                "Value": "Volunteer;Member;Alumni"
            },
            {
                "AttributeId": "3607C77D-19DC-4EE0-A0CD-A352762A8EF0",
                "Value": "1985"
            }
        ],
        "Recurrence": {
            "DayOfMonth": 26,
            "DayOfWeek": null,
            "EndDate": null,
            "Frequency": 2,
            "Month": null,
            "StartDate": "/Date(1337227200000-0400)/"
        },
        "Tribute": {
            "Acknowledgee": {
                "AddressLines": "123 Sunset ln.",
                "City": "Charleston",
                "Country": "USA",
                "Email": "email@address.com",
                "FirstName": "Joe",
                "LastName": "Schmo",
                "Phone": "123-123-1234",
                "PostalCode": "29482",
                "State": "SC"
            },
            "TributeDefinition": {
                "Description": "New tribute",
                "FirstName": "John",
                "LastName": "Hancock",
                "Type": "Tribute"
            },
            "TributeId": null
        }
    },
    "Origin": {
        "AppealId": "C3B20FD8-6A81-451E-BF78-D195E82B4CBF",
        "PageId": 784,
        "PageName": "Sample Page"
    },
    "BBSPReturnUri": "http://www.mydomain.com",
    "BBSPTemplateSitePageId": 784,
    "MerchantAccountId": "A9EBE81D-65A8-4BBF-8446-FB2ED0276209"
}
Response
400 Bad Request Error[] A validation error was found with the post data or an error occurred in the processing. Returns an array of Errror objects. Possible Errors:
  • RecordNotFound (106)
  • RequiredFieldMissing (101)
  • InvalidFieldSupplied (102)
  • ValueBelowMinimum (103)
  • ValueExceedsMaximum (104)
  • ValueNotAllowed (105)
  • ExceedsMaximumLength (107)
 
[
	{
		"ErrorCode":101,
		"Field":"Donor.LastName",
		"Message":null
	},
	{
		"ErrorCode":103,
		"Field":"Gift.Designations.Amount",
		"Message":"A designation's amount should be greater than 0."
	}
]
201 OK CreateDonationReply Returns a CreateDonationReply object containing information about the created donation and optionally a Uri for completing payment of the donation with Blackbaud secured payment. A location header is also returned containing a Uri of the new donation object. If the part is configured to use a Payment 2.0 page, the reply will contain a URI to the selected payment page instead of a secure payment URI. 
{
    "Donation": {
        "Donor": {
            "Address": {
                "City": "Columbia",
                "Country": "United States",
                "PostalCode": "29212",
                "State": "SC",
                "StreetAddress": "123 Main St."
            },
            "EmailAddress": "john.doe@blackbaud.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Phone": "555-555-5555",
            "Title": "Mr."
        },
        "Gift": {
            "Designations": [
                {
                    "Amount": 5,
                    "DesignationId": "3439a5c7-9977-4f9c-ba11-fadfb8144d35"
                }
            ],
            "FinderNumber": 0,
            "IsAnonymous": false,
            "PaymentMethod": 1,
            "Comments": "Gift comments here.",
            "CreateGiftAidDeclaration": false,
            "Attributes": [
                {
                    "AttributeId": "BD18B3FD-B382-4183-A415-8F84B1E0E411",
                    "Value": "Volunteer;Member;Alumni"
                },
                {
                    "AttributeId": "3607C77D-19DC-4EE0-A0CD-A352762A8EF0",
                    "Value": "1985"
                }
            ],
            "Recurrence": {
                "DayOfMonth": 26,
                "DayOfWeek": null,
                "EndDate": null,
                "Frequency": 2,
                "Month": null,
                "StartDate": "/Date(1337227200000-0400)/"
            },
            "Tribute": {
                "Acknowledgee": {
                    "AddressLines": "123 Sunset ln.",
                    "City": "Charleston",
                    "Country": "USA",
                    "Email": "email@address.com",
                    "FirstName": "Joe",
                    "LastName": "Schmo",
                    "Phone": "123-123-1234",
                    "PostalCode": "29482",
                    "State": "SC"
                },
                "TributeDefinition": {
                    "Description": "New tribute",
                    "FirstName": "John",
                    "LastName": "Hancock",
                    "Type": "Tribute"
                },
                "TributeId": null
            }
        },
        "Id": "853f96be-bf08-4828-aefa-326a06e48d31",
        "Origin": {
            "AppealId": "C3B20FD8-6A81-451E-BF78-D195E82B4CBF",
            "PageId": 784,
            "PageName": "Sample Page"
        },
        "TransactionStatus": 1
    },
    "BBSPCheckoutUri": " https://payments.blackbaud.com/Pages/Index.aspx?t=853f96be-bf08-4828-aefa-326a06e48d31"
}

{PartId}/Donation/{Id}/CompleteBBSPDonationPOST

Description

Signals the application to confirm that the donation has been paid in Blackbaud secured payment and to complete the creation of the donation.

Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database. Ensures the donation is a credit card donation and not already in a completed state. If not, then confirms with Blackbaud secured payment whether the donation is paid. If so, updates the donation status and sends the acknowledgment email.

Parameters
PartId (Integer) Required Id of a donation form part.
Id (GUID) Required Id of a donation.
Response
403 Forbidden User does not have access to the specified donation.
404 Not Found No donation was found by the specified Id.
400 Bad Request Error[] The donation payment was not properly completed in Blackbaud secured payment or the donation has already been marked as completed. Possible Errors:
  • InvalidOperation (102)
  • BBSPTransactionNotProcessed (203)
 
[
    {
        "ErrorCode": 102,
        "Field": null,
        "Message": null
    }
]
200 OK Donation Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database. Ensures the donation is a credit card donation and not already in a completed state. If not, then confirms with Blackbaud secured payment whether the donation is paid. If so, updates the donation status and sends the acknowledgment email. 
{
    "Donor": {
        "Address": {
            "City": "Columbia",
            "Country": "United States",
            "PostalCode": "29212",
            "State": "SC",
            "StreetAddress": "123 Main St."
        },
        "EmailAddress": "john.doe@blackbaud.com",
        "FirstName": "John",
        "LastName": "Doe",
        "Phone": "555-555-5555",
        "Title": "Mr."
    },
    "Gift": {
        "Designations": [
            {
                "Amount": 5,
                "DesignationId": "3439a5c7-9977-4f9c-ba11-fadfb8144d35"
            }
        ],
        "FinderNumber": 0,
        "IsAnonymous": false,
        "PaymentMethod": 1,
        "Comments": "Gift comments here.",
        "CreateGiftAidDeclaration": false,
        "Attributes": [
            {
                "AttributeId": "BD18B3FD-B382-4183-A415-8F84B1E0E411",
                "Value": "Volunteer;Member;Alumni"
            },
            {
                "AttributeId": "3607C77D-19DC-4EE0-A0CD-A352762A8EF0",
                "Value": "1985"
            }
        ],
        "Recurrence": {
            "DayOfMonth": 26,
            "DayOfWeek": null,
            "EndDate": null,
            "Frequency": 2,
            "Month": null,
            "StartDate": "/Date(1337227200000-0400)/"
        },
        "Tribute": {
            "Acknowledgee": {
                "AddressLines": "123 Sunset ln.",
                "City": "Charleston",
                "Country": "USA",
                "Email": "email@address.com",
                "FirstName": "Joe",
                "LastName": "Schmo",
                "Phone": "123-123-1234",
                "PostalCode": "29482",
                "State": "SC"
            },
            "TributeDefinition": {
                "Description": "New tribute",
                "FirstName": "John",
                "LastName": "Hancock",
                "Type": "Tribute"
            },
            "TributeId": null
        }
    },
    "Id": "853f96be-bf08-4828-aefa-326a06e48d31",
    "Origin": {
        "AppealId": "C3B20FD8-6A81-451E-BF78-D195E82B4CBF",
        "PageId": 784,
        "PageName": "Sample Page"
    },
    "TransactionStatus": 1
}

{PartId}/Donation/{Id}/ConfirmationHtmlGET

Description

Gets HTML for a confirmation screen for the completed donation.

Ensures the user has access to this donation by finding the Id in their session. If so, loads the donation out of the database and merges the fields into the part’s confirmation block.

Parameters
PartId (Integer) Required Id of a donation form part.
Id (GUID) Required Id of a donation.
Response
403 Forbidden User does not have access to the specified donation.
404 Not Found No donation was found by the specified Id.
200 OK String Returns a string containing the HTML block of the confirmation with the donation fields merged in. 
<div>Thank you for donating $10.00.</div>

{PartId}/Donation/GetBankingSystemTypesPOST

Description

Gets an array of Banking Type object containing all banking types that is enabled in CRM.

Parameters
PartId (Integer) Required Id of a donation form part.
Response
200 OK Object Returns an array of banking type object with all banking types. 
[
{
 "Abbreviation": "USA",
 "Description": "USA(ACH)"
}
]
400 Bad Request Error[]

{PartId}/Donation/GetAccountTypesPOST

Description

Gets an array of Account Type object containing all supported account types.

Parameters
PartId (Integer) Required Id of a donation form part.
Response
200 OK Object Returns an array of account type object with all account types. 
[
{
"Id": "1",
"Description": "Checking"
}
]
400 Bad Request Error[]

{PartId}/Donation/GetOriginIdAndTimePOST

Description

Gets OriginData object containing information about client id and time.

Parameters
PartId (Integer) Required Id of a donation form part.
Response
200 OK Object Returns a originData object with client id and time. 
{
"OriginId": "1",
"Time": "01/01/1999"
}
400 Bad Request Error[]

Images?FolderGUID={Id}GET

Description

Gets the image objects that the user has access to within the specified folder.

Returns information about all images that the current user has access to and exist within the specified folder.

Parameters
Id (GUID) Required Id of an image folder.
Response
200 OK Array of Images Returns an array of Image objects that current user has access to and exist within the specified folder. 
[
  {
    "Caption": "Sunset", 
    "Url": "http://www.mydomain.com/image/sunset.jpg"
  }
]

Images?Tag={TagName}GET

Description

Gets the image objects that the user has access to tagged with the specified tag.

Returns information about all images that the current user has access to and are tagged with the specified tag.

Parameters
TagName (String) Required Name of the tag
Response
200 OK Array of Images Returns an array of Image objects that current user has access to and are tagged with the specified tag. 
[
  {
    "Caption": "Sunset",
    "Url": "http://www.mydomain.com/image/sunset.jpg"
  }
]

Images/{FolderName}/{SubFolderName}GET

Description

Gets the image objects that the user has access to under the specified folder name/path.

Returns information about all images that the current user has access to and exist under the specified folder path.

Parameters
FolderName (String) Required Path/name of the folder.
Response
200 OK Array of Images Returns an array of Image objects that current user has access to and exist under the specified folder path. 
[
  {
    "Caption": "Sunset", 
    "Url": "http://www.mydomain.com/image/sunset.jpg"
  }
]
404 Not Found No folder exists at the given path.

Query/{Id}?Column1Name={ColumnFilter}&Column2Name={ColumnFilter} GET

Description

Returns the results for the specified query.

Returns the result of executing the specified, published query. The query is executed as the last user to save the query. The results are cached and may be up to 10 minutes old. The results are limited to 5000 rows.

Parameters
Id (GUID) Required Id of a query that has been published.
ColumnFilter (String) Filters the results to rows that contain the specified value in the specified column. When specifying a column, use the name that is found in the query response. Depending on the type of column being filtered, the results may filter to rows that exactly match the specified value instead of those that contain the specified value. Summary columns such as MAX, MIN, and COUNT cannot be used as filters and will be ignored.
Response
404 Not Found No published query was found by the specified Id.
200 OK QueryResults Returns a Query object containing results of executing the specified query. 
{
  "Fields": [
    {
      "Caption": "ID",
      "Name": "System record ID"
    },
    {
      "Caption": "Fund",
      "Name": "Purpose\\Public Name"
    }
  ],
  "Rows":[
    {
      "Values": [
        "1BB27696-3045-405E-BD74-DC8853506977", 
        "Sample Designation 1"
      ]
    },
    {
      "Values": [
        "2AE550FB-B3FC-43CE-A07A-B23C45BF1A2E", 
        "Sample Designation 2"
      ]
    },
    {
      "Values": [
        "2AE550FB-B3FC-43CE-A07A-B23C45BF1A2E", 
        "Sample Designation 3"
      ]
    }
  ]
}

UserGET

Description

Gets basic profile information about the current user.

Returns profile information for the current user. If the user is not logged in, then it may be populated based on the current email-recipient information.

Response
200 OK UserInformation Returns profile information about the current user. 
{
  "Addresses": [
    {
      "City": "Daniel Island",
      "Country": "United States",
      "Id": "53064038-dea9-48d4-bbd6-42725f78b234",
      "IsPrimary": true,
      "PostalCode": "29464",
      "State": "SC",
      "StreetAddress": "123 Sample Drive",
      "Type": "fda0e1f0-6918-4e96-8cb5-9a9a841d4ee6"
    },
    {
      "City": "Columbia",
      "Country": "United States",
      "Id":" d35a3299-407b-465f-b3f1-43465a60713e",
      "IsPrimary": false,
      "PostalCode": "29212",
      "State": "SC",
      "StreetAddress": "200 Harbison Boulevard",
      "Type": "17b13db9-1fab-4203-8b66-a2f26db637c5"
    }
  ],
  "EmailAddresses": [
    {
      "EmailAddress": "JohnDoe@organization.com",
      "Id": "9127174d-4b16-4c38-8b35-f0dbc61d7e27",
      "IsPrimary": true,
      "Type": "51d52fc2-6ac1-4687-bec0-c4fed5a05b65"
    },
    {
      "EmailAddress": "JohnDoe@personal.com",
      "Id": "8e48a013-6484-42b8-9746-c40a8eee9729",
      "IsPrimary": false,
      "Type": "51d52fc2-6ac1-4687-bec0-c4fed5a05b65"
    }
  ],
  "FirstName": "John",
  "LastName": "Doe",
  "Phone": "803-781-8851",
  "Title": "Mr"
}

Blackbaud Internet Solutions

Blackbaud Developer Network

© 2014 Blackbaud, Inc. All rights reserved.