Basics

The following information provides an overview of some key concepts within the SKY API. We'll assume you have some familiarity with RESTful programming concepts and the associated tools and techniques for consuming web services.

Base URL

All endpoints within the SKY API are located at the following base URL:

https://api.sky.blackbaud.com

Within this address, you'll find APIs (collections of related endpoints) covering the broad functional areas within the SKY API. For example, we currently surface the following APIs:

API Location Purpose
Accounts Payable /accountspayable Used to manage accounts payable, including vendors and invoices.
Constituent /constituent Used to manage constituent information, including related entities such as addresses, phones, emails, and notes.
Fundraising (Beta) /fundraising Used to manage information within the fundraising hierarchy and related entities such as campaigns, funds, and appeals.
General Ledger /generalledger Used to manage the general ledger, including accounts, projects, and journal entries.
Gift (Beta) /gift Used to manage gift information, including related entities such as acknowledgements, fundraisers, and receipts.
Opportunity (Beta) /opportunity Used to manage opportunity information, including related entities such as opportunity fundraisers and opportunity attachments.
Treasury (Beta) /treasury Used to manage Treasury information, including related entities such as adjustments, checks, and deposits.

Within each API, you'll find domain-specific endpoints that allow you to access data and perform operations like searching for records, updating information, etc. The SKY API is based on REST principles, where resources are accessed via standard requests to an API endpoint.

Scheme

For security, the SKY API communicates exclusively over HTTPS.

Subscription

In order to call the SKY API, you'll need a subscription associated with your developer account. This subscription represents our permission for you to call the API, and you'll include your subscription key in the bb-api-subscription-key header on every request (see request headers).

To obtain a subscription, visit the Products page, select SKY API Standard Edition and click Review terms and subscribe to initiate the request process. You must review all the terms by scrolling down the page before you can agree to the terms and subscribe. You will receive an email notification when your request is approved, and you'll be able to locate your subscription details within your developer profile.

Note:  Currently, SKY API access is limited to Blackbaud Partners and customers using Raiser's Edge NXT or Financial Edge NXT. Subscription requests are reviewed and must be approved by Blackbaud. If you are interested in using SKY API to build an integration for a specific customer, contact that organization's administrator to receive a user invite for the Blackbaud product. If you are interested in using SKY API to build an integration for multiple customers, we encourage you to become a partner.

Why two subscription keys?

Blackbaud provides two subscription keys labeled primary key and secondary key. You are free to use either in your requests to the API. As a security best practice it’s a good idea to rotate which key your applications use when calling the API. This mitigates the risk of a compromised key. Blackbaud won’t mandate a key rotation schedule. You are free to adopt a rotation strategy that best fits your needs. We also give you a mechanism to regenerate the keys associated with your subscription(s) in your Developer account profile.

Authorization

All endpoints within the SKY API require user-authorization, so in addition to a subscription key you'll also need to supply an OAuth 2.0 access token to access a specific Blackbaud customer's data. This token can be obtained through the authorization process, and should be included on every request as part of the Authorization header (see request headers).

Note: The token should be considered an opaque value and is tied to the authenticated user's account and organization. This means that your application can only access data to which the authenticated user has permission.

HTTP verbs

The SKY API is designed to have predictable, resource-oriented URLs to make learning easier. Where possible, the API strives to use the appropriate HTTP verb for each action:

Verb Description
GET Used to retrieve resources.
POST Used to create resources.
PATCH Used to update the properties of a resource.
DELETE Used to delete resources.

Request headers

The following request headers are required when calling the SKY API:

  • bb-api-subscription-key - This is your API subscription key, which represents Blackbaud's permission to you to call the SKY API. You can use either the primary or the secondary key associated with your subscription (both are equally functional). For more information on obtaining an API subscription, see subscription.
  • Authorization - This value is an OAuth 2.0 Bearer token, which is obtained during the authorization process and represents a Blackbaud customer's permission for you to access their data. The expected format of this header value is "Bearer token" (note the space in the middle).

For endpoints that accept JSON in the request body, the Content-Type request header with a value of application/json is required.

Content types

Unless otherwise noted, all endpoints within the SKY API accept and return data formatted as JSON. The Content-Type request header with a value of application/json is required when providing content on the body of a request.

Response status codes

The SKY API uses the following set of standard HTTP response status codes, as defined in RFC 2616 and RFC 6585. Response codes in the 4xx range indicate a problem with your request, while response codes in the 5xx range indicate a problem on our end.

