├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── api_v4_readme.md ├── images └── betterplace.svg └── sections ├── Searching.md ├── blog_post_details.md ├── blog_posts_list.md ├── categories_list.md ├── client_details.md ├── client_direct_deposit_create.md ├── client_donation_details.md ├── client_donation_pledge_status.md ├── client_donation_pledges_creation.md ├── client_donations_list.md ├── client_forwarding_request_details.md ├── client_forwarding_requests_list.md ├── client_fundraising_event_statistics.md ├── client_mailing_subscriptions.md ├── client_newsletter_opt_ins.md ├── client_project_statistics.md ├── client_project_tags_list.md ├── client_tag_projects_list.md ├── client_tags_list.md ├── contact_data_details.md ├── fundraising_event_details.md ├── fundraising_event_forwardings_list.md ├── fundraising_events_featured_projects_list.md ├── fundraising_events_list.md ├── matching_fund_details.md ├── matching_funds_list.md ├── need_details.md ├── needs_list.md ├── opinions_list.md ├── organisation_details.md ├── organisations_list.md ├── pool_details.md ├── project_details.md ├── project_picture_details.md ├── project_pictures_list.md └── projects_list.md /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | All notable changes to the betterplace.org API v4 will be documented in this file. 3 | 4 | ## 2022-10-24 5 | 6 | - Deprecate `comments_count` on [project details](sections/project_details.md). (The comments feature had already been removed in 2021.) 7 | 8 | ## 2022-06-09 9 | 10 | ### Removed 11 | - Volunteering endpoint 12 | - Clients Volunteering endpoint 13 | 14 | ## 2021-06-08 15 | 16 | ### Changed 17 | 18 | - Deprecate `donor_count` on [project details](sections/project_details.md) and [fundraising events details](section/fundraising_event_details.md). We will remove this value after 2021-12-31. Please use `donations_count` instead. 19 | - Deprecate `external_donated_amount_in_cents` on [client project statistics](sections/client_project_statistics.md). We will remove this value in the future. 20 | 21 | ## 2020-12-10 22 | ### Changed 23 | - Only published [blog posts](sections/blog_posts_list.md) will be handed out by the API from now on. 24 | 25 | ### Added 26 | - Added `published_at` to [Blog posts endpoint](sections/blog_posts_list.md). 27 | - Added `activate_donations_at` DateTime to [Fundraising events details](section/fundraising_event_details.md) and updated the `donations_prohibited` documentation accordingly. 28 | 29 | ## 2020-04-30 30 | ### Added 31 | - Added `donor` and `message` to [client donations](sections/client_donations_list.md). 32 | 33 | ## 2020-03-09 34 | ### Changed 35 | - Project `carrier` can be NULL if none was selected. Mostly happens for legacy projects. [project details](sections/project_details.md) 36 | - `carrier` now contains its ID as a separate field 37 | 38 | ## 2020-01-27 39 | ### Removed 40 | - Donor contact data endpoint 41 | - Listing of illustrations 42 | 43 | ## 2019-02-25 44 | ### Changed 45 | - Changed behavior of `validate_address` of [donation pledges](sections/client_donation_pledges.md): `first_name`, `last_name` and `email` won't be validated if set to `false` 46 | 47 | ## 2019-01-28 48 | ### Added 49 | - Added `donation_count` to [fundraising events details](sections/fundraising_events_details.md) 50 | - Added `new_message` link to [fundraising events details](sections/fundraising_events_details.md) 51 | - [Blog posts endpoint](sections/blog_posts_list.md) is now available for fundraising events as well. 52 | - Extended [fundraising event forwarding list](sections/fundraising_event_forwardings_list.md), eg. with project name and platform url 53 | 54 | 55 | ## 2018-06-01 56 | ### Fixed 57 | - Fixed ordering of opinions for projects and fundraising event 58 | - Fixed `has_message` facet filter on opinions 59 | 60 | ## 2017-08-15 61 | ### Added 62 | - Added support for `tracking_via` to [donation pledges](sections/client_donation_pledges_list.md) and [forwarding requests](sections/client_forwarding_requests_list.md). 63 | 64 | 65 | ## 2017-07-20 66 | ### Added 67 | - Added `summary` to [project details](sections/project_details.md). 68 | 69 | 70 | ## 2017-06-16 71 | ### Added 72 | - Added `donations_count` integer to [project details](sections/project_details.md). 73 | - Added `comments_count` integer to [project details](sections/project_details.md). 74 | 75 | ### Removed 76 | - Removed [endpoint](sections/opinions_list.md) for clients 77 | 78 | ### Changed 79 | - Deprecated `positive_opinions_count` and `negative_opinions_count` on [project](sections/project_details.md) as well as `positive_or_negative` on [opinion](sections/opinion_list.md) 80 | 81 | 82 | ## 2017-03-03 83 | ### Removed 84 | - Removed [Fundraising Challenge] endpoint 85 | 86 | 87 | ## 2016-12-05 88 | ### Added 89 | - Added [endpoint](sections/client_donation_pledge_details.md) for [donation pledges](sections/client_donation_pledges_list.md). 90 | - Added [endpoint](sections/client_forwarding_request_details.md) for [forwarding requests](sections/client_forwarding_requests_list.md). 91 | 92 | 93 | ## 2016-12-01 94 | ### Removed 95 | - [Opinion Details] endpoint removed 96 | 97 | 98 | ## 2016-06-28 99 | ### Changed 100 | - [Opinion Lists](sections/opinions_list.md) now come with the same default order as opinions on betterplace.org - newest first. 101 | 102 | 103 | ## 2016-04-18 104 | ### Added 105 | - Added client API endpoint to submit volunteering inquiries to. 106 | See [here](sections/volunteering_inquiries.md) 107 | 108 | 109 | ## 2016-04-12 110 | ### Added 111 | - [Volunteering List](sections/volunteering_list.md) can now be sorted by the 112 | `content_updated_at` order parameter. 113 | 114 | 115 | ## 2016-04-11 116 | ### Changed 117 | - [Organisation Details](sections/organisation_details.md): The `description` now contains `br` tags instead of newlines 118 | - [Volunteering Details](sections/volunteering_details.md): The `description` now contains `br` tags instead of newlines 119 | 120 | 121 | ## 2016-03-15 122 | ### Changed 123 | - [donation pledges](sections/client_donation_pledges.md): lowered the minimum value for `amount_in_cents` to 1 124 | 125 | 126 | ## 2016-02-16 127 | ### Changed 128 | - [pagination](README.md#pagination): introduced a limit for the `per_page` parameter 129 | 130 | 131 | ## 2016-02-12 132 | ### Removed some deprecated attributes 133 | - Removed `donated_amount_in_cents` from [client endpoint](sections/client_details.md) 134 | - Removed `pool_balance_in_cents` from [client endpoint](sections/client_details.md) 135 | - Removed `open_amount_in_cents` from [client endpoint](sections/client_details.md) 136 | - Removed `requested_amount_in_cents` from [client endpoint](sections/client_details.md) 137 | - Removed `projects_count` from [client endpoint](sections/client_details.md) 138 | - Removed `client_donated_amount_in_cents` from [client endpoint](sections/client_details.md) 139 | - Removed `client_matched_amount_in_cents` from [client endpoint](sections/client_details.md) 140 | - Removed `client_donations_count` from [client endpoint](sections/client_details.md) 141 | 142 | 143 | ## 2016-01-12 144 | ### Removed 145 | - Removed `open_amount_in_cents` from [client statistics](sections/client_project_statistics.md) 146 | - Removed `pool_balance_in_cents` from [client statistics](sections/client_project_statistics.md) 147 | - Removed `client_matched_amount_in_cents` from [client statistics](sections/client_project_statistics.md) 148 | 149 | ### Changed 150 | - `donated_amount_in_cents` does no longer include external donations [client statistics](sections/client_project_statistics.md) 151 | - `client_donated_amount_in_cents` now includes matching fund forwardings [client statistics](sections/client_project_statistics.md) 152 | - `client_donated_amount_in_cents` doesn't include pool donations any more [client statistics](sections/client_project_statistics.md) 153 | - [donation pledges](sections/client_donation_pledges.md): introduced `validate_address` option 154 | 155 | ### Added 156 | - [**Client** Details](sections/client_details.md): client specific endpoint for volunteering offers 157 | 158 | 159 | ## 2015-10-09 160 | ### Added 161 | - Improved documentation for [donation pledges](sections/client_donation_pledges.md) 162 | 163 | 164 | ## 2015-09-15 165 | ### Added 166 | - Added facet filter ```closed:true/false``` [projects list](sections/projects_list.md). 167 | 168 | 169 | ## 2015-08-28 170 | ### Added 171 | - Added ```closed_at``` datetime to 172 | [project details](sections/project_details.md). 173 | - Extended documentation for created_at and completed_at in 174 | [project details](sections/project_details.md). 175 | 176 | 177 | ## 2015-07-30 178 | ### Fixed 179 | - Documentation wording for donor opinions ```facets=has_donation:true/false``` and ```donated_amount_in_cents```. 180 | The documentation is more detailed now and also includes two know issues where donor opinions do not behave 181 | as expected. 182 | 183 | 184 | ## 2015-06-17 185 | ### Deprecated 186 | - The url params for the ThirdPartyApp custom donation form changed: 187 | - ```donation_presenter[some_value]=123``` is deprecated now. Please update your app until 12/2015. 188 | - ```some_value=123``` is the new way [as described in the documentation](donation_form/third_party_app_donation_form.md). 189 | 190 | 191 | ## 2015-04-28 192 | ### Added 193 | - Added API endpoint for clients to query donor data if permission was granted. See details at 194 | [**Client** Donor Contact Data](sections/donor_contact_data_details.md) 195 | 196 | 197 | ## 2015-04-07 198 | ### Added 199 | 200 | - Added two API endpoints for client statistics. 201 | 0. [**Client** Project Statistics](sections/client_project_statistics.md) 202 | 0. [**Client** Fundraising Event Statistics](sections/client_fundraising_event_statistics.md) 203 | 204 | ## Deprecated 205 | - [**Client** Details](sections/client_details.md): All statistic values. This end point will be removed after 31.5.2015 206 | 207 | 208 | ## 2015-03-05 209 | ### Added 210 | - Added API endpoints for fundraising events and linked to them from all 211 | relevant resources. This includes related features for clients as well. 212 | See [here](sections/fundraising_events_list.md) and 213 | [here](sections/fundraising_event_details.md). 214 | 215 | ### Deprecated 216 | - [Fundraising Events Details](sections/fundraising_event_details.md#response-links) 217 | - **profile_picture:** `fill_618x322`, `fill_270x141` 218 | - [Fundraising Events List](sections/fundraising_events_list.md#response-links) 219 | - **profile_picture:** `fill_618x322`, `fill_270x141` 220 | - [Matching Fund Projects List](sections/matching_fund_projects_list.md#response-links) 221 | - **profile_picture:** `fill_618x322`, `fill_270x141` 222 | - [Project Details](sections/project_details.md#response-links) 223 | - **profile_picture:** `fill_618x322`, `fill_270x141` 224 | - [Projects List](sections/projects_list.md#response-links) 225 | - **profile_picture:** `fill_618x322`, `fill_270x141` 226 | - [Volunteering Details](sections/volunteering_details.md#response-links) 227 | - **profile_picture:** `fill_618x322`, `fill_270x141` 228 | - **image:** `fill_618x322`, `fill_270x141`, `original`, `thumb`, `medium`, `regular` 229 | - [Volunteering List](sections/volunteering_list.md#response-links) 230 | - **profile_picture:** `fill_618x322`, `fill_270x141` 231 | - **image:** `fill_618x322`, `fill_270x141`, `original`, `thumb`, `medium`, `regular` 232 | 233 | 234 | ## 2015-02-16 235 | ### Added 236 | - Added client API endpoint for submit donation pledges to. 237 | See [here](sections/client_donation_pledges.md) 238 | - Added client API endpoint to subscribe to project newsletters. 239 | See [here](sections/client_mailing_subscriptions.md). 240 | 241 | ### Deprecated 242 | - Authentication via `api_token` parameter and `Api-Token` header is 243 | deprecated in favor of using basic authentication. 244 | 245 | ### Fixed 246 | - Reworked order and hierarchy in readme. 247 | 248 | 249 | ## 2015-01-15 250 | ### Added 251 | - Added the `around` parameter for project and volunteering 252 | listings, that sorts by distance to its value. 253 | 254 | 255 | ## 2014-11-18 256 | 257 | ### Added 258 | - Fallback flag for profile pictures to indicate whether the given picture is a 259 | default picture or was uploaded by the user 260 | 261 | 262 | ## 2014-09-05 263 | 264 | ### Added 265 | - Clarify the order behaviour for fundraising challenge results. 266 | 267 | 268 | ## 2014-08-14 269 | 270 | ### Added 271 | - This CHANGELOG, following the ideas of http://keepachangelog.com/ 272 | - Refactor the previous changelog to follow this convention. 273 | - Update todo-note in table of content 274 | - Add two more websites to "Example Integrations" for ThidPartyApp Donation 275 | Form 276 | 277 | ### Removed 278 | - Previous Changelog in README 279 | 280 | 281 | ## 2014-08-11 282 | 283 | ### Added 284 | - Add Fundraising Challenge to API and Documentation 285 | 286 | 287 | ## 2014-01 - 2014-04 288 | This is the aggrgated changelog for all changes for this time interval. 289 | 290 | ### Added 291 | * 2013-06-20: Add `client.pool_balance_in_cents` property, see doc for details 292 | * 2013-06-14: Add platform-link to `blog_posts-details` 293 | * 2013-05-15: Opinions have a link to the project now. All API-link are "api.betterplace.org" now (not www. anymore). Opinions have have a facets=has_message-Feature now. 294 | * 2013-04-19: Change the naming of api-docu-files to follow rails-pluralization-convention. 295 | * 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). 296 | * 2013-04-17: Add project pictures API. Please note the DEPRECATION warning for the project- and volunteering-profilepicture (sizes large, profile and thumb are deprecated and therefore renamed.) 297 | 298 | ### Removed 299 | * 2014-03-04: Remove all deprecated picture links from responses. 300 | * 2014-01-26: Remove the beta-flag; add matching-fund api; add code and usage examples; minor improvements 301 | 302 | ### Fixed 303 | * 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. 304 | 305 | 306 | ## 2014-01 - 2014-04 307 | This is the aggrgated changelog for all changes for this time interval. 308 | 309 | ### Added 310 | * 2012-04-15: Add "Client Project-Tag Project List". 311 | * 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. 312 | * 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. 313 | * 2012-05~15: Add known issues, improve documentation, add `opinion.donated_amount_in_cents`, project.description returns html now 314 | * 2012-03-13: Update TOC, fix opinions-details and -list response, fix empty documentation (@tordans) 315 | * 2012-03-12: Several updates to readme, updates to descriptions for clients, updated opinions-docu, added know-issues and changelog sections (@tordans) 316 | 317 | ### Removed 318 | * 2012-05~15: Removed `opinion.with_donation` 319 | 320 | 321 | ## 2012-03-11 322 | 323 | ### Added 324 | - Initial version (@betterplace) 325 | 326 | 327 | 328 | --- 329 | 330 | # Template 331 | 332 | ## 201x-0x-xx 333 | 334 | ### Added 335 | - Nothing. 336 | 337 | ### Deprecated 338 | - Nothing. 339 | 340 | ### Removed 341 | - Nothing. 342 | 343 | ### Fixed 344 | - Nothing. 345 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright 2012 gut.org gAG 2 | 3 | All rights reserved. This is our API documentation, and not meant for redistribution. 4 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | betterplace.org 2 | 3 | # This documents covers betterplace APIs and api-like products 4 | 5 | Betterplace offers 4 distinct types of apis and api like products. 6 | 7 | 8 | ## [API V4](api_v4_readme.md) 9 | This is the latest API for betterplace.org. It's a REST-style API that returns JSON. 10 | It is split into a public API which is free to use for everybody and a client API which requires a contract with betterplace but provides a range of additional features. 11 | For more information click the following links 12 | - [Public API](api_v4_readme.md#public-api) 13 | This Api is fully public and unauthenticated. While everybody is free to use it to build private projects based on it we reserve the rights to throttle as we see fit in case of aggressive polling. It only includes public data which would also be found on public pages of the betterplace.org site. 14 | - [Client API](api_v4_readme.md#client-api) 15 | This API provides special features for companies and organisations as part of the services offered by our [betterplace solutions](http://www.betterplace-solutions.de). This client access requires a special contract. 16 | 17 | ## Iframe donation form 18 | An Iframe donation form that can be embedded on your website to collect to donations through betterplace.org. this is only available to project or organisation managers of charities which are registered in Germany. 19 | After your registration and creation of a project on betterplace.org you can generate a code snippet which you can embed on your website. 20 | You can find more information by clicking on "Donation form"/"Spendenformular" in the project manage area or by following this link. 21 | 22 | `https://www.betterplace.org/de/manage/projects//iframe_donation_form/new` 23 | 24 | ## Streaming Widgets and Donation Webhooks 25 | You can use our public API to show donation statistics and other details of your fundraising event. But we also have out-of-the box features for livestreams that you can use. 26 | 27 | These products include: 28 | * Customizable streaming widgets to be included in OBS or other broadcasting software 29 | * Highest donation 30 | * Current donation volume 31 | * Last donor comments 32 | * Top Donor 33 | * Donor leader board 34 | * Alerts with gifs and sounds 35 | * Last donation 36 | * and many more... this part of the product is currently in active development 37 | * Voting/Polling functionality to interact with your community 38 | * Webhooks from betterplace.org to your system whenever your fundraising event receives a donation. Which can be used for sellout streams, alerts and similar customized functionality. 39 | 40 | You can find more information and examples of streams like Friendly Fire and März mit Herz on our [dedicated page for streamers](https://www.betterplace.org/c/spenden-sammeln/charity-stream), watch our [livestream widget tutorial video](https://www.youtube.com/watch?v=3-DkrkkPC4o) or reach out to our team at charitystream@betterplace.org for expert support with your charity stream idea. 41 | 42 | ## About betterplace.org 43 | Learn more about betterplace at https://www.betterplace.org/c/about-us/ 44 | 45 | ## License of this documentation 46 | See the [license file](LICENSE). 47 | 48 | ## Shareable URL 49 | Share these docs with your friends and family: 50 | [api-docs.betterplace.org](https://api-docs.betterplace.org) 51 | -------------------------------------------------------------------------------- /api_v4_readme.md: -------------------------------------------------------------------------------- 1 | # The betterplace.org API Version 4 2 | This is the latest API for betterplace.org. It's a REST-style API that returns 3 | JSON for serialization. It incorporates some ideas from [hypermedia APIs](https://www.google.de/search?q=hypermedia+api) 4 | such as the link structure. 5 | It is split into a public, unauthenticated API and a private, authenticated Client-API. The public API is getting deprecated. 6 | 7 | ### Table of Contents 8 | 1. [Public API](#public-api) (⚠️ deprecated ⚠️) 9 | - [Endpoints](#endpoints-public-api) 10 | 2. [Client API](#client-api) 11 | - [Client Authentication](#client-authentication) 12 | - [Client Projects](#client-projects) 13 | - [Endpoints](#endpoints-public-api) 14 | 3. [Technical Details](#technical-details-applying-to-public-api-and-client-api) 15 | - [Request Parameter Format](#request-parameter-format) 16 | - [Addressing the Locale of a Resource](#addressing-the-locale-of-a-resource) 17 | - [Pagination](#pagination) 18 | - [Sanitization](#sanitization) 19 | - [Picture Formats](#picture-formats) 20 | - [HTTP Status Codes](#http-status-codes) 21 | - [Error Messages](#error-messages) 22 | - [Known Issues](#known-issues) 23 | - [API Client Libraries](#api-client-libraries) 24 | - [Changelog](CHANGELOG.md) 25 | - [Code Examples](#code-examples) 26 | 27 | ## Public API 28 | This Api is fully public and unauthenticated. While everybody is free to use it to build private projects based on it we reserve the rights to throttle as we see fit in case of aggressive polling. It only includes public data which would also be found on public pages of the betterplace.org site. 29 | 30 | ### ⚠️ This api is slowly getting deprecated! ⚠️ 31 | This means: 32 | * we will only fix bugs and provide support for registered clients who also use our client API. 33 | * no new features will be added to it 34 | * we do not take any responsibility if things you build based on it suddenly break 35 | * 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 to discontinue providing this api 36 | 37 | ### Endpoints public api 38 | - Projects 39 | - [Projects List and Search](sections/projects_list.md) 40 | - [Project Details](sections/project_details.md) 41 | - [Project Needs List](sections/needs_list.md) 42 | - [Project Need Details](sections/need_details.md) 43 | - [Project Blog Posts List](sections/blog_posts_list.md) 44 | - [Project Blog Post Details](sections/blog_post_details.md) 45 | - [Project Categories List](sections/categories_list.md) 46 | - [Project Opinions List](sections/opinions_list.md) 47 | - [Project Pictures List](sections/project_pictures_list.md) 48 | - [Project Picture Details](sections/project_picture_details.md) 49 | - Fundraising Events 50 | - [Fundraising Events List and Search](sections/fundraising_events_list.md) 51 | - [Fundraising Events Details](sections/fundraising_event_details.md) 52 | - [Fundraising Event Opinions List](sections/opinions_list.md) 53 | - [Fundraising Event Featured Projects List](sections/fundraising_events_featured_projects_list.md) 54 | - [Fundraising Event Forwarding List](sections/fundraising_event_forwardings_list.md) 55 | - Organisations 56 | - [Organisations List](sections/organisations_list.md) 57 | - [Organisation Details](sections/organisation_details.md) 58 | 59 | ## Client API 60 | This API provides special features for companies and organisations as part of the services offered by our [betterplace solutions](http://www.betterplace-solutions.de). 61 | This client access requires a special contract. Please [contact us](http://www.betterplace-solutions.de) with your questions. 62 | 63 | ### Client Authentication 64 | Some features of the betterplace.org client API require your authentication. 65 | * Please use your API Credentials to authenticate with [HTTP Basic Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication#Client_side) username and password. 66 | * Please use the special scope for clients that is described [above](#client-projects). 67 | Username, password and client scope are provided as part of a contract with betterplace.org 68 | 69 | ### Client Projects 70 | Clients projects are projects on betterplace.org that are associated with an api client as part of the services that betterplace.org provides for companies. This way clients can control what projects are visible on their external platform. 71 | 72 | Some URLs have a special scope for clients. Examples: 73 | 74 | * `/clients/example_client/projects` 75 | will only show projects of the client "example_client" 76 | * `/clients/example_client/tags/rainforest/projects` 77 | will only show projects of the client "example_client" that are tagged with "rainforest". 78 | 79 | If you request data for a project that is not part of the client 80 | projects, the API will return an HTTP error code `404`. 81 | 82 | ### Endpoints client API 83 | - Clients 84 | - [Client Details](sections/client_details.md) 85 | - [Client Project Statistics](sections/client_project_statistics.md) 86 | - [Client Fundraising Event Statistics](sections/client_fundraising_event_statistics.md) 87 | - Donations 88 | - [Client Donation Pledge Creation](sections/client_donation_pledges_creation.md) 89 | - [Client Donation Pledge Status](sections/client_donation_pledge_status.md) 90 | - [Client Forwarding Request Creation](sections/client_forwarding_requests_list.md) 91 | - [Client Forwarding Request Status](sections/client_forwarding_request_details.md) 92 | - [Client Donations List](sections/client_donations_list.md) 93 | - [Client Pool Details](sections/pool_details.md) 94 | - Contact Data 95 | - [User Contact Data Details](sections/contact_data_details.md) 96 | - Projects 97 | - [Client Projects List and Search](sections/projects_list.md) 98 | - [Client Project Details](sections/project_details.md) 99 | - [Client Blog Posts List](sections/blog_posts_list.md) 100 | - [Client Mailing Subscriptions](sections/client_mailing_subscriptions.md) 101 | - Tags 102 | - [Client Tags List](sections/client_tags_list.md) 103 | - [Client-Tag Projects List](sections/client_tag_projects_list.md) 104 | - [Client-Project Tags List](sections/client_project_tags_list.md) 105 | 106 | ## Technical details applying to Public API and Client API 107 | * The API is https only, all non-https requests will be redirected accordingly 108 | * The response format is JSON 109 | * We support [Cross-origin resource sharing (CORS)](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing), so no proxy or JSONP is required 110 | 111 | ### Request parameter format 112 | The `order` and `facets` request parameters accept multiple key-value pairs. 113 | We use the same convention as the [Google Static Maps API V2](https://developers.google.com/maps/documentation/staticmaps/#URL_Parameters). 114 | 115 | Example: `foo:bar|lorem:ipsum` 116 | 117 | This way you may specify a primary and secondary sort order such as 118 | `order=rank:DESC|created_at:DESC`, which will cause higher ranked objects to 119 | come first and more recently created objects to come first if they have equal 120 | rank. 121 | 122 | * Split key and value by a colon `:` 123 | * Split multiple key-value pairs by a pipe `|` (`%7C`) 124 | * [URL-encode](http://de.wikipedia.org/wiki/URL-Encoding) all params, so the pipe becomes `%7C` 125 | * Note that for readability reasons we don't URL-encode the params in this documentation 126 | 127 | 128 | ### Addressing the locale of a resource 129 | * Some resources offer translated content. To access the translated content you 130 | need to set the lang-prefix in the API URL. 131 | `api_v4/de/projects/…` returns the German translations while 132 | `api_v4/en/projects/…` return the English ones. Non-translated 133 | content will fall back to the original content language. 134 | We currently support content with German and English translations. 135 | * The same pattern applies to creating resources for a specific language. 136 | 137 | 138 | ### Pagination 139 | All list requests can be paginated with the following parameters. 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 |
ParameterDescriptionDefault
pageUsed to paginate through the list1
per_pageThe number of entries per page20
158 | 159 | The per_page parameter is capped at 200. Any higher value for per_page grants at most 200 results. 160 | 161 | The following attributes are returned in all list view responses: 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 |
AttributeDescriptionExample
total_entriesCount of all entries23
offsetThe number of entries that are skipped before the current listing begins, = max(page - 1, 0) * per_page0
total_pagesCount of all pages, based on per_page42
current_pageWhat page we are on1
per_pageNumber of entries per page20
195 | 196 | 197 | ### Sanitization 198 | Every string attribute returned in a JSON document is sanitized HTML. By 199 | default only ```a, b, br, em, i, li, ol, p, strong, ul``` tags are allowed. 200 | If an attribute allows for a different set of tags it is specified in the 201 | documentation of this field under the "Response Attributes" headline. 202 | We might adapt the allowed this set of tags at any time without further notice, 203 | e.g. to avert upcoming security problems. 204 | 205 | 206 | ### Picture formats 207 | Please note that all over the API only the `original` image version will always 208 | be available. There are additional image versions for various entities, e.g. 209 | fill_960x500 for projects. You can use these versions, but they might change in 210 | the future! 211 | 212 | 213 | ### HTTP Status Codes 214 | The following HTTP result codes can be returned: 215 | 216 | * [HTTP Code `200`](http://httpstatus.es/200) 217 | if all is good and 218 | [HTTP Code `304`](http://httpstatus.es/304) 219 | if this good thing has not been modified (based on ETag). 220 | * [HTTP Code `201`](http://httpstatus.es/201) 221 | if a resource was created successfully. 222 | * [HTTP Code `202`](http://httpstatus.es/202) 223 | if a resource was successfully submitted for delayed processing. 224 | * [HTTP Code `400`](http://httpstatus.es/400) 225 | if a requested resource could not be created or updated, 226 | if the submitted data was invalid. 227 | * [HTTP Code `401`](http://httpstatus.es/401) 228 | if a resource requires [client authentication](#client-authentication) 229 | but the authentication failed. 230 | * [HTTP Code `403`](http://httpstatus.es/403) 231 | if a resource requires [client authentication](#client-authentication) 232 | but no client was authenticated. 233 | * [HTTP Code `404`](http://httpstatus.es/404) 234 | if a requested resource could not be found. 235 | Also used for projects that are not part of a given client scope. 236 | * [HTTP Code `422`](http://httpstatus.es/422) 237 | if the submitted resource could not be accepted due to erroneous parameters. 238 | * [HTTP Code `500`](http://httpstatus.es/500) 239 | if a software error on the server was encountered. 240 | * [HTTP Code `503`](http://httpstatus.es/503) 241 | if the server is unavailable due to high load. 242 | 243 | ### Error Messages 244 | If an error occurs, a JSON response message is returned with a `name` and `reason` (optional). 245 | Clients that use the betterplace.org staging environment will also see a 246 | `backtrace` and `message` property. 247 | 248 | Example: 249 | 250 | ```json 251 | { 252 | "name": "GeneralError", 253 | "status": "not_found", 254 | "status_code": 404, 255 | "reason": "Record Not Found", 256 | "backtrace": [ 257 | "/path/to/file:23:in 'method'", 258 | "/path/to/file:42:in 'method2'" 259 | ], 260 | "message": "Couldn't find Project with id=666", 261 | "links":[] 262 | } 263 | ``` 264 | 265 | If errors occur during the creation process of a resource, the answer will 266 | contain helpful information about how to resolve the issue. Please note 267 | that this information is not meant to be used in your application directly 268 | but only for your development process. We might change the specs for the 269 | error response at any time without further notice. 270 | 271 | Example with validation errors: 272 | 273 | ```json 274 | { 275 | "name": "GeneralError", 276 | "status": "unprocessable_entity", 277 | "status_code": 422, 278 | "reason": "Cannot Process Submitted Data", 279 | "backtrace": [ 280 | "/path/to/file:23:in 'method'", 281 | "/path/to/file:42:in 'method2'" 282 | ], 283 | "message": "First name Dies ist ein Pflichtfeld", 284 | "errors": { "first_name": [ "Dies ist ein Pflichtfeld." ] }, 285 | "links":[] 286 | } 287 | ``` 288 | 289 | ### Known issues 290 | Please contact api@betterplace.org for more information 291 | 292 | * Documentation: Not all resources have a documentation URL as part of the JSON response 293 | * Documentation: The response table does not show the root documentation for response elements with sub-elements (for example carrier.name is documented but carrier is not) 294 | 295 | 296 | ### API Client Libraries 297 | While we currently do not offer any official client API libraries, [Duilio Ruggiero](https://github.com/sinetris) implemented the prototypical ruby client [bettery](https://github.com/sinetris/bettery). 298 | 299 | We would love to hear from you if you plan to use/extend bettery or implement your own client and publish the code. 300 | 301 | 302 | ### Code examples 303 | * [Using the API with PHP](https://gist.github.com/svjv1160/7749784) 304 | * [WordPress Plugin by freifunk](https://github.com/freifunk/www.freifunk.net/tree/master/wp-plugins/betterplace-project-table) which [shows the freifunk projects as a table](http://spenden.freifunk.net) 305 | * _Please send us your code examples to api@betterplace.org_ 306 | -------------------------------------------------------------------------------- /images/betterplace.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /sections/blog_post_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Blog Post Details ⇄ [List](blog_posts_list.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/projects/1114/blog_posts/88972.json 6 | ``` 7 | 8 | The details of a blog post of a betterplace.org project. 9 | The details and list view show the same data. 10 | 11 | **For [betterplace.org clients](../README.md#client-api):** 12 | There is no client-scoped URL. 13 | Please use the API calls that are provided inside the client project _url_ response 14 | to make sure you only request data that is associated with one of your projects. 15 | 16 | 17 | ## URL Parameters 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 35 | 36 | 37 | 38 | 39 | 40 | 45 | 46 |
ParameterExampleRequiredDescription
project_id1114yes 31 | 32 | Project id as an integer number. 33 | 34 |
id88972yes 41 | 42 | Blogpost id as an integer number. 43 | 44 |
47 | 48 | 49 | ## Response Attributes 50 | 51 | 52 | ### Root Attributes 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 70 | 71 | 72 | 73 | 74 | 75 | 80 | 81 | 82 | 83 | 84 | 85 | 90 | 91 | 92 | 93 | 94 | 95 | 100 | 101 | 102 | 103 | 104 | 105 | 112 | 113 | 114 | 115 | 116 | 117 | 122 | 123 | 124 | 125 | 126 | 127 | 132 | 133 | 134 | 135 | 136 | 137 | 145 | 146 | 147 | 152 | 153 | 154 | 159 | 160 |
AttributeTypesExampleDescription
idnumber1 66 | 67 | An integer number ≥ 1 68 | 69 |
created_atstring"1994-11-05T13:15:30Z" 76 | 77 | DateTime (ISO8601 with Timezone) 78 | 79 |
updated_atstring"1994-11-05T13:15:30Z" 86 | 87 | DateTime (ISO8601 with Timezone) 88 | 89 |
langstringen 96 | 97 | Blog posts have only one language at the moment 98 | 99 |
typestringBlogPost 106 | 107 | Blogposts are always created by a user, and this 108 | field always has the value BlogPost. 109 | 110 | 111 |
titlestringThank you from Beijing 118 | 119 | 120 | 121 |
published_atstring"1994-11-05T13:15:30Z" 128 | 129 | DateTime (ISO8601 with Timezone) 130 | 131 |
bodystringI am so happy to hear about the first donation for the Good Gifted Garden. If I told Chun … 138 | 139 | The body may contain html such as links, embedded videos, and picture or 140 | any of the following HTML tags: 141 | ```a, b, br, div, em, i, iframe, img, li, ol, p, strong, ul```. 142 | 143 | 144 |
148 | 149 | ↓author 150 | 151 | null | object 155 | 156 | The user that wrote the blog post. 157 | 158 |
161 | 162 | ### ↑Nested Attributes: author 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 180 | 181 | 182 | 183 | 184 | 185 | 195 | 196 | 197 | 202 | 203 | 204 | 209 | 210 |
AttributeTypesExampleDescription
author.idnumber1 176 | 177 | An integer number ≥ 1 178 | 179 |
author.namenull | string"Till B." 186 | 187 | Display name of a betterplace.org user. 188 | Possible formats: "Till B.", "T. Behnke", "Till Behnke". 189 | 190 | In the case of donation-opinions the name might also be 191 | empty/null for anonymous donations for anonymous donations. 192 | 193 | 194 |
198 | 199 | ↓author.picture 200 | 201 | object//betterplace-assets.betterplace.org ↪/uploads/user/profile_picture ↪/000/000/001 ↪/fill_100x100_original_tb.jpg 205 | 206 | User profile picture or a fallback image 207 | 208 |
211 | 212 | ### ↑Nested Attributes: author.picture 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 230 | 231 |
AttributeTypesExampleDescription
author.picture.fallbackbooleantrue 226 | 227 | Specifies whether a fallback image is given or not 228 | 229 |
232 | 233 | 234 | ## Response Links 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 247 | 254 | 255 | 256 | 261 | 266 | 267 | 268 | 273 | 279 | 280 | 281 | 286 | 295 | 296 | 297 | 302 | 310 | 311 | 312 | 317 | 322 | 323 | 324 | 329 | 334 | 335 |
LinknameDescription
243 | 244 | self 245 | 246 | 248 | 249 | Link to this resource itself 250 | (blog post details) 251 | 252 | 253 |
257 | 258 | platform 259 | 260 | 262 | 263 | Permalink to betterplace.org 264 | 265 |
269 | 270 | documentation 271 | 272 | 274 | 275 | Link to this resource in the documentation 276 | 277 | 278 |
282 | 283 | author.platform 284 | 285 | 287 | 288 | The user's profile on betterplace.org. 289 | To view a user profile you have to be logged in. 290 | This array is empty if the user has no useraccount 291 | with betterplace.org but donated via one of our partner. 292 | 293 | 294 |
298 | 299 | author.contact_data 300 | 301 | 303 | 304 | The user's contact data. Please note that you need to be 305 | authenticated as a client with matching 306 | access rights in order to see this information. 307 | 308 | 309 |
313 | 314 | author.picture.fill_100x100 315 | 316 | 318 | 319 | 100×100 Pixel 320 | 321 |
325 | 326 | author.picture.original 327 | 328 | 330 | 331 | Maximum sized image. This is the original image with default-cropping or user-cropping applied. 332 | 333 |
336 | 337 | ## Response Example 338 | 339 | ```json 340 | { 341 | "id": 88972, 342 | "created_at": "2013-10-30T12:39:27+01:00", 343 | "updated_at": "2013-10-30T12:39:27+01:00", 344 | "lang": "en", 345 | "type": "BlogPost", 346 | "title": "First Climbing Contest Held in Afghanistan", 347 | "published_at": "2013-10-30T12:39:27+01:00", 348 | "body": "


