Introduction

The FundraisingBox REST API is implemented as JSON over HTTPS.
Every resource, like donation, person, or project, has their own URL and are manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles as much as we can.

You can explore the view part of the API (everything that’s fetched with GET) through a regular browser. Pretty much any URL in the FundraisingBox can be viewed in its JSON form by adding the .json extension. So /persons/4 becomes /persons/4.json if you want to see the JSON version.

🚧

API package required

Please note that a booked API package is required.

Base URL and versioning

Please use https://api.fundraisingbox.com/v1 as base URL followed by a specific endpoint.

At the moment there is only one API version (v1).

Authentication

When you’re using the API, it’s always through an existing user in your FundraisingBox. There’s no special API user. Authenticating is done with an authentication token. Please contact our support team to retrieve your token.

When using the authentication token, you don’t need a separate password. But since FundraisingBox uses HTTP Basic Authentication, and lots of implementations assume that you want to have a password, it’s often easier just to pass in a dummy password, like "X".

Example using the authentication token and a dummy password through curl:

curl -u 605b32dd:X https://api.fundraisingbox.com/v1/persons/1.json

Remember that anyone who has your authentication token can see and change everything you have access to. So you want to guard that as well as you guard your username and password. If you come to fear that it has been compromised, you can regenerate it at any time. Just open a ticket.

Reading through the API

The FundraisingBox API has two category of actions for reading: show and list. Show returns a single record whereas list returns a collection. There’s usually just a single show action for each resource, but many lists. All these actions are done through GET, which also means that they’re all easily explorable through a browser as described above.

A few examples of reading with curl:

curl -u 605b32dd:X https://api.fundraisingbox.com/v1/persons/5.json

curl -u 605b32dd:X https://api.fundraisingbox.com/v1/donations/5.json

If the read is successful, you’ll get an JSON response back along with the status code „200 OK“.

📘

Filter

You can narrow the search to get better results. Filtering is done by adding parameters like amount=50&fb_project_id=7 to the URL. Please find further information about the available filters at relevant documentation for each endpoint.

Pagination

Every endpoint has a limitation of at most 100 datasets in the returned result set. You can use a URL parameter called page={page_number} to fetch further results.

If you request a list view via GET https://api.fundraisingbox.com/v1/persons.json the result looks like this:

{
    "hasMore":true,
    "data":[
        ...
    ]
}

The hasMore information indicates whether or not there are more pages. Just request further objects via GET https://secure.fundraisingbox.com/v1/persons.json?page=2

Writing through the API

If a user has the access rights for writing datasets can be manipulated through the API as well. While GET requests are used for reading writing is implemented with the following HTTP methods:

Dealing with failure

If a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like:

HTTP/1.1 404 The record could not be found
Date: Thu, 16 Mar 2016 17:41:40 GMT
...

Note that, in general, if a request causes a new record to be created (like a new message, or to-do item, etc.), the response will use the „201 Created“ status. Any other successful operation (like a successful query, delete, or update) will use a 200 status code.

🚧

SSL Note

Always use https://api.fundraisingbox.com! If you perform a request on http you will get a redirect answer in return.

Please find further information at the error codes section

Conventions in the API documentation

In the documentation that follows, the following notation is used:

{text}: Indicates text that should be replaced by your own data

...: Indicates content from the response has been elided for brevity in documentation. See the list of data responses at the end of the page for a full description of the format of that response type.

These notations are used to describe datatypes: