Blackbaud CRM API User Guide

This guide describes the Blackbaud CRM API and how it can be used to integrate CRM with other systems. This includes configuring a CRM environment to use the API.

Prerequisites

The API was released for general availability in Service Pack 20. To use the API, the CRM environment that will be connected to the API must accept inbound HTTPS traffic from the internet for certain IPs. More details can be found in the Notes and Troubleshooting section.

API Configuration

In order to use the API, an account must be created in the portal. This can be done by clicking the 'Sign In' link on the far right of the portal home page. This will navigate to a sign-in page that has a link to sign up.

An email containing an activation link will be sent during sign up. Following the link will complete activation, but subscribing to a product is required to complete setup of an account.

To subscribe to the CRM API product, navigate to the 'Product' tab.

Select the 'CRM API' product to navigate to a list of APIs supported by the product.

This page also has a 'Review terms and subscribe' button that links to the product subscription confirmation page. A terms sheet will be displayed before navigating to the confirmation page and that must be accepted.

After subscribing, the primary subscription key that will be used for all API calls can be accessed. To get the key, navigate to the Products page and select the newly added 'CRM API' subscription. This will navigate to a profile page that has subscription key information.

After subscribing, all available endpoints can be viewed on the APIs page. These endpoints group major CRM functionality into groups such as 'Constituent' or 'Fundraising'. Each endpoint contains multiple operations for CRM resources.

CRM configuration

To configure a CRM environment to communicate with the API, navigate to the 'Administration' functional area and select 'API Configuration'.

To setup a connection from a CRM environment to the API, a configuration record must be created. Select the 'Add configuration' action to open the add form.

All fields are required and each is described below.

Web Service URL - base URL of the CRM business operation web service directory. This can be found by browsing to the CRM start page 'Endpoints' link. After selecting the 'Endpoints' link, select 'Business Operation Services' from the list of endpoints. Note that this CRM environment must allow inbound HTTP traffic for certain IPs and must have a valid certificate (not a self-signed test certificate). Please see the Notes and Troubleshooting section for more details.

The URL will always be in the format https://host_name/virtual_directory_name/vpp/bizops/db[database_name]/catalog.ashx. An example URL - https://bbcrm.eastus.cloudapp.azure.com/bbappfx/vpp/bizops/db[BBINFINITY]/catalog.ashx

Note that in Service Pack 29 and later, the web service URL is pre-populated when opening the add form. This was added to help users configure the correct URL.

Subscription key - the primary subscription key assigned by the API portal for an account. Note that a different key and account should be used for each CRM environment. The API infrastructure will only allow a single mapping for each subscription key. This is necessary to route and authenticate API traffic to an environment by subscription key.

Username - The username that will be associated with the API configuration. This user should be an administrator or there could be authentication issues when using the API.

Password - The password for the username that will be associated with the API configuration.

Verifying API Configuration

Once the API is configured, any calls made to the API will be routed to the CRM environment associated with the subscription key header. The configuration can be verified by using the testing capabilities of the portal, a REST tool, or code. Every call must use the primary subscription key as the value of the 'Bbcrm-Api-Subscription-Key' header.

If a CRM environment is on Service Pack 29 or higher, API configurations are verified before they are saved in the add and edit forms. We found that many users experienced problems due to invalid URLs and credentials. Validation should provide relevant error messages and prevent bad configurations from being saved.

API endpoints

As mentioned in the previous section, each endpoint in the API portal groups functionally related operations. For example, all operations related to adding, editing or deleting a constituent interaction are located in the 'Constituent' endpoint.

Clicking on an operation will display the all the fields that can be used in a REST call to that operation. The field descriptions explain how the fields are used in CRM and if they are required. A sample request is also included on this page.

The portal also provides a convenient way to test API calls. Each method has a 'Try it' button that takes users to a page that can be used to send calls to the corresponding method.

Notes and Troubleshooting

If there are issues with the configuration saved for a CRM environment, a 400 response will normally be returned with one of the following error messages:

Error parsing CRM response: '>' is an unexpected token

This error is normally seen when CRM returns HTML instead of the expected SOAP message. This is commonly seen when the configured URL is incorrect or the CRM environment is using SSO for authentication.

If SSO is used to secure an environment, a change in application configuration must be made to change authentication for SOAP endpoints only. Add the following to web.config to make this change:

Unable to connect to the remote server

This issue is normally caused by an incorrect hostname in the URL or by blocked traffic to the SOAP endpoints of an environment. If an environment is behind a firewall that blocks inbound traffic from the internet, API calls could give this error.

Allowing HTTPS(port 443) traffic from 40.76.212.242 and 20.88.182.78 should resolve this issue.

The underlying connection closed: Could not establish trust relationship for the SSL/TLS secure channel

If a CRM environment is using a web server with a self-signed SSL certificate, this error is returned. The API can only be connected over HTTPS to an environment with a valid certificate.

Error sending SOAP message to CRM: The remote server returned an error: (401) Unauthorized

This error is normally caused by bad credentials. Insure that the username includes the domain for a Windows login or the email address associated with your BBID account.

When the user associated with the API configuration is not an administrator, the role(s) assigned to the user must have permission to the underlying feature called by the API. If the role permissions aren't sufficient, a 401 error will be returned.