\n

On\r\n Saturday 28th September, Skateistan Kabul's volunteers and staff took \r\npart in the inaugural indoor climbing competition held at the facility, \r\nwith both girls and boys competing (ages 11-22). This was the 1st \r\nclimbing competition that has taken place at Skateistan and the 1st \r\nknown climbing contest held in Afghanistan!

The climbing \r\ncompetition had both female and male categories with contests that \r\nincluded speed climbing and fastest rope coil. The competition was \r\njudged by our amazing volunteer climbing teachers, including the \r\ncompetition organiser Gio Trambaiolo who has been instrumental in \r\nteaching climbing to the Skateistan volunteers. Gio has volunteered as a\r\n climbing teacher nearly each week for well over a year. Skateistan is \r\nextremely lucky to have such a wonderful team of dedicated volunteers, \r\nwho include around a dozen foreigners with certified climbing \r\nbackgrounds.

\n

\" Everyone did very well, it's amazing to\r\n see how the instructors and volunteers have progressed over the past \r\nfew months. \" - Gio, volunteer climbing teacher

\n

Each \r\nweek since June 2012, climbing lessons have been provided \r\nto Skateistan's Youth Leaders, who are Afghan staff and volunteers with \r\nthe project. They have learned climbing techniques, as well as built \r\nup trust and respect for each other through the sport. It is been \r\ninspiring to watch the volunteers develop as climbers and to see the \r\nhigh skill level our Youth Leaders have developed since the program took\r\n shape last year. Through the program, 14 young Afghans (50% girls) have\r\n received certificates to be Beginner Climbing Instructors, and they now\r\n facilitate climbing classes with more than 400 students who attend \r\nSkateistan.

\n

A brief prize ceremony was held the following week to \r\ngive the final results of the competition, as well as some prizes which \r\nwere given to everyone who participated.

We\r\n want to thank all the climbing volunteers who have created a hugely \r\nsuccesful sports program for our staff and students. We wish to thank \r\nGiovanni Trambaiolo, Sheilagh Henry, Kate Hughes, Mindy Visser, Colin R,\r\n Erin Blankenship, Jeffery Dow, Kelsey Noonan, Sarah-Jean \r\nCunningham, and Stephanie Faser. Your constant creativity and innovative\r\n training have made climbing one of the leading activities for the Youth\r\n Leaders at Skateistan. The development of students who attend your \r\nclasses has been a great pleasure to watch, and will benefit hundreds of\r\n children who will continue to be taught by their Afghan peers.


\n


\n
", 349 | "author": null, 350 | "links": [ 351 | { 352 | "rel": "self", 353 | "href": "https://api.betterplace.org/de/api_v4/blog_posts/88972.json" 354 | }, 355 | { 356 | "rel": "platform", 357 | "href": "https://www.betterplace.org/de/projects/1114-unterstuetze-skateistan-sport-bildung-fuer-kinder/news/88972" 358 | }, 359 | { 360 | "rel": "documentation", 361 | "href": "https://github.com/betterplace/betterplace_apidocs/blob/master/sections/blog_post_details.md" 362 | } 363 | ] 364 | } 365 | ``` 366 | 367 | -------------------------------------------------------------------------------- /sections/categories_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Categories List 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/projects/1114/categories.json 6 | ``` 7 | 8 | A list of betterplace.org project categories. 9 | Results are contained in a *data* attribute. 10 | 11 | 12 | ## URL Parameters 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 30 | 31 |
ParameterExampleRequiredDescription
project_id1114yes 26 | 27 | Project id as an integer number. 28 | 29 |
32 | 33 | 34 | ## Response Attributes 35 | 36 | 37 | ### Root Attributes 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 55 | 56 | 57 | 58 | 59 | 60 | 65 | 66 | 67 | 68 | 69 | 70 | 75 | 76 | 77 | 78 | 79 | 80 | 85 | 86 | 87 | 88 | 89 | 90 | 95 | 96 |
AttributeTypesExampleDescription
idnumber1 51 | 52 | An integer number ≥ 1 53 | 54 |
created_atstring"1994-11-05T13:15:30Z" 61 | 62 | DateTime (ISO8601 with Timezone) 63 | 64 |
updated_atstring"1994-11-05T13:15:30Z" 71 | 72 | DateTime (ISO8601 with Timezone) 73 | 74 |
namestringThe category 81 | 82 | Name to be displayed for this category 83 | 84 |
slugstringcategory 91 | 92 | Slug for this category 93 | 94 |
97 | 98 | 99 | ## Response Links 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 112 | 117 | 118 |
LinknameDescription
108 | 109 | platform 110 | 111 | 113 | 114 | Permalink to betterplace.org discover category 115 | 116 |
119 | 120 | ## Response Example 121 | 122 | ```json 123 | { 124 | "total_entries": 3, 125 | "offset": 0, 126 | "total_pages": 1, 127 | "current_page": 1, 128 | "per_page": 3, 129 | "data": [ 130 | { 131 | "id": 3, 132 | "created_at": "2016-12-13T16:18:14+01:00", 133 | "updated_at": "2018-12-03T17:26:13+01:00", 134 | "name": "Bildung", 135 | "slug": "bildung", 136 | "links": [ 137 | { 138 | "rel": "platform", 139 | "href": "https://www.betterplace.org/de/discover/3-bildung" 140 | } 141 | ] 142 | }, 143 | { 144 | "id": 15, 145 | "created_at": "2016-12-13T17:07:22+01:00", 146 | "updated_at": "2018-03-02T12:21:51+01:00", 147 | "name": "Sport", 148 | "slug": "sport", 149 | "links": [ 150 | { 151 | "rel": "platform", 152 | "href": "https://www.betterplace.org/de/discover/15-sport" 153 | } 154 | ] 155 | }, 156 | { 157 | "id": 2, 158 | "created_at": "2016-12-13T16:17:58+01:00", 159 | "updated_at": "2021-11-04T09:09:35+01:00", 160 | "name": "Kinder und Jugend", 161 | "slug": "kinder", 162 | "links": [ 163 | { 164 | "rel": "platform", 165 | "href": "https://www.betterplace.org/de/discover/2-kinder" 166 | } 167 | ] 168 | } 169 | ] 170 | } 171 | ``` 172 | 173 | -------------------------------------------------------------------------------- /sections/client_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Details 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund.json 6 | ``` 7 | 8 | This API endpoint returns links to more specific information about this client. 9 | 10 | ## URL Parameters 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 28 | 29 |
ParameterExampleRequiredDescription
idvolksfreundyes 24 | 25 | The betterplace.org-internal client permalink 26 | 27 |
30 | 31 | 32 | ## Response Attributes 33 | 34 | No response example defined 35 | 36 | 37 | ## Response Links 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 50 | 56 | 57 | 58 | 63 | 69 | 70 | 71 | 76 | 82 | 83 | 84 | 89 | 95 | 96 | 97 | 102 | 110 | 111 | 112 | 117 | 123 | 124 | 125 | 130 | 136 | 137 |
LinknameDescription
46 | 47 | projects 48 | 49 | 51 | 52 | Link to the project list of this client 53 | 54 | 55 |
59 | 60 | client_donations 61 | 62 | 64 | 65 | Link to the client donations list of this client 66 | 67 | 68 |
72 | 73 | client_project_tags 74 | 75 | 77 | 78 | Link to the tags list of this client 79 | 80 | 81 |
85 | 86 | client_fundraising_events 87 | 88 | 90 | 91 | Link to the fundraising events list of this client 92 | 93 | 94 |
98 | 99 | project_mailing_subscriptions 100 | 101 | 103 | 104 | Link to the templated client mailing subscriptions 105 | of this client. Replace {project_id} with the ID of a project that is 106 | part of you client projects list. 107 | 108 | 109 |
113 | 114 | project_statistics 115 | 116 | 118 | 119 | Link to the project statistics of this client 120 | 121 | 122 |
126 | 127 | fundraising_event_statistics 128 | 129 | 131 | 132 | Link to the fundraising event statistics of this client 133 | 134 | 135 |
138 | 139 | ## Response Example 140 | 141 | ```json 142 | { 143 | "links": [ 144 | { 145 | "rel": "projects", 146 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/projects.json" 147 | }, 148 | { 149 | "rel": "client_donations", 150 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/client_donations.json" 151 | }, 152 | { 153 | "rel": "client_project_tags", 154 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/tags.json" 155 | }, 156 | { 157 | "rel": "client_fundraising_events", 158 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/fundraising_events.json" 159 | }, 160 | { 161 | "rel": "project_mailing_subscriptions", 162 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/projects/%7Bproject_id%7D/mailing_subscriptions.json", 163 | "templated": true 164 | }, 165 | { 166 | "rel": "project_statistics", 167 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/project_statistics.json" 168 | }, 169 | { 170 | "rel": "fundraising_event_statistics", 171 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/fundraising_event_statistics.json" 172 | } 173 | ] 174 | } 175 | ``` 176 | 177 | -------------------------------------------------------------------------------- /sections/client_direct_deposit_create.md: -------------------------------------------------------------------------------- 1 | 2 | # Creating a Direct Deposit Donation ⇄ [Status](direct_deposit_details.md) 3 | 4 | ```Cirru 5 | POST https://api.betterplace.org/de/api_v4/clients/bergluft/projects/1114/direct_deposits.json 6 | ``` 7 | 8 | Create an unconfirmed direct deposit donation to a project. 9 | The donation is confirmed when the money arrives on the betterplace 10 | bank account. 11 | 12 | **:lock: Only available if authenticated as a client.** 13 | See [betterplace.org clients](../README.md#client-api). 14 | 15 | **:lock: This is an experimental feature and needs additional privileges.** 16 | 17 | ### Response and error codes: 18 | 19 | [A list of all response and error codes](../README.md#http-status-codes). 20 | 21 | The most likely ones are: 22 | 23 | [HTTP Code **`202`**](http://httpstatus.es/202) 24 | if the donation was created. The response data 25 | will include an IBAN and the reference number to submit the actual 26 | bank transfer. 27 | 28 | [HTTP Code **`422`**](http://httpstatus.es/422) 29 | if the submitted resource could not be accepted due to erroneous parameters 30 | or missing data. 31 | 32 | 33 | ## URL Parameters 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 51 | 52 | 53 | 54 | 55 | 56 | 61 | 62 |
ParameterExampleRequiredDescription
client_idbergluftyes 47 | 48 | The betterplace.org-internal client permalink. 49 | 50 |
project_id1114yes 57 | 58 | Project id as an integer number. 59 | 60 |
63 | 64 | ## JSON Parameters 65 | 66 | JSON parameters have to be provided in the body of the request with the 67 | Content-Type header set to "application/json". The parameters are part of a 68 | flat JSON document without any nesting. Some parameters are required, others 69 | are optional. 70 | 71 | ### Example 72 | 73 | ```json 74 | { 75 | "first_name": "Max", 76 | "last_name": "Mustermann", 77 | "company_name": "Mustermann Inc.", 78 | "email": "mm@example.com", 79 | "message": "Great Project!", 80 | "amount_cents": 100, 81 | "client_reference": "djksbf23u4sjkdn234p", 82 | "street": "Rheinstrasse 202", 83 | "city": "Wiesbaden", 84 | "zip": "65185", 85 | "country_alpha2": "DE", 86 | "validate_address": true 87 | } 88 | ``` 89 | 90 | ### Supported Parameters 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 107 | 113 | 114 | 115 | 116 | 117 | 118 | 121 | 127 | 128 | 129 | 130 | 131 | 132 | 135 | 141 | 142 | 143 | 144 | 145 | 146 | 149 | 156 | 157 | 158 | 159 | 160 | 161 | 164 | 170 | 171 | 172 | 173 | 174 | 175 | 178 | 187 | 188 | 189 | 190 | 191 | 192 | 195 | 212 | 213 | 214 | 215 | 216 | 217 | 220 | 230 | 231 | 232 | 233 | 234 | 235 | 238 | 247 | 248 | 249 | 250 | 251 | 252 | 255 | 264 | 265 | 266 | 267 | 268 | 269 | 272 | 283 | 284 | 285 | 286 | 287 | 288 | 291 | 305 | 306 |
ParameterExampleTypesRequiredDescription
first_nameMaxstring 105 | yes 106 | 108 | 109 | First name of the donor. 110 | 111 | 112 |
last_nameMustermannstring 119 | yes 120 | 122 | 123 | Last name of the donor. 124 | 125 | 126 |
company_nameMustermann Inc.string 133 | no 134 | 136 | 137 | Company name of the donor. 138 | 139 | 140 |
emailmm@example.comstring 147 | yes 148 | 150 | 151 | Email address of the donor. 152 | Only valid email addresses will be accepted. 153 | 154 | 155 |
messageGreat Project!string 162 | no 163 | 165 | 166 | A message from the donor to be shown on the project profile page. 167 | 168 | 169 |
amount_cents100number 176 | yes 177 | 179 | 180 | The amount of cents that are donated. 181 | Must be a positive integer between 182 | 1 183 | and 1000000. 184 | 185 | 186 |
client_referencedjksbf23u4sjkdn234pstring 193 | yes 194 | 196 | 197 | A unique identifier for this transaction. 198 | With this reference one can find the donation and its status later 199 | by using the client_reference-facet on the 200 | donation list endpoint. 201 |
202 | Allowed characters are a-zA-Z0-9_-. 203 |
204 | Attention: If you use a non-unique client reference, 205 | the donation pledge endpoint will still respond with success. 206 | However the pledge will not be processed into a donation but ignored. 207 |
208 | This is to make sure that one transaction is only processed once. 209 | 210 | 211 |
streetRheinstrasse 202string 218 | see description 219 | 221 | 222 | The street of the donors address. 223 | Used to issue a donation receipt if the donation is tax deductible. 224 | 225 | This field is required by default, but optional with 226 | validate_address=false. 227 | 228 | 229 |
cityWiesbadenstring 236 | see description 237 | 239 | 240 | The city of the donors address. 241 | Used to issue a donation receipt if the donation is tax deductible. 242 | 243 | This field is required default, but optional with validate_address=false. 244 | 245 | 246 |
zip65185string 253 | see description 254 | 256 | 257 | Zip code of the city or region the donor lives in. 258 | Used to issue a donation receipt if the donation is tax deductible. 259 | 260 | This field is required by default, but optional with validate_address=false. 261 | 262 | 263 |
country_alpha2DEstring 270 | see description 271 | 273 | 274 | ISO2 code of the country the donor lives in. A list of valid ISO2 codes 275 | can be found at 276 | Wikipedia ISO_3166-1_alpha-2. Used to issue a donation receipt if 277 | the donation is tax deductible. 278 | 279 | This field is required by default, but optional with validate_address=false. 280 | 281 | 282 |
validate_addresstrueboolean 289 | no 290 | 292 | 293 | Pass false to allow donations without a donor address. 294 |
295 | Attention: Donation receipts can only be issued to donors who 296 | provide their full address details. Therefore a warning might be 297 | in order when using this option: Let donors know that they won't get a 298 | donation receipt, or that they will only get a receipt if they do enter 299 | their address. 300 |
301 | True by default. 302 | 303 | 304 |
307 | 308 | ## Response Attributes 309 | 310 | 311 | ### Root Attributes 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 331 | 332 | 333 | 334 | 335 | 336 | 341 | 342 | 343 | 344 | 345 | 346 | 351 | 352 | 353 | 354 | 355 | 356 | 362 | 363 | 364 | 365 | 366 | 367 | 373 | 374 |
AttributeTypesExampleDescription
reference_idnumber123456 325 | 326 | The reference for the pending debit donation. Use it within 327 | the transaction to ensure it gets matched with the donation. 328 | 329 | 330 |
created_atstring"1994-11-05T13:15:30Z" 337 | 338 | DateTime (ISO8601 with Timezone) 339 | 340 |
updated_atstring"1994-11-05T13:15:30Z" 347 | 348 | DateTime (ISO8601 with Timezone) 349 | 350 |
ibanstringDE123 357 | 358 | The IBAN for the SEPA transaction. 359 | 360 | 361 |
holder_namestringbetterplace 368 | 369 | The holder name for the SEPA transaction. 370 | 371 | 372 |
375 | 376 | 377 | ## Response Links 378 | 379 | 380 | 381 | 382 | 383 | 384 | 385 |
LinknameDescription
No response example defined
386 | 387 | ## Response Example 388 | 389 | ```json 390 | { 391 | "id": 1563628, 392 | "created_at": "2018-08-21T16:52:43+02:00", 393 | "updated_at": "2018-09-01T09:00:29+02:00", 394 | "reference_id": 1563628, 395 | "iban": "DE14672700030088880032", 396 | "holder_name": "gut.org", 397 | "links": [ 398 | 399 | ] 400 | } 401 | ``` 402 | 403 | -------------------------------------------------------------------------------- /sections/client_donation_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Donation Details ⇄ [List](client_donations_list.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund/client_donations/d0d35e347873169aec71.json 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | 10 | The details of a betterplace.org client donation. 11 | The details and list view show the same data. 12 | 13 | 14 | ## URL Parameters 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 32 | 33 | 34 | 35 | 36 | 37 | 44 | 45 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 28 | 29 | The betterplace.org-internal client permalink. 30 | 31 |
idd0d35e347873169aec71yes 38 | 39 | The donation token that the client donation form passed to the 40 | callback url or the client_reference that was provided by the client. 41 | 42 | 43 |
46 | 47 | 48 | ## Response Attributes 49 | 50 | 51 | ### Root Attributes 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 69 | 70 | 71 | 72 | 73 | 74 | 85 | 86 | 87 | 92 | 93 | 94 | 100 | 101 | 102 | 103 | 104 | 105 | 113 | 114 | 115 | 116 | 117 | 118 | 124 | 125 | 126 | 127 | 128 | 129 | 139 | 140 | 141 | 142 | 143 | 144 | 149 | 150 | 151 | 152 | 153 | 154 | 161 | 162 | 163 | 164 | 165 | 166 | 171 | 172 | 173 | 174 | 175 | 176 | 181 | 182 |
AttributeTypesExampleDescription
amount_in_centsnumber10100 65 | 66 | Donated amount in cents 67 | 68 |
statestring"confirmed" 75 | 76 | At the moment, all donations that are returned by the API are "confirmed". 77 | Unconfirmed donations do not show up at all or disappear after they were revoked. 78 | Revocations usually take place during the first 14 days – but there are no guarantees. 79 | 80 | Please make sure to check for the "confirmed" state in your application explicitly since 81 | we might add a "revoked" state in the future. 82 | 83 | 84 |
88 | 89 | ↓donor 90 | 91 | null | objectTODO 95 | 96 | Donor information, if available. 97 | 98 | 99 |
messagenull | string"This is a great project. In spring 2007 I travelled around the area together with my children and …" 106 | 107 | An optional message by users. 108 | 109 | The body is plain text potentially containing line-breaks. 110 | 111 | 112 |
tokenstringofMmTgfiPL-n1dDlNmFWqTQN 119 | 120 | A token uniquely identifies a donation on the platform. 121 | 122 | 123 |
client_referencestring922ec9b-etc 130 | 131 | Client Donations can be identified via a custom client reference token. 132 | 133 | This client_reference can be provided by users of our 134 | 135 | ThirdPartyApp custom donation form for organisations, for example. 136 | 137 | 138 |
created_atstring"1994-11-05T13:15:30Z" 145 | 146 | DateTime (ISO8601 with Timezone) 147 | 148 |
receiver_typestring"Project" 155 | 156 | Client donations may go to a Project, 157 | a FundraisingEvent, a Pool. 158 | 159 | 160 |
receiver_idnumber1114 167 | 168 | The id of the project, project element or fundraising event. 169 | 170 |
receiver_titlestring"Skateistan Afghanistan" 177 | 178 | The title of the project, project element or fundraising event. 179 | 180 |
183 | 184 | ### ↑Nested Attributes: donor 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 202 | 203 | 204 | 205 | 206 | 207 | 217 | 218 | 219 | 224 | 225 | 226 | 231 | 232 |
AttributeTypesExampleDescription
donor.idnumber1 198 | 199 | An integer number ≥ 1 200 | 201 |
donor.namenull | string"Till B." 208 | 209 | Display name of a betterplace.org user. 210 | Possible formats: "Till B.", "T. Behnke", "Till Behnke". 211 | 212 | In the case of donation-opinions the name might also be 213 | empty/null for anonymous donations for anonymous donations. 214 | 215 | 216 |
220 | 221 | ↓donor.picture 222 | 223 | object//betterplace-assets.betterplace.org ↪/uploads/user/profile_picture ↪/000/000/001 ↪/fill_100x100_original_tb.jpg 227 | 228 | User profile picture or a fallback image 229 | 230 |
233 | 234 | ### ↑Nested Attributes: donor.picture 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 252 | 253 |
AttributeTypesExampleDescription
donor.picture.fallbackbooleantrue 248 | 249 | Specifies whether a fallback image is given or not 250 | 251 |
254 | 255 | 256 | ## Response Links 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 269 | 280 | 281 | 282 | 287 | 294 | 295 | 296 | 301 | 310 | 311 | 312 | 317 | 325 | 326 | 327 | 332 | 337 | 338 | 339 | 344 | 349 | 350 |
LinknameDescription
265 | 266 | receiver 267 | 268 | 270 | 271 | Link to the project details, 272 | project need details, 273 | fundraising event details, 274 | that is associated with this donation.
275 | Right now, there is no api end point for donations that are 276 | redirect or donated to the client pool. 277 | 278 | 279 |
283 | 284 | self 285 | 286 | 288 | 289 | Link to this resource itself 290 | (client donation details) 291 | 292 | 293 |
297 | 298 | donor.platform 299 | 300 | 302 | 303 | The user's profile on betterplace.org. 304 | To view a user profile you have to be logged in. 305 | This array is empty if the user has no useraccount 306 | with betterplace.org but donated via one of our partner. 307 | 308 | 309 |
313 | 314 | donor.contact_data 315 | 316 | 318 | 319 | The user's contact data. Please note that you need to be 320 | authenticated as a client with matching 321 | access rights in order to see this information. 322 | 323 | 324 |
328 | 329 | donor.picture.fill_100x100 330 | 331 | 333 | 334 | 100×100 Pixel 335 | 336 |
340 | 341 | donor.picture.original 342 | 343 | 345 | 346 | Maximum sized image. This is the original image with default-cropping or user-cropping applied. 347 | 348 |
351 | 352 | ## Response Example 353 | 354 | ```json 355 | { 356 | "amount_in_cents": 200, 357 | "state": "confirmed", 358 | "donor": null, 359 | "message": "Gemeinsam für Kinder!", 360 | "token": "c65e1cd3ff166c67adf7", 361 | "client_reference": null, 362 | "created_at": "2011-12-13T13:48:15+01:00", 363 | "receiver_type": "FundraisingEvent", 364 | "receiver_id": 8821, 365 | "receiver_title": "Stark fürs Leben - für die Zukunft unserer Kinder", 366 | "links": [ 367 | { 368 | "rel": "receiver", 369 | "href": "https://api.betterplace.org/de/api_v4/fundraising_events/8821.json" 370 | }, 371 | { 372 | "rel": "self", 373 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/client_donations/c65e1cd3ff166c67adf7.json" 374 | } 375 | ] 376 | } 377 | ``` 378 | 379 | -------------------------------------------------------------------------------- /sections/client_donation_pledge_status.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Donation Pledges Status ⇄ [Creation](client_donation_pledges_creation.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/devk/donation_pledges/1170.json 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | 10 | After submitting a donation pledge, you should check the status of the asynchronous 11 | pledge job. It returns a JSON response, containing information about its status, 12 | including failure reasons in the case of a failure. 13 | 14 | **TODO: Be aware that you need a donation pledge ID to use this endpoint which is not 15 | fully implemented yet. Please contact us in case you need it!** 16 | 17 | 18 | ## URL Parameters 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 36 | 37 | 38 | 39 | 40 | 41 | 46 | 47 | 48 | 49 | 50 | 51 | 60 | 61 |
ParameterExampleRequiredDescription
languageenyes 32 | 33 | The donation is marked with the language you use in your URL. 34 | 35 |
client_iddevkyes 42 | 43 | The betterplace.org-internal client permalink. 44 | 45 |
id1170yes 52 | 53 | The ID of the donation pledge. 54 | 55 | TODO: In the future this will be returned within the 56 | response of a successful donation pledge POST. 57 | 58 | 59 |
62 | 63 | 64 | ## Response Attributes 65 | 66 | 67 | ### Root Attributes 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 85 | 86 | 87 | 88 | 89 | 90 | 95 | 96 | 97 | 98 | 99 | 100 | 105 | 106 | 107 | 108 | 109 | 110 | 115 | 116 | 117 | 118 | 119 | 120 | 125 | 126 | 127 | 128 | 129 | 130 | 146 | 147 | 148 | 149 | 150 | 151 | 171 | 172 | 173 | 174 | 175 | 176 | 187 | 188 |
AttributeTypesExampleDescription
idnumber1 81 | 82 | An integer number ≥ 1 83 | 84 |
created_atstring"1994-11-05T13:15:30Z" 91 | 92 | DateTime (ISO8601 with Timezone) 93 | 94 |
updated_atstring"1994-11-05T13:15:30Z" 101 | 102 | DateTime (ISO8601 with Timezone) 103 | 104 |
confirmed_atstring2016-11-11T09:50:06+01:00 111 | 112 | DateTime (ISO8601 with Timezone) 113 | 114 |
failed_atstring2016-11-11T09:50:06+01:00 121 | 122 | DateTime (ISO8601 with Timezone) 123 | 124 |
statestring"confirmed" 131 | 132 | One of "pending", "confirmed" or "failed". 133 |
    134 |
  • pending 135 | The system is still processing this donation. 136 | Please check again soon. 137 |
  • confirmed 138 | The donation is confirmed. This state is final. 139 |
  • failed 140 | The donation failed. Please check the failure_code. 141 | This state is final. 142 |
143 | 144 | 145 |
failure_codestringpool_missing 152 | 153 | A set of failure codes.
154 | You could use this to choose follow up actions in 155 | your application. More details about each error are 156 | part of the failure_reason. 157 |
    158 |
  • pool_missing No pool available 159 |
  • pool_empty Not enough money on the pool 160 |
  • receiver_prohibited_from_receiving_donations The forwarding request's receiver may not receive donations 161 |
  • donation_invalid Generic error, look at failure_reason for details 162 |
