Skip to content

API Documentation for the betterplace platform


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



15 Commits

Repository files navigation

The API Version 4

This is the latest API for It's a REST-style API that returns JSON for serialization. It incorporates some ideas from hypermedia APIs such as the link structure.

⚠️ This api is slowly getting deprecated! ⚠️

This means:

  • we will only fix bugs and provide support for registered clients who also use our client API.
  • no new features will be added to it
  • we do not take any responsibility if things you build based on it suddenly break
  • there is no official EOL date and due to it's public and unauthenticated nature we might not have the possibility to inform you if we decide on one

Table of content

General information

  1. General information ↓ below
  2. Changelog
  3. Request Parameter Format ↓ below
  4. Addressing the locale of a resource ↓ below
  5. Pagination ↓ below
  6. HTML Sanitization of string attributes ↓ below
  7. Picture formats ↓ below
  8. HTTP Status Codes ↓ below
  9. Error Messages ↓ below
  10. Known issues ↓ below
  11. API Client Libraries ↓ below
  12. Code examples ↓ below
  13. Example apps ↓ below

Public API

  1. Projects
    1. Projects List and Search
    2. Project Details
    3. Project Needs List
    4. Project Need Details
    5. Project Blog Posts List
    6. Project Blog Post Details
    7. Project Categories List
    8. Project Opinions List
    9. Project Pictures List
    10. Project Picture Details
  2. Fundraising Events
    1. Fundraising Events List and Search
    2. Fundraising Events Details
    3. Fundraising Event Opinions List
    4. Fundraising Event Featured Projects List
    5. Fundraising Event Forwarding List
  3. Organisations
    1. Organisations List
    2. Organisation Details
  4. MatchingFunds
    1. MatchingFunds List
    2. MatchingFund Details
  5. Illustrations
    1. Illustrations List

Client API

  1. General Information
    1. General Information ↓ below
    2. Client Projects ↓ below
    3. Client Authentication ↓ below
    4. Client Details
    5. Client Project Statistics
    6. Client Fundraising Event Statistics
  2. Donations
    1. Client Donation Pledge Creation 🔒
    2. Client Donation Pledge Status 🔒
    3. Client Forwarding Request Creation 🔒
    4. Client Forwarding Request Status 🔒
    5. Client Donations List
    6. Client Pool Details 🔒
  3. Contact Data
    1. User Contact Data Details 🔒
  4. Projects
    1. Client Projects List and Search –  See client section and "Client Projects"
    2. Client Project Details –  See client section and "Client Projects"
    3. Client Blog Posts List – See client section
    4. Client Mailing Subscribtions 🔒
  5. Tags
    1. Client Tags List
    2. Client-Tag Projects List
    3. Client-Project Tags List

Organisation API

  1. ThirdPartyApp custom donation form for organisations

General information

  • The API is https only, all non-https requests will be redirected accordingly
  • The response format is JSON
  • We support Cross-origin resource sharing (CORS), so no proxy or JSONP is required
  • Authentication: Most API calls are public. Some client API features require authentication. Learn more
  • The data of betterplace Users is not part of the API at this moment.

Request parameter format

The order and facets request parameters accept multiple key-value pairs. We use the same convention as the Google Static Maps API V2.

Example: foo:bar|lorem:ipsum

This way you may specify a primary and secondary sort order such as order=rank:DESC|created_at:DESC, which will cause higher ranked objects to come first and more recently created objects to come first if they have equal rank.

  • Split key and value by a colon :
  • Split multiple key-value pairs by a pipe | (%7C)
  • URL-encode all params, so the pipe becomes %7C
  • Note that for readability reasons we don't URL-encode the params in this documentation

Addressing the locale of a resource

  • Some resources offer translated content. To access the translated content you need to set the lang-prefix in the API URL. api_v4/de/projects/… returns the German translations while api_v4/en/projects/… return the English ones. Non-translated content will fall back to the original content language. We currently support content with German and English translations.
  • The same pattern applies to creating resources for a specific language.