You can view the common authentication issues page for additional guidance, and if you are experiencing a problem, feel free to review your support options in our Support area. You can also check the check the Issues page to see if we are experiencing any problems on our end.

For response codes in the 4xx or 5xx range (which indicate failures), the response body may contain more details on why the request failed.

Status codes

Status code Description
200 OK The request was successful, and you can read the results from the body and headers of the response. For operations that create new resources, you'll typically find the ID of the newly created resource in the response body. For simplicity, we don't distinguish between successful calls that create, update, or delete resources.
400 Bad Request The request failed due to an error on your part, such as a syntax error or malformed content in the request body.
401 Unauthorized The request failed because the required authorization was not satisfied. This could be because you provided an invalid subscription key (see subscription), or an invalid or expired access token (see common authentication issues).
403 Forbidden The request failed because the user in whose context the API is being called either does not have permission to perform the operation itself, or does not have permission to access the data being requested. You may also see this response when the API quota associated with your subscription has been met (see quota).
404 Not Found The requested resource could not be found. You may be trying to access a record that does not exist, or you may have supplied an invalid URL.
415 Unsupported Media Type The request failed because the correct Content-Type header was not provided on the request. For endpoints that accept JSON in the request body, you must use the Content-Type header application/json.
429 Too Many Requests You will see this response if you've exceeded the rate limit associated with your API subscription (see rate limits).
500 Internal Server Error An unexpected error has occurred on our side. You should never receive this response, but if you do please let us know and we'll fix it.
503 Service Unavailable One or more API services are not available. This is usually a temporary condition caused by an unexpected outage or due to planned downtime. We'll be proactive about broadcasting outages or downtime on the Issues page, so check there for more information.

Rate limits

Calls to the SKY API are subject to the rate limit associated with your API subscription (see subscription).

Rate limits help us to keep our backend servers from being overloaded with too many requests in a short period of time by limiting the number of calls you can make within that period. When your rate limit is exceeded, you'll receives a 429 - Too Many Requests response from the API, and the body of the response will indicate how long you must wait before making the next call (you can also inspect the Retry-After header which will contain the number of seconds to wait):

Retry-After: 1
Date: Tue, 06 Dec 2016 19:47:44 GMT
Content-Length: 83
Content-Type: application/json

{
  "statusCode": 429,
  "message": "Rate limit is exceeded. Try again in 1 second."
}

The current rate limit for the SKY API Standard Edition is 5 calls per second.

Quotas

Calls to the SKY API are subject to the quota associated with your API subscription (see subscription).

Quotas allow us to enforce an appropriate level of API use over a broad period of time by limiting the number of calls you can make within that period. When your quota is reached, you'll receive a 403 - Quota Exceeded response from the API, and the body of the response will indicate how long you must wait before the quota period renews (you can also inspect the Retry-After header which will contain the number of seconds to wait):

Retry-After: 406
Date: Tue, 24 May 2016 19:47:44 GMT
Content-Length: 83
Content-Type: application/json

{
  "statusCode": 403,
  "message": "Out of call volume quota. Quota will be replenished in 00:06:46."
}

The quota enforced for the SKY API Standard Edition is 25,000 calls per day. If you need to increase your quota, please fill out our request form.

Pagination

Many endpoints in the SKY API return a collection of records. In some cases (such as the Constituents (Get List) endpoint), we also support the concept of pagination, where instead of returning all of the results in a single response, we return them in smaller sets called pages. This approach allows us to keep the performance high on the server, and also minimizes the size of our responses on the wire by breaking them into smaller, more manageable blocks.

limit and offset

When an endpoint supports pagination, it will accept limit and offset query string parameters to allow you to control the paging. The limit parameter represents the number of records to return (page size), while the offset parameter represents the number of records to skip.

Here's an example request for returning the first 50 constituents via the Constituents (Get List) endpoint and the limit query string parameter:

GET https://api.sky.blackbaud.com/constituent/constituent?limit=50

To retrieve the next 50 records, include offset=50 to skip the first 50 records:

GET https://api.sky.blackbaud.com/constituent/constituent?limit=50&offset=50

To retrieve the next 50 records, include offset=100 to skip the first 100 records:

GET https://api.sky.blackbaud.com/constituent/constituent?limit=50&offset=100

Note that offset numbering is zero-based, and that omitting the offset parameter will return the first n elements (where n represents the limit parameter). Refer to the endpoint documentation for specifics about any default/maximum allowed page size values.

Some paginated endpoints may include a hypermedia link that can be used to fetch the next page of results. This value can be found in the next_link property of the collection response.

Date formats

Unless otherwise specified, dates are represented within the SKY API in ISO 8601 format. Some endpoints may further support time components or Coordinated Universal Time (UTC) format. Refer to the specific endpoint documentation for details on what date formats are supported.

Note that fuzzy dates are handled differently from the ISO-8601 standard. For more information on fuzzy dates, see fuzzy dates.

Fuzzy dates

Fuzzy dates are found on entities with date-like properties where the complete date may be unknown. They are represented in the SKY API as a JSON object with 3 fields for the year, month, and day components: y,m,d.

Fuzzy date fields generally allow the following formats:

  • month, day, and year
  • month and year
  • year only

Some entities may support additional formats, so be sure to reference the specific documentation for an endpoint that accepts or returns a fuzzy date.

For example, the constituent entity birthdate field is a fuzzy date that supports "month and day" as well as the above formats. In the below sample JSON representation, only the y property of the fuzzy date is shown which indicates that only the year value is known:

Date: Tue, 24 May 2016 19:47:44 GMT
Content-Type: application/json; charset=utf-8

{
  "id": "280",
  "type": "individual",
  "lookup_id": "96",
  "inactive": false,
  "name": "Dr. Robert C. Hernandez",
  "last": "Hernandez",
  "first": "Robert",
  "middle": "Carlos",
  "nickname": "Bob",
  "title": "Dr.",
  "gender": "male",
  "birthdate": {
    "y": 1961
  }
}

The following example shows a partial collection of notes for a constituent. The date property is a fuzzy date, and in the first note the value represented is June, 2007.

Date: Tue, 24 May 2016 19:47:44 GMT
Content-Type: application/json; charset=utf-8

{
  "count": 25,
  "value": [
    {
      "id": "12",
      "type": "Address Changes",
      "date": {
        "y": 2007,
        "m": 6
      },
      "summary": "Vacation",
      "text": "Dr. Hernandez has purchased a vacation home in Arizona."
    },
    {
      "id": "10",
      "type": "Career",
      "date": {
        "y": 2006,
        "m": 6,
        "d": 11
      },
      "summary": "Opening of Pediatric Clinic with Partner",
      "text": "Dr. Hernandez plans to leave the pharmaceutical company to open a practice with his former colleague."
    }, ...
  ]
}

Fuzzy dates are not traditional dates and do not conform to the ISO 8601 standard.

For additional information about fuzzy dates, see the entity reference.

Security

When calling the SKY API or when manually working with data in the underlying products, remember that specific operations and access to data follow the same rules. Required fields on records, business rules, and your user security (including advanced security) are all considered. For further information, review endpoint descriptions.

Activating the SKY API Console

The SKY API Console is a Blackbaud application built into the Endpoint Reference that can be used to test the SKY API. Before jumping in to build your own applications, we recommend you add the SKY API Console to your or your customer's tenant to aid with testing and development.

To access a tenant's data, the SKY API Console, must be approved by a tenant administrator. For Blackbaud customers, a tenant administrator is a user within the organization that is part of the Supervisor security group. This may include Partners or API subscribers that have their own dedicated tenant, or are Supervisor users in their customer's tenant. Administrators provide approval for applications, including the SKY API Console, by activating the application within the Applications area of the product.

To activate the SKY API Console, the tenant administrator needs to do the following:

  1. Copy the SKY API Console Application ID:

    A056CA6B-A3A8-4AC7-B325-997666306E52

  2. Visit the Control Panel, Applications area of the product.

  3. Select Add application, paste the SKY API Console Application ID, and select Save.

Once added, The SKY API Console will appear in the list of activated applications for the tenant.

Important!  The same process can be followed to activate additional applications for your tenant. Simply substitute the application ID for the one provided in the My Applications area of your Developer Account to add your own application, or use the application ID provided to you by a Partner or third party developer that you know and trust.

Breaking changes

Breaking changes are any changes that could potentially cause failures in applications that consume SKY API. If an API change could cause API calls to fail or return different results than before, then we consider it a breaking change. This includes changes to entities such as new data types or property names, changes to response data types or status codes, and changes to result sets for collection endpoints.

We strive to avoid breaking changes if at all possible, so breaking changes are few and far between. However, they are sometimes necessary. We only make breaking changes when we determine that they are critical, and we weigh the disruption that the breaking changes will cause. We strive to be transparent about these changes, and we announce them in a changelog on the SKY API website and in the Community blog at least one week before we deploy to give consumers of the API time to assess the impact of the changes, to raise any questions, and to plan accordingly.

For more information about how we define and handle breaking changes, please see the breaking changes post in the Community blog.