163 | This list might be extended at any time. Please 164 | make sure you receive a notification if you encounter 165 | a new code. Codes will note be removed but might be 166 | deprecated and not used anymore at some point in the 167 | future. 168 | 169 | 170 |
failure_reasonstring 177 | 178 | A more detailed description of the failure.
179 | This message is meant to be interpreted by a 180 | developer, not by a customer/user. 181 | The message might change at any time, don't 182 | use it to match actions based on the message 183 | string. 184 | 185 | 186 |
189 | 190 | 191 | ## Response Links 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 204 | 211 | 212 |
LinknameDescription
200 | 201 | donation 202 | 203 | 205 | 206 | Link to the related donation 207 | (client donation details) 208 | 209 | 210 |
213 | 214 | ## Response Example 215 | 216 | ```json 217 | { 218 | "id": 1, 219 | "created_at": "2016-04-04T17:50:22+02:00", 220 | "updated_at": "2016-04-04T17:50:23+02:00", 221 | "confirmed_at": "2016-04-04T17:50:23+02:00", 222 | "failed_at": null, 223 | "state": "confirmed", 224 | "failure_code": null, 225 | "failure_reason": null, 226 | "links": [ 227 | { 228 | "rel": "donation", 229 | "href": "https://api.betterplace.org/de/api_v4/clients/natehelps/client_donations/6f6fa9122f7d1628a139.json" 230 | } 231 | ] 232 | } 233 | ``` 234 | 235 | -------------------------------------------------------------------------------- /sections/client_donation_pledges_creation.md: -------------------------------------------------------------------------------- 1 | 2 | # Creating a Client Donation Pledge ⇄ [Status](client_donation_pledge_status.md) 3 | 4 | ```Cirru 5 | POST https://api.betterplace.org/de/api_v4/clients/volksfreund/projects/1114/donation_pledges.json 6 | ``` 7 | 8 | Submit a donation pledge into the system. This will be transformed into 9 | a donation to the receiver. The request has to be a POST request with a 10 | JSON body. 11 | 12 | **:lock: Only available if authenticated as a client.** 13 | See [betterplace.org clients](../README.md#client-api). 14 | 15 | 16 | ### Process Flow 17 | 18 | [This flow chart describes the process…](https://ixwphj.axshare.com/donation-pledge-flow.html). 19 | 20 | 21 | ### What if the donation receiver is fully funded? 22 | 23 | The donation will be booked in the receiver account even 24 | if the receiver is fully funded. The receiver will than show a 25 | progress percentage > 100 %. For a project that means, the project 26 | manager has to add new money needs to pay out the additional funds. 27 | 28 | Please note that a closed project is prohibited from receiving donations. 29 | 30 | 31 | ### What if the donation receiver is prohibited from receiving donations? 32 | 33 | At the time when the pledge is received the system does not check the receiver 34 | status. Therefore the API will always respond with a success message for all 35 | receivers. Should the receiver be prohibited from receiving donations at the 36 | time when the donation is processed, the donation will be redirected to a 37 | specific client donation pool. Clients can later forward this money to 38 | projects they choose. 39 | 40 | 41 | ### Reconciliation of donation pledges 42 | 43 | Part of the contract for the usage of this donation pledge API will 44 | be the time period in which the pledges need to be reconciled. Ususally 45 | every two weeks or once a month. At the end of this time, the client 46 | will sum all pledges in the client system, wire us the donations and 47 | also send us a CSV file which allows betterplace.org to check the amounts. 48 | 49 | The fields for the CSV files are: 50 | - receiver_type, eg. `Project` 51 | - receiver_id, eg. `1114` 52 | - amount_in_cents, eg. `12000` 53 | - client_reference, eg. `123123123123` 54 | - datetime (ISO8601 with Timezone), eg `2007-11-01T13:15:30Z` 55 | 56 | Please use these names as column titles, use utf-8, use "," 57 | as a separator and force double quotes around all values. 58 | 59 | Here is [a flow chart describing the process](https://ixwphj.axshare.com/money-transfer-flow.html). 60 | 61 | 62 | ### Sending donation pledges to the client-pool 63 | 64 | It is possible to send donation pledges directly to the client-pool, by 65 | submitting to this endpoint instead of the project specific one: 66 | 67 | `POST https://api.betterplace.org/de/api_v4/clients/{CLIENT}/pool/donation_pledges.json` 68 | 69 | This endpoint will respond and behave like described above, but the 70 | money will be stored on the pool. Clients can later forward this money to 71 | projects they choose. 72 | 73 | 74 | ### Response and error codes: 75 | 76 | [A list of all response and error codes](../README.md#http-status-codes). 77 | 78 | The most likely ones are: 79 | 80 | [HTTP Code **`202`**](http://httpstatus.es/202) 81 | if a resource was successfully submitted for delayed processing. 82 | A successful request will return HTTP status 202 (accepted). The 83 | donation pledge is now saved and queued and will be processed 84 | by background workers. This part takes place asynchronously and might 85 | take up to a few minutes, especially in high traffic scenarios. 86 | Please make sure that you queue and retry your API calls until you 87 | receive clear answer (202, 422, 404, etc.) from us. 88 | Note that we will book only one 89 | donation per client_reference so there's no need to 90 | worry about retrying the pledge-sending. 91 | 92 | [HTTP Code **`422`**](http://httpstatus.es/422) 93 | if the submitted resource could not be accepted due to erroneous parameters. 94 | Please remember to validate all user input on your side before submitting 95 | it to the API. 96 | 97 | [HTTP Code **`404`**](http://httpstatus.es/404) 98 | if a requested resource could not be found. This might happen if 99 | the resource has been deleted in the timeframe between selection by the 100 | user and confirmation of the pledge by the client. In this case, either 101 | contact your user and change the resource (most likely a project) or 102 | redirect the donation to the client pool (the URL is provided by 103 | betterplace.org). 104 | 105 | 106 | ## URL Parameters 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 124 | 125 | 126 | 127 | 128 | 129 | 134 | 135 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 120 | 121 | The betterplace.org-internal client permalink. 122 | 123 |
project_id1114yes 130 | 131 | Project id as an integer number. 132 | 133 |
136 | 137 | ## JSON Parameters 138 | 139 | JSON parameters have to be provided in the body of the request with the 140 | Content-Type header set to "application/json". The parameters are part of a 141 | flat JSON document without any nesting. Some parameters are required, others 142 | are optional. 143 | 144 | ### Example 145 | 146 | ```json 147 | { 148 | "first_name": "Max", 149 | "last_name": "Mustermann", 150 | "email": "mm@example.com", 151 | "amount_in_cents": 100, 152 | "client_reference": "djksbf23u4sjkdn234p", 153 | "tracking_via": "campaign-0815", 154 | "earmark": 123, 155 | "street": "Rheinstrasse 202", 156 | "city": "Wiesbaden", 157 | "zip": "65185", 158 | "country_code": "DE", 159 | "validate_address": false 160 | } 161 | ``` 162 | 163 | ### Supported Parameters 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 180 | 189 | 190 | 191 | 192 | 193 | 194 | 197 | 206 | 207 | 208 | 209 | 210 | 211 | 214 | 224 | 225 | 226 | 227 | 228 | 229 | 232 | 241 | 242 | 243 | 244 | 245 | 246 | 249 | 266 | 267 | 268 | 269 | 270 | 271 | 274 | 283 | 284 | 285 | 286 | 287 | 288 | 291 | 301 | 302 | 303 | 304 | 305 | 306 | 309 | 318 | 319 | 320 | 321 | 322 | 323 | 326 | 335 | 336 | 337 | 338 | 339 | 340 | 343 | 352 | 353 | 354 | 355 | 356 | 357 | 360 | 371 | 372 | 373 | 374 | 375 | 376 | 379 | 393 | 394 |
ParameterExampleTypesRequiredDescription
first_nameMaxstring 178 | see description 179 | 181 | 182 | First name of the donor. 183 | 184 | This field is required by default, but optional with 185 | validate_address=false. 186 | 187 | 188 |
last_nameMustermannstring 195 | see description 196 | 198 | 199 | Last name of the donor. 200 | 201 | This field is required by default, but optional with 202 | validate_address=false. 203 | 204 | 205 |
emailmm@example.comstring 212 | see description 213 | 215 | 216 | Email address of the donor. 217 | Only valid email addresses will be accepted. 218 | 219 | This field is required by default, but optional with 220 | validate_address=false. 221 | 222 | 223 |
amount_in_cents100number 230 | yes 231 | 233 | 234 | The amount of cents that are donated. 235 | Must be a positive integer between 236 | 1 237 | and 1000000. 238 | 239 | 240 |
client_referencedjksbf23u4sjkdn234pstring 247 | yes 248 | 250 | 251 | A unique identifier for this transaction. 252 | With this reference one can find the donation and its status later 253 | by using the client_reference-facet on the 254 | donation list endpoint. 255 |
256 | Allowed characters are a-zA-Z0-9_-. 257 |
258 | Attention: If you use a non-unique client reference, 259 | the donation pledge endpoint will still respond with success. 260 | However the pledge will not be processed into a donation but ignored. 261 |
262 | This is to make sure that one transaction is only processed once. 263 | 264 | 265 |
tracking_viacampaign-0815string 272 | no 273 | 275 | 276 | A tracking identifier for the current campaign, origin or similar 277 | information. Default is blank. 278 |
279 | Allowed characters are a-zA-Z0-9_-. 280 | 281 | 282 |
earmark123number 289 | no 290 | 292 | 293 | An "earmark" indicating which need this donation should go to. 294 | Attention: this parameter may be completely ignored by the API 295 | at any time. There is no guarantee that the earmark will have an effect 296 | on the donation, and support for the feature may be pulled in the 297 | future. 298 | 299 | 300 |
streetRheinstrasse 202string 307 | see description 308 | 310 | 311 | The street of the donors address. 312 | Used to issue a donation receipt if the donation is tax deductible. 313 | 314 | This field is required by default, but optional with validate_address=false. 315 | 316 | 317 |
cityWiesbadenstring 324 | see description 325 | 327 | 328 | The city of the donors address. 329 | Used to issue a donation receipt if the donation is tax deductible. 330 | 331 | This field is required by default, but optional with validate_address=false. 332 | 333 | 334 |
zip65185string 341 | see description 342 | 344 | 345 | Zip code of the city or region the donor lives in. 346 | Used to issue a donation receipt if the donation is tax deductible. 347 | 348 | This field is required by default, but optional with validate_address=false. 349 | 350 | 351 |
country_codeDEstring 358 | see description 359 | 361 | 362 | ISO2 code of the country the donor lives in. A list of valid ISO2 codes 363 | can be found at 364 | Wikipedia ISO_3166-1_alpha-2. Used to issue a donation receipt if 365 | the donation is tax deductible. 366 | 367 | This field is required by default, but optional with validate_address=false. 368 | 369 | 370 |
validate_addressfalseboolean 377 | no 378 | 380 | 381 | Pass false to allow donations without a donor address. 382 |
383 | Attention: Donation receipts can only be issued to donors who 384 | provide their full address details. Therefore a warning might be 385 | in order when using this option: Let donors know that they won't get a 386 | donation receipt, or that they will only get a receipt if they do enter 387 | their address. 388 |
389 | True by default. 390 | 391 | 392 |
395 | 396 | ## Response Attributes 397 | 398 | 399 | ### Root Attributes 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 420 | 421 | 422 | 423 | 424 | 425 | 431 | 432 |
AttributeTypesExampleDescription
statusstringaccepted 413 | 414 | HTTP status code as a descriptive string. 415 | For a list of codes, see httpstatus.es. 416 | Example: "accepted" for code 202 417 | 418 | 419 |
status_codenumber202 426 | 427 | HTTP status code as an integer number, e.g. 202. 428 | 429 | 430 |
433 | 434 | 435 | ## Response Links 436 | 437 | 438 | 439 | 440 | 441 | 442 | 443 | 448 | 455 | 456 |
LinknameDescription
444 | 445 | location 446 | 447 | 449 | 450 | Location where the created/updated resource can be viewed or more 451 | information about it can be gathered. 452 | 453 | 454 |
457 | 458 | ## Response Example 459 | 460 | ```json 461 | { 462 | "status": "accepted", 463 | "status_code": 202, 464 | "links": [ 465 | { 466 | "rel": "location", 467 | "href": "https://api.betterplace.dev/de/api_v4/clients/some_client/client_donations/666-a-reference" 468 | } 469 | ] 470 | } 471 | ``` 472 | 473 | -------------------------------------------------------------------------------- /sections/client_donations_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Donations List ⇄ [Details](client_donation_details.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund/client_donations.json?facets=client_reference%3A922ec9b-etc 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | 10 | This API returns all donations to all client projects that where made using 11 | the client donation form (but none of the other donation-sources). 12 | 13 | Results are contained in a *data* attribute. 14 | 15 | 16 | ## URL Parameters 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 34 | 35 | 36 | 37 | 38 | 39 | 56 | 57 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 30 | 31 | The betterplace.org-internal client permalink. 32 | 33 |
facetsclient_reference:922ec9b-etcno 40 | 41 | You can search for a specific client_reference: ?facets=client_reference:54 42 | 43 |
44 | Example: 45 | 46 | https://api.betterplace.org/en/api_v4/ clients/karmic_minion/ client_donations?facets=client_reference:54 47 | 48 | 49 |
50 | This feature is only used in some cases that relate to the 51 | ThirdPartyApp custom donation form for organisations 52 | and the Client donation pledge endpoint. 53 | 54 | 55 |
58 | 59 | 60 | ## Response Attributes 61 | 62 | 63 | ### Root Attributes 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 81 | 82 | 83 | 84 | 85 | 86 | 97 | 98 | 99 | 104 | 105 | 106 | 112 | 113 | 114 | 115 | 116 | 117 | 125 | 126 | 127 | 128 | 129 | 130 | 136 | 137 | 138 | 139 | 140 | 141 | 151 | 152 | 153 | 154 | 155 | 156 | 161 | 162 | 163 | 164 | 165 | 166 | 173 | 174 | 175 | 176 | 177 | 178 | 183 | 184 | 185 | 186 | 187 | 188 | 193 | 194 |
AttributeTypesExampleDescription
amount_in_centsnumber10100 77 | 78 | Donated amount in cents 79 | 80 |
statestring"confirmed" 87 | 88 | At the moment, all donations that are returned by the API are "confirmed". 89 | Unconfirmed donations do not show up at all or disappear after they were revoked. 90 | Revocations usually take place during the first 14 days – but there are no guarantees. 91 | 92 | Please make sure to check for the "confirmed" state in your application explicitly since 93 | we might add a "revoked" state in the future. 94 | 95 | 96 |
100 | 101 | ↓donor 102 | 103 | null | objectTODO 107 | 108 | Donor information, if available. 109 | 110 | 111 |
messagenull | string"This is a great project. In spring 2007 I travelled around the area together with my children and …" 118 | 119 | An optional message by users. 120 | 121 | The body is plain text potentially containing line-breaks. 122 | 123 | 124 |
tokenstringofMmTgfiPL-n1dDlNmFWqTQN 131 | 132 | A token uniquely identifies a donation on the platform. 133 | 134 | 135 |
client_referencestring922ec9b-etc 142 | 143 | Client Donations can be identified via a custom client reference token. 144 | 145 | This client_reference can be provided by users of our 146 | 147 | ThirdPartyApp custom donation form for organisations, for example. 148 | 149 | 150 |
created_atstring"1994-11-05T13:15:30Z" 157 | 158 | DateTime (ISO8601 with Timezone) 159 | 160 |
receiver_typestring"Project" 167 | 168 | Client donations may go to a Project, 169 | a FundraisingEvent, a Pool. 170 | 171 | 172 |
receiver_idnumber1114 179 | 180 | The id of the project, project element or fundraising event. 181 | 182 |
receiver_titlestring"Skateistan Afghanistan" 189 | 190 | The title of the project, project element or fundraising event. 191 | 192 |
195 | 196 | ### ↑Nested Attributes: donor 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 214 | 215 | 216 | 217 | 218 | 219 | 229 | 230 | 231 | 236 | 237 | 238 | 243 | 244 |
AttributeTypesExampleDescription
donor.idnumber1 210 | 211 | An integer number ≥ 1 212 | 213 |
donor.namenull | string"Till B." 220 | 221 | Display name of a betterplace.org user. 222 | Possible formats: "Till B.", "T. Behnke", "Till Behnke". 223 | 224 | In the case of donation-opinions the name might also be 225 | empty/null for anonymous donations for anonymous donations. 226 | 227 | 228 |
232 | 233 | ↓donor.picture 234 | 235 | object//betterplace-assets.betterplace.org ↪/uploads/user/profile_picture ↪/000/000/001 ↪/fill_100x100_original_tb.jpg 239 | 240 | User profile picture or a fallback image 241 | 242 |
245 | 246 | ### ↑Nested Attributes: donor.picture 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 264 | 265 |
AttributeTypesExampleDescription
donor.picture.fallbackbooleantrue 260 | 261 | Specifies whether a fallback image is given or not 262 | 263 |
266 | 267 | 268 | ## Response Links 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 281 | 292 | 293 | 294 | 299 | 306 | 307 | 308 | 313 | 322 | 323 | 324 | 329 | 337 | 338 | 339 | 344 | 349 | 350 | 351 | 356 | 361 | 362 |
LinknameDescription
277 | 278 | receiver 279 | 280 | 282 | 283 | Link to the project details, 284 | project need details, 285 | fundraising event details, 286 | that is associated with this donation.
287 | Right now, there is no api end point for donations that are 288 | redirect or donated to the client pool. 289 | 290 | 291 |
295 | 296 | self 297 | 298 | 300 | 301 | Link to this resource itself 302 | (client donation details) 303 | 304 | 305 |
309 | 310 | donor.platform 311 | 312 | 314 | 315 | The user's profile on betterplace.org. 316 | To view a user profile you have to be logged in. 317 | This array is empty if the user has no useraccount 318 | with betterplace.org but donated via one of our partner. 319 | 320 | 321 |
325 | 326 | donor.contact_data 327 | 328 | 330 | 331 | The user's contact data. Please note that you need to be 332 | authenticated as a client with matching 333 | access rights in order to see this information. 334 | 335 | 336 |
340 | 341 | donor.picture.fill_100x100 342 | 343 | 345 | 346 | 100×100 Pixel 347 | 348 |
352 | 353 | donor.picture.original 354 | 355 | 357 | 358 | Maximum sized image. This is the original image with default-cropping or user-cropping applied. 359 | 360 |
363 | 364 | ## Response Example 365 | 366 | ```json 367 | { 368 | "total_entries": 21545, 369 | "offset": 0, 370 | "total_pages": 7182, 371 | "current_page": 1, 372 | "per_page": 3, 373 | "data": [ 374 | { 375 | "amount_in_cents": 200, 376 | "state": "confirmed", 377 | "donor": null, 378 | "message": "Gemeinsam für Kinder!", 379 | "token": "c65e1cd3ff166c67adf7", 380 | "client_reference": null, 381 | "created_at": "2011-12-13T13:48:15+01:00", 382 | "receiver_type": "FundraisingEvent", 383 | "receiver_id": 8821, 384 | "receiver_title": "Stark fürs Leben - für die Zukunft unserer Kinder", 385 | "links": [ 386 | { 387 | "rel": "receiver", 388 | "href": "https://api.betterplace.org/de/api_v4/fundraising_events/8821.json" 389 | }, 390 | { 391 | "rel": "self", 392 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/client_donations/c65e1cd3ff166c67adf7.json" 393 | } 394 | ] 395 | }, 396 | { 397 | "amount_in_cents": 100, 398 | "state": "confirmed", 399 | "donor": null, 400 | "message": "", 401 | "token": "e0099cc079adbf1c13c0", 402 | "client_reference": null, 403 | "created_at": "2012-05-23T16:41:06+02:00", 404 | "receiver_type": "FundraisingEvent", 405 | "receiver_id": 9866, 406 | "receiver_title": "Fab&Vivien Nr. 3 | The third fundraising bet", 407 | "links": [ 408 | { 409 | "rel": "receiver", 410 | "href": "https://api.betterplace.org/de/api_v4/fundraising_events/9866.json" 411 | }, 412 | { 413 | "rel": "self", 414 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/client_donations/e0099cc079adbf1c13c0.json" 415 | } 416 | ] 417 | }, 418 | { 419 | "amount_in_cents": 1000, 420 | "state": "confirmed", 421 | "donor": null, 422 | "message": "", 423 | "token": "cfa60978d12bb91589cf", 424 | "client_reference": null, 425 | "created_at": "2012-06-12T16:53:03+02:00", 426 | "receiver_type": "FundraisingEvent", 427 | "receiver_id": 10987, 428 | "receiver_title": "Touchrugbyturnier", 429 | "links": [ 430 | { 431 | "rel": "receiver", 432 | "href": "https://api.betterplace.org/de/api_v4/fundraising_events/10987.json" 433 | }, 434 | { 435 | "rel": "self", 436 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/client_donations/cfa60978d12bb91589cf.json" 437 | } 438 | ] 439 | } 440 | ] 441 | } 442 | ``` 443 | 444 | -------------------------------------------------------------------------------- /sections/client_forwarding_request_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Forwarding Request Status ⇄ [Creation](client_forwarding_requests_list.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/some_client/forwarding_requests/1337.json 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | 10 | After submitting a forwarding request, you should check the status of the asynchronous 11 | forwarding job. It returns a JSON response, containing information about its status, 12 | including failure reasons in the case of a failure. 13 | 14 | 15 | ## URL Parameters 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 33 | 34 | 35 | 36 | 37 | 38 | 43 | 44 | 45 | 46 | 47 | 48 | 55 | 56 |
ParameterExampleRequiredDescription
languageenyes 29 | 30 | The donation is marked with the language you use in your URL. 31 | 32 |
client_idsome_clientyes 39 | 40 | The betterplace.org-internal client permalink. 41 | 42 |
id1337yes 49 | 50 | The ID of the forwarding request, returned within the 51 | response of a successful forwarding request POST. 52 | 53 | 54 |
57 | 58 | 59 | ## Response Attributes 60 | 61 | 62 | ### Root Attributes 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 80 | 81 | 82 | 83 | 84 | 85 | 90 | 91 | 92 | 93 | 94 | 95 | 100 | 101 | 102 | 103 | 104 | 105 | 110 | 111 | 112 | 113 | 114 | 115 | 120 | 121 | 122 | 123 | 124 | 125 | 141 | 142 | 143 | 144 | 145 | 146 | 166 | 167 | 168 | 169 | 170 | 171 | 182 | 183 |
AttributeTypesExampleDescription
idnumber1 76 | 77 | An integer number ≥ 1 78 | 79 |
created_atstring"1994-11-05T13:15:30Z" 86 | 87 | DateTime (ISO8601 with Timezone) 88 | 89 |
updated_atstring"1994-11-05T13:15:30Z" 96 | 97 | DateTime (ISO8601 with Timezone) 98 | 99 |
confirmed_atstring2016-11-11T09:50:06+01:00 106 | 107 | DateTime (ISO8601 with Timezone) 108 | 109 |
failed_atstring2016-11-11T09:50:06+01:00 116 | 117 | DateTime (ISO8601 with Timezone) 118 | 119 |
statestring"confirmed" 126 | 127 | One of "pending", "confirmed" or "failed". 128 |
    129 |
  • pending 130 | The system is still processing this donation. 131 | Please check again soon. 132 |
  • confirmed 133 | The donation is confirmed. This state is final. 134 |
  • failed 135 | The donation failed. Please check the failure_code. 136 | This state is final. 137 |
138 | 139 | 140 |
failure_codestringpool_missing 147 | 148 | A set of failure codes.
149 | You could use this to choose follow up actions in 150 | your application. More details about each error are 151 | part of the failure_reason. 152 |
    153 |
  • pool_missing No pool available 154 |
  • pool_empty Not enough money on the pool 155 |
  • receiver_prohibited_from_receiving_donations The forwarding request's receiver may not receive donations 156 |
  • donation_invalid Generic error, look at failure_reason for details 157 |
158 | This list might be extended at any time. Please 159 | make sure you receive a notification if you encounter 160 | a new code. Codes will note be removed but might be 161 | deprecated and not used anymore at some point in the 162 | future. 163 | 164 | 165 |
failure_reasonstring 172 | 173 | A more detailed description of the failure.
174 | This message is meant to be interpreted by a 175 | developer, not by a customer/user. 176 | The message might change at any time, don't 177 | use it to match actions based on the message 178 | string. 179 | 180 | 181 |
184 | 185 | 186 | ## Response Links 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 199 | 206 | 207 |
LinknameDescription
195 | 196 | donation 197 | 198 | 200 | 201 | Link to the related donation 202 | (client donation details) 203 | 204 | 205 |
208 | 209 | ## Response Example 210 | 211 | ```json 212 | { 213 | "id": 1, 214 | "created_at": "2017-03-17T10:12:08+01:00", 215 | "updated_at": "2017-03-17T10:12:09+01:00", 216 | "confirmed_at": "2017-03-17T10:12:09+01:00", 217 | "failed_at": null, 218 | "state": "confirmed", 219 | "failure_code": null, 220 | "failure_reason": null, 221 | "links": [ 222 | { 223 | "rel": "donation", 224 | "href": "https://api.betterplace.org/de/api_v4/clients/particulate-sww/client_donations/b99fe8ce93dda908f81b.json" 225 | } 226 | ] 227 | } 228 | ``` 229 | 230 | -------------------------------------------------------------------------------- /sections/client_forwarding_requests_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Creating a Client Forwarding Request ⇄ [Status](client_forwarding_request_details.md) 3 | 4 | ```Cirru 5 | POST https://api.betterplace.org/de/api_v4/clients/volksfreund/projects/1114/forwarding_requests.json 6 | ``` 7 | 8 | Transfer money from a client donation pool to a Project. 9 | The request has to be a POST request with a JSON body. 10 | 11 | **:lock: Only available if authenticated as a client.** 12 | See [betterplace.org clients](../README.md#client-api). 13 | 14 | 15 | ### Process Flow 16 | 17 | [This flow chart describes the process…](https://ixwphj.axshare.com/forwarding-request-flow.html). 18 | 19 | 20 | ### What if the donation receiver is fully funded? 21 | 22 | The donation will be booked in the receiver account even 23 | if the receiver is fully funded. The receiver will than show a 24 | progress percentage > 100 %. For a project that means, the project 25 | manager has to add new money needs to pay out the additional funds. 26 | 27 | Please note that closed projects are prohibited from receiving donations. 28 | 29 | 30 | ### What if the donation receiver is prohibited from receiving donations? 31 | 32 | At the time when the forwarding request is received, the system does not 33 | check the receiver status. Therefore the API will always respond with a 34 | success message for all receivers. 35 | 36 | Should the receiver be prohibited from receiving donations at the time 37 | when the donation is processed, the forwarding will not be inserted into 38 | the system. The forwarding request will then be marked as "failed" and 39 | the "error_reason" field holds detailed information about the problem. 40 | Learn more at [Client Forwarding Request Status](client_forwarding_request_details.md). 41 | 42 | There are two possible next steps: 43 | 44 | _Option 1:_ Handle those cases manually with the betterplace.org-support-team. 45 | This option is only feasible in selected cases. 46 | 47 | _Option 2:_ The client system reacts to the error-state of the 48 | forwarding request automatically. For example by moving the donation 49 | to a fallback project. 50 | 51 | 52 | ### Response and error codes: 53 | 54 | [A list of all response and error codes](../README.md#http-status-codes). 55 | 56 | The most likely ones are: 57 | 58 | [HTTP Code **`202`**](http://httpstatus.es/202) 59 | if a resource was successfully submitted for delayed processing. 60 | A successful request will return HTTP status 202 (accepted). The 61 | forwarding request is now saved and queued and will be processed 62 | by background workers. This part takes place asynchronously and might 63 | take up to a few minutes, especially in high traffic scenarios. 64 | Please make sure that you queue and retry your API calls until you 65 | receive clear answer (202, 422, 404, etc.) from us. 66 | Note that we will book only one 67 | donation per client_reference so there's no need to 68 | worry about retrying the forwarding. 69 | 70 | [HTTP Code **`422`**](http://httpstatus.es/422) 71 | if the submitted resource could not be accepted due to erroneous parameters. 72 | Please remember to validate all user input on your side before submitting 73 | it to the API. 74 | 75 | [HTTP Code **`404`**](http://httpstatus.es/404) 76 | if a requested resource could not be found. This might happen if 77 | the resource has been deleted in the timeframe between selection by the 78 | user and confirmation of the forwarding request by the client. In this 79 | case, either contact your user and change the resource (most likely a 80 | project) or redirect the donation to the client pool (the URL is 81 | provided by betterplace.org). 82 | 83 | 84 | ## URL Parameters 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 102 | 103 | 104 | 105 | 106 | 107 | 112 | 113 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 98 | 99 | The betterplace.org-internal client permalink. 100 | 101 |
project_id1114yes 108 | 109 | Project id as an integer number. 110 | 111 |
114 | 115 | ## JSON Parameters 116 | 117 | JSON parameters have to be provided in the body of the request with the 118 | Content-Type header set to "application/json". The parameters are part of a 119 | flat JSON document without any nesting. Some parameters are required, others 120 | are optional. 121 | 122 | ### Example 123 | 124 | ```json 125 | { 126 | "amount_in_cents": 100, 127 | "client_reference": "djksbf23u4sjkdn234p", 128 | "tracking_via": "campaign-0815" 129 | } 130 | ``` 131 | 132 | ### Supported Parameters 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 149 | 158 | 159 | 160 | 161 | 162 | 163 | 166 | 183 | 184 | 185 | 186 | 187 | 188 | 191 | 200 | 201 |
ParameterExampleTypesRequiredDescription
amount_in_cents100number 147 | yes 148 | 150 | 151 | The amount of cents that are forwarded. 152 | Must be a positive integer between 153 | 1 154 | and 1000000. 155 | 156 | 157 |
client_referencedjksbf23u4sjkdn234pstring 164 | yes 165 | 167 | 168 | A unique identifier for this transaction. 169 | With this reference one can find the donation and its status later 170 | by using the client_reference-facet on the 171 | donation list endpoint. 172 |
173 | Allowed characters are a-zA-Z0-9_-. 174 |
175 | Attention: If you use a non-unique client reference, 176 | the donation pledge endpoint will still respond with success. 177 | However the pledge will not be processed into a donation but ignored. 178 |
179 | This is to make sure that one transaction is only processed once. 180 | 181 | 182 |
tracking_viacampaign-0815string 189 | no 190 | 192 | 193 | A tracking identifier for the current campaign, origin or similar 194 | information. Default is blank. 195 |
196 | Allowed characters are a-zA-Z0-9_-. 197 | 198 | 199 |
202 | 203 | ## Response Attributes 204 | 205 | 206 | ### Root Attributes 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 227 | 228 | 229 | 230 | 231 | 232 | 238 | 239 |
AttributeTypesExampleDescription
statusstringaccepted 220 | 221 | HTTP status code as a descriptive string. 222 | For a list of codes, see httpstatus.es. 223 | Example: "accepted" for code 202 224 | 225 | 226 |
status_codenumber202 233 | 234 | HTTP status code as an integer number, e.g. 202. 235 | 236 | 237 |
240 | 241 | 242 | ## Response Links 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 255 | 262 | 263 |
LinknameDescription
251 | 252 | location 253 | 254 | 256 | 257 | Location where the created/updated resource can be viewed or more 258 | information about it can be gathered. 259 | 260 | 261 |
264 | 265 | ## Response Example 266 | 267 | ```json 268 | { 269 | "status": "accepted", 270 | "status_code": 202, 271 | "links": [ 272 | { 273 | "rel": "location", 274 | "href": "https://api.betterplace.dev/de/api_v4/clients/some_client/forwarding_requests/1337" 275 | } 276 | ] 277 | } 278 | ``` 279 | 280 | -------------------------------------------------------------------------------- /sections/client_fundraising_event_statistics.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Fundraising Event Statistics 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund/fundraising_event_statistics.json 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | Some client-statistics for a betterplace.org client. All results are cached for 20 minutes. 10 | 11 | 12 | ## URL Parameters 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 30 | 31 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 26 | 27 | The betterplace.org-internal client permalink 28 | 29 |
32 | 33 | 34 | ## Response Attributes 35 | 36 | 37 | ### Root Attributes 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 61 | 62 | 63 | 64 | 65 | 66 | 74 | 75 | 76 | 77 | 78 | 79 | 88 | 89 | 90 | 91 | 92 | 93 | 102 | 103 |
AttributeTypesExampleDescription
donated_amount_in_centsnumber10100 51 | 52 | How many cents are donated already to all fundraising events of this client. 53 | 54 | It does not include the money of the client-pool-fundraising-event. 55 | 56 | Remember: This includes all donations to fundraising events of this client even those 57 | that are donated via betterplace.org or other channels. 58 | 59 | 60 |
fundraising_events_countnumber100 67 | 68 | The number of fundraising events of this client. 69 | 70 | Blocked fundraising events are excluded from this count and from the API in general. 71 | 72 | 73 |
client_donated_amount_in_centsnumber8100 80 | 81 | How many cents are donated through the clients donation page to 82 | all fundraising events (those that are active, closed, blocked and so on). 83 | 84 | The client-pool-fundraising-event is ignored. 85 | 86 | 87 |
client_donations_countnumber200 94 | 95 | The number of client donations for this client to 96 | all fundraising events (those that are active, closed, blocked and so on). 97 | 98 | The client-pool-fundraising-event is ignored. 99 | 100 | 101 |
104 | 105 | 106 | ## Response Links 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 |
LinknameDescription
No response example defined
115 | 116 | ## Response Example 117 | 118 | ```json 119 | { 120 | "donated_amount_in_cents": 0, 121 | "fundraising_events_count": 0, 122 | "client_donated_amount_in_cents": 0, 123 | "client_donations_count": 0, 124 | "links": [ 125 | 126 | ] 127 | } 128 | ``` 129 | 130 | -------------------------------------------------------------------------------- /sections/client_mailing_subscriptions.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Mailing Subscriptions 3 | 4 | ```Cirru 5 | POST https://api.betterplace.org/de/api_v4/clients/volksfreund/projects/4425/mailing_subscriptions.json 6 | ``` 7 | 8 | Create or update a mailing subscriptions for a project. 9 | 10 | **:lock: Only available if authenticated as a client.** 11 | See [betterplace.org clients](../README.md#client-api). 12 | 13 | 14 | ### Process Flow 15 | 16 | [This flow chart describes the process…](https://ixwphj.axshare.com/user-subscriptions-flow.html). 17 | 18 | 19 | ### Response and error codes: 20 | 21 | A successful request will return HTTP status 201 (created). 22 | 23 | If an error occurs the HTTP return code will be 422 (unprocessable 24 | entity). [More error codes](../README.md#http-status-codes). 25 | 26 | 27 | ## URL Parameters 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 49 | 50 | 51 | 52 | 53 | 54 | 59 | 60 | 61 | 62 | 63 | 64 | 69 | 70 |
ParameterExampleRequiredDescription
languageenyes 41 | 42 | The subscription is marked with the language you use in your URL. 43 | Newsletter authors write their content in a specific lang which you can 44 | target with the subscription lang. To target a lang see 45 | api setting lang. 46 | 47 | 48 |
client_idvolksfreundyes 55 | 56 | The betterplace.org-internal client permalink. 57 | 58 |
project_id4425yes 65 | 66 | Project id as an integer number. 67 | 68 |
71 | 72 | ## JSON Parameters 73 | 74 | JSON parameters have to be provided in the body of the request with the 75 | Content-Type header set to "application/json". The parameters are part of a 76 | flat JSON document without any nesting. Some parameters are required, others 77 | are optional. 78 | 79 | ### Example 80 | 81 | ```json 82 | { 83 | "email": "peter.paul@betterplace.org", 84 | "first_name": "Peter", 85 | "last_name": "Paul", 86 | "active": true 87 | } 88 | ``` 89 | 90 | ### Supported Parameters 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 107 | 112 | 113 | 114 | 115 | 116 | 117 | 120 | 125 | 126 | 127 | 128 | 129 | 130 | 133 | 138 | 139 | 140 | 141 | 142 | 143 | 146 | 151 | 152 |
ParameterExampleTypesRequiredDescription
emailpeter.paul@betterplace.orgstring 105 | yes 106 | 108 | 109 | The email of the user 110 | 111 |
first_namePeterstring 118 | yes 119 | 121 | 122 | The first name of the user 123 | 124 |
last_namePaulstring 131 | yes 132 | 134 | 135 | The last name of the user 136 | 137 |
activetrueboolean 144 | yes 145 | 147 | 148 | State of the subscription: active/inactive 149 | 150 |
153 | 154 | ## Response Attributes 155 | 156 | 157 | ### Root Attributes 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 178 | 179 | 180 | 181 | 182 | 183 | 189 | 190 |
AttributeTypesExampleDescription
statusstringaccepted 171 | 172 | HTTP status code as a descriptive string. 173 | For a list of codes, see httpstatus.es. 174 | Example: "accepted" for code 202 175 | 176 | 177 |
status_codenumber202 184 | 185 | HTTP status code as an integer number, e.g. 202. 186 | 187 | 188 |
191 | 192 | 193 | ## Response Links 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 206 | 213 | 214 |
LinknameDescription
202 | 203 | location 204 | 205 | 207 | 208 | Location where the created/updated resource can be viewed or more 209 | information about it can be gathered. 210 | 211 | 212 |
215 | 216 | ## Response Example 217 | 218 | ```json 219 | { 220 | "status": "created", 221 | "status_code": 201, 222 | "links": [ 223 | 224 | ] 225 | } 226 | ``` 227 | 228 | -------------------------------------------------------------------------------- /sections/client_newsletter_opt_ins.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Newsletter OptIns 3 | 4 | ```Cirru 5 | POST https://api.betterplace.org/de/api_v4/clients/volksfreund/newsletter_opt_ins.json 6 | ``` 7 | 8 | Start the opt-in process to subscribe an email address to the 9 | betterplace platform newsletter. 10 | 11 | **:lock: Only available if authenticated as a client.** 12 | See [betterplace.org clients](../README.md#client-api). 13 | 14 | ### Response and error codes: 15 | 16 | A successful request will return HTTP status 201 (created). 17 | 18 | If an error occurs the HTTP return code will be 422 (unprocessable 19 | entity). [More error codes](../README.md#http-status-codes). 20 | 21 | 22 | ## URL Parameters 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 40 | 41 | 42 | 43 | 44 | 45 | 50 | 51 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 36 | 37 | The betterplace.org-internal client permalink. 38 | 39 |
languageenyes 46 | 47 | The language preference of the subscriber. 48 | 49 |
52 | 53 | ## JSON Parameters 54 | 55 | JSON parameters have to be provided in the body of the request with the 56 | Content-Type header set to "application/json". The parameters are part of a 57 | flat JSON document without any nesting. Some parameters are required, others 58 | are optional. 59 | 60 | ### Example 61 | 62 | ```json 63 | { 64 | "email": "peter.paul@betterplace.org", 65 | "first_name": "Peter", 66 | "last_name": "Paul", 67 | "wording": "I want to receive newsletters from betterplace" 68 | } 69 | ``` 70 | 71 | ### Supported Parameters 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 88 | 93 | 94 | 95 | 96 | 97 | 98 | 101 | 106 | 107 | 108 | 109 | 110 | 111 | 114 | 119 | 120 | 121 | 122 | 123 | 124 | 127 | 136 | 137 |
ParameterExampleTypesRequiredDescription
emailpeter.paul@betterplace.orgstring 86 | yes 87 | 89 | 90 | The email of the user 91 | 92 |
first_namePeterstring 99 | yes 100 | 102 | 103 | The first name of the user 104 | 105 |
last_namePaulstring 112 | yes 113 | 115 | 116 | The last name of the user 117 | 118 |
wordingI want to receive newsletters from betterplacestring 125 | yes 126 | 128 | 129 | The text that has been used to explain the subscription to the user. 130 | E.g. if you have a checkbox to subscribe, pass its label text. 131 | 132 | This text must be recorded due to GDPR requirements. 133 | 134 | 135 |
138 | 139 | ## Response Attributes 140 | 141 | 142 | ### Root Attributes 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 163 | 164 | 165 | 166 | 167 | 168 | 174 | 175 |
AttributeTypesExampleDescription
statusstringaccepted 156 | 157 | HTTP status code as a descriptive string. 158 | For a list of codes, see httpstatus.es. 159 | Example: "accepted" for code 202 160 | 161 | 162 |
status_codenumber202 169 | 170 | HTTP status code as an integer number, e.g. 202. 171 | 172 | 173 |
176 | 177 | 178 | ## Response Links 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 191 | 198 | 199 |
LinknameDescription
187 | 188 | location 189 | 190 | 192 | 193 | Location where the created/updated resource can be viewed or more 194 | information about it can be gathered. 195 | 196 | 197 |
200 | 201 | ## Response Example 202 | 203 | ```json 204 | { 205 | "status": "created", 206 | "status_code": 201, 207 | "links": [ 208 | 209 | ] 210 | } 211 | ``` 212 | 213 | -------------------------------------------------------------------------------- /sections/client_project_statistics.md: -------------------------------------------------------------------------------- 1 | 2 | # Client Project Statistics 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund/project_statistics.json 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | Some client statistics for a betterplace.org client. All results are cached for 20 minutes. 10 | 11 | 12 | ## URL Parameters 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 30 | 31 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 26 | 27 | The betterplace.org-internal client permalink 28 | 29 |
32 | 33 | 34 | ## Response Attributes 35 | 36 | 37 | ### Root Attributes 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 60 | 61 | 62 | 63 | 64 | 65 | 75 | 76 | 77 | 78 | 79 | 80 | 92 | 93 | 94 | 95 | 96 | 97 | 103 | 104 | 105 | 106 | 107 | 108 | 115 | 116 | 117 | 118 | 119 | 120 | 126 | 127 |
AttributeTypesExampleDescription
donated_amount_in_centsnumber10100 51 | 52 | How many cents are donated already through user donations or forwardings 53 | to all client projects. 54 | 55 | Remember: This includes all donations to projects of this client even those 56 | that are donated via betterplace.org or other channels. 57 | 58 | 59 |
external_donated_amount_in_centsnumber10100 66 | 67 | ⚠️ DEPRECATED! 68 | This value will be removed in the future. 69 | 70 | How many cents are external donations, that means they were given directly 71 | to the project on other, non-betterplace channels. 72 | 73 | 74 |
requested_amount_in_centsnumber11000 81 | 82 | How many cents were requested by all client projects in total. 83 | This calculation is based on the sum of all 84 | needs (requested_amount_in_cents). 85 | 86 | Calculate the amount of cents that is still missing until all projects 87 | are completed like this: 88 | `requested_amount_in_cents - donated_amount_in_cents - external_donated_amount_in_cents` 89 | 90 | 91 |
projects_countnumber100 98 | 99 | The number of projects of this client. 100 | 101 | 102 |
client_donated_amount_in_centsnumber8100 109 | 110 | How many cents are donated through the client's donation page and forwarded 111 | from the clients donation pool or matching funds of this client. 112 | 113 | 114 |
client_donations_countnumber200 121 | 122 | The number of client donations for this client. 123 | 124 | 125 |
128 | 129 | 130 | ## Response Links 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 |
LinknameDescription
No response example defined
139 | 140 | ## Response Example 141 | 142 | ```json 143 | { 144 | "donated_amount_in_cents": 0, 145 | "external_donated_amount_in_cents": 0, 146 | "requested_amount_in_cents": 0, 147 | "projects_count": 0, 148 | "client_donated_amount_in_cents": 0, 149 | "client_donations_count": 0, 150 | "links": [ 151 | 152 | ] 153 | } 154 | ``` 155 | 156 | -------------------------------------------------------------------------------- /sections/client_project_tags_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Client-project tags list 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund/projects/4425/tags.json?order=projects_count%3ADESC 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | 10 | This API returns all tags assigned by this client for this project. 11 | Client project tags are a custom client feature and andministered 12 | as a service of [betterplace solutions](http://www.betterplace-solutions.de/#buergerzeitung). 13 | 14 | Results are contained in a *data* attribute. 15 | 16 | To guarantee stable search results, all clients are required to specify an order with each 17 | request as explained below. 18 | 19 | 20 | ## URL Parameters 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 38 | 39 | 40 | 41 | 42 | 43 | 48 | 49 | 50 | 51 | 52 | 53 | 72 | 73 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 34 | 35 | The betterplace.org-internal client permalink 36 | 37 |
project_id4425yes 44 | 45 | Project id as an integer number. 46 | 47 |
orderprojects_count:DESCno 54 | 55 | Order the result set. 56 |
57 | It is strongly recommended to specify an order with each request. 58 | The default order might change at any time without notice. 59 | A recommended order is 60 | projects_count:asc| slug:asc (without the spaces). 61 |
62 | Supported orders are: 63 |
    64 |
  • slug:ASC/DESC – tag name 65 |
  • projects_count:ASC/DESC - how many projects are using that client? 66 |
