Basics

The following information provides an overview of some key concepts within the Blackbaud ON 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 Blackbaud ON API are located at the following base URL:

https://{school}.myschoolapp.com/api

Within this address, you'll find APIs (collections of related endpoints) covering the broad functional areas within the Blackbaud ON API.

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 Blackbaud ON API is based on REST principles, where resources are accessed via standard requests to an API endpoint.

Scheme

For security, the Blackbaud ON API communicates exclusively over HTTPS.

Subscription

In order to call the Blackbaud ON API, your school must have the SDK installed. Talk to your Account Manager if you do not have the SDK and would like to inquire about getting it.

Note:  Currently, ON API access is limited to Blackbaud Partners and customers. If you are interested in using ON API to build an integration for multiple customers, we encourage you to become a partner.

Authentication

Learn about the login/logout methods for our REST API.

Note: Blackbaud strongly recommends that schools create new user(s) for each unique integration using the API including Ecosystem partners.


GET /authentication/login

Login and get a token which lasts 20 minutes before expiring after no use.

Request parameters

username Property is required string

The username of the person logging in

password Property is required

The password of the person logging in

Example:

https://[school].myschoolapp.com/api/authentication/login/?username=XXXX&password=XXXX&format=json

Replace [school].myschoolapp.com with your school's URL.

GET /authentication/logout

Request parameters

t Property is required

The authentication token to logout

Example:

https://[school].myschoolapp.com/api/authentication/logout/?t=ceaa9061-59e8-4e32-8162-9f4c66721c40&format=json 

Replace [school].myschoolapp.com with your school's URL.


Properties


NameDescriptionType
TokenAuthentication token valid for the session.guid
UserIdUserId of the authenticated user.int

Samples

Sample XML

<LoginContext xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <Token>e459a9cd-8faf-46de-80d2-7f9e1e20c2c9</Token>
   <UserId>2795080</UserId>
</LoginContext>

Sample JSON

{
  "Token": "e459a9cd-8faf-46de-80d2-7f9e1e20c2c9",
  "UserId": 2795080
}



HTTP verbs

The ON 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

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 Blackbaud ON 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.

Rate limits

/authentication/login/

The rate limit for authentication requests is 10 requests per second.

/list/{id}

Users can call the list API endpoint once every 2 seconds. Too many requests will result in a 503 error.

Response status codes

The Blackbaud ON 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.

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.
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.
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.
418 I'm a Teapot "This site is protected by an enhanced security system to ensure a safe browsing experience. While rare, occasionally this system can block legitimate traffic. You are seeing this page because an action you took violated a Security Rule." This generally happens when 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. It can also mean that a request had some characters that the Web Application Firewall (K-12 Shield) blocked as potentially harmful.
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.

Response Message

A container which holds a single string that will be returned through the API.

Formats

XML (Extensible Markup Language)

A set of rules for encoding documents in machine-reabable form.

JSON (Javascript Object Notation)

A lightweight text-based open standard designed for human-readable data exchange.

Sample JSON

{ "Message": "Never laugh at live dragons." }

Security

The Blackbaud ON API is protected by several industry recommended best practices. This includes:

  • A WAF ( Web Application Firewall ) to inspect all traffic to the API looking for SQL injection, Cross-site scripting (XSS), and more.

  • The API is rate limited to protect itself from runaway threads, endless loops, and request floods that can degrade performance.

  • The API only supports secure connections over TLS, so all data to and from the API is encrypted.

  • All third party vendors using the API only have access to a whitelisted set of API routes for that vendor. This prevents access to data that is not approved for that vendor.