Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

API Documentation for the betterplace platform (BETA)

branch: master

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 like the link-strukture.

Please provide feedback: Please don't hesitate to provide any feedback about the API and this documentation at

Mailing list for service announcements: Please send an email to to subscribe to the api-v4-mailing list to receive service announcements about updates and scheduled downtimes.

Table of content

Public API

Client API

This part of the API can only be used in agreement with Please contact someone at betterplace solutions for more information.

(⁂1) Client projects: Clients projects are projects on that are associated with a client-user. This way clients can control what projects are visible on their plattform.

Request-URLs: Clients have to prepend some requests with their client-id. For projects that would be /clients/PERMALINK/projects.json and /clients/PERMALINK/projects/ID.json. More information can be found in the description of each request.

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

Usage example: The local german newspaper "Trierischer Volksfreund" has it's own donation portal at "Meine Hilfe zählt". All data are pulled from this api. In addition they use the betterplac.rog whitelabel donation form, which is another service provides for clients.

Client Authentication

In order to use some special features of the betterplace API, you need to authenticate yourself with an API-Token. These tokens are provided by betterplace, please contact betterplace solutions if you are interested.

To authenticate with a token you'll need to pass it as an additional http header Api-Token or with an additional http parameter api_token.

General information

  • The API is https only, all non-https requests will be redirected accordingly
  • The response format is json, the request format extention .json
  • The response language is defined by the URL-language-prefix (/en/, /de/ (default))
  • We support Cross-origin resource sharing (CORS), so no proxy or JSONP is required
  • No Authentication: All api calls are public at the moment but there will be feature that require authentication in the future.

Request parameter format

The order and facets request parameters accept multiple key-value-parameter. 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 secondaray sort order: order=rank:ASC|created_at:DESC

  • Split key and value by a colon :
  • Split multiple key-value-parameter 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

List parameters and attributes

The following request parameters can be set for all list views.

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

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

HTTP Result Codes and Error Messages

Error Messages

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


  "name": "ActiveRecord::RecordNotFound",
  "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"

HTTP Result Codes

The following HTTP result codes can be returned:

  • HTTP Code 200 if all is good and 304 if this good thing has not been modified (based on ETag).

  • HTTP Code 404 is returned if a requested resource could not be found.

  • HTTP Code 400 is returned if a requested resource could not be created or updated, if the submitted data was invalid.

  • HTTP Code 500 is returned if a software error on the server was encountered.

  • HTTP Code 403 is returned if a resource requires client authentication but no client was authenticated.


  • 2014-03-04: Remove all deprecated picture links from responses.
  • 2014-01-26: Remove the beta-flag; add matching-fund api; add code and usage examples; minor improvements
  • 2013-06-20: Add client.pool_balance_in_cents property, see doc for details
  • 2013-06-14: Add platform-link to blog_posts-details
  • 2013-05-15: Opinions have a link to the project now. All API-link are "" now (not www. anymore). Opinions have have a facets=has_message-Feature now.
  • 2013-04-19: Change the naming of api-docu-files to follow rails-pluralization-convention.
  • 2013-04-19: Added 'client project-tag list' (a list of all project-tags for a client) and 'client project-tag projects list' (a list of all projects for a client-project-tag).
  • 2013-04-18: Fixed project opinions. Add client opinions-feature. Note that many of the opinions-facets changed! Please re-read this part of the documentation.
  • 2013-04-17: Add project pictures API. Please note the DEPRICATION warning for the project- and volunteering-profilepicture (sizes large, profile and thumb are deprecated and therefore renamed.)
  • 2012-04-15: Add "Client Project-Tag Project List".
  • 2012-03-03: Add picture size 'large' and 'original' to image list for projects. Please note that the images-part of the API ist still beta and might change slightly in the future.
  • 2012-03-28: The project-list now returns the full result-set for each project. The minimal result set is gone for now but will be added later. The default-number of results changed to 20 for all lists.
  • 2012-05~15: Add known issues, improve documentation, remove opinion.with_donation, add opinion.donated_amount_in_cents, project.description returns html now
  • 2012-03-13: Update TOC, fix opinions-details and -list response, fix empty documentation (@tordans)
  • 2012-03-12: Several updates to readme, updates to descriptions for clients, updated opinions-docu, added know-issues and changelog sections (@tordans)
  • 2012-03-11: Initial version (@betterplace)

Known issues

Please contact for more information

  1. Documentation: Not all resources have a documentation-url as part of the json
  2. Documentation: The response-table does not show the root-documentation for response-elements with sub-elements (for example is documented but carrier is not)
  3. Blogposts: There is no way yet to filter BlogPosts from PayoutBlogPost

Code examples

Example apps

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.

Something went wrong with that request. Please try again.