67 | It is possible to set multiple order filters. 68 | Learn how to format the parameter. 69 | 70 | 71 |
74 | 75 | 76 | ## Response Attributes 77 | 78 | 79 | ### Root Attributes 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 98 | 99 | 100 | 101 | 102 | 103 | 110 | 111 | 112 | 113 | 114 | 115 | 122 | 123 |
AttributeTypesExampleDescription
tagstring"Education" 93 | 94 | The name of the tag. It is unique per client. 95 | 96 | 97 |
slugstring"education" 104 | 105 | The slug of the tag. It is unique per client and used to build urls. 106 | It must not contain any non url-safe characters. 107 | 108 | 109 |
projects_countnumber23 116 | 117 | The number of projects 118 | that were tagged with this tag. 119 | 120 | 121 |
124 | 125 | 126 | ## Response Links 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 139 | 145 | 146 |
LinknameDescription
135 | 136 | projects 137 | 138 | 140 | 141 | Link to the client-tag projects list – all projects that are tagged with given client-tag. 142 | 143 | 144 |
147 | 148 | ## Response Example 149 | 150 | ```json 151 | { 152 | "total_entries": 5, 153 | "offset": 0, 154 | "total_pages": 2, 155 | "current_page": 1, 156 | "per_page": 3, 157 | "data": [ 158 | { 159 | "tag": "Trier", 160 | "slug": "Trier", 161 | "projects_count": 31, 162 | "links": [ 163 | { 164 | "rel": "projects", 165 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/tags/Trier/projects.json" 166 | } 167 | ] 168 | }, 169 | { 170 | "tag": "KinderJugendliche", 171 | "slug": "KinderJugendliche", 172 | "projects_count": 33, 173 | "links": [ 174 | { 175 | "rel": "projects", 176 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/tags/KinderJugendliche/projects.json" 177 | } 178 | ] 179 | }, 180 | { 181 | "tag": "Familien", 182 | "slug": "Familien", 183 | "projects_count": 10, 184 | "links": [ 185 | { 186 | "rel": "projects", 187 | "href": "https://api.betterplace.org/de/api_v4/clients/volksfreund/tags/Familien/projects.json" 188 | } 189 | ] 190 | } 191 | ] 192 | } 193 | ``` 194 | 195 | -------------------------------------------------------------------------------- /sections/client_tag_projects_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Client tag projects list 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund/tags/bildung/projects.json 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | 10 | This API returns all projects that are tagged with the given client-tag. 11 | 12 | The result is a filtered view of the '[Projects List](projects_list.md)' result. 13 | 14 | 15 | ## URL Parameters 16 | 17 | Same as for the [Projects List](projects_list.md) result. 18 | 19 | 20 | ## Response Attributes 21 | 22 | Same as for the [Projects List](projects_list.md) result. 23 | 24 | 25 | ## Response Links 26 | 27 | Same as for the [Projects List](projects_list.md) result. 28 | 29 | 30 | ## Response Example 31 | 32 | Same as for the [Projects List](projects_list.md) result. 33 | -------------------------------------------------------------------------------- /sections/client_tags_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Client tags list 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/volksfreund/tags.json 6 | ``` 7 | 8 | **For [betterplace.org clients](../README.md#client-api) only:** 9 | 10 | This API returns all tags defined for a client. 11 | 12 | Results are contained in a *data* attribute. 13 | 14 | 15 | ## URL Parameters 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 33 | 34 |
ParameterExampleRequiredDescription
client_idvolksfreundyes 29 | 30 | The betterplace.org-internal client id 31 | 32 |
35 | 36 | 37 | ## Response Attributes 38 | 39 | 40 | ### Root Attributes 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 59 | 60 | 61 | 62 | 63 | 64 | 71 | 72 | 73 | 74 | 75 | 76 | 83 | 84 |
AttributeTypesExampleDescription
tagstring"Education" 54 | 55 | The name of the tag. It is unique per client. 56 | 57 | 58 |
slugstring"education" 65 | 66 | The slug of the tag. It is unique per client and used to build urls. 67 | It must not contain any non url-safe characters. 68 | 69 | 70 |
projects_countnumber23 77 | 78 | The number of projects 79 | that were tagged with this tag. 80 | 81 | 82 |
85 | 86 | 87 | ## Response Links 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 100 | 106 | 107 |
LinknameDescription
96 | 97 | projects 98 | 99 | 101 | 102 | Link to the client-tag projects list – all projects that are tagged with given client-tag. 103 | 104 | 105 |
108 | 109 | ## Response Example 110 | 111 | ```json 112 | { 113 | "total_entries": 14, 114 | "offset": 0, 115 | "total_pages": 7, 116 | "current_page": 1, 117 | "per_page": 2, 118 | "data": [ 119 | { 120 | "tag": "Bedürftige", 121 | "slug": "Bedürftige", 122 | "projects_count": 13, 123 | "links": [ 124 | { 125 | "rel": "projects", 126 | "href": "https://api.betterplace.org/de/api_v4/clients/heidenheim/tags/Bed%C3%BCrftige/projects.json" 127 | } 128 | ] 129 | }, 130 | { 131 | "tag": "Inklusion", 132 | "slug": "Behinderte", 133 | "projects_count": 16, 134 | "links": [ 135 | { 136 | "rel": "projects", 137 | "href": "https://api.betterplace.org/de/api_v4/clients/heidenheim/tags/Behinderte/projects.json" 138 | } 139 | ] 140 | } 141 | ] 142 | } 143 | ``` 144 | 145 | -------------------------------------------------------------------------------- /sections/contact_data_details.md: -------------------------------------------------------------------------------- 1 | 2 | # User Contact Data Details 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/users/250285/contact_data.json 6 | ``` 7 | 8 | Name and email for the given user. 9 | 10 | Used by api clients to access data about 11 | the managers of projects that belog to this 12 | client. 13 | 14 | **:lock: Only available if authenticated as a client and only if this clients has permissions to access this data.** 15 | See [betterplace.org clients](../README.md#client-api). 16 | 17 | 18 | ## URL Parameters 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 36 | 37 |
ParameterExampleRequiredDescription
user_id250285yes 32 | 33 | User-id as an integer number. 34 | 35 |
38 | 39 | 40 | ## Response Attributes 41 | 42 | 43 | ### Root Attributes 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 61 | 62 | 63 | 64 | 65 | 66 | 71 | 72 | 73 | 74 | 75 | 76 | 81 | 82 |
AttributeTypesExampleDescription
first_namestringPeter 57 | 58 | The first name of the user or donor. 59 | 60 |
last_namestringPaul 67 | 68 | The last name of the user or donor. 69 | 70 |
emailstringpeter.paul@betterplace.org 77 | 78 | The email address of the user or donor. 79 | 80 |
83 | 84 | 85 | ## Response Links 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 |
LinknameDescription
No response example defined
94 | 95 | ## Response Example 96 | 97 | ```json 98 | { 99 | "first_name": "Taylan", 100 | "last_name": "Oswald", 101 | "email": "mjo@betterplace.org", 102 | "links": [ 103 | 104 | ] 105 | } 106 | ``` 107 | 108 | -------------------------------------------------------------------------------- /sections/fundraising_event_forwardings_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Fundraising Event Forwardings List 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/fundraising_events/19267/forwardings.json 6 | ``` 7 | 8 | A list of forwarings from the fundraising event to its projects. 9 | 10 | **This is an experimental feature and is still under heavy development. Please use it with caution.** 11 | 12 | 13 | ## URL Parameters 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 31 | 32 |
ParameterExampleRequiredDescription
fundraising_event_id19267yes 27 | 28 | Fundraising Event id as an integer number. 29 | 30 |
33 | 34 | 35 | ## Response Attributes 36 | 37 | 38 | ### Root Attributes 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 57 | 58 | 59 | 60 | 61 | 62 | 67 | 68 | 69 | 70 | 71 | 72 | 77 | 78 |
AttributeTypesExampleDescription
forwarded_amount_in_centsnumber12300 52 | 53 | The amount in cents the fundraising event has forwarded to this project. 54 | 55 | 56 |
titlestringRescue the turtles 63 | 64 | The name of the receiving project 65 | 66 |
project_idnumber1 73 | 74 | The ID of the receiving project 75 | 76 |
79 | 80 | 81 | ## Response Links 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 94 | 100 | 101 | 102 | 107 | 112 | 113 |
LinknameDescription
90 | 91 | project 92 | 93 | 95 | 96 | Link to the project to which the money was forwarded. 97 | 98 | 99 |
103 | 104 | platform 105 | 106 | 108 | 109 | Link to the project on betterplace.org. Can be blank if project is hidden. 110 | 111 |
114 | 115 | ## Response Example 116 | 117 | ```json 118 | { 119 | "total_entries": 2, 120 | "offset": null, 121 | "total_pages": 1, 122 | "current_page": 1, 123 | "per_page": null, 124 | "data": [ 125 | { 126 | "forwarded_amount_in_cents": 76900, 127 | "title": "Pro-A-kids e.V.-Hilfe für die Kinder Kongonis", 128 | "project_id": 358, 129 | "links": [ 130 | { 131 | "rel": "project", 132 | "href": "https://api.betterplace.org/de/api_v4/projects/358.json" 133 | }, 134 | { 135 | "rel": "platform", 136 | "href": "https://www.betterplace.org/de/projects/358-pro-a-kids-e-v-hilfe-fuer-die-kinder-kongonis" 137 | } 138 | ] 139 | }, 140 | { 141 | "forwarded_amount_in_cents": 15702, 142 | "title": "Die Arche: Mittagstisch für bedürftige Kinder", 143 | "project_id": 7910, 144 | "links": [ 145 | { 146 | "rel": "project", 147 | "href": "https://api.betterplace.org/de/api_v4/projects/7910.json" 148 | }, 149 | { 150 | "rel": "platform", 151 | "href": "https://www.betterplace.org/de/projects/7910-die-arche-mittagstisch-fuer-beduerftige-kinder" 152 | } 153 | ] 154 | } 155 | ] 156 | } 157 | ``` 158 | 159 | -------------------------------------------------------------------------------- /sections/matching_fund_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Matching Fund Details ⇄ [List](matching_funds_list.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/matching_funds/2.json 6 | ``` 7 | 8 | The details of a betterplace.org matching fund. 9 | The details and list view show the same data. 10 | 11 | 12 | ## URL Parameters 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 30 | 31 |
ParameterExampleRequiredDescription
id2yes 26 | 27 | matching-fund-id as an integer number. 28 | 29 |
32 | 33 | 34 | ## Response Attributes 35 | 36 | 37 | ### Root Attributes 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 55 | 56 | 57 | 58 | 59 | 60 | 65 | 66 | 67 | 68 | 69 | 70 | 75 | 76 | 77 | 78 | 79 | 80 | 85 | 86 | 87 | 88 | 89 | 90 | 95 | 96 | 97 | 98 | 99 | 100 | 105 | 106 | 107 | 108 | 109 | 110 | 115 | 116 | 117 | 118 | 119 | 120 | 125 | 126 | 127 | 128 | 129 | 130 | 135 | 136 | 137 | 138 | 139 | 140 | 145 | 146 | 147 | 148 | 149 | 150 | 155 | 156 | 157 | 158 | 159 | 160 | 165 | 166 | 167 | 168 | 169 | 170 | 175 | 176 |
AttributeTypesExampleDescription
idnumber1 51 | 52 | An integer number ≥ 1 53 | 54 |
created_atstring"1994-11-05T13:15:30Z" 61 | 62 | DateTime (ISO8601 with Timezone) 63 | 64 |
updated_atstring"1994-11-05T13:15:30Z" 71 | 72 | DateTime (ISO8601 with Timezone) 73 | 74 |
activated_atnull | string"1994-11-05T13:15:30Z" 81 | 82 | DateTime (ISO8601 with Timezone) 83 | 84 |
titlestringACME Matching Everything 91 | 92 | Our matching fund's name 93 | 94 |
descriptionstringIt's all about matching donations… 101 | 102 | The description of the matching fund 103 | 104 |
company_namestringACME 111 | 112 | The company that supports it 113 | 114 |
client_idstringclientname 121 | 122 | The client to which the matching fund belongs 123 | 124 |
provided_amount_in_centsnumber12300 131 | 132 | The amount in cents the company provided to be matched 133 | 134 |
donated_amount_in_centsnumber12300 141 | 142 | The amount in cents the company already donated 143 | 144 |
statestringactivated 151 | 152 | Current state of this matching fund: either activated or closed 153 | 154 |
logo_urlstringhttp://example.com/images/logo.png 161 | 162 | The URL of the logo image. 163 | 164 |
maximum_matching_amount_in_centsnumber10000 171 | 172 | Up to this amount donations get matched by the matching fund 173 | 174 |
177 | 178 | 179 | ## Response Links 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 192 | 199 | 200 | 201 | 206 | 211 | 212 | 213 | 218 | 225 | 226 | 227 | 232 | 238 | 239 |
LinknameDescription
188 | 189 | self 190 | 191 | 193 | 194 | Link to this resource itself 195 | (matching fund details) 196 | 197 | 198 |
202 | 203 | platform 204 | 205 | 207 | 208 | Permalink to betterplace.org 209 | 210 |
214 | 215 | projects 216 | 217 | 219 | 220 | Link to the list of projects 221 | belonging to this matching fund 222 | 223 | 224 |
228 | 229 | documentation 230 | 231 | 233 | 234 | Link to this resource in the documentation 235 | 236 | 237 |
240 | 241 | ## Response Example 242 | 243 | ```json 244 | { 245 | "id": 2, 246 | "created_at": "2013-10-14T15:26:19+02:00", 247 | "updated_at": "2016-10-27T16:34:11+02:00", 248 | "activated_at": "2013-10-21T09:54:41+02:00", 249 | "title": "Jetzt mitmachen – OTTO verdoppelt jede Spende!", 250 | "description": "### OTTO hilft Hamburgs Stadtgrün – helfen Sie mit!\n\nGemeinsam mit der Loki Schmidt Stiftung und der Stadt Hamburg schließen wir Baumlücken in strukturschwachen Stadtteilen. Diese Lücken entstehen aufgrund von Krankheiten oder mangelnder Standfestigkeit der Straßenbäume.\n\n\"\"\n\nSeit 2011 sind Hamburger Bürger aufgerufen, gemeinsam mit den beiden Partner-Organisationen für neue Bäume zu spenden.\n\nBereits in diesem Jahr hat OTTO das Projekt unterstützt und mit 25.000 Euro 50 Baumlücken in Gebieten geschlossen, in denen weniger gespendet wird – nämlich in Mümmelmannsberg, Nettelnburg, Steinbek, Steilshoop und Willhelmsburg!\n\nNun wollen wir noch weitere Bäume pflanzen – und zwar gemeinsam mit Ihnen!\n\n### Das funktioniert folgendermaßen:\n\n1. Sie spenden einen beliebig hohen Betrag auf betterplace.org. \n2. OTTO verdoppelt Ihren Betrag! \n3. Sobald durch Sie und OTTO 500 Euro zusammengekommen sind, legt die Stadt Hamburg die restlichen 500 Euro drauf, die für eine Pflanzung notwendig sind. \n4. Ein Baum wird gepflanzt – Hamburg wird grüner!\n\nIhr Engagement zählt – und OTTO honoriert das mit dieser Verdopplungsaktion bis zu einem Maximalbetrag von 15.000 Euro! Helfen Sie jetzt hier mit!\n\n", 251 | "company_name": "OTTO", 252 | "client_id": null, 253 | "provided_amount_in_cents": 521500, 254 | "donated_amount_in_cents": 521500, 255 | "state": "closed", 256 | "logo_url": "https://www.betterplace.dev/uploads/matching_fund/logo/000/000/002/bp1477578851_OTTO_QUADRAT_4c_M-mid.png", 257 | "maximum_matching_amount_in_cents": 10000, 258 | "links": [ 259 | { 260 | "rel": "self", 261 | "href": "https://api.betterplace.org/de/api_v4/matching_funds/2.json" 262 | }, 263 | { 264 | "rel": "platform", 265 | "href": "https://www.betterplace.org/de/matching-funds/2-otto" 266 | }, 267 | { 268 | "rel": "projects", 269 | "href": "https://api.betterplace.org/de/api_v4/matching_funds/2/projects.json" 270 | }, 271 | { 272 | "rel": "documentation", 273 | "href": "https://github.com/betterplace/betterplace_apidocs/blob/master/sections/matching_fund_details.md" 274 | } 275 | ] 276 | } 277 | ``` 278 | 279 | -------------------------------------------------------------------------------- /sections/matching_funds_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Matching Funds List ⇄ [Details](matching_fund_details.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/matching_funds.json?facets=state%3Aactivated 6 | ``` 7 | 8 | A list of betterplace.org matching funds. 9 | 10 | 11 | ## URL Parameters 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 33 | 34 | 35 | 36 | 37 | 38 | 45 | 46 |
ParameterExampleRequiredDescription
project_id28013no 25 | 26 | Optional project id as an integer number. 27 | Allows to filter the list of matching funds. 28 | This way one can show a list of matching funds where 29 | the given project is part of the matching fund projects list. 30 | 31 | 32 |
facetsstate:activatedno 39 | 40 | Filter the result set by state (activated|closed) 41 | Learn how to format the parameter. 42 | 43 | 44 |
47 | 48 | 49 | ## Response Attributes 50 | 51 | 52 | ### Root Attributes 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 70 | 71 | 72 | 73 | 74 | 75 | 80 | 81 | 82 | 83 | 84 | 85 | 90 | 91 | 92 | 93 | 94 | 95 | 100 | 101 | 102 | 103 | 104 | 105 | 110 | 111 | 112 | 113 | 114 | 115 | 120 | 121 | 122 | 123 | 124 | 125 | 130 | 131 | 132 | 133 | 134 | 135 | 140 | 141 | 142 | 143 | 144 | 145 | 150 | 151 | 152 | 153 | 154 | 155 | 160 | 161 | 162 | 163 | 164 | 165 | 170 | 171 | 172 | 173 | 174 | 175 | 180 | 181 | 182 | 183 | 184 | 185 | 190 | 191 |
AttributeTypesExampleDescription
idnumber1 66 | 67 | An integer number ≥ 1 68 | 69 |
created_atstring"1994-11-05T13:15:30Z" 76 | 77 | DateTime (ISO8601 with Timezone) 78 | 79 |
updated_atstring"1994-11-05T13:15:30Z" 86 | 87 | DateTime (ISO8601 with Timezone) 88 | 89 |
activated_atnull | string"1994-11-05T13:15:30Z" 96 | 97 | DateTime (ISO8601 with Timezone) 98 | 99 |
titlestringACME Matching Everything 106 | 107 | Our matching fund's name 108 | 109 |
descriptionstringIt's all about matching donations… 116 | 117 | The description of the matching fund 118 | 119 |
company_namestringACME 126 | 127 | The company that supports it 128 | 129 |
client_idstringclientname 136 | 137 | The client to which the matching fund belongs 138 | 139 |
provided_amount_in_centsnumber12300 146 | 147 | The amount in cents the company provided to be matched 148 | 149 |
donated_amount_in_centsnumber12300 156 | 157 | The amount in cents the company already donated 158 | 159 |
statestringactivated 166 | 167 | Current state of this matching fund: either activated or closed 168 | 169 |
logo_urlstringhttp://example.com/images/logo.png 176 | 177 | The URL of the logo image. 178 | 179 |
maximum_matching_amount_in_centsnumber10000 186 | 187 | Up to this amount donations get matched by the matching fund 188 | 189 |
192 | 193 | 194 | ## Response Links 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 207 | 214 | 215 | 216 | 221 | 226 | 227 | 228 | 233 | 240 | 241 | 242 | 247 | 253 | 254 |
LinknameDescription
203 | 204 | self 205 | 206 | 208 | 209 | Link to this resource itself 210 | (matching fund details) 211 | 212 | 213 |
217 | 218 | platform 219 | 220 | 222 | 223 | Permalink to betterplace.org 224 | 225 |
229 | 230 | projects 231 | 232 | 234 | 235 | Link to the list of projects 236 | belonging to this matching fund 237 | 238 | 239 |
243 | 244 | documentation 245 | 246 | 248 | 249 | Link to this resource in the documentation 250 | 251 | 252 |
255 | 256 | ## Response Example 257 | 258 | ```json 259 | { 260 | "total_entries": 9, 261 | "offset": 0, 262 | "total_pages": 5, 263 | "current_page": 1, 264 | "per_page": 2, 265 | "data": [ 266 | { 267 | "id": 11, 268 | "created_at": "2015-10-29T17:06:32+01:00", 269 | "updated_at": "2016-10-27T16:34:28+02:00", 270 | "activated_at": "2015-10-31T08:33:12+01:00", 271 | "title": "Fressnapf verdoppelt deine Spende", 272 | "description": "", 273 | "company_name": "Fressnapf", 274 | "client_id": "fressnapf", 275 | "provided_amount_in_cents": 1000000, 276 | "donated_amount_in_cents": 1000000, 277 | "state": "closed", 278 | "logo_url": "https://www.betterplace.dev/uploads/matching_fund/logo/000/000/011/bp1477578868_Logo_Fressnapf.png", 279 | "maximum_matching_amount_in_cents": 10000, 280 | "links": [ 281 | { 282 | "rel": "self", 283 | "href": "https://api.betterplace.org/de/api_v4/matching_funds/11.json" 284 | }, 285 | { 286 | "rel": "platform", 287 | "href": "https://www.betterplace.org/de/matching-funds/11-fressnapf" 288 | }, 289 | { 290 | "rel": "projects", 291 | "href": "https://api.betterplace.org/de/api_v4/matching_funds/11/projects.json" 292 | }, 293 | { 294 | "rel": "documentation", 295 | "href": "https://github.com/betterplace/betterplace_apidocs/blob/master/sections/matching_fund_details.md" 296 | } 297 | ] 298 | }, 299 | { 300 | "id": 34, 301 | "created_at": "2016-04-13T15:57:01+02:00", 302 | "updated_at": "2016-11-29T14:54:07+01:00", 303 | "activated_at": "2016-07-07T09:59:35+02:00", 304 | "title": "2016-07-07 Gut für Köln und Bonn", 305 | "description": "Die Sparkasse KölnBonn verdoppelt Deine Spende auf gut-fuer-koeln-und-bonn.de!", 306 | "company_name": "Die Sparkasse KölnBonn", 307 | "client_id": "sk-koelnbonn", 308 | "provided_amount_in_cents": 997500, 309 | "donated_amount_in_cents": 997500, 310 | "state": "closed", 311 | "logo_url": null, 312 | "maximum_matching_amount_in_cents": 10000, 313 | "links": [ 314 | { 315 | "rel": "self", 316 | "href": "https://api.betterplace.org/de/api_v4/matching_funds/34.json" 317 | }, 318 | { 319 | "rel": "platform", 320 | "href": "https://www.betterplace.org/de/matching-funds/34-die-sparkasse-koelnbonn" 321 | }, 322 | { 323 | "rel": "projects", 324 | "href": "https://api.betterplace.org/de/api_v4/matching_funds/34/projects.json" 325 | }, 326 | { 327 | "rel": "documentation", 328 | "href": "https://github.com/betterplace/betterplace_apidocs/blob/master/sections/matching_fund_details.md" 329 | } 330 | ] 331 | } 332 | ] 333 | } 334 | ``` 335 | 336 | -------------------------------------------------------------------------------- /sections/need_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Need Details ⇄ [List](needs_list.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/projects/1114/needs/59220.json 6 | ``` 7 | 8 | The details of a betterplace.org project need (donate money). 9 | The details and list view show the same data per project need. 10 | 11 | **For [betterplace.org clients](../README.md#client-api):** 12 | There is no client-scoped URL. 13 | Please use the API calls that are provided inside the client project _url_ response 14 | to make sure you only request data that is associated with one of your projects. 15 | 16 | 17 | ## URL Parameters 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 35 | 36 | 37 | 38 | 39 | 40 | 45 | 46 |
ParameterExampleRequiredDescription
project_id1114yes 31 | 32 | Project id as an integer number. 33 | 34 |
id59220yes 41 | 42 | Need-id as an integer number. 43 | 44 |
47 | 48 | 49 | ## Response Attributes 50 | 51 | 52 | ### Root Attributes 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 70 | 71 | 72 | 73 | 74 | 75 | 80 | 81 | 82 | 83 | 84 | 85 | 90 | 91 | 92 | 93 | 94 | 95 | 100 | 101 | 102 | 103 | 104 | 105 | 110 | 111 | 112 | 113 | 114 | 115 | 120 | 121 | 122 | 123 | 124 | 125 | 130 | 131 | 132 | 133 | 134 | 135 | 146 | 147 | 148 | 149 | 150 | 151 | 156 | 157 | 158 | 159 | 160 | 161 | 166 | 167 |
AttributeTypesExampleDescription
idnumber1 66 | 67 | An integer number ≥ 1 68 | 69 |
created_atstring"1994-11-05T13:15:30Z" 76 | 77 | DateTime (ISO8601 with Timezone) 78 | 79 |
updated_atstring"1994-11-05T13:15:30Z" 86 | 87 | DateTime (ISO8601 with Timezone) 88 | 89 |
titlestring 96 | 97 | Max 50 character 98 | 99 |
descriptionstring 106 | 107 | 108 | 109 |
completedbooleanfalse 116 | 117 | True if the need is 100 % financed 118 | 119 |
progress_percentagenumber82 126 | 127 | % financed 128 | 129 |
donated_amount_in_centsnumber12382 136 | 137 | How many cents are donated already. 138 | This includes all donations that can be given to a need 139 | (direct donation, forwarding of project donation, 140 | forwarding of organisation donation, 141 | forwarding of fundraising event donations, 142 | offline donations and also(!) external donations) 143 | 144 | 145 |
open_amount_in_centsnumber12382 152 | 153 | How many cents are still needed to complete the need 154 | 155 |
requested_amount_in_centsnumber12382 162 | 163 | How much money is needed in total 164 | 165 |
168 | 169 | 170 | ## Response Links 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 183 | 190 | 191 | 192 | 197 | 203 | 204 | 205 | 210 | 216 | 217 | 218 | 223 | 229 | 230 |
LinknameDescription
179 | 180 | self 181 | 182 | 184 | 185 | Link to this resource itself 186 | (need details) 187 | 188 | 189 |
193 | 194 | project 195 | 196 | 198 | 199 | Link to the related project's details 200 | 201 | 202 |
206 | 207 | new_client_donation 208 | 209 | 211 | 212 | Link to the donation form. Templated, needs insertion of the client_id. 213 | 214 | 215 |
219 | 220 | new_donation 221 | 222 | 224 | 225 | Link to the regular donation form. 226 | 227 | 228 |
231 | 232 | ## Response Example 233 | 234 | ```json 235 | { 236 | "id": 357682, 237 | "created_at": "2021-11-23T13:43:53+01:00", 238 | "updated_at": "2022-08-30T08:42:43+02:00", 239 | "title": "Skateistan: A New Chapter", 240 | "description": "Unser Ziel: im Laufe des nächsten Jahres auf 20 Standorte zu expandieren und jede Woche 4 500 Schüler zu erreichen. Helft uns, das nächste Kapitel der Geschichte von Skateistan zu schreiben!", 241 | "completed": false, 242 | "progress_percentage": 22.03, 243 | "donated_amount_in_cents": 110135, 244 | "open_amount_in_cents": 389865, 245 | "requested_amount_in_cents": 500000, 246 | "links": [ 247 | { 248 | "rel": "self", 249 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/needs/357682.json" 250 | }, 251 | { 252 | "rel": "project", 253 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 254 | }, 255 | { 256 | "rel": "new_client_donation", 257 | "href": "https://www.betterplace.org/de/donate/%7Bclient_id%7D/projects/1114?need_id=357682", 258 | "templated": true 259 | }, 260 | { 261 | "rel": "new_donation", 262 | "href": "https://www.betterplace.org/de/donate/platform/projects/1114?need_id=357682" 263 | } 264 | ] 265 | } 266 | ``` 267 | 268 | -------------------------------------------------------------------------------- /sections/needs_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Needs List ⇄ [Details](need_details.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/projects/1114/needs.json?facets=completed%3Afalse&order=position%3AASC 6 | ``` 7 | 8 | A list of betterplace.org projects needs (donate money). 9 | Results are contained in a *data* attribute. 10 | The details and list view show the same data per project need. 11 | 12 | **For [betterplace.org clients](../README.md#client-api):** 13 | There is no client-scoped URL. 14 | Please use the API calls that are provided inside the client project _url_ response 15 | to make sure you only request data that is associated with one of your projects. 16 | 17 | 18 | ## URL Parameters 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 36 | 37 | 38 | 39 | 40 | 41 | 52 | 53 | 54 | 55 | 56 | 57 | 68 | 69 |
ParameterExampleRequiredDescription
project_id1114yes 32 | 33 | Project id as an integer number. 34 | 35 |
facetscompleted:falseno 42 | 43 | Filter the result set. 44 | Documented and supported filters are: 45 |
    46 |
  • completed:true/false – is this need fully funded? 47 |