All list requests can be paginated with the following parameters.

Parameter Description Default
page Used to paginate through the list 1
per_page The number of entries per page 20

The per_page parameter is capped at 200. Any higher value for per_page grants at most 200 results.

The following attributes are returned in all list view responses:

Attribute Description Example
total_entries Count of all entries 23
offset The number of entries that are skipped before the current listing begins, = max(page - 1, 0) * per_page 0
total_pages Count of all pages, based on per_page 42
current_page What page we are on 1
per_page Number of entries per page 20


Every string attribute returned in a JSON document is sanitized HTML. By default only a, b, br, em, i, li, ol, p, strong, ul tags are allowed. If an attribute allows for a different set of tags it is specified in the documentation of this field under the "Response Attributes" headline. We might adapt the allowed this set of tags at any time without further notice, e.g. to avert upcoming security problems.

Picture formats

Please note that all over the API only the original image version will always be available. There are additional image versions for various entities, e.g. fill_960x500 for projects. You can use these versions, but they might change in the future!

HTTP Status Codes

The following HTTP result codes can be returned:

Error Messages

If an error occurs, a JSON response message is returned with a name and reason (optional). Clients that use the staging environment will also see a backtrace and message property.


  "name": "GeneralError",
  "status": "not_found",
  "status_code": 404,
  "reason": "Record Not Found",
  "backtrace": [
    "/path/to/file:23:in 'method'",
    "/path/to/file:42:in 'method2'"
  "message": "Couldn't find Project with id=666",

If errors occur during the creation process of a resource, the answer will contain helpful information about how to resolve the issue. Please note that this information is not meant to be used in your application directly but only for your development process. We might change the specs for the error response at any time without further notice.

Example with validation errors:

  "name": "GeneralError",
  "status": "unprocessable_entity",
  "status_code": 422,
  "reason": "Cannot Process Submitted Data",
  "backtrace": [
    "/path/to/file:23:in 'method'",
    "/path/to/file:42:in 'method2'"
  "message": "First name Dies ist ein Pflichtfeld",
  "errors": { "first_name": [ "Dies ist ein Pflichtfeld." ] },

Known issues

Please contact for more information

  • Documentation: Not all resources have a documentation URL as part of the JSON response
  • Documentation: The response table does not show the root documentation for response elements with sub-elements (for example is documented but carrier is not)

API Client Libraries

While we currently do not offer any official client API libraries, Duilio Ruggiero implemented the prototypical ruby client bettery.

We would love to hear from you if you plan to use/extend bettery or implement your own client and publish the code.

Code examples

Example apps

Client API

This API provides special features for companies and organisations as part of the services offered by our betterplace solutions. This client access requires a special contract. Please contact us with your questions.

Client Projects

Clients projects are projects on that are associated with an api client as part of the services that provides for companies. This way clients can control what projects are visible on their external platform.

Some URLs have a special scope for clients. Examples:

  • /clients/example_client/projects will only show projects of the client "example_client"
  • /clients/example_client/tags/rainforest/projects will only show projects of the client "example_client" that are tagged with "rainforest".

If you request data for a project that is not part of the client projects, the API will return an HTTP error code 404.

Client Authentication

Some features of the client API require your authentication.

  • Please use your API Credentials to authenticate with HTTP Basic Authentication username and password.
  • Please use the special scope for clients that is described above.

Username, password and client scope are provided as part of a contract with our betterplace solutions.

Usage example

The local German newspaper "Trierischer Volksfreund" has its own donation portal at "Meine Hilfe zählt". All data is pulled from this API. They also use the whitelabel donation form, which is another service provides for clients.

API V1, V2, V3 has three deprecated APIs. For more information contact


Learn more about betterplace at

License of this documentation

See the license file.

Shareable URL

Share these docs with your friends and family: