{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Introduction","type":"basic","slug":"introduction-json","excerpt":"Rest-API","body":"The FundraisingBox REST API is implemented as JSON over HTTPS.\nEvery resource, like donation, person, or project, has their own URL and are manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles as much as we can.\n\nYou can explore the view part of the API (everything that’s fetched with GET) through a regular browser. Pretty much any URL in the FundraisingBox can be viewed in its JSON form by adding the .json extension. So /persons/4 becomes /persons/4.json if you want to see the JSON version. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"API package required\",\n  \"body\": \"Please note that a booked API package is required.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Base URL and versioning\"\n}\n[/block]\nPlease use https://api.fundraisingbox.com/v1 as base URL followed by a specific endpoint.\n\nAt the moment there is only one API version (v1). \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nWhen you’re using the API, it’s always through an existing user in your FundraisingBox. There’s no special API user. Authenticating is done with an authentication token. Please contact our support team to retrieve your token.\n\nWhen using the authentication token, you don’t need a separate password. But since FundraisingBox uses HTTP Basic Authentication, and lots of implementations assume that you want to have a password, it’s often easier just to pass in a dummy password, like \"X\".\n\nExample using the authentication token and a dummy password through curl:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -u 605b32dd:X https://api.fundraisingbox.com/persons/1.json\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nRemember that anyone who has your authentication token can see and change everything you have access to. So you want to guard that as well as you guard your username and password. If you come to fear that it has been compromised, you can regenerate it at any time. Just open a ticket.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Reading through the API\"\n}\n[/block]\nThe FundraisingBox API has two category of actions for reading: show and list. Show returns a single record whereas list returns a collection. There’s usually just a single show action for each resource, but many lists. All these actions are done through GET, which also means that they’re all easily explorable through a browser as described above.\n\nA few examples of reading with curl:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -u 605b32dd:X https://api.fundraisingbox.com/v1/persons/5.json\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -u 605b32dd:X https://api.fundraisingbox.com/v1/donations/5.json\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nIf the read is successful, you’ll get an JSON response back along with the status code „200 OK“.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Filter\",\n  \"body\": \"You can narrow the search to get better results. Filtering is done by adding parameters like amount=50&fb_project_id=7 to the URL. Please find further information about the available filters at relevant documentation for each endpoint.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Pagination\"\n}\n[/block]\nEvery endpoint has a limitation of at most 100 datasets in the returned result set. You can use a URL parameter called *page={page_number}* to fetch further results. \n\nIf you request a list view via GET https://api.fundraisingbox.com/v1/persons.json the result looks like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"hasMore\\\":true,\\n    \\\"data\\\":[\\n        ...\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe hasMore information indicates whether or not there are more pages. Just request further objects via GET https://secure.fundraisingbox.com/v1/persons.json?page=2\n[block:api-header]\n{\n  \"title\": \"Writing through the API\"\n}\n[/block]\nIf a user has the access rights for writing datasets can be manipulated through the API as well. While GET requests are used for reading writing is implemented with the following HTTP methods:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"HTTP Method\",\n    \"h-1\": \"Operation\",\n    \"h-2\": \"Data returned\",\n    \"0-0\": \"POST\",\n    \"1-0\": \"PUT\",\n    \"2-0\": \"DELETE\",\n    \"0-1\": \"Creates a new object\",\n    \"1-1\": \"Edits an existing object\",\n    \"2-1\": \"Deletes an existing object\",\n    \"0-2\": \"the JSON representation of the created object\",\n    \"1-2\": \"the JSON representation of the edited object\",\n    \"2-2\": \"The ID of the just deleted object like this:\\n\\n*{\\n    \\\"id\\\":\\\"123\\\",\\n    \\\"deleted\\\":true\\n}* \",\n    \"h-3\": \"HTTP status code\",\n    \"0-3\": \"201\\nCreated\",\n    \"1-3\": \"200\\nOK\",\n    \"2-3\": \"200\\nOK\"\n  },\n  \"cols\": 4,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Dealing with failure\"\n}\n[/block]\nIf a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/1.1 404 The record could not be found\\nDate: Thu, 16 Mar 2016 17:41:40 GMT\\n...\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nNote that, in general, if a request causes a new record to be created (like a new message, or to-do item, etc.), the response will use the „201 Created“ status. Any other successful operation (like a successful query, delete, or update) will use a 200 status code.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Always use [https://api.fundraisingbox.com](https://api.fundraisingbox.com)! If you perform a request on http you will get a redirect answer in return.\",\n  \"title\": \"SSL Note\"\n}\n[/block]\nPlease find further information [at the error codes section](https://developer.fundraisingbox.com/v1.0/docs/error-codes)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Conventions in the API documentation\"\n}\n[/block]\nIn the documentation that follows, the following notation is used:\n\n{text}: Indicates text that should be replaced by your own data\n    \n...: Indicates content from the response has been elided for brevity in documentation. See the list of data responses at the end of the page for a full description of the format of that response type.\n\nThese notations are used to describe datatypes:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Type\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"int\",\n    \"1-0\": \"float\",\n    \"2-0\": \"string\",\n    \"3-0\": \"date\",\n    \"0-1\": \"An integer number\",\n    \"0-2\": \"2205\",\n    \"1-1\": \"A coma number with decimal point\",\n    \"1-2\": \"1.24\",\n    \"2-1\": \"An alphanumerical text\",\n    \"2-2\": \"Hello World\",\n    \"3-1\": \"A date with format yyyy-mm-dd or a UNIX timestamp as integer (number of seconds since January 1 1970 00:00:00 GMT)\",\n    \"3-2\": \"2019-05-22\\nor\\n1558483200\",\n    \"6-0\": \"Enum\",\n    \"6-1\": \"A finite list of fixed values\",\n    \"6-2\": \"\\\"active\\\", \\\"inactive\\\"\",\n    \"4-0\": \"datetime\",\n    \"4-1\": \"A date (incl. timestamp) with the format yyyy-mm-dd hh:mm:ss or a UNIX timestamp as integer (number of seconds since January 1 1970 00:00:00 GMT)\",\n    \"4-2\": \"2019-05-22 09:41:44\\nor\\n1558518104\",\n    \"5-0\": \"boolean\",\n    \"5-2\": \"true\",\n    \"5-1\": \"A boolean value given by true resp. false.\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]","updates":[],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5cbedda63a7fdc004b6ba248","project":"571f5e8cd8667f0e00a3c498","version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["571f5e8cd8667f0e00a3c49c","571f73cfcb4baa0e00d13a80","571f7451cb4baa0e00d13a88","571f7d2720695f3400f38797","571f7fb0ac2a080e0014c661","571f884be54f2d0e003ebb0a","572200c9ecb38d0e00d80ebd","572c301e7c8eff0e00aaa174","57df91b2c6348d0e0020c452","57e104db9ff1e21900a721ab","57fd04caeaa77f19008b8202","5899c7113514ce0f0014da84","5cbeda4b862d090013abd413","5e60d6278f8b380072f0b1e3"],"_id":"571f5e8cd8667f0e00a3c49b","hasDoc":true,"releaseDate":"2016-04-26T12:26:52.312Z","__v":14,"hasReference":true,"createdAt":"2016-04-26T12:26:52.312Z","project":"571f5e8cd8667f0e00a3c498"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"JSON-REST-API (API-Package)","slug":"rest-api-json","order":9,"from_sync":false,"reference":false,"_id":"5cbeda4b862d090013abd413","project":"571f5e8cd8667f0e00a3c498","version":"571f5e8cd8667f0e00a3c49b","createdAt":"2019-04-23T09:26:35.210Z","__v":1},"user":"5720ba18c669e80e00c35051","createdAt":"2019-04-23T09:40:54.453Z","__v":0,"parentDoc":null}