48 | Learn how to format the parameter. 49 | 50 | 51 |
orderposition:ASCno 58 | 59 | Order the result set. Documented and supported orders are: 60 |
    61 |
  • created_at:asc/desc – DESC: Latest needs first. 62 |
  • position:asc/desc – Priority of the need defined by the project manager 63 |
64 | Learn how to format the parameter. 65 | 66 | 67 |
70 | 71 | 72 | ## Response Attributes 73 | 74 | 75 | ### Root Attributes 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 93 | 94 | 95 | 96 | 97 | 98 | 103 | 104 | 105 | 106 | 107 | 108 | 113 | 114 | 115 | 116 | 117 | 118 | 123 | 124 | 125 | 126 | 127 | 128 | 133 | 134 | 135 | 136 | 137 | 138 | 143 | 144 | 145 | 146 | 147 | 148 | 153 | 154 | 155 | 156 | 157 | 158 | 169 | 170 | 171 | 172 | 173 | 174 | 179 | 180 | 181 | 182 | 183 | 184 | 189 | 190 |
AttributeTypesExampleDescription
idnumber1 89 | 90 | An integer number ≥ 1 91 | 92 |
created_atstring"1994-11-05T13:15:30Z" 99 | 100 | DateTime (ISO8601 with Timezone) 101 | 102 |
updated_atstring"1994-11-05T13:15:30Z" 109 | 110 | DateTime (ISO8601 with Timezone) 111 | 112 |
titlestring 119 | 120 | Max 50 character 121 | 122 |
descriptionstring 129 | 130 | 131 | 132 |
completedbooleanfalse 139 | 140 | True if the need is 100 % financed 141 | 142 |
progress_percentagenumber82 149 | 150 | % financed 151 | 152 |
donated_amount_in_centsnumber12382 159 | 160 | How many cents are donated already. 161 | This includes all donations that can be given to a need 162 | (direct donation, forwarding of project donation, 163 | forwarding of organisation donation, 164 | forwarding of fundraising event donations, 165 | offline donations and also(!) external donations) 166 | 167 | 168 |
open_amount_in_centsnumber12382 175 | 176 | How many cents are still needed to complete the need 177 | 178 |
requested_amount_in_centsnumber12382 185 | 186 | How much money is needed in total 187 | 188 |
191 | 192 | 193 | ## Response Links 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 206 | 213 | 214 | 215 | 220 | 226 | 227 | 228 | 233 | 239 | 240 | 241 | 246 | 252 | 253 |
LinknameDescription
202 | 203 | self 204 | 205 | 207 | 208 | Link to this resource itself 209 | (need details) 210 | 211 | 212 |
216 | 217 | project 218 | 219 | 221 | 222 | Link to the related project's details 223 | 224 | 225 |
229 | 230 | new_client_donation 231 | 232 | 234 | 235 | Link to the donation form. Templated, needs insertion of the client_id. 236 | 237 | 238 |
242 | 243 | new_donation 244 | 245 | 247 | 248 | Link to the regular donation form. 249 | 250 | 251 |
254 | 255 | ## Response Example 256 | 257 | ```json 258 | { 259 | "total_entries": 110, 260 | "offset": 0, 261 | "total_pages": 37, 262 | "current_page": 1, 263 | "per_page": 3, 264 | "data": [ 265 | { 266 | "id": 5228, 267 | "created_at": "2009-03-10T11:38:39+01:00", 268 | "updated_at": "2017-07-04T15:09:32+02:00", 269 | "title": "Warme Mahlzeiten", 270 | "description": "Wer sich viel bewegt, der muss auch richtig essen: Mit nur 50 Euro im Monat lassen sich 8-10 warme Mahlzeiten für rund 30 Waisenkinder bereitstellen, die zweimal in der Woche von dem Skateistan-Team besucht werden und lernen Skateboard zu fahren.", 271 | "completed": true, 272 | "progress_percentage": 100.0, 273 | "donated_amount_in_cents": 5000, 274 | "open_amount_in_cents": 0, 275 | "requested_amount_in_cents": 5000, 276 | "links": [ 277 | { 278 | "rel": "self", 279 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/needs/5228.json" 280 | }, 281 | { 282 | "rel": "project", 283 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 284 | }, 285 | { 286 | "rel": "new_client_donation", 287 | "href": "https://www.betterplace.org/de/donate/%7Bclient_id%7D/projects/1114?need_id=5228", 288 | "templated": true 289 | }, 290 | { 291 | "rel": "new_donation", 292 | "href": "https://www.betterplace.org/de/donate/platform/projects/1114?need_id=5228" 293 | } 294 | ] 295 | }, 296 | { 297 | "id": 5229, 298 | "created_at": "2009-03-10T11:54:30+01:00", 299 | "updated_at": "2017-07-04T15:09:32+02:00", 300 | "title": "Skateboardlehrer", 301 | "description": "Mirwais, 13, ist Afghanistans erster talentierter Skateboardlehrer. Früher wusch er für 2 Dollar am Tag Autos auf der Straße. Heute ist er Skateistans Angestellter und kann mit seinem Gehalt (167 Euro/Monat) seine Familie ernähren.", 302 | "completed": true, 303 | "progress_percentage": 100.0, 304 | "donated_amount_in_cents": 16700, 305 | "open_amount_in_cents": 0, 306 | "requested_amount_in_cents": 16700, 307 | "links": [ 308 | { 309 | "rel": "self", 310 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/needs/5229.json" 311 | }, 312 | { 313 | "rel": "project", 314 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 315 | }, 316 | { 317 | "rel": "new_client_donation", 318 | "href": "https://www.betterplace.org/de/donate/%7Bclient_id%7D/projects/1114?need_id=5229", 319 | "templated": true 320 | }, 321 | { 322 | "rel": "new_donation", 323 | "href": "https://www.betterplace.org/de/donate/platform/projects/1114?need_id=5229" 324 | } 325 | ] 326 | }, 327 | { 328 | "id": 5237, 329 | "created_at": "2009-03-10T15:22:08+01:00", 330 | "updated_at": "2017-07-04T15:09:32+02:00", 331 | "title": "Skateboardlehrer", 332 | "description": "Mirwais, 16, ist Afghanistans erster talentierter Skateboardlehrer. Früher wusch er für 2 Dollar am Tag Autos auf der Straße. Heute ist er Skateistans Angestellter und kann mit seinem Gehalt (167 Euro/Monat) seine Familie ernähren.", 333 | "completed": true, 334 | "progress_percentage": 100.0, 335 | "donated_amount_in_cents": 16700, 336 | "open_amount_in_cents": 0, 337 | "requested_amount_in_cents": 16700, 338 | "links": [ 339 | { 340 | "rel": "self", 341 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/needs/5237.json" 342 | }, 343 | { 344 | "rel": "project", 345 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 346 | }, 347 | { 348 | "rel": "new_client_donation", 349 | "href": "https://www.betterplace.org/de/donate/%7Bclient_id%7D/projects/1114?need_id=5237", 350 | "templated": true 351 | }, 352 | { 353 | "rel": "new_donation", 354 | "href": "https://www.betterplace.org/de/donate/platform/projects/1114?need_id=5237" 355 | } 356 | ] 357 | } 358 | ] 359 | } 360 | ``` 361 | 362 | -------------------------------------------------------------------------------- /sections/opinions_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Opinions List 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/projects/1114/opinions.json?facets=has_message%3Atrue&order=confirmed_at%3ADESC 6 | ``` 7 | 8 | A list of betterplace.org projects or fundraising event opinions (donate money). 9 | There is no details view for opinions. 10 | 11 | * Example for project opinions `…/api_v4/projects/1114/opinions.json` 12 | * Example for fundraising event opinions `…/api_v4/fundraising_events/19267/opinions.json` 13 | 14 | Results are contained in a *data* attribute. 15 | 16 | 17 | ## URL Parameters 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 38 | 39 | 40 | 41 | 42 | 43 | 51 | 52 | 53 | 54 | 55 | 56 | 79 | 80 | 81 | 82 | 83 | 84 | 95 | 96 |
ParameterExampleRequiredDescription
project_id1114no 31 | 32 | Project id as an integer number. 33 | This parameter is required in case you want to show project opinions. 34 | Also check the URL example in the introduction. 35 | 36 | 37 |
fundraising_event_id19267no 44 | 45 | Fundraising Event id as an integer number. 46 | This parameter is required in case you want to show fundraising event opinions. 47 | Also check the URL example in the introduction. 48 | 49 | 50 |
orderconfirmed_at:DESCno 57 | 58 | Order the result set. 59 |
60 | It is strongly recommended to specify an order with each request. 61 | The default order might change at any time without notice. 62 | A recommended order is confirmed_at:DESC, which sorts the 63 | project opinions by the confirmation time in descending order. 64 | This is also the order of the opinions 65 | list on the betterplae project details page.
66 | Other supported orders are: 67 |
    68 |
  • created_at:ASC/DESC 69 |
  • updated_at:ASC/DESC 70 |
  • confirmed_at:ASC/DESC 71 |
  • id:ASC/DESC 72 |
  • amount_in_cents:ASC/DESC 73 |
74 | It is possible to set multiple order parameters. 75 | Learn how to format the parameter. 76 | 77 | 78 |
facetshas_message:trueno 85 | 86 | Filter the result set. 87 | Documented and supported filters are: 88 |
    89 |
  • has_message:true/false – did the donor add a message to her donation 90 |
91 | Learn how to format the parameter. 92 | 93 | 94 |
97 | 98 | 99 | ## Response Attributes 100 | 101 | 102 | ### Root Attributes 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 120 | 121 | 122 | 123 | 124 | 125 | 130 | 131 | 132 | 133 | 134 | 135 | 140 | 141 | 142 | 143 | 144 | 145 | 157 | 158 | 159 | 160 | 161 | 162 | 173 | 174 | 175 | 176 | 177 | 178 | 186 | 187 | 188 | 189 | 190 | 191 | 197 | 198 | 199 | 200 | 201 | 202 | 208 | 209 | 210 | 215 | 216 | 217 | 223 | 224 | 225 | 230 | 231 | 232 | 238 | 239 | 240 | 241 | 242 | 243 | 251 | 252 | 253 | 254 | 255 | 256 | 261 | 262 |
AttributeTypesExampleDescription
idnumber1 116 | 117 | An integer number ≥ 1 118 | 119 |
created_atstring"1994-11-05T13:15:30Z" 126 | 127 | DateTime (ISO8601 with Timezone) 128 | 129 |
updated_atstring"1994-11-05T13:15:30Z" 136 | 137 | DateTime (ISO8601 with Timezone) 138 | 139 |
donated_amount_in_centsnumber5000 146 | 147 | The amount donated, but only if the user allowed the amount to be 148 | visible. Most donation forms allow the donor to specify if they 149 | want their amount to be visible. As a default, the donated amount 150 | is visible. 151 | 152 | Known issue: For forwarding donations (money that is forwarded from a fundraising event to a project) 153 | this field is always empty, which is wrong. 154 | 155 | 156 |
matched_amount_in_centsnumber5000 163 | 164 | If a matching fund was active during the donation then the amount 165 | donated by a user might was matched with another donation. 166 | 167 | This amount is normally as high as the actual donation amount, with some 168 | restrictions, e.g. when the matching fund is depleted or the donation 169 | was higher than the maximum matching threshold. 170 | 171 | 172 |
matchedbooleantrue 179 | 180 | The matched field is true if this is a donor opinion for a donation that 181 | was matched by a matching fund. 182 | It's false otherwise. 183 | 184 | 185 |
client_namestringPAYBACK Spendenwelt 192 | 193 | Name of the related client, if available. 194 | 195 | 196 |
scorestringpositive 203 | 204 | DEPRECATED 2017-06-16 - Always returns "positive" 205 | 206 | 207 |
211 | 212 | ↓author 213 | 214 | null | objectTODO 218 | 219 | Donor information, if available. 220 | 221 | 222 |
226 | 227 | ↓backed_by_fundraising_event 228 | 229 | objectTODO 233 | 234 | Information about the fundraising event through which the donation came in, if available. 235 | 236 | 237 |
messagenull | string"This is a great project. In spring 2007 I travelled around the area together with my children and …" 244 | 245 | An optional message by users. 246 | 247 | The body is plain text potentially containing line-breaks. 248 | 249 | 250 |
confirmed_atstring"1994-11-05T13:15:30Z" 257 | 258 | DateTime (ISO8601 with Timezone) 259 | 260 |
263 | 264 | ### ↑Nested Attributes: author 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 282 | 283 | 284 | 285 | 286 | 287 | 297 | 298 | 299 | 304 | 305 | 306 | 311 | 312 |
AttributeTypesExampleDescription
author.idnumber1 278 | 279 | An integer number ≥ 1 280 | 281 |
author.namenull | string"Till B." 288 | 289 | Display name of a betterplace.org user. 290 | Possible formats: "Till B.", "T. Behnke", "Till Behnke". 291 | 292 | In the case of donation-opinions the name might also be 293 | empty/null for anonymous donations for anonymous donations. 294 | 295 | 296 |
300 | 301 | ↓author.picture 302 | 303 | object//betterplace-assets.betterplace.org ↪/uploads/user/profile_picture ↪/000/000/001 ↪/fill_100x100_original_tb.jpg 307 | 308 | User profile picture or a fallback image 309 | 310 |
313 | 314 | ### ↑Nested Attributes: author.picture 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 332 | 333 |
AttributeTypesExampleDescription
author.picture.fallbackbooleantrue 328 | 329 | Specifies whether a fallback image is given or not 330 | 331 |
334 | 335 | ### ↑Nested Attributes: backed_by_fundraising_event 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 353 | 354 | 355 | 356 | 357 | 358 | 364 | 365 | 366 | 367 | 368 | 369 | 375 | 376 | 377 | 378 | 379 | 380 | 386 | 387 | 388 | 389 | 390 | 391 | 397 | 398 |
AttributeTypesExampleDescription
backed_by_fundraising_event.idnumber1 349 | 350 | An integer number ≥ 1 351 | 352 |
backed_by_fundraising_event.urlstringLorem ipsum 359 | 360 | URL of the fundraising event 361 | 362 | 363 |
backed_by_fundraising_event.titlestringLorem ipsum 370 | 371 | Title of the fundraising event 372 | 373 | 374 |
backed_by_fundraising_event.donor_countnumber100 381 | 382 | Number of donors who donated to the fundraising event 383 | 384 | 385 |
backed_by_fundraising_event.sponsoring_namestringCompany XY 392 | 393 | Company name if it is a sponsored fundraising event 394 | 395 | 396 |
399 | 400 | 401 | ## Response Links 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 414 | 421 | 422 | 423 | 428 | 435 | 436 | 437 | 442 | 449 | 450 | 451 | 456 | 465 | 466 | 467 | 472 | 480 | 481 | 482 | 487 | 492 | 493 | 494 | 499 | 504 | 505 | 506 | 511 | 516 | 517 |
LinknameDescription
410 | 411 | project 412 | 413 | 415 | 416 | Link to the project this opinion belongs to 417 | (project details) 418 | 419 | 420 |
424 | 425 | fundraising_event 426 | 427 | 429 | 430 | Link to the fundraising event this opinion belongs to 431 | (fundraising event details) 432 | 433 | 434 |
438 | 439 | matching_fund 440 | 441 | 443 | 444 | Link to the matching fund that matched this donation. 445 | (matching fund details) 446 | 447 | 448 |
452 | 453 | author.platform 454 | 455 | 457 | 458 | The user's profile on betterplace.org. 459 | To view a user profile you have to be logged in. 460 | This array is empty if the user has no useraccount 461 | with betterplace.org but donated via one of our partner. 462 | 463 | 464 |
468 | 469 | author.contact_data 470 | 471 | 473 | 474 | The user's contact data. Please note that you need to be 475 | authenticated as a client with matching 476 | access rights in order to see this information. 477 | 478 | 479 |
483 | 484 | author.picture.fill_100x100 485 | 486 | 488 | 489 | 100×100 Pixel 490 | 491 |
495 | 496 | author.picture.original 497 | 498 | 500 | 501 | Maximum sized image. This is the original image with default-cropping or user-cropping applied. 502 | 503 |
507 | 508 | backed_by_fundraising_event.sponsoring_logo 509 | 510 | 512 | 513 | Sponsoring Logo 514 | 515 |
518 | 519 | ## Response Example 520 | 521 | ```json 522 | { 523 | "total_entries": 1, 524 | "offset": 0, 525 | "total_pages": 1, 526 | "current_page": 1, 527 | "per_page": 3, 528 | "data": [ 529 | { 530 | "id": 357891, 531 | "created_at": "2012-04-19T16:08:51+02:00", 532 | "updated_at": "2016-11-28T15:40:02+01:00", 533 | "matched": false, 534 | "score": "positive", 535 | "author": { 536 | "name": "Logan Jackson", 537 | "picture": { 538 | "links": [ 539 | { 540 | "rel": "fill_100x100", 541 | "href": "https://betterplace-assets.betterplace.org/uploads/donation/profile_picture/d94/884/32c58c9bb85f004661cfa5bdc614e0dc2/fill_100x100_bp1480344002_crop_original_bp1469459430_20160505-DSC_0627.jpg" 542 | }, 543 | { 544 | "rel": "original", 545 | "href": "https://betterplace-assets.betterplace.org/uploads/donation/profile_picture/d94/884/32c58c9bb85f004661cfa5bdc614e0dc2/crop_original_bp1480344002_crop_original_bp1469459430_20160505-DSC_0627.jpg" 546 | } 547 | ] 548 | }, 549 | "links": [ 550 | 551 | ] 552 | }, 553 | "message": "", 554 | "confirmed_at": "2012-04-19T16:08:51+02:00", 555 | "links": [ 556 | { 557 | "rel": "project", 558 | "href": "https://api.betterplace.org/de/api_v4/projects/9241.json" 559 | } 560 | ] 561 | } 562 | ] 563 | } 564 | ``` 565 | 566 | -------------------------------------------------------------------------------- /sections/organisation_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Organisation Details ⇄ [List](organisations_list.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/organisations/125.json 6 | ``` 7 | 8 | The details of a betterplace.org organisation. 9 | The details and list view show the same data per organisation. 10 | 11 | **For [betterplace.org clients](../README.md#client-api):** 12 | There is no client-scoped URL. 13 | Please use the API calls that are provided inside the client project _url_ response 14 | to make sure you only request data that is associated with one of your projects. 15 | 16 | 17 | ## URL Parameters 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 35 | 36 |
ParameterExampleRequiredDescription
id125yes 31 | 32 | Organisation-id as an integer number. 33 | 34 |
37 | 38 | 39 | ## Response Attributes 40 | 41 | 42 | ### Root Attributes 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 60 | 61 | 62 | 63 | 64 | 65 | 70 | 71 | 72 | 73 | 74 | 75 | 80 | 81 | 82 | 83 | 84 | 85 | 90 | 91 | 92 | 93 | 94 | 95 | 100 | 101 | 102 | 103 | 104 | 105 | 110 | 111 | 112 | 113 | 114 | 115 | 120 | 121 | 122 | 123 | 124 | 125 | 130 | 131 | 132 | 133 | 134 | 135 | 140 | 141 | 142 | 143 | 144 | 145 | 150 | 151 | 152 | 153 | 154 | 155 | 162 | 163 | 164 | 165 | 166 | 167 | 172 | 173 | 174 | 175 | 176 | 177 | 184 | 185 | 186 | 187 | 188 | 189 | 197 | 198 | 199 | 204 | 205 | 206 | 211 | 212 | 213 | 218 | 219 | 220 | 225 | 226 |
AttributeTypesExampleDescription
idnumber1 56 | 57 | An integer number ≥ 1 58 | 59 |
created_atstring"1994-11-05T13:15:30Z" 66 | 67 | DateTime (ISO8601 with Timezone) 68 | 69 |
updated_atstring"1994-11-05T13:15:30Z" 76 | 77 | DateTime (ISO8601 with Timezone) 78 | 79 |
latitudenumber52.499007 86 | 87 | Decimal degrees based on user input 88 | 89 |
longitudenumber13.44947 96 | 97 | Decimal degrees based on user input 98 | 99 |
streetnull | string"Schlesische Straße 26" 106 | 107 | Street address 108 | 109 |
zipnull | string"10997" 116 | 117 | ZIP code 118 | 119 |
citynull | string"Berlin" 126 | 127 | Name of the city 128 | 129 |
countrynull | string"Deutschland" 136 | 137 | Name of the country 138 | 139 |
content_updated_atstring"1994-11-05T13:15:30Z" 146 | 147 | DateTime (ISO8601 with Timezone) 148 | 149 |
slugstringvivaconagua 156 | 157 | URL slug 158 | for the permalink 159 | 160 | 161 |
namestring"Viva con Agua de Sankt Pauli e.V." 168 | 169 | Name of the organisation 170 | 171 |
descriptionstring 178 | 179 | A description of the organisation. 180 | This may contain br tags. 181 | 182 | 183 |
tax_deductiblebooleantrue 190 | 191 | ⚠️ DEPRECATED! 192 | 193 | This value is deprecated and will be removed. 194 | 195 | 196 |
200 | 201 | ↓contact 202 | 203 | object 207 | 208 | The public contact person for this organisation. 209 | 210 |
214 | 215 | ↓picture 216 | 217 | null | object 221 | 222 | TODO 223 | 224 |
227 | 228 | ### ↑Nested Attributes: contact 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 241 | 246 | 247 | 248 | 249 | 250 | 251 | 261 | 262 | 263 | 268 | 269 | 270 | 275 | 276 |
AttributeTypesExampleDescription
contact.idnumber1 242 | 243 | An integer number ≥ 1 244 | 245 |
contact.namenull | string"Till B." 252 | 253 | Display name of a betterplace.org user. 254 | Possible formats: "Till B.", "T. Behnke", "Till Behnke". 255 | 256 | In the case of donation-opinions the name might also be 257 | empty/null for anonymous donations for anonymous donations. 258 | 259 | 260 |
264 | 265 | ↓contact.picture 266 | 267 | object//betterplace-assets.betterplace.org ↪/uploads/user/profile_picture ↪/000/000/001 ↪/fill_100x100_original_tb.jpg 271 | 272 | User profile picture or a fallback image 273 | 274 |
277 | 278 | ### ↑Nested Attributes: contact.picture 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 296 | 297 |
AttributeTypesExampleDescription
contact.picture.fallbackbooleantrue 292 | 293 | Specifies whether a fallback image is given or not 294 | 295 |
298 | 299 | ### ↑Nested Attributes: picture 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 317 | 318 |
AttributeTypesExampleDescription
picture.fallbackbooleantrue 313 | 314 | Specifies whether a fallback image is given or not 315 | 316 |
319 | 320 | 321 | ## Response Links 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 334 | 341 | 342 | 343 | 348 | 353 | 354 | 355 | 360 | 366 | 367 | 368 | 373 | 378 | 379 | 380 | 385 | 394 | 395 | 396 | 401 | 409 | 410 | 411 | 416 | 421 | 422 | 423 | 428 | 433 | 434 | 435 | 440 | 445 | 446 | 447 | 452 | 457 | 458 | 459 | 464 | 469 | 470 | 471 | 476 | 481 | 482 |
LinknameDescription
330 | 331 | self 332 | 333 | 335 | 336 | Link to this resource itself 337 | (organisation details) 338 | 339 | 340 |
344 | 345 | platform 346 | 347 | 349 | 350 | Permalink to betterplace.org 351 | 352 |
356 | 357 | projects 358 | 359 | 361 | 362 | Link to the project list of this organisation 363 | 364 | 365 |
369 | 370 | website 371 | 372 | 374 | 375 | Link to the website of this organisation. 376 | 377 |
381 | 382 | contact.platform 383 | 384 | 386 | 387 | The user's profile on betterplace.org. 388 | To view a user profile you have to be logged in. 389 | This array is empty if the user has no useraccount 390 | with betterplace.org but donated via one of our partner. 391 | 392 | 393 |
397 | 398 | contact.contact_data 399 | 400 | 402 | 403 | The user's contact data. Please note that you need to be 404 | authenticated as a client with matching 405 | access rights in order to see this information. 406 | 407 | 408 |
412 | 413 | contact.picture.fill_100x100 414 | 415 | 417 | 418 | 100×100 Pixel 419 | 420 |
424 | 425 | contact.picture.original 426 | 427 | 429 | 430 | Maximum sized image. This is the original image with default-cropping or user-cropping applied. 431 | 432 |
436 | 437 | picture.fill_100x100 438 | 439 | 441 | 442 | 100×100 Pixel 443 | 444 |
448 | 449 | picture.fill_200x200 450 | 451 | 453 | 454 | 200×200 Pixel 455 | 456 |
460 | 461 | picture.fill_400x400 462 | 463 | 465 | 466 | 400×400 Pixel 467 | 468 |
472 | 473 | picture.original 474 | 475 | 477 | 478 | Maximum sized image. This is the original image with default-cropping or user-cropping applied. 479 | 480 |
483 | 484 | ## Response Example 485 | 486 | ```json 487 | { 488 | "id": 125, 489 | "created_at": "2008-02-06T17:10:42+01:00", 490 | "updated_at": "2022-02-11T00:01:12+01:00", 491 | "latitude": 53.55759811401367, 492 | "longitude": 9.96815967559815, 493 | "street": "Mühlgasse 175", 494 | "zip": "20357", 495 | "city": "Hamburg", 496 | "country": "Deutschland", 497 | "content_updated_at": "2020-04-09T18:24:12+02:00", 498 | "slug": "vivaconagua", 499 | "name": "Viva con Agua de Sankt Pauli e.V.", 500 | "description": "Viva con Agua aktiviert und inspiriert - für eine Welt ohne Durst!

Viva con Agua ist ein internationales Netzwerk von Menschen und Organisationen, das sich für den sicheren Zugang zu sauberem Trinkwasser und sanitärer Grundversorgung einsetzt.
2006 wurde der gemeinnützige Verein Viva con Agua de Sankt Pauli ins Leben gerufen.
Inzwischen unterstützen die Vision „WASSER FÜR ALLE – ALLE FÜR WASSER“ mehr als 15.000 ehrenamtliche Supporter, die mit zahlreichen Aktionen und ebenso viel Spaß Spenden für WASH-Projekte weltweit sammeln – darunter viele Künstler und Musiker.
Gemeinsam seinen internationalen und lokalen Partnerorganisationen konnte die Bewegung so bereits über drei Millionen Menschen in WASH-Projekten (WAter, Sanitation, Hygiene) erreichen.

Neben dem Hamburger Verein zählen mittlerweile die Viva con Agua Stiftung und lokal aktive Organisationen in Uganda, Österreich, den Niederlanden, der Schweiz und neuerdings in Südafrika und Kalifornien zum international tätigen Netzwerk. Darüber hinaus unterstützen die ausgegründeten Social Business Unternehmen Viva con Agua Wasser GmbH, Viva con Agua ARTS gGmbH und Goldeimer gGmbH mit ihren Aktivitäten die Trinkwasser- und Sanitärprojekte von VcA.

WASSER FÜR ALLE - ALLE FÜR WASSER!", 501 | "tax_deductible": true, 502 | "contact": { 503 | "id": 561728, 504 | "name": "Lucas\tMason\tAlexander Köhler (display)", 505 | "picture": { 506 | "links": [ 507 | { 508 | "rel": "fill_100x100", 509 | "href": "https://betterplace-assets.betterplace.org/uploads/user/profile_picture/000/561/728/fill_100x100_bp1587649479_VCA_Tropfen.png" 510 | }, 511 | { 512 | "rel": "original", 513 | "href": "https://betterplace-assets.betterplace.org/uploads/user/profile_picture/000/561/728/crop_original_bp1587649479_VCA_Tropfen.png" 514 | } 515 | ] 516 | }, 517 | "links": [ 518 | { 519 | "rel": "platform", 520 | "href": "https://www.betterplace.org/de/users/561728" 521 | }, 522 | { 523 | "rel": "contact_data", 524 | "href": "https://api.betterplace.org/de/api_v4/users/561728/contact_data.json" 525 | } 526 | ] 527 | }, 528 | "picture": { 529 | "links": [ 530 | { 531 | "rel": "fill_100x100", 532 | "href": "https://betterplace-assets.betterplace.org/uploads/organisation/profile_picture/000/000/125/fill_100x100_VcA_Projektlogo.jpg" 533 | }, 534 | { 535 | "rel": "fill_200x200", 536 | "href": "https://betterplace-assets.betterplace.org/uploads/organisation/profile_picture/000/000/125/fill_200x200_VcA_Projektlogo.jpg" 537 | }, 538 | { 539 | "rel": "fill_400x400", 540 | "href": "https://betterplace-assets.betterplace.org/uploads/organisation/profile_picture/000/000/125/fill_400x400_VcA_Projektlogo.jpg" 541 | }, 542 | { 543 | "rel": "original", 544 | "href": "https://betterplace-assets.betterplace.org/uploads/organisation/profile_picture/000/000/125/crop_original_VcA_Projektlogo.jpg" 545 | } 546 | ] 547 | }, 548 | "links": [ 549 | { 550 | "rel": "self", 551 | "href": "https://api.betterplace.org/de/api_v4/organisations/125.json" 552 | }, 553 | { 554 | "rel": "platform", 555 | "href": "https://www.betterplace.org/de/organisations/125-viva-con-agua-de-sankt-pauli-e-v" 556 | }, 557 | { 558 | "rel": "projects", 559 | "href": "https://api.betterplace.org/de/api_v4/organisations/125/projects.json" 560 | }, 561 | { 562 | "rel": "website", 563 | "href": "http://www.vivaconagua.org" 564 | } 565 | ] 566 | } 567 | ``` 568 | 569 | -------------------------------------------------------------------------------- /sections/pool_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Pool Details 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/clients/payback/pool.json 6 | ``` 7 | 8 | The details of a betterplace.org client pool. 9 | 10 | The result is cached for 5 minutes. 11 | 12 | **:lock: Only available if authenticated as a client.** 13 | See [betterplace.org clients](../README.md#client-api). 14 | 15 | **For [betterplace.org clients](../README.md#client-api):** 16 | Use this resource as follows: `/clients/PERMALINK/pool.json` 17 | 18 | 19 | ## URL Parameters 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 37 | 38 |
ParameterExampleRequiredDescription
client_idpaybackyes 33 | 34 | The betterplace.org-internal client permalink. 35 | 36 |
39 | 40 | 41 | ## Response Attributes 42 | 43 | 44 | ### Root Attributes 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 62 | 63 | 64 | 65 | 66 | 67 | 72 | 73 | 74 | 75 | 76 | 77 | 82 | 83 | 84 | 85 | 86 | 87 | 92 | 93 | 94 | 95 | 96 | 97 | 103 | 104 |
AttributeTypesExampleDescription
idnumber1 58 | 59 | An integer number ≥ 1 60 | 61 |
created_atstring"1994-11-05T13:15:30Z" 68 | 69 | DateTime (ISO8601 with Timezone) 70 | 71 |
updated_atstring"1994-11-05T13:15:30Z" 78 | 79 | DateTime (ISO8601 with Timezone) 80 | 81 |
donated_amount_in_centsnumber232323 88 | 89 | The amount in cents this pool has received 90 | 91 |
forwarded_amount_in_centsnumber12300 98 | 99 | The amount in cents the pool has forwarded to projects. 100 | 101 | 102 |
105 | 106 | 107 | ## Response Links 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 120 | 127 | 128 |
LinknameDescription
116 | 117 | self 118 | 119 | 121 | 122 | Link to this resource itself 123 | (pool details) 124 | 125 | 126 |
129 | 130 | ## Response Example 131 | 132 | ```json 133 | { 134 | "id": 4, 135 | "created_at": "2016-01-14T15:12:34+01:00", 136 | "updated_at": "2022-02-12T19:55:35+01:00", 137 | "donated_amount_in_cents": 105828770, 138 | "forwarded_amount_in_cents": 104036054, 139 | "links": [ 140 | { 141 | "rel": "self", 142 | "href": "https://api.betterplace.org/de/api_v4/clients/payback/pool.json" 143 | } 144 | ] 145 | } 146 | ``` 147 | 148 | -------------------------------------------------------------------------------- /sections/project_picture_details.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Picture Details ⇄ [List](project_pictures_list.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/projects/1114/pictures/286505.json 6 | ``` 7 | 8 | The details of a betterplace.org project picture. 9 | The details and list view show the same data. 10 | 11 | *Custom picture-sizes:* [Please read more!](project_picture_list.md) 12 | 13 | **For [betterplace.org clients](../README.md#client-api):** 14 | If you request data for a project that is not part of the client 15 | projects, the API will return a `404` HTTP code. 16 | 17 | 18 | ## URL Parameters 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 36 | 37 | 38 | 39 | 40 | 41 | 46 | 47 |
ParameterExampleRequiredDescription
project_id1114yes 32 | 33 | Project id as an integer number. 34 | 35 |
id286505yes 42 | 43 | Picture-id as an integer number. 44 | 45 |
48 | 49 | 50 | ## Response Attributes 51 | 52 | 53 | ### Root Attributes 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 71 | 72 | 73 | 74 | 75 | 76 | 81 | 82 | 83 | 84 | 85 | 86 | 91 | 92 | 93 | 94 | 95 | 96 | 101 | 102 |
AttributeTypesExampleDescription
idnumber1 67 | 68 | An integer number ≥ 1 69 | 70 |
created_atstring"1994-11-05T13:15:30Z" 77 | 78 | DateTime (ISO8601 with Timezone) 79 | 80 |
updated_atstring"1994-11-05T13:15:30Z" 87 | 88 | DateTime (ISO8601 with Timezone) 89 | 90 |
descriptionstringYada… 97 | 98 | Description of the picture 99 | 100 |
103 | 104 | 105 | ## Response Links 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 118 | 123 | 124 | 125 | 130 | 135 | 136 | 137 | 142 | 147 | 148 | 149 | 154 | 159 | 160 | 161 | 166 | 171 | 172 | 173 | 178 | 183 | 184 | 185 | 190 | 195 | 196 |
LinknameDescription
114 | 115 | image 116 | 117 | 119 | 120 | Link to the original image as uploaded by the user 121 | 122 |
126 | 127 | limit_620x323 128 | 129 | 131 | 132 | Link to a small version (max 620x323 px) of the image 133 | 134 |
138 | 139 | limit_620x323_2x 140 | 141 | 143 | 144 | Link to a small version (max 620x323 px) of the image @2x 145 | 146 |
150 | 151 | limit_450x235 152 | 153 | 155 | 156 | Link to a small version (max 450x235 px) of the image 157 | 158 |
162 | 163 | limit_450x235_2x 164 | 165 | 167 | 168 | Link to a small version (max 450x235 px) of the image @2x 169 | 170 |
174 | 175 | self 176 | 177 | 179 | 180 | The single resource for this picture 181 | 182 |
186 | 187 | parent 188 | 189 | 191 | 192 | The parent object of this picture. 193 | 194 |
197 | 198 | ## Response Example 199 | 200 | ```json 201 | { 202 | "id": 266144, 203 | "created_at": "2021-11-24T11:38:20+01:00", 204 | "updated_at": "2021-11-24T11:38:20+01:00", 205 | "description": null, 206 | "links": [ 207 | { 208 | "rel": "image", 209 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266144/image.png" 210 | }, 211 | { 212 | "rel": "limit_620x323", 213 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266144/limit_620x323_image.png" 214 | }, 215 | { 216 | "rel": "limit_620x323_2x", 217 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266144/limit_620x323_2x_image.png" 218 | }, 219 | { 220 | "rel": "limit_450x235", 221 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266144/limit_450x235_image.png" 222 | }, 223 | { 224 | "rel": "limit_450x235_2x", 225 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266144/limit_450x235_2x_image.png" 226 | }, 227 | { 228 | "rel": "self", 229 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/pictures/266144.json" 230 | }, 231 | { 232 | "rel": "parent", 233 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 234 | } 235 | ] 236 | } 237 | ``` 238 | 239 | -------------------------------------------------------------------------------- /sections/project_pictures_list.md: -------------------------------------------------------------------------------- 1 | 2 | # Project Pictures List ⇄ [Details](project_picture_details.md) 3 | 4 | ```Cirru 5 | GET https://api.betterplace.org/de/api_v4/projects/1114/pictures.json 6 | ``` 7 | 8 | A list of pictures of a betterplace.org project (donate money). 9 | Results are contained in a *data* attribute. 10 | 11 | *Custom picture-sizes:* This API will only deliver the orginal image. 12 | That is the largest image betterplace.org can provide. 13 | Please use an image transformation service of your choice to resize this 14 | image to your liking. Note, however, that some image names contain 15 | non-url-safe characters that might break services such as Sencha Source. 16 | 17 | We are working on a better solution. Please contact us for more information. 18 | 19 | In the meantime, the following links might help: 20 | 21 | * [Sencha Source](http://docs.sencha.io/current/index.html#!/guide/src) provides a simple URL-based solution 22 | * [adaptive-images.com](http://adaptive-images.com/) is a self-hosted solution 23 | * [Google mod_pagespeed "image resizing"](https://developers.google.com/speed/docs/mod_pagespeed/filter-image-optimize) 24 | should also help – and give you more performance goodies as well 25 | 26 | **For [betterplace.org clients](../README.md#client-api):** 27 | If you request data for a project that is not part of the client 28 | projects, the API will return a `404` HTTP code. 29 | 30 | 31 | ## URL Parameters 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 49 | 50 |
ParameterExampleRequiredDescription
project_id1114yes 45 | 46 | Project id as an integer number. 47 | 48 |
51 | 52 | 53 | ## Response Attributes 54 | 55 | 56 | ### Root Attributes 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 74 | 75 | 76 | 77 | 78 | 79 | 84 | 85 | 86 | 87 | 88 | 89 | 94 | 95 | 96 | 97 | 98 | 99 | 104 | 105 |
AttributeTypesExampleDescription
idnumber1 70 | 71 | An integer number ≥ 1 72 | 73 |
created_atstring"1994-11-05T13:15:30Z" 80 | 81 | DateTime (ISO8601 with Timezone) 82 | 83 |
updated_atstring"1994-11-05T13:15:30Z" 90 | 91 | DateTime (ISO8601 with Timezone) 92 | 93 |
descriptionstringYada… 100 | 101 | Description of the picture 102 | 103 |
106 | 107 | 108 | ## Response Links 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 121 | 126 | 127 | 128 | 133 | 138 | 139 | 140 | 145 | 150 | 151 | 152 | 157 | 162 | 163 | 164 | 169 | 174 | 175 | 176 | 181 | 186 | 187 | 188 | 193 | 198 | 199 |
LinknameDescription
117 | 118 | image 119 | 120 | 122 | 123 | Link to the original image as uploaded by the user 124 | 125 |
129 | 130 | limit_620x323 131 | 132 | 134 | 135 | Link to a small version (max 620x323 px) of the image 136 | 137 |
141 | 142 | limit_620x323_2x 143 | 144 | 146 | 147 | Link to a small version (max 620x323 px) of the image @2x 148 | 149 |
153 | 154 | limit_450x235 155 | 156 | 158 | 159 | Link to a small version (max 450x235 px) of the image 160 | 161 |
165 | 166 | limit_450x235_2x 167 | 168 | 170 | 171 | Link to a small version (max 450x235 px) of the image @2x 172 | 173 |
177 | 178 | self 179 | 180 | 182 | 183 | The single resource for this picture 184 | 185 |
189 | 190 | parent 191 | 192 | 194 | 195 | The parent object of this picture. 196 | 197 |
200 | 201 | ## Response Example 202 | 203 | ```json 204 | { 205 | "total_entries": 39, 206 | "offset": 3, 207 | "total_pages": 13, 208 | "current_page": 2, 209 | "per_page": 3, 210 | "data": [ 211 | { 212 | "id": 266141, 213 | "created_at": "2021-11-24T11:38:14+01:00", 214 | "updated_at": "2021-11-24T11:38:20+01:00", 215 | "description": null, 216 | "links": [ 217 | { 218 | "rel": "image", 219 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266141/image.png" 220 | }, 221 | { 222 | "rel": "limit_620x323", 223 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266141/limit_620x323_image.png" 224 | }, 225 | { 226 | "rel": "limit_620x323_2x", 227 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266141/limit_620x323_2x_image.png" 228 | }, 229 | { 230 | "rel": "limit_450x235", 231 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266141/limit_450x235_image.png" 232 | }, 233 | { 234 | "rel": "limit_450x235_2x", 235 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266141/limit_450x235_2x_image.png" 236 | }, 237 | { 238 | "rel": "self", 239 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/pictures/266141.json" 240 | }, 241 | { 242 | "rel": "parent", 243 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 244 | } 245 | ] 246 | }, 247 | { 248 | "id": 266140, 249 | "created_at": "2021-11-24T11:38:13+01:00", 250 | "updated_at": "2021-11-24T11:38:20+01:00", 251 | "description": null, 252 | "links": [ 253 | { 254 | "rel": "image", 255 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266140/image.png" 256 | }, 257 | { 258 | "rel": "limit_620x323", 259 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266140/limit_620x323_image.png" 260 | }, 261 | { 262 | "rel": "limit_620x323_2x", 263 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266140/limit_620x323_2x_image.png" 264 | }, 265 | { 266 | "rel": "limit_450x235", 267 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266140/limit_450x235_image.png" 268 | }, 269 | { 270 | "rel": "limit_450x235_2x", 271 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266140/limit_450x235_2x_image.png" 272 | }, 273 | { 274 | "rel": "self", 275 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/pictures/266140.json" 276 | }, 277 | { 278 | "rel": "parent", 279 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 280 | } 281 | ] 282 | }, 283 | { 284 | "id": 266139, 285 | "created_at": "2021-11-24T11:38:13+01:00", 286 | "updated_at": "2021-11-24T11:38:20+01:00", 287 | "description": null, 288 | "links": [ 289 | { 290 | "rel": "image", 291 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266139/image.png" 292 | }, 293 | { 294 | "rel": "limit_620x323", 295 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266139/limit_620x323_image.png" 296 | }, 297 | { 298 | "rel": "limit_620x323_2x", 299 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266139/limit_620x323_2x_image.png" 300 | }, 301 | { 302 | "rel": "limit_450x235", 303 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266139/limit_450x235_image.png" 304 | }, 305 | { 306 | "rel": "limit_450x235_2x", 307 | "href": "https://betterplace-assets.betterplace.org/uploads/project/image/000/001/114/266139/limit_450x235_2x_image.png" 308 | }, 309 | { 310 | "rel": "self", 311 | "href": "https://api.betterplace.org/de/api_v4/projects/1114/pictures/266139.json" 312 | }, 313 | { 314 | "rel": "parent", 315 | "href": "https://api.betterplace.org/de/api_v4/projects/1114.json" 316 | } 317 | ] 318 | } 319 | ] 320 | } 321 | ``` 322 | 323 | --------------------------------------------------------------------------------