Introduction

Rest-API

The FundraisingBox REST API is implemented as JSON over HTTPS. Every resource, like donation, person, or project, has their own URL and are manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles as much as we can. You can explore the view part of the API (everything that’s fetched with GET) through a regular browser. Pretty much any URL in the FundraisingBox can be viewed in its JSON form by adding the .json extension. So /persons/4 becomes /persons/4.json if you want to see the JSON version. [block:callout] { "type": "warning", "title": "API package required", "body": "Please note that a booked API package is required." } [/block] [block:api-header] { "title": "Base URL and versioning" } [/block] Please use https://api.fundraisingbox.com/v1 as base URL followed by a specific endpoint. At the moment there is only one API version (v1). [block:api-header] { "type": "basic", "title": "Authentication" } [/block] When you’re using the API, it’s always through an existing user in your FundraisingBox. There’s no special API user. Authenticating is done with an authentication token. Please contact our support team to retrieve your token. When using the authentication token, you don’t need a separate password. But since FundraisingBox uses HTTP Basic Authentication, and lots of implementations assume that you want to have a password, it’s often easier just to pass in a dummy password, like "X". Example using the authentication token and a dummy password through curl: [block:code] { "codes": [ { "code": "curl -u 605b32dd:X https://api.fundraisingbox.com/persons/1.json", "language": "curl" } ] } [/block] Remember that anyone who has your authentication token can see and change everything you have access to. So you want to guard that as well as you guard your username and password. If you come to fear that it has been compromised, you can regenerate it at any time. Just open a ticket. [block:api-header] { "type": "basic", "title": "Reading through the API" } [/block] The FundraisingBox API has two category of actions for reading: show and list. Show returns a single record whereas list returns a collection. There’s usually just a single show action for each resource, but many lists. All these actions are done through GET, which also means that they’re all easily explorable through a browser as described above. A few examples of reading with curl: [block:code] { "codes": [ { "code": "curl -u 605b32dd:X https://api.fundraisingbox.com/v1/persons/5.json", "language": "curl" } ] } [/block] [block:code] { "codes": [ { "code": "curl -u 605b32dd:X https://api.fundraisingbox.com/v1/donations/5.json", "language": "curl" } ] } [/block] If the read is successful, you’ll get an JSON response back along with the status code „200 OK“. [block:callout] { "type": "info", "title": "Filter", "body": "You can narrow the search to get better results. Filtering is done by adding parameters like amount=50&fb_project_id=7 to the URL. Please find further information about the available filters at relevant documentation for each endpoint." } [/block] [block:api-header] { "title": "Pagination" } [/block] Every endpoint has a limitation of at most 100 datasets in the returned result set. You can use a URL parameter called *page={page_number}* to fetch further results. If you request a list view via GET https://api.fundraisingbox.com/v1/persons.json the result looks like this: [block:code] { "codes": [ { "code": "{\n \"hasMore\":true,\n \"data\":[\n ...\n ]\n}", "language": "json" } ] } [/block] The hasMore information indicates whether or not there are more pages. Just request further objects via GET https://secure.fundraisingbox.com/v1/persons.json?page=2 [block:api-header] { "title": "Writing through the API" } [/block] If a user has the access rights for writing datasets can be manipulated through the API as well. While GET requests are used for reading writing is implemented with the following HTTP methods: [block:parameters] { "data": { "h-0": "HTTP Method", "h-1": "Operation", "h-2": "Data returned", "0-0": "POST", "1-0": "PUT", "2-0": "DELETE", "0-1": "Creates a new object", "1-1": "Edits an existing object", "2-1": "Deletes an existing object", "0-2": "the JSON representation of the created object", "1-2": "the JSON representation of the edited object", "2-2": "The ID of the just deleted object like this:\n\n*{\n \"id\":\"123\",\n \"deleted\":true\n}* ", "h-3": "HTTP status code", "0-3": "201\nCreated", "1-3": "200\nOK", "2-3": "200\nOK" }, "cols": 4, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Dealing with failure" } [/block] If a request fails, the error information is returned with the HTTP status code. For instance, if a requested record could not be found, the HTTP response might look something like: [block:code] { "codes": [ { "code": "HTTP/1.1 404 The record could not be found\nDate: Thu, 16 Mar 2016 17:41:40 GMT\n...", "language": "http" } ] } [/block] Note that, in general, if a request causes a new record to be created (like a new message, or to-do item, etc.), the response will use the „201 Created“ status. Any other successful operation (like a successful query, delete, or update) will use a 200 status code. [block:callout] { "type": "warning", "body": "Always use [https://api.fundraisingbox.com](https://api.fundraisingbox.com)! If you perform a request on http you will get a redirect answer in return.", "title": "SSL Note" } [/block] Please find further information [at the error codes section](https://developer.fundraisingbox.com/v1.0/docs/error-codes) [block:api-header] { "type": "basic", "title": "Conventions in the API documentation" } [/block] In the documentation that follows, the following notation is used: {text}: Indicates text that should be replaced by your own data ...: Indicates content from the response has been elided for brevity in documentation. See the list of data responses at the end of the page for a full description of the format of that response type. These notations are used to describe datatypes: [block:parameters] { "data": { "h-0": "Type", "h-1": "Description", "h-2": "Example", "0-0": "int", "1-0": "float", "2-0": "string", "3-0": "date", "0-1": "An integer number", "0-2": "2205", "1-1": "A coma number with decimal point", "1-2": "1.24", "2-1": "An alphanumerical text", "2-2": "Hello World", "3-1": "A date with format yyyy-mm-dd or a UNIX timestamp as integer (number of seconds since January 1 1970 00:00:00 GMT)", "3-2": "2019-05-22\nor\n1558483200", "6-0": "Enum", "6-1": "A finite list of fixed values", "6-2": "\"active\", \"inactive\"", "4-0": "datetime", "4-1": "A date (incl. timestamp) with the format yyyy-mm-dd hh:mm:ss or a UNIX timestamp as integer (number of seconds since January 1 1970 00:00:00 GMT)", "4-2": "2019-05-22 09:41:44\nor\n1558518104", "5-0": "boolean", "5-2": "true", "5-1": "A boolean value given by true resp. false." }, "cols": 3, "rows": 7 } [/block]