Welcome!

The BetterNow API provides the building blocks that allow charities and event organizers to integrate their fundraising and donation activities on the BetterNow platform and Branded Sites with other information systems.

Here are a few of the real-world integrations that use the API today:

Participants in a charity sports event automatically get a fundraiser created for them when registering for the event, via an integration with the event’s ticketing system.
A charity’s CRM system is automatically updated in real-time as donations and fundraisers are created on their BetterNow sites, via webhooks that push activity on the BetterNow sites to the charity’s system.
A charity’s home page displays the top fundraiser for a specific project, with donation amounts that are updated in real-time, and direct links to donate to the fundraiser or create another fundraiser for the same cause.

We ♥︎ helping our customers build new integrations. Contact us at apisupport@betternow.org if you have any questions, or book an appointment with our tech team.

Setup

In the Integrations section of your charity dashboard, you can create API keys that will grant you access to the API.

When you create an API user, you can decide if the keys should be limited to activity for only one Project, or for all present and future Projects for your charity.

In addition, you can add an email address and a short description for each set of keys.

Authentication

When you create an API user in your charity dashboard, we generate a publishable key and a secret key.

The publishable key can be used in client-side integrations, as shown in the HTML example below. The publishable key grants read-only access to the same publicly available information that is displayed on the BetterNow or Branded site.

The secret key grants write access to some resources and read access to private information.

The secret key should never be exposed in client-side code, commited to source control, or saved/sent via an insecure channel.

The secret key has all of the access rights of a publishable key, so if your integration is server-side only, you can use the secret key only.

Both keys can be used as the password via HTTP Basic-Auth, or in the browser as shown in our HTML example. When using HTTP Basic-Auth, send your email address as the username. We will use the email address to contact you if we notice problems with your API client.

API keys grant access to specific resources such as Organisations/Charities, Events, etc. and all of their associated “sub-resources”, such as Fundraising Pages and Teams.

Authenticated requests for other resources will return a 403 Forbidden response.

Caching

All responses include an ETag (or Entity Tag) header, identifying the specific version of a returned resource.

Use this value to check for changes to a resource by repeating the request and passing the ETag value in the If-None-Match header.

If the resource has not changed, a 304 Not Modified status will be returned with an empty body. If the resource has changed, the request will proceed normally.

Web browser api clients should do this automatically via HTTP Conditional Get

Clients

Clients must address requests to api.betternow.org using HTTPS and specify the Accept: application/vnd.betternow+json; version=1 Accept header.

Non-browser clients should specify a User-Agent header to facilitate tracking and debugging.

CORS

The API fully supports cross-origin resource sharing (CORS) to enable browser-based clients.

Rate Limits

We continually monitor the health of our API and reserve the right to enforce rate limits.

Rate-limited requests will receive a response with a 429 Too Many Requests status.

We encourage you to add something like exponential back-off to your API client, periodically retrying your requests if you receive a 429 status code.

Pagination via Ranges

List requests will return a Content-Range header indicating the range of values returned. Large lists may require additional requests to retrieve. If a list response has been truncated you will receive a 206 Partial Content status and the Next-Range header will be set. 50 resources will be sent at a time.

To retrieve the next range, repeat the request with the Range header set to the value of the previous request’s Next-Range header and the Range-Unit: items header, e.g:

Initial request to paginated resource

curl -n -sS -i -H 'Accept: application/vnd.betternow+json; version=1' \
  https://api.betternow.org/fundraisers

HTTP/1.1 206 Partial Content
#... ommitted headers
Accept-Ranges: items
Content-Range: 0-49/7167
Link: <https://api.betternow.org/fundraisers>; rel="next"; items="50-7216", <https://api.betternow.org/fundraisers>; rel="last"; items="7150-14316"
Next-Range: 50-7216
Range-Unit: items
Status: 206 Partial Content

Subsequent request to paginated resource

curl -n -sS -i -H 'Accept: application/vnd.betternow+json; version=1' \
  -H 'Range-Unit: items' \
  -H 'Range: 50-7216' \
  https://api.betternow.org/fundraisers

The rel=next relation in the Link header may also be used.

If the list is empty, a 204 No Content status with the correct range headers and an empty request body will be returned.

JSON Schema

The machine-readable version of the API documentation is schema.json. You can use tools like committee with the schema to test and stub a local version of the api when you’re developing your client.

“Sub-resources”

When resources are related to other resources (e.g. a list of Projects that can be supported for one Organisation, or a list of Fundraising Pages that are members of one Team), they will be represented as a reference to an url that can be dereferenced to return a list of the embedded resources.

Clients should prefer following the url included in the parent resource rather then constructing their own urls.

Example Usage

On the right you can see two examples for how to retrieve a fundraiser via the API.

curl example

# Save api credentials in .netrc, for use with `curl -n`
#
# You can use any email address as the `login`. We will only use the email address to
# contact you in case we see problems with your API client.
#
# You can use either your `publishable` or `secret key` as the `password`.
#
cat >> ~/.netrc
machine api.betternow.org
  login <YOUR EMAIL ADDRESS>
  password <YOUR API KEY>


curl -n -sS -i -H 'Accept: application/vnd.betternow+json; version=1' \
  https://api.betternow.org/fundraisers/<REPLACE_WITH_YOUR_FUNDRAISER_ID_OR_SLUG>

HTML/Javascript (browser) example

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>BetterNow API browser client example</title>
    <script>

      // Base64 encoding function
      var Base64={_keyStr:"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=",encode:function(e){var t="";var n,r,i,s,o,u,a;var f=0;e=Base64._utf8_encode(e);while(f<e.length){n=e.charCodeAt(f++);r=e.charCodeAt(f++);i=e.charCodeAt(f++);s=n>>2;o=(n&3)<<4|r>>4;u=(r&15)<<2|i>>6;a=i&63;if(isNaN(r)){u=a=64}else if(isNaN(i)){a=64}t=t+this._keyStr.charAt(s)+this._keyStr.charAt(o)+this._keyStr.charAt(u)+this._keyStr.charAt(a)}return t},decode:function(e){var t="";var n,r,i;var s,o,u,a;var f=0;e=e.replace(/[^A-Za-z0-9\+\/\=]/g,"");while(f<e.length){s=this._keyStr.indexOf(e.charAt(f++));o=this._keyStr.indexOf(e.charAt(f++));u=this._keyStr.indexOf(e.charAt(f++));a=this._keyStr.indexOf(e.charAt(f++));n=s<<2|o>>4;r=(o&15)<<4|u>>2;i=(u&3)<<6|a;t=t+String.fromCharCode(n);if(u!=64){t=t+String.fromCharCode(r)}if(a!=64){t=t+String.fromCharCode(i)}}t=Base64._utf8_decode(t);return t},_utf8_encode:function(e){e=e.replace(/\r\n/g,"\n");var t="";for(var n=0;n<e.length;n++){var r=e.charCodeAt(n);if(r<128){t+=String.fromCharCode(r)}else if(r>127&&r<2048){t+=String.fromCharCode(r>>6|192);t+=String.fromCharCode(r&63|128)}else{t+=String.fromCharCode(r>>12|224);t+=String.fromCharCode(r>>6&63|128);t+=String.fromCharCode(r&63|128)}}return t},_utf8_decode:function(e){var t="";var n=0;var r=c1=c2=0;while(n<e.length){r=e.charCodeAt(n);if(r<128){t+=String.fromCharCode(r);n++}else if(r>191&&r<224){c2=e.charCodeAt(n+1);t+=String.fromCharCode((r&31)<<6|c2&63);n+=2}else{c2=e.charCodeAt(n+1);c3=e.charCodeAt(n+2);t+=String.fromCharCode((r&15)<<12|(c2&63)<<6|c3&63);n+=3}}return t}}

      // This can be any email address - we will use it to contact you in case
      // we are seeing issues with your API client
      var yourEmailAddress = "<REPLACE WITH YOUR EMAIL>"

      // You could also use your secret key here, if accessing an endpoint that
      // requires it.
      var publishableKey = "<REPLACE WITH YOUR API KEY>";

      // This is just an example for retrieving a fundraiser. If you would
      // rather use another endpoint, you can change the url used in the
      // `xhr.open` line below.
      var fundraiserSlugOrId = "<REPLACE WITH A FUNDRAISER ID or SLUG>";

      // Create a new request object
      var xhr = new XMLHttpRequest();

      // Setup the URL for the request
      xhr.open("get", "https://api.betternow.org/fundraisers/" + fundraiserSlugOrId, true);

      // Encode the email & token, and set the required `Authorization` header
      xhr.setRequestHeader("Authorization", "Bearer " + Base64.encode(yourEmailAddress + ":" + publishableKey))

      // Set the required `Accept` header
      xhr.setRequestHeader("Accept", "application/vnd.betternow+json; version=1");

      // Add a handler for the response
      xhr.onload = function() {
        alert(this.responseText);
      }

      // Send the request
      xhr.send();
    </script>
  </head>
  <body>
    <p>If you don't get an alert something is wrong...</p>
  </body>
</html>

API Endpoints/Resources

Following is a list of the endpoints/resources that are available via the api, the operations that are supported for each resource, and examples of response data.

The curl examples use the -n flag to authenticate using the .netrc file. For more information about configuring your .netrc see the curl example above.

Common definitions

Common definitions used by multiple resources

Contact Permission

Information about the contact permissions gathered in connection with the creation of a Fundraiser, Donation or Team. Depending on the configuration for the region/site/organisation more or less detail will be available. A secret key is required to access this information.

Attributes

Name	Type	Description	Example
allow_organisation_contact	boolean	If the person has consented to be contacted by the organisation	`true`
allow_site_contact	boolean	If the person has consented to be contacted by the site. If the value is null, the person has not been asked	`false`
created_at	date-time	when resource was created	`"2012-01-01T12:00:00Z"`
id	string	unique identifier	`1234567`
organisation_contact_methods:email	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
organisation_contact_methods:phone	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
organisation_contact_methods:post	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
organisation_contact_methods:sms	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
person:avatar_url	uri	The URL for the avatar image for the user. 92x92 pixels	`"https://cdn.example.net/avatar.jpg"`
person:first_name	string	The first name of the user	`"Firstname"`
person:last_name	string	The last name of the user	`"Lastname"`
person:middle_name	string	The middle name of the user	`"Middlename"`
person:private_person_url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`
recipient:html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
recipient:id	string	Unique identifier of organisation	`1234567`
recipient:name	string	The name of the Organisation	`"HelpNow"`
recipient:url	uri		`"https://api.betternow.org/organisations/1234567"`
site_contact_methods:email	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
site_contact_methods:phone	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
site_contact_methods:post	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
site_contact_methods:sms	boolean	If the person has agreed to be contacted via the method. If the value is null, the person has not been asked about specific contact methods.	`true`
source:source_id	string	unique identifier	`1234567`
source:source_type	string	one of:`"Donation"` or `"Fundraiser"` or `"Team"`	`"Donation"`
source:url	uri		`"https://url.example.net"`
url	uri		`"https://url.example.net"`

Contact Permission Info

Info for existing donation.

GET /contact-permissions/{contact_permission_id}

Curl Example

$ curl -n https://api.betternow.org/contact-permissions/$CONTACT_PERMISSION_ID \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "allow_organisation_contact": true,
  "allow_site_contact": false,
  "created_at": "2012-01-01T12:00:00Z",
  "id": 1234567,
  "organisation_contact_methods": {
    "email": true,
    "post": true,
    "sms": true,
    "phone": true
  },
  "site_contact_methods": {
    "email": true,
    "post": true,
    "sms": true,
    "phone": true
  },
  "person": {
    "avatar_url": "https://cdn.example.net/avatar.jpg",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
  },
  "recipient": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "source": {
    "source_type": "Donation",
    "source_id": 1234567,
    "url": "https://url.example.net"
  },
  "url": "https://url.example.net"
}

Donation

The publicly available details about a donation

Attributes

Name	Type	Description	Example
allow_organisation_contact	boolean	If the person has consented to be contacted by the organisation	`true`
amount:cents	integer	Numeric amount in cents	`12345`
amount:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
comment	string	The comment given with the donation	`"Wow, what a great idea!"`
created_at	date-time	when donation was created	`"2012-01-01T12:00:00Z"`
event:html_url	uri	The url to the Event page on BetterNow	`"https://dk.betternow.org/events/copenhagen-marathon-2013"`
event:id	string	unique identifier of event	`1234567`
event:name	string	the name of the Event	`"Copenhagen Marathon 2013"`
event:url	uri		`"https://api.betternow.org/events/1234567"`
fundraiser:html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
fundraiser:id	string	Unique identifier of organisation	`1234567`
fundraiser:name	string	The name of the Organisation	`"HelpNow"`
fundraiser:url	uri		`"https://api.betternow.org/organisations/1234567"`
id	integer	unique identifier of donation	`1234567`
name	string	The name on the donation	`"Joes Truck Stop"`
private_details_url	uri	An url where private information about the donation and donor can be retrieved. Requires a secret key.	`"https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d"`
project:html_url	uri	The current url to view the project page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/projects/helpnow-projekt"`
project:id	string	Unique identifier of project	`1234567`
project:name	string	The name of the Project	`"HelpNows generelle arbejde"`
project:url	uri		`"https://api.betternow.org/projects/1234567"`
recipient:html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
recipient:id	string	Unique identifier of organisation	`1234567`
recipient:name	string	The name of the Organisation	`"HelpNow"`
recipient:url	uri		`"https://api.betternow.org/organisations/1234567"`
team:html_url	uri	The url to the Team page on BetterNow	`"https://dk.betternow.org/teams/team-novo"`
team:id	string	unique identifier of team	`1234567`
team:name	string	the name of the Team	`"Team NOVO"`
team:url	uri		`"https://api.betternow.org/team/1234567"`
updated_at	date-time	when donation was updated	`"2012-01-01T12:00:00Z"`
your_reference	string	A string that you can use to identify the project and its fundraisers and donations. The value will be inherited by any fundraisers created for the project and any donations made via the fundraisers. Commonly used to assign donations to e.g. a campaign in your CRM system. You can set this value in the dashboard for your project.	`"my-crm-project-reference-123456"`

Donation Info

Info for existing donation.

GET /donations/{donation_id}

Curl Example

$ curl -n https://api.betternow.org/donations/$DONATION_ID \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "amount": {
    "cents": 12345,
    "currency": "EUR"
  },
  "allow_organisation_contact": true,
  "comment": "Wow, what a great idea!",
  "created_at": "2012-01-01T12:00:00Z",
  "id": 1234567,
  "private_details_url": "https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d",
  "name": "Joes Truck Stop",
  "updated_at": "2012-01-01T12:00:00Z",
  "fundraiser": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "recipient": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "team": {
    "id": 1234567,
    "name": "Team NOVO",
    "url": "https://api.betternow.org/team/1234567",
    "html_url": "https://dk.betternow.org/teams/team-novo"
  },
  "project": {
    "id": 1234567,
    "name": "HelpNows generelle arbejde",
    "url": "https://api.betternow.org/projects/1234567",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
  },
  "event": {
    "id": 1234567,
    "name": "Copenhagen Marathon 2013",
    "url": "https://api.betternow.org/events/1234567",
    "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
  },
  "your_reference": "my-crm-project-reference-123456"
}

Donation Details

The private details about a donation. Includes Personally Identifieable Information. A secret key is required to access this information.

Attributes

Name	Type	Description	Example
address:city	string		`"Copenhagen K"`
address:country	string	ISO alpha-2 country code pattern: `^([A-Z]{2})$`	`"DK"`
address:postal_code	string		`"1434"`
address:province	string		`"Region Hovedstaden"`
address:street_line_1	string		`"Danneskiold-Samsøes Allé 41"`
address:street_line_2	string		`"Suite 103"`
allow_organisation_contact	boolean	Has the donor given permission for the recipient of the donation to contact them?	`true`
allow_site_contact	boolean	Has the donor given permission for the operator of the site on which the donation was given to contact them?	`true`
amount:cents	integer	Numeric amount in cents	`12345`
amount:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
comment	string	The comment given with the donation	`"Wow, what a great idea!"`
company_name	string		`"BetterNow Worldwide ApS"`
created_at	date-time	when donation was created	`"2012-01-01T12:00:00Z"`
custom_form_values	object	An object containing values for custom form fields. Structure varies depending on the customer.
donor:allow_site_contact	boolean	true if the user has agreed to be contacted by the site they either donated via or signed up on.	`true`
donor:birth_day	integer	Range: `1 <= value <= 31`	`1`
donor:birth_month	integer	Range: `1 <= value <= 12`	`1`
donor:created_at	date-time	when user was created	`"2012-01-01T12:00:00Z"`
donor:donations:count	integer	The count of all donations made by this person	`123`
donor:donations:total_donated:cents	integer	Numeric amount in cents	`1234500`
donor:donations:total_donated:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
donor:donations:url	uri	The url to retrieve details on all donations made by this person	`"https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/donations"`
donor:email	string		`"user@example.com"`
donor:first_name	string	The first name of the user	`"Firstname"`
donor:fundraisers:count	integer	The number of active fundraisers	`12`
donor:fundraisers:url	uri	The url to retrieve all fundraisers	`"https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/fundraisers"`
donor:id	string	unique identifier of person	`"fdb6cd2a-3ca7-40db-8fae-135daebecdab"`
donor:last_name	string	The last name of the user	`"Lastname"`
donor:locale	string	ISO 639-1 locale code	`"en"`
donor:middle_name	string	The middle name of the user	`"Middlename"`
donor:partner_reference	string	This is an external identifier that is intended to be used in linking partner systems to BetterNow. The partner reference can be supplied when creating a user.	`"example"`
donor:phone	string	Phone number in E.164 format	`"+4510101010"`
donor:teams:count	integer	The number of teams	`12`
donor:teams:url	uri	The url to retrieve all teams	`"https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/teams"`
donor:title	string		`"Director of Personal Fundraising"`
donor:url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`
donor_ip_address	string		`"127.0.0.1"`
donor_type	string	one of:`"unknown"` or `"personal"` or `"organisation"`	`"personal"`
event:html_url	uri	The url to the Event page on BetterNow	`"https://dk.betternow.org/events/copenhagen-marathon-2013"`
event:id	string	unique identifier of event	`1234567`
event:name	string	the name of the Event	`"Copenhagen Marathon 2013"`
event:url	uri		`"https://api.betternow.org/events/1234567"`
first_name	string	The first name of the user	`"Firstname"`
fundraiser:html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
fundraiser:id	string	Unique identifier of organisation	`1234567`
fundraiser:name	string	The name of the Organisation	`"HelpNow"`
fundraiser:url	uri		`"https://api.betternow.org/organisations/1234567"`
hidden_name	boolean	Has the donor requested to hide their name (donate anonymously on the public site)?	`true`
id	integer	unique identifier of donation	`1234567`
last_name	string	The last name of the user	`"Lastname"`
legal_name	string		`"BetterNow LTD"`
middle_name	string	The middle name of the user	`"Middlename"`
name_shown	string	The name on the donation	`"Joes Truck Stop"`
payment:acquirer	string	What company acquires the payment	`"clearhaus"`
payment:payment_id_for_processor	string	the id we send to the payment processor and acquirer	`"12345-slyellei_0"`
payment:processor_id	string	the payment processor’s id for the payment	`"123456789"`
payment:settled_by_betternow	boolean	If BetterNow transfers the money to you	`false`
project:html_url	uri	The current url to view the project page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/projects/helpnow-projekt"`
project:id	string	Unique identifier of project	`1234567`
project:name	string	The name of the Project	`"HelpNows generelle arbejde"`
project:url	uri		`"https://api.betternow.org/projects/1234567"`
recipient:html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
recipient:id	string	Unique identifier of organisation	`1234567`
recipient:name	string	The name of the Organisation	`"HelpNow"`
recipient:url	uri		`"https://api.betternow.org/organisations/1234567"`
tax_deduction_requested	boolean	whether the donor requested a tax deduction (or Gift Aid in UK)	`false`
tax_id	string	country-specific tax identification number	`"example"`
team:html_url	uri	The url to the Team page on BetterNow	`"https://dk.betternow.org/teams/team-novo"`
team:id	string	unique identifier of team	`1234567`
team:name	string	the name of the Team	`"Team NOVO"`
team:url	uri		`"https://api.betternow.org/team/1234567"`
updated_at	date-time	when donation was updated	`"2012-01-01T12:00:00Z"`
url	uri	An url where private information about the donation and donor can be retrieved. Requires a secret key.	`"https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d"`
your_reference	string	A string that you can use to identify the project and its fundraisers and donations. The value will be inherited by any fundraisers created for the project and any donations made via the fundraisers. Commonly used to assign donations to e.g. a campaign in your CRM system. You can set this value in the dashboard for your project.	`"my-crm-project-reference-123456"`

Donation Details Info

Info for existing donation.

GET /donation-details/{donation_id}

Curl Example

$ curl -n https://api.betternow.org/donation-details/$DONATION_ID \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "amount": {
    "cents": 12345,
    "currency": "EUR"
  },
  "comment": "Wow, what a great idea!",
  "name_shown": "Joes Truck Stop",
  "hidden_name": true,
  "first_name": "Firstname",
  "middle_name": "Middlename",
  "last_name": "Lastname",
  "company_name": "BetterNow Worldwide ApS",
  "legal_name": "BetterNow LTD",
  "donor_type": "personal",
  "tax_id": "example",
  "tax_deduction_requested": false,
  "created_at": "2012-01-01T12:00:00Z",
  "id": 1234567,
  "updated_at": "2012-01-01T12:00:00Z",
  "address": {
    "street_line_1": "Danneskiold-Samsøes Allé 41",
    "street_line_2": "Suite 103",
    "city": "Copenhagen K",
    "postal_code": "1434",
    "province": "Region Hovedstaden",
    "country": "DK"
  },
  "fundraiser": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "recipient": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "team": {
    "id": 1234567,
    "name": "Team NOVO",
    "url": "https://api.betternow.org/team/1234567",
    "html_url": "https://dk.betternow.org/teams/team-novo"
  },
  "project": {
    "id": 1234567,
    "name": "HelpNows generelle arbejde",
    "url": "https://api.betternow.org/projects/1234567",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
  },
  "event": {
    "id": 1234567,
    "name": "Copenhagen Marathon 2013",
    "url": "https://api.betternow.org/events/1234567",
    "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
  },
  "donor_ip_address": "127.0.0.1",
  "allow_organisation_contact": true,
  "allow_site_contact": true,
  "url": "https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d",
  "donor": {
    "id": "fdb6cd2a-3ca7-40db-8fae-135daebecdab",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "email": "user@example.com",
    "phone": "+4510101010",
    "title": "Director of Personal Fundraising",
    "created_at": "2012-01-01T12:00:00Z",
    "birth_month": 1,
    "birth_day": 1,
    "locale": "en",
    "allow_site_contact": true,
    "partner_reference": "example",
    "url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/donations"
    },
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/fundraisers"
    },
    "teams": {
      "count": 12,
      "url": "https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/teams"
    }
  },
  "your_reference": "my-crm-project-reference-123456",
  "custom_form_values": null,
  "payment": {
    "processor_id": "123456789",
    "payment_id_for_processor": "12345-slyellei_0",
    "settled_by_betternow": false,
    "acquirer": "clearhaus"
  }
}

Event

An Event is something that takes place at a particular time and/or place. It could be a sporting event like the Copenhagen Marathon 2013, or a holiday like Christmas 2014

Attributes

Name	Type	Description	Example
activity_score	integer	A number that can be used for sorting lists of events. More recently active events should have a higher activity score than events who have raised more money long ago.	`987654321`
choose_project_to_fundraise_for_url	uri	The url on BetterNow for people who want to fundraise in connection with an event	`"https://www.betternow.org/dk/fundraisers/new?event_id=1234567"`
cover_media:image:url	uri	The url for the image. On the BetterNow site, the video takes precedence if both exist. 461x306 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:thumb:url	uri	The url for the cover media that should be displayed in e.g. a card view. 120x80 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:video:oembed_html	string	The OEmbed HTML to display the video. Could be blank.	`"<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"`
cover_media:video:url	uri	The url for the video. Currently only YouTube and Vimeo are supported. Could be blank.	`"https://youtu.be/12345"`
created_at	date-time	when event was created	`"2012-01-01T12:00:00Z"`
description	string	Text describing the Event added by the event organiser. Contains HTML.	`"<p>This is really, <b>REALLY</b> great</p> <br><br>"`
donations:count	integer	The count of all donations made via this Event	`123`
donations:total_donated:cents	integer	Numeric amount in cents	`1234500`
donations:total_donated:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
donations:url	uri	The url to retrieve details on all donations made via this Event	`"https://api.betternow.org/events/1234567/donations"`
end_date	date-time	The date when the Event ends. May be blank in the case of a single day event.	`"2012-01-01"`
fundraisers:count	integer	The number of active fundraisers	`12`
fundraisers:url	uri	The url to retrieve all fundraisers	`"https://api.betternow.org/events/1234567/fundraisers"`
html_url	uri	The url to the Event page on BetterNow	`"https://dk.betternow.org/events/copenhagen-marathon-2013"`
id	string	unique identifier of event	`1234567`
location:city	string	The name of a city	`"København"`
logo_url	uri	The logo for the Event	`"https://cdn.example.net/logo.png"`
name	string	the name of the Event	`"Copenhagen Marathon 2013"`
slug	string	The current url path component to identify the event. This can, and does, change. pattern: `^([a-z0-9-]{2,})$`	`"cph-marathon-2013"`
start_date	date-time	The date when the Event starts	`"2012-01-01"`
updated_at	date-time	when event was updated	`"2012-01-01T12:00:00Z"`
url	uri		`"https://api.betternow.org/events/1234567"`

Event Info

Info for existing event.

GET /events/{event_id_or_slug}

Curl Example

$ curl -n https://api.betternow.org/events/$EVENT_ID_OR_SLUG \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "activity_score": 987654321,
  "choose_project_to_fundraise_for_url": "https://www.betternow.org/dk/fundraisers/new?event_id=1234567",
  "cover_media": {
    "image": {
      "url": "https://cnd.example.net/image.jpg"
    },
    "video": {
      "url": "https://youtu.be/12345",
      "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
    },
    "thumb": {
      "url": "https://cnd.example.net/image.jpg"
    }
  },
  "created_at": "2012-01-01T12:00:00Z",
  "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/events/1234567/donations"
  },
  "end_date": "2012-01-01",
  "fundraisers": {
    "count": 12,
    "url": "https://api.betternow.org/events/1234567/fundraisers"
  },
  "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013",
  "id": 1234567,
  "location": {
    "city": "København"
  },
  "name": "Copenhagen Marathon 2013",
  "logo_url": "https://cdn.example.net/logo.png",
  "updated_at": "2012-01-01T12:00:00Z",
  "slug": "cph-marathon-2013",
  "start_date": "2012-01-01",
  "url": "https://api.betternow.org/events/1234567"
}

Event List

List existing events.

GET /events

Curl Example

$ curl -n https://api.betternow.org/events \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "choose_project_to_fundraise_for_url": "https://www.betternow.org/dk/fundraisers/new?event_id=1234567",
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/events/1234567/donations"
    },
    "end_date": "2012-01-01",
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/events/1234567/fundraisers"
    },
    "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013",
    "id": 1234567,
    "location": {
      "city": "København"
    },
    "name": "Copenhagen Marathon 2013",
    "logo_url": "https://cdn.example.net/logo.png",
    "updated_at": "2012-01-01T12:00:00Z",
    "slug": "cph-marathon-2013",
    "start_date": "2012-01-01",
    "url": "https://api.betternow.org/events/1234567"
  }
]

Event List Projects

List all Projects associated with an Event

GET /events/{event_id_or_slug}/projects

Curl Example

$ curl -n https://api.betternow.org/events/$EVENT_ID_OR_SLUG/projects \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "We need your money for this <b>GREAT</b> project",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/projects/1234567/donations"
    },
    "donate_url": "https://www.betternow.org/dk/fundraisers/helpnow-indsamling21/donations/new",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt",
    "id": 1234567,
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/projects/1234567/fundraisers"
    },
    "name": "HelpNows generelle arbejde",
    "new_fundraiser_url": "https://www.betternow.org/dk/projects/helpnow-projekt/fundraisers/new",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/projects/1234567",
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "slug": "helpnow-project",
    "state": "published",
    "your_reference": "my-crm-project-reference-123456"
  }
]

Event List Fundraisers

List all Fundraisers associated with an Event

GET /events/{event_id_or_slug}/fundraisers

Curl Example

$ curl -n https://api.betternow.org/events/$EVENT_ID_OR_SLUG/fundraisers \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "allow_organisation_contact": true,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "state": "published",
    "fundraiser_type": "birthday",
    "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/fundraisers/1234567/donations"
    },
    "end_date": "2012-01-01",
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "headline": "Firstname Lastname's Fundraiser for HelpNow",
    "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
    "id": 1234567,
    "owner": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "partner_data": null,
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "slug": "firstname-lastnames-fundraiser-for-helpnow",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/fundraisers/1234567",
    "your_reference": "my-crm-project-reference-123456",
    "honoree": "Dorthe Jensen Hansen",
    "birth_date": "2012-01-01",
    "death_date": "2012-01-01",
    "funeral_date": "2012-01-01"
  }
]

Event List Teams

List all Teams associated with an Event

GET /events/{event_id_or_slug}/teams

Curl Example

$ curl -n https://api.betternow.org/events/$EVENT_ID_OR_SLUG/teams \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "captain": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "contact_information": {
      "captain_name": "Helle Hansen",
      "email": "myteam@example.com",
      "phone": "+4599999999 ex. 1234"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/teams/1234567/donations"
    },
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/teams/1234567/fundraisers"
    },
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "html_url": "https://dk.betternow.org/teams/team-novo",
    "id": 1234567,
    "logo_url": "https://cdn.example.net/logo.png",
    "name": "Team NOVO",
    "partner_data": null,
    "slug": "team-novo",
    "state": "published",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/team/1234567"
  }
]

Fundraising Page

Detailed information about a single Fundraising Page on BetterNow.org

Attributes

Name	Type	Description	Example
activity_score	integer	A number that can be used for sorting lists of fundraisers. More recently active fundraisers should have a higher activity score than fundraisers who have raised more money long ago.	`987654321`
allow_organisation_contact	boolean	If the person has consented to be contacted by the organisation	`true`
birth_date	date	The day the person who a tribute_fund fundraiser is honoring was born.	`"2012-01-01"`
cover_media:image:url	uri	The url for the image. On the BetterNow site, the video takes precedence if both exist. 461x306 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:thumb:url	uri	The url for the cover media that should be displayed in e.g. a card view. 120x80 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:video:oembed_html	string	The OEmbed HTML to display the video. Could be blank.	`"<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"`
cover_media:video:url	uri	The url for the video. Currently only YouTube and Vimeo are supported. Could be blank.	`"https://youtu.be/12345"`
created_at	date-time	when resource was created	`"2012-01-01T12:00:00Z"`
death_date	date	The day the person who a tribute_fund fundraiser is honoring died.	`"2012-01-01"`
description	string	The text written by the fundraiser owner. Contains HTML.	`"<p>This is really, <b>REALLY</b> great</p> <br><br>"`
donate_url	uri	The current url to donate via the fundraising page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new"`
donations:count	integer	The count of all donations made to this fundraiser	`123`
donations:total_donated:cents	integer	Numeric amount in cents	`1234500`
donations:total_donated:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
donations:url	uri	The url to retrieve details on all donations made to this fundraiser	`"https://api.betternow.org/fundraisers/1234567/donations"`
end_date	date	The end date for a fundraiser.	`"2012-01-01"`
event:html_url	uri	The url to the Event page on BetterNow	`"https://dk.betternow.org/events/copenhagen-marathon-2013"`
event:id	string	unique identifier of event	`1234567`
event:name	string	the name of the Event	`"Copenhagen Marathon 2013"`
event:url	uri		`"https://api.betternow.org/events/1234567"`
fundraiser_type	string	The type of the fundraiser on BetterNow one of:`"birthday"` or `"anniversary"` or `"in_memory_of"` or `"sports_event"` or `"corporate"` or `"cultural_event"` or `"sponsorable"` or `"tribute_fund"` or `"other"`	`"birthday"`
funeral_date	date	The date of the funeral for the person who a tribute_fund fundraiser is honoring.	`"2012-01-01"`
goal:cents	integer	Numeric amount in cents	`1234500`
goal:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
headline	string	The headline for this fundraising page	`"Firstname Lastname's Fundraiser for HelpNow"`
honoree	string	The name of the person who a tribute_fund fundraiser is honoring	`"Dorthe Jensen Hansen"`
html_url	uri	The current url to view the fundraising page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow"`
id	string	The unique identifier of the fundraising page	`1234567`
owner:avatar_url	uri	The URL for the avatar image for the user. 92x92 pixels	`"https://cdn.example.net/avatar.jpg"`
owner:first_name	string	The first name of the user	`"Firstname"`
owner:last_name	string	The last name of the user	`"Lastname"`
owner:middle_name	string	The middle name of the user	`"Middlename"`
owner:private_person_url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`
partner_data	object	An object containing data from partner systems. Structure varies depending on the partner.
project:html_url	uri	The current url to view the project page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/projects/helpnow-projekt"`
project:id	string	Unique identifier of project	`1234567`
project:name	string	The name of the Project	`"HelpNows generelle arbejde"`
project:url	uri		`"https://api.betternow.org/projects/1234567"`
recipient:html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
recipient:id	string	Unique identifier of organisation	`1234567`
recipient:name	string	The name of the Organisation	`"HelpNow"`
recipient:url	uri		`"https://api.betternow.org/organisations/1234567"`
slug	string	The current url path component to identify the fundraiser. This can, and does, change. pattern: `^([a-z0-9-]{2,})$`	`"firstname-lastnames-fundraiser-for-helpnow"`
state	string	The state of this fundraiser	`"published"`
team:html_url	uri	The url to the Team page on BetterNow	`"https://dk.betternow.org/teams/team-novo"`
team:id	string	unique identifier of team	`1234567`
team:name	string	the name of the Team	`"Team NOVO"`
team:url	uri		`"https://api.betternow.org/team/1234567"`
updated_at	date-time	when resource was updated	`"2012-01-01T12:00:00Z"`
url	uri		`"https://api.betternow.org/fundraisers/1234567"`
your_reference	string	A string that you can use to identify the project and its fundraisers and donations. The value will be inherited by any fundraisers created for the project and any donations made via the fundraisers. Commonly used to assign donations to e.g. a campaign in your CRM system. You can set this value in the dashboard for your project.	`"my-crm-project-reference-123456"`

Fundraising Page Info

Info for existing fundraiser.

GET /fundraisers/{fundraiser_id_or_slug}

Curl Example

$ curl -n https://api.betternow.org/fundraisers/$FUNDRAISER_ID_OR_SLUG \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "activity_score": 987654321,
  "allow_organisation_contact": true,
  "cover_media": {
    "image": {
      "url": "https://cnd.example.net/image.jpg"
    },
    "video": {
      "url": "https://youtu.be/12345",
      "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
    },
    "thumb": {
      "url": "https://cnd.example.net/image.jpg"
    }
  },
  "created_at": "2012-01-01T12:00:00Z",
  "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
  "state": "published",
  "fundraiser_type": "birthday",
  "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/fundraisers/1234567/donations"
  },
  "end_date": "2012-01-01",
  "goal": {
    "cents": 1234500,
    "currency": "EUR"
  },
  "headline": "Firstname Lastname's Fundraiser for HelpNow",
  "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
  "id": 1234567,
  "owner": {
    "avatar_url": "https://cdn.example.net/avatar.jpg",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
  },
  "partner_data": null,
  "recipient": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "team": {
    "id": 1234567,
    "name": "Team NOVO",
    "url": "https://api.betternow.org/team/1234567",
    "html_url": "https://dk.betternow.org/teams/team-novo"
  },
  "project": {
    "id": 1234567,
    "name": "HelpNows generelle arbejde",
    "url": "https://api.betternow.org/projects/1234567",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
  },
  "event": {
    "id": 1234567,
    "name": "Copenhagen Marathon 2013",
    "url": "https://api.betternow.org/events/1234567",
    "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
  },
  "slug": "firstname-lastnames-fundraiser-for-helpnow",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://api.betternow.org/fundraisers/1234567",
  "your_reference": "my-crm-project-reference-123456",
  "honoree": "Dorthe Jensen Hansen",
  "birth_date": "2012-01-01",
  "death_date": "2012-01-01",
  "funeral_date": "2012-01-01"
}

Fundraising Page List

List existing fundraisers.

GET /fundraisers

Curl Example

$ curl -n https://api.betternow.org/fundraisers \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "allow_organisation_contact": true,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "state": "published",
    "fundraiser_type": "birthday",
    "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/fundraisers/1234567/donations"
    },
    "end_date": "2012-01-01",
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "headline": "Firstname Lastname's Fundraiser for HelpNow",
    "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
    "id": 1234567,
    "owner": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "partner_data": null,
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "slug": "firstname-lastnames-fundraiser-for-helpnow",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/fundraisers/1234567",
    "your_reference": "my-crm-project-reference-123456",
    "honoree": "Dorthe Jensen Hansen",
    "birth_date": "2012-01-01",
    "death_date": "2012-01-01",
    "funeral_date": "2012-01-01"
  }
]

Fundraising Page Create

Create a fundraiser. Requires a secret key.

POST /fundraisers

Required Parameters

Name	Type	Description	Example
email	string		`"user@example.com"`
first_name	string	The first name of the user	`"Firstname"`
last_name	string	The last name of the user	`"Lastname"`
name	string	The headline for this fundraising page	`"Firstname Lastname's Fundraiser for HelpNow"`
project_id	string	Unique identifier of project	`1234567`
site_id	integer	unique identifier of site	`1234567`

Optional Parameters

Name	Type	Description	Example
avatar_url	uri	The url of an image to be shown in place of the owner’s avatar.	`"https://example.com/image.jpg"`
birth_date	date	The day the person who a tribute_fund fundraiser is honoring was born.	`"2012-01-01"`
death_date	date	The day the person who a tribute_fund fundraiser is honoring died.	`"2012-01-01"`
description	string	The text written by the fundraiser owner. Contains HTML.	`"<p>This is really, <b>REALLY</b> great</p> <br><br>"`
end_date	date	The end date for a fundraiser.	`"2012-01-01"`
event_id	string	unique identifier of event	`1234567`
fundraiser_type	string	The type of the fundraiser on BetterNow one of:`"birthday"` or `"anniversary"` or `"in_memory_of"` or `"sports_event"` or `"corporate"` or `"cultural_event"` or `"sponsorable"` or `"tribute_fund"` or `"other"`	`"birthday"`
funeral_date	date	The date of the funeral for the person who a tribute_fund fundraiser is honoring.	`"2012-01-01"`
goal:cents	integer	Numeric amount in cents	`1234500`
goal:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
honoree	string	The name of the person who a tribute_fund fundraiser is honoring	`"Dorthe Jensen Hansen"`
middle_name	string	The middle name of the user	`"Middlename"`
phone	string	Phone number in E.164 format	`"+4510101010"`
team_id	string	unique identifier of team	`1234567`

Curl Example

$ curl -n -X POST https://api.betternow.org/fundraisers \
  -d '{
  "name": "Firstname Lastname's Fundraiser for HelpNow",
  "email": "user@example.com",
  "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
  "goal": {
    "cents": 1234500,
    "currency": "EUR"
  },
  "end_date": "2012-01-01",
  "team_id": 1234567,
  "event_id": 1234567,
  "fundraiser_type": "birthday",
  "first_name": "Firstname",
  "middle_name": "Middlename",
  "last_name": "Lastname",
  "phone": "+4510101010",
  "site_id": 1234567,
  "project_id": 1234567,
  "avatar_url": "https://example.com/image.jpg",
  "honoree": "Dorthe Jensen Hansen",
  "birth_date": "2012-01-01",
  "death_date": "2012-01-01",
  "funeral_date": "2012-01-01"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "activity_score": 987654321,
  "allow_organisation_contact": true,
  "cover_media": {
    "image": {
      "url": "https://cnd.example.net/image.jpg"
    },
    "video": {
      "url": "https://youtu.be/12345",
      "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
    },
    "thumb": {
      "url": "https://cnd.example.net/image.jpg"
    }
  },
  "created_at": "2012-01-01T12:00:00Z",
  "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
  "state": "published",
  "fundraiser_type": "birthday",
  "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/fundraisers/1234567/donations"
  },
  "end_date": "2012-01-01",
  "goal": {
    "cents": 1234500,
    "currency": "EUR"
  },
  "headline": "Firstname Lastname's Fundraiser for HelpNow",
  "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
  "id": 1234567,
  "owner": {
    "avatar_url": "https://cdn.example.net/avatar.jpg",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
  },
  "partner_data": null,
  "recipient": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "team": {
    "id": 1234567,
    "name": "Team NOVO",
    "url": "https://api.betternow.org/team/1234567",
    "html_url": "https://dk.betternow.org/teams/team-novo"
  },
  "project": {
    "id": 1234567,
    "name": "HelpNows generelle arbejde",
    "url": "https://api.betternow.org/projects/1234567",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
  },
  "event": {
    "id": 1234567,
    "name": "Copenhagen Marathon 2013",
    "url": "https://api.betternow.org/events/1234567",
    "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
  },
  "slug": "firstname-lastnames-fundraiser-for-helpnow",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://api.betternow.org/fundraisers/1234567",
  "your_reference": "my-crm-project-reference-123456",
  "honoree": "Dorthe Jensen Hansen",
  "birth_date": "2012-01-01",
  "death_date": "2012-01-01",
  "funeral_date": "2012-01-01"
}

Fundraising Page List Donations

List the donations for existing fundraiser. Donations will always be returned in reverse-chronological order (newest first).

GET /fundraisers/{fundraiser_id_or_slug}/donations

Curl Example

$ curl -n https://api.betternow.org/fundraisers/$FUNDRAISER_ID_OR_SLUG/donations \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "amount": {
      "cents": 12345,
      "currency": "EUR"
    },
    "comment": "Wow, what a great idea!",
    "created_at": "2012-01-01T12:00:00Z",
    "id": 1234567,
    "name": "Joes Truck Stop",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/donations/542e5f3b-7d8e-475c-8d25-5a2c0742672d",
    "private_details_url": "https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d"
  }
]

Fundraising Page List Fundraiser Updates

List the updates for existing fundraiser.

GET /fundraisers/{fundraiser_id_or_slug}/updates

Curl Example

$ curl -n https://api.betternow.org/fundraisers/$FUNDRAISER_ID_OR_SLUG/updates \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "body": "<p>Thanks for all your support - you <strong>rock!</strong>",
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "owner": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "title": "Great job everyone!",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Fundraiser Invitation

An invitation to create a fundraiser for a specific project

Attributes

Name	Type	Description	Example
created_at	date-time	when the invitation was created	`"2012-01-01T12:00:00Z"`
id	string	The unique identifier of the fundraiser invitation	`1234567`
invitation_link	uri		`"https://example.betternow.org/i/invitation-token"`
invitee:avatar_url	uri	The URL for the avatar image for the user. 92x92 pixels	`"https://cdn.example.net/avatar.jpg"`
invitee:first_name	string	The first name of the user	`"Firstname"`
invitee:last_name	string	The last name of the user	`"Lastname"`
invitee:middle_name	string	The middle name of the user	`"Middlename"`
invitee:private_person_url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`
inviter:avatar_url	uri	The URL for the avatar image for the user. 92x92 pixels	`"https://cdn.example.net/avatar.jpg"`
inviter:first_name	string	The first name of the user	`"Firstname"`
inviter:last_name	string	The last name of the user	`"Lastname"`
inviter:middle_name	string	The middle name of the user	`"Middlename"`
inviter:private_person_url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`
project:html_url	uri	The current url to view the project page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/projects/helpnow-projekt"`
project:id	string	Unique identifier of project	`1234567`
project:name	string	The name of the Project	`"HelpNows generelle arbejde"`
project:url	uri		`"https://api.betternow.org/projects/1234567"`
updated_at	date-time	when invitation was updated	`"2012-01-01T12:00:00Z"`

Fundraiser Invitation Create

Create a fundraiser invitation. Requires a secret key.

POST /fundraiser-invitations

Required Parameters

Name	Type	Description	Example
email	string	The email that will be sent the invitation	`"user@example.com"`
first_name	string	The first name of the user	`"Firstname"`
inviter_email	string	Must be an exisiting user in the BetterNow system	`"user@example.com"`
last_name	string	The last name of the user	`"Lastname"`
project_id	string	Unique identifier of project	`1234567`
site_id	integer	unique identifier of site	`1234567`

Optional Parameters

Name	Type	Description	Example
middle_name	string	The middle name of the user	`"Middlename"`

Curl Example

$ curl -n -X POST https://api.betternow.org/fundraiser-invitations \
  -d '{
  "inviter_email": "user@example.com",
  "site_id": 1234567,
  "project_id": 1234567,
  "email": "user@example.com",
  "first_name": "Firstname",
  "middle_name": "Middlename",
  "last_name": "Lastname"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "created_at": "2012-01-01T12:00:00Z",
  "id": 1234567,
  "inviter": {
    "avatar_url": "https://cdn.example.net/avatar.jpg",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
  },
  "invitee": {
    "avatar_url": "https://cdn.example.net/avatar.jpg",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
  },
  "invitation_link": "https://example.betternow.org/i/invitation-token",
  "project": {
    "id": 1234567,
    "name": "HelpNows generelle arbejde",
    "url": "https://api.betternow.org/projects/1234567",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
  },
  "updated_at": "2012-01-01T12:00:00Z"
}

Fundraiser Update

An update that was sent to all donors to this fundraiser and posted on the fundraiser page

Attributes

Name	Type	Description	Example
body	string	The body of the update, can contain HTML	`"<p>Thanks for all your support - you <strong>rock!</strong>"`
cover_media:image:url	uri	The url for the image. On the BetterNow site, the video takes precedence if both exist. 461x306 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:thumb:url	uri	The url for the cover media that should be displayed in e.g. a card view. 120x80 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:video:oembed_html	string	The OEmbed HTML to display the video. Could be blank.	`"<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"`
cover_media:video:url	uri	The url for the video. Currently only YouTube and Vimeo are supported. Could be blank.	`"https://youtu.be/12345"`
created_at	date-time	when update was created	`"2012-01-01T12:00:00Z"`
owner:avatar_url	uri	The URL for the avatar image for the user. 92x92 pixels	`"https://cdn.example.net/avatar.jpg"`
owner:first_name	string	The first name of the user	`"Firstname"`
owner:last_name	string	The last name of the user	`"Lastname"`
owner:middle_name	string	The middle name of the user	`"Middlename"`
owner:private_person_url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`
title	string	The title of the update	`"Great job everyone!"`
updated_at	date-time	when update was updated	`"2012-01-01T12:00:00Z"`

Organisation

An Organisation can receive Donations on BetterNow

Attributes

Name	Type	Description	Example
cover_media:image:url	uri	The url for the image. On the BetterNow site, the video takes precedence if both exist. 461x306 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:thumb:url	uri	The url for the cover media that should be displayed in e.g. a card view. 120x80 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:video:oembed_html	string	The OEmbed HTML to display the video. Could be blank.	`"<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"`
cover_media:video:url	uri	The url for the video. Currently only YouTube and Vimeo are supported. Could be blank.	`"https://youtu.be/12345"`
created_at	date-time	When organisation was created	`"2012-01-01T12:00:00Z"`
description	string	The text written by the Organisation’s administrators. Contains HTML	`"HelpNow is a dummy organisation created by BetterNow - to help us doing tutorial videos and screenshots. It is not a real organisation, and you cannot donate here.<br><br><br>"`
donate_url	uri	The current url to donate directly to the organisation on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://www.betternow.org/dk/fundraisers/helpnow-indsamling1/donations/new"`
donations:count	integer	The count of all donations made to this project	`123`
donations:total_donated:cents	integer	Numeric amount in cents	`1234500`
donations:total_donated:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
donations:url	uri	The url to retrieve details on all donations made to this organisation	`"https://api.betternow.org/organisations/1234567/donations"`
fundraisers:count	integer	The number of active fundraisers	`12`
fundraisers:url	uri	The url to retrieve all fundraisers	`"https://api.betternow.org/organisations/1234567/fundraisers"`
html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
id	string	Unique identifier of organisation	`1234567`
logo_url	uri	The logo for the Organisation. 92x92 pixels.	`"https://cdn.example.net/logo.png"`
name	string	The name of the Organisation	`"HelpNow"`
new_fundraiser_url	uri	The current url to create a new Fundraiser for this organisation on BetterNow. This can, and does, change. Requests to old urls will redirect to the current url.	`"https://www.betternow.org/dk/projects/helpnow-projekt/fundraisers/new"`
projects:count	integer	The count of the organisation’s active projects	`12`
projects:url	uri	The url to retrieve details about this organisation’s projects	`"https://api.betternow.org/organisations/1234567/projects"`
updated_at	date-time	When organisation was updated	`"2012-01-01T12:00:00Z"`
url	uri		`"https://api.betternow.org/organisations/1234567"`

Organisation Info

Info for existing organisation.

GET /organisations/{organisation_id_or_slug}

Curl Example

$ curl -n https://api.betternow.org/organisations/$ORGANISATION_ID_OR_SLUG \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "cover_media": {
    "image": {
      "url": "https://cnd.example.net/image.jpg"
    },
    "video": {
      "url": "https://youtu.be/12345",
      "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
    },
    "thumb": {
      "url": "https://cnd.example.net/image.jpg"
    }
  },
  "created_at": "2012-01-01T12:00:00Z",
  "description": "HelpNow is a dummy organisation created by BetterNow - to help us doing tutorial videos and screenshots. It is not a real organisation, and you cannot donate here.<br><br><br>",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/organisations/1234567/donations"
  },
  "donate_url": "https://www.betternow.org/dk/fundraisers/helpnow-indsamling1/donations/new",
  "fundraisers": {
    "count": 12,
    "url": "https://api.betternow.org/organisations/1234567/fundraisers"
  },
  "html_url": "https://dk.betternow.org/charities/helpnow",
  "id": 1234567,
  "logo_url": "https://cdn.example.net/logo.png",
  "name": "HelpNow",
  "new_fundraiser_url": "https://www.betternow.org/dk/projects/helpnow-projekt/fundraisers/new",
  "projects": {
    "count": 12,
    "url": "https://api.betternow.org/organisations/1234567/projects"
  },
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://api.betternow.org/organisations/1234567"
}

Organisation List Projects

List all Projects for an existing Organisation. Projects will be ordered by activity score, descending.

GET /organisations/{organisation_id_or_slug}/projects

Curl Example

$ curl -n https://api.betternow.org/organisations/$ORGANISATION_ID_OR_SLUG/projects \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "We need your money for this <b>GREAT</b> project",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/projects/1234567/donations"
    },
    "donate_url": "https://www.betternow.org/dk/fundraisers/helpnow-indsamling21/donations/new",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt",
    "id": 1234567,
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/projects/1234567/fundraisers"
    },
    "name": "HelpNows generelle arbejde",
    "new_fundraiser_url": "https://www.betternow.org/dk/projects/helpnow-projekt/fundraisers/new",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/projects/1234567",
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "slug": "helpnow-project",
    "state": "published",
    "your_reference": "my-crm-project-reference-123456"
  }
]

Organisation List Fundraisers

List all Fundraisers for an existing Organisation. Fundraisers will be ordered by activity score, descending.

GET /organisations/{organisation_id_or_slug}/fundraisers

Curl Example

$ curl -n https://api.betternow.org/organisations/$ORGANISATION_ID_OR_SLUG/fundraisers \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "allow_organisation_contact": true,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "state": "published",
    "fundraiser_type": "birthday",
    "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/fundraisers/1234567/donations"
    },
    "end_date": "2012-01-01",
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "headline": "Firstname Lastname's Fundraiser for HelpNow",
    "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
    "id": 1234567,
    "owner": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "partner_data": null,
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "slug": "firstname-lastnames-fundraiser-for-helpnow",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/fundraisers/1234567",
    "your_reference": "my-crm-project-reference-123456",
    "honoree": "Dorthe Jensen Hansen",
    "birth_date": "2012-01-01",
    "death_date": "2012-01-01",
    "funeral_date": "2012-01-01"
  }
]

Organisation List Donations

List the donations for an existing Organisation. Donations will always be returned in reverse-chronological order (newest first).

GET /organisations/{organisation_id_or_slug}/donations

Curl Example

$ curl -n https://api.betternow.org/organisations/$ORGANISATION_ID_OR_SLUG/donations \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "amount": {
      "cents": 12345,
      "currency": "EUR"
    },
    "allow_organisation_contact": true,
    "comment": "Wow, what a great idea!",
    "created_at": "2012-01-01T12:00:00Z",
    "id": 1234567,
    "private_details_url": "https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d",
    "name": "Joes Truck Stop",
    "updated_at": "2012-01-01T12:00:00Z",
    "fundraiser": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "your_reference": "my-crm-project-reference-123456"
  }
]

Person

Private (personally identifiable) information about a BetterNow user (donor, fundraiser owner, team captain, etc.) Requires a secret key.

Attributes

Name	Type	Description	Example
allow_site_contact	boolean	true if the user has agreed to be contacted by the site they either donated via or signed up on.	`true`
birth_day	integer	Range: `1 <= value <= 31`	`1`
birth_month	integer	Range: `1 <= value <= 12`	`1`
created_at	date-time	when user was created	`"2012-01-01T12:00:00Z"`
donations:count	integer	The count of all donations made by this person	`123`
donations:total_donated:cents	integer	Numeric amount in cents	`1234500`
donations:total_donated:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
donations:url	uri	The url to retrieve details on all donations made by this person	`"https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/donations"`
email	string		`"user@example.com"`
first_name	string	The first name of the user	`"Firstname"`
fundraisers:count	integer	The number of active fundraisers	`12`
fundraisers:url	uri	The url to retrieve all fundraisers	`"https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/fundraisers"`
id	string	unique identifier of person	`"fdb6cd2a-3ca7-40db-8fae-135daebecdab"`
last_name	string	The last name of the user	`"Lastname"`
locale	string	ISO 639-1 locale code	`"en"`
middle_name	string	The middle name of the user	`"Middlename"`
partner_reference	string	This is an external identifier that is intended to be used in linking partner systems to BetterNow. The partner reference can be supplied when creating a user.	`"example"`
phone	string	Phone number in E.164 format	`"+4510101010"`
teams:count	integer	The number of teams	`12`
teams:url	uri	The url to retrieve all teams	`"https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/teams"`
title	string		`"Director of Personal Fundraising"`
url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`

Person Info

Info for existing person.

GET /people/{person_id}

Curl Example

$ curl -n https://api.betternow.org/people/$PERSON_ID \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "id": "fdb6cd2a-3ca7-40db-8fae-135daebecdab",
  "first_name": "Firstname",
  "middle_name": "Middlename",
  "last_name": "Lastname",
  "email": "user@example.com",
  "phone": "+4510101010",
  "title": "Director of Personal Fundraising",
  "created_at": "2012-01-01T12:00:00Z",
  "birth_month": 1,
  "birth_day": 1,
  "locale": "en",
  "allow_site_contact": true,
  "partner_reference": "example",
  "url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/donations"
  },
  "fundraisers": {
    "count": 12,
    "url": "https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/fundraisers"
  },
  "teams": {
    "count": 12,
    "url": "https://api.betternow.org/people/fdb6cd2a-3ca7-40db-8fae-135daebecdab/teams"
  }
}

Person List Donations

List this person’s donations. Donations will always be returned in reverse-chronological order (newest first).

GET /people/{person_id}/donations

Curl Example

$ curl -n https://api.betternow.org/people/$PERSON_ID/donations \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "amount": {
      "cents": 12345,
      "currency": "EUR"
    },
    "allow_organisation_contact": true,
    "comment": "Wow, what a great idea!",
    "created_at": "2012-01-01T12:00:00Z",
    "id": 1234567,
    "private_details_url": "https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d",
    "name": "Joes Truck Stop",
    "updated_at": "2012-01-01T12:00:00Z",
    "fundraiser": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "your_reference": "my-crm-project-reference-123456"
  }
]

Person List Fundraisers

List all of this persons Fundraising Pages. Fundraisers will be ordered by activity score, descending.

GET /people/{person_id}/fundraisers

Curl Example

$ curl -n https://api.betternow.org/people/$PERSON_ID/fundraisers \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "allow_organisation_contact": true,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "state": "published",
    "fundraiser_type": "birthday",
    "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/fundraisers/1234567/donations"
    },
    "end_date": "2012-01-01",
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "headline": "Firstname Lastname's Fundraiser for HelpNow",
    "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
    "id": 1234567,
    "owner": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "partner_data": null,
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "slug": "firstname-lastnames-fundraiser-for-helpnow",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/fundraisers/1234567",
    "your_reference": "my-crm-project-reference-123456",
    "honoree": "Dorthe Jensen Hansen",
    "birth_date": "2012-01-01",
    "death_date": "2012-01-01",
    "funeral_date": "2012-01-01"
  }
]

Person List Teams

List all Teams this person is a member of

GET /people/{person_id}/teams

Curl Example

$ curl -n https://api.betternow.org/people/$PERSON_ID/teams \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "captain": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "contact_information": {
      "captain_name": "Helle Hansen",
      "email": "myteam@example.com",
      "phone": "+4599999999 ex. 1234"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/teams/1234567/donations"
    },
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/teams/1234567/fundraisers"
    },
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "html_url": "https://dk.betternow.org/teams/team-novo",
    "id": 1234567,
    "logo_url": "https://cdn.example.net/logo.png",
    "name": "Team NOVO",
    "partner_data": null,
    "slug": "team-novo",
    "state": "published",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/team/1234567"
  }
]

Project

A Project is a specific cause that Users can Fundraise for. An Organisation typically has several Projects

Attributes

Name	Type	Description	Example
activity_score	integer	A number that can be used for sorting lists of projects. More recently active projects should have a higher activity score than projects who have raised more money long ago.	`987654321`
cover_media:image:url	uri	The url for the image. On the BetterNow site, the video takes precedence if both exist. 461x306 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:thumb:url	uri	The url for the cover media that should be displayed in e.g. a card view. 120x80 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:video:oembed_html	string	The OEmbed HTML to display the video. Could be blank.	`"<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"`
cover_media:video:url	uri	The url for the video. Currently only YouTube and Vimeo are supported. Could be blank.	`"https://youtu.be/12345"`
created_at	date-time	When project was created	`"2012-01-01T12:00:00Z"`
description	string	The text written by the Project’s administrators. Contains HTML	`"We need your money for this <b>GREAT</b> project"`
donate_url	uri	The current url to donate directly to the project on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://www.betternow.org/dk/fundraisers/helpnow-indsamling21/donations/new"`
donations:count	integer	The count of all donations made to this project	`123`
donations:total_donated:cents	integer	Numeric amount in cents	`1234500`
donations:total_donated:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
donations:url	uri	The url to retrieve details on all donations made to this project	`"https://api.betternow.org/projects/1234567/donations"`
fundraisers:count	integer	The number of active fundraisers	`12`
fundraisers:url	uri	The url to retrieve all fundraisers	`"https://api.betternow.org/projects/1234567/fundraisers"`
html_url	uri	The current url to view the project page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/projects/helpnow-projekt"`
id	string	Unique identifier of project	`1234567`
name	string	The name of the Project	`"HelpNows generelle arbejde"`
new_fundraiser_url	uri	The current url to create a new Fundraiser for this project on BetterNow. This can, and does, change. Requests to old urls will redirect to the current url.	`"https://www.betternow.org/dk/projects/helpnow-projekt/fundraisers/new"`
recipient:html_url	uri	The current url to view the organisation page on BetterNow. This can, and does, change. Requests to old urls will be redirect to the current url.	`"https://dk.betternow.org/charities/helpnow"`
recipient:id	string	Unique identifier of organisation	`1234567`
recipient:name	string	The name of the Organisation	`"HelpNow"`
recipient:url	uri		`"https://api.betternow.org/organisations/1234567"`
slug	string	The current url path component to identify the project. This can, and does, change. pattern: `^([a-z0-9-]{2,})$`	`"helpnow-project"`
state	string	The state of this project	`"published"`
updated_at	date-time	When project was updated	`"2012-01-01T12:00:00Z"`
url	uri		`"https://api.betternow.org/projects/1234567"`
your_reference	string	A string that you can use to identify the project and its fundraisers and donations. The value will be inherited by any fundraisers created for the project and any donations made via the fundraisers. Commonly used to assign donations to e.g. a campaign in your CRM system. You can set this value in the dashboard for your project.	`"my-crm-project-reference-123456"`

Project Info

Info for existing project.

GET /projects/{project_id_or_slug}

Curl Example

$ curl -n https://api.betternow.org/projects/$PROJECT_ID_OR_SLUG \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "activity_score": 987654321,
  "cover_media": {
    "image": {
      "url": "https://cnd.example.net/image.jpg"
    },
    "video": {
      "url": "https://youtu.be/12345",
      "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
    },
    "thumb": {
      "url": "https://cnd.example.net/image.jpg"
    }
  },
  "created_at": "2012-01-01T12:00:00Z",
  "description": "We need your money for this <b>GREAT</b> project",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/projects/1234567/donations"
  },
  "donate_url": "https://www.betternow.org/dk/fundraisers/helpnow-indsamling21/donations/new",
  "html_url": "https://dk.betternow.org/projects/helpnow-projekt",
  "id": 1234567,
  "fundraisers": {
    "count": 12,
    "url": "https://api.betternow.org/projects/1234567/fundraisers"
  },
  "name": "HelpNows generelle arbejde",
  "new_fundraiser_url": "https://www.betternow.org/dk/projects/helpnow-projekt/fundraisers/new",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://api.betternow.org/projects/1234567",
  "recipient": {
    "id": 1234567,
    "name": "HelpNow",
    "url": "https://api.betternow.org/organisations/1234567",
    "html_url": "https://dk.betternow.org/charities/helpnow"
  },
  "slug": "helpnow-project",
  "state": "published",
  "your_reference": "my-crm-project-reference-123456"
}

Project List Fundraisers

List all Fundraisers for an existing Project. Fundraisers will be ordered by activity score, descending.

GET /projects/{project_id_or_slug}/fundraisers

Curl Example

$ curl -n https://api.betternow.org/projects/$PROJECT_ID_OR_SLUG/fundraisers \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "allow_organisation_contact": true,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "state": "published",
    "fundraiser_type": "birthday",
    "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/fundraisers/1234567/donations"
    },
    "end_date": "2012-01-01",
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "headline": "Firstname Lastname's Fundraiser for HelpNow",
    "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
    "id": 1234567,
    "owner": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "partner_data": null,
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "slug": "firstname-lastnames-fundraiser-for-helpnow",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/fundraisers/1234567",
    "your_reference": "my-crm-project-reference-123456",
    "honoree": "Dorthe Jensen Hansen",
    "birth_date": "2012-01-01",
    "death_date": "2012-01-01",
    "funeral_date": "2012-01-01"
  }
]

Project List Donations

List the donations for existing project. Donations will always be returned in reverse-chronological order (newest first).

GET /projects/{project_id_or_slug}/donations

Curl Example

$ curl -n https://api.betternow.org/projects/$PROJECT_ID_OR_SLUG/donations \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "amount": {
      "cents": 12345,
      "currency": "EUR"
    },
    "allow_organisation_contact": true,
    "comment": "Wow, what a great idea!",
    "created_at": "2012-01-01T12:00:00Z",
    "id": 1234567,
    "private_details_url": "https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d",
    "name": "Joes Truck Stop",
    "updated_at": "2012-01-01T12:00:00Z",
    "fundraiser": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "your_reference": "my-crm-project-reference-123456"
  }
]

Site

A website running the BetterNow software.

Attributes

Name	Type	Description	Example
cname	string	The CNAME dns record.	`"fundraising.betternow.org"`
created_at	date-time	when site was created	`"2012-01-01T12:00:00Z"`
hostname	string	The hostname for this site.	`"sample-event.eventsite.org"`
id	integer	unique identifier of site	`1234567`
subdomain	string	The unique subdomain for this site.	`"sample-event"`
updated_at	date-time	when site was updated	`"2012-01-01T12:00:00Z"`

Site List

List existing sites

GET /sites

Curl Example

$ curl -n https://api.betternow.org/sites \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "cname": "fundraising.betternow.org",
    "created_at": "2012-01-01T12:00:00Z",
    "id": 1234567,
    "hostname": "sample-event.eventsite.org",
    "subdomain": "sample-event",
    "updated_at": "2012-01-01T12:00:00Z"
  }
]

Team

A Team is a collection of Fundraisers, who may or may not be raising money in connection with a single Event.

Attributes

Name	Type	Description	Example
captain:avatar_url	uri	The URL for the avatar image for the user. 92x92 pixels	`"https://cdn.example.net/avatar.jpg"`
captain:first_name	string	The first name of the user	`"Firstname"`
captain:last_name	string	The last name of the user	`"Lastname"`
captain:middle_name	string	The middle name of the user	`"Middlename"`
captain:private_person_url	uri	The URL to retreive private information about the user. A secret key is required for this URL	`"https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"`
contact_information:captain_name	string	the public captain name for the team	`"Helle Hansen"`
contact_information:email	string	the public contact email for the team	`"myteam@example.com"`
contact_information:phone	string	the public contact phone for the team	`"+4599999999 ex. 1234"`
cover_media:image:url	uri	The url for the image. On the BetterNow site, the video takes precedence if both exist. 461x306 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:thumb:url	uri	The url for the cover media that should be displayed in e.g. a card view. 120x80 pixels	`"https://cnd.example.net/image.jpg"`
cover_media:video:oembed_html	string	The OEmbed HTML to display the video. Could be blank.	`"<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"`
cover_media:video:url	uri	The url for the video. Currently only YouTube and Vimeo are supported. Could be blank.	`"https://youtu.be/12345"`
created_at	date-time	when team was created	`"2012-01-01T12:00:00Z"`
description	string	Text describing the Team added by the Team Captain. Contains HTML.	`"<p>This is really, <b>REALLY</b> great</p> <br><br>"`
donations:count	integer	The count of all donations made	`123`
donations:total_donated:cents	integer	Numeric amount in cents	`1234500`
donations:total_donated:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
donations:url	uri	The url to retrieve details on all donations made via team members	`"https://api.betternow.org/teams/1234567/donations"`
fundraisers:count	integer	The number of active fundraisers	`12`
fundraisers:url	uri	The url to retrieve all fundraisers	`"https://api.betternow.org/teams/1234567/fundraisers"`
goal:cents	integer	Numeric amount in cents	`1234500`
goal:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
html_url	uri	The url to the Team page on BetterNow	`"https://dk.betternow.org/teams/team-novo"`
id	string	unique identifier of team	`1234567`
logo_url	uri	The logo for the team. 92x92 pixels.	`"https://cdn.example.net/logo.png"`
name	string	the name of the Team	`"Team NOVO"`
partner_data	object	An object containing data from partner systems. Structure varies depending on the partner.
slug	string	The current url path component to identify the team. This can, and does, change. pattern: `^([a-z0-9-]{2,})$`	`"team-novo"`
state	string	The state of this team	`"published"`
updated_at	date-time	when team was updated	`"2012-01-01T12:00:00Z"`
url	uri		`"https://api.betternow.org/team/1234567"`

Team Info

Info for existing team.

GET /teams/{team_id_or_slug}

Curl Example

$ curl -n https://api.betternow.org/teams/$TEAM_ID_OR_SLUG \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "captain": {
    "avatar_url": "https://cdn.example.net/avatar.jpg",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
  },
  "cover_media": {
    "image": {
      "url": "https://cnd.example.net/image.jpg"
    },
    "video": {
      "url": "https://youtu.be/12345",
      "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
    },
    "thumb": {
      "url": "https://cnd.example.net/image.jpg"
    }
  },
  "contact_information": {
    "captain_name": "Helle Hansen",
    "email": "myteam@example.com",
    "phone": "+4599999999 ex. 1234"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/teams/1234567/donations"
  },
  "fundraisers": {
    "count": 12,
    "url": "https://api.betternow.org/teams/1234567/fundraisers"
  },
  "goal": {
    "cents": 1234500,
    "currency": "EUR"
  },
  "html_url": "https://dk.betternow.org/teams/team-novo",
  "id": 1234567,
  "logo_url": "https://cdn.example.net/logo.png",
  "name": "Team NOVO",
  "partner_data": null,
  "slug": "team-novo",
  "state": "published",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://api.betternow.org/team/1234567"
}

Team List

List existing teams.

GET /teams

Curl Example

$ curl -n https://api.betternow.org/teams \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "captain": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "contact_information": {
      "captain_name": "Helle Hansen",
      "email": "myteam@example.com",
      "phone": "+4599999999 ex. 1234"
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/teams/1234567/donations"
    },
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/teams/1234567/fundraisers"
    },
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "html_url": "https://dk.betternow.org/teams/team-novo",
    "id": 1234567,
    "logo_url": "https://cdn.example.net/logo.png",
    "name": "Team NOVO",
    "partner_data": null,
    "slug": "team-novo",
    "state": "published",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/team/1234567"
  }
]

Team Create

Create a team.

POST /teams

Required Parameters

Name	Type	Description	Example
description	string	Text describing the Team added by the Team Captain. Contains HTML.	`"<p>This is really, <b>REALLY</b> great</p> <br><br>"`
email	string		`"user@example.com"`
event_id	string	unique identifier of event	`1234567`
goal:cents	integer	Numeric amount in cents	`1234500`
goal:currency	string	3 character currency code, as specified in ISO 4217 pattern: `^([A-Z]{3})$`	`"EUR"`
name	string	the name of the Team	`"Team NOVO"`
site_id	integer	unique identifier of site	`1234567`

Optional Parameters

Name	Type	Description	Example
first_name	string	The first name of the user	`"Firstname"`
last_name	string	The last name of the user	`"Lastname"`
middle_name	string	The middle name of the user	`"Middlename"`
public_captain_name	string	the public captain name for the team	`"Helle Hansen"`
public_phone_number	string	the public contact phone for the team	`"+4599999999 ex. 1234"`
public_team_email	string	the public contact email for the team	`"myteam@example.com"`

Curl Example

$ curl -n -X POST https://api.betternow.org/teams \
  -d '{
  "name": "Team NOVO",
  "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
  "goal": {
    "cents": 1234500,
    "currency": "EUR"
  },
  "email": "user@example.com",
  "first_name": "Firstname",
  "middle_name": "Middlename",
  "last_name": "Lastname",
  "event_id": 1234567,
  "site_id": 1234567,
  "public_captain_name": "Helle Hansen",
  "public_phone_number": "+4599999999 ex. 1234",
  "public_team_email": "myteam@example.com"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

{
  "captain": {
    "avatar_url": "https://cdn.example.net/avatar.jpg",
    "first_name": "Firstname",
    "middle_name": "Middlename",
    "last_name": "Lastname",
    "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
  },
  "cover_media": {
    "image": {
      "url": "https://cnd.example.net/image.jpg"
    },
    "video": {
      "url": "https://youtu.be/12345",
      "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
    },
    "thumb": {
      "url": "https://cnd.example.net/image.jpg"
    }
  },
  "contact_information": {
    "captain_name": "Helle Hansen",
    "email": "myteam@example.com",
    "phone": "+4599999999 ex. 1234"
  },
  "created_at": "2012-01-01T12:00:00Z",
  "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
  "donations": {
    "count": 123,
    "total_donated": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "url": "https://api.betternow.org/teams/1234567/donations"
  },
  "fundraisers": {
    "count": 12,
    "url": "https://api.betternow.org/teams/1234567/fundraisers"
  },
  "goal": {
    "cents": 1234500,
    "currency": "EUR"
  },
  "html_url": "https://dk.betternow.org/teams/team-novo",
  "id": 1234567,
  "logo_url": "https://cdn.example.net/logo.png",
  "name": "Team NOVO",
  "partner_data": null,
  "slug": "team-novo",
  "state": "published",
  "updated_at": "2012-01-01T12:00:00Z",
  "url": "https://api.betternow.org/team/1234567"
}

Team List Fundraisers

List all Fundraisers that are members of this Team. Fundraisers will be ordered by the amount of money donated, descending

GET /teams/{team_id_or_slug}/fundraisers

Curl Example

$ curl -n https://api.betternow.org/teams/$TEAM_ID_OR_SLUG/fundraisers \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "allow_organisation_contact": true,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "<p>This is really, <b>REALLY</b> great</p> <br><br>",
    "state": "published",
    "fundraiser_type": "birthday",
    "donate_url": "https://www.betternow.org/dk/fundraisers/firstname-lastnames-fundraiser/donations/new",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/fundraisers/1234567/donations"
    },
    "end_date": "2012-01-01",
    "goal": {
      "cents": 1234500,
      "currency": "EUR"
    },
    "headline": "Firstname Lastname's Fundraiser for HelpNow",
    "html_url": "https://dk.betternow.org/fundraisers/firstname-lastnames-fundraiser-for-helpnow",
    "id": 1234567,
    "owner": {
      "avatar_url": "https://cdn.example.net/avatar.jpg",
      "first_name": "Firstname",
      "middle_name": "Middlename",
      "last_name": "Lastname",
      "private_person_url": "https://api.betternow.org/people/3e9344ff-69be-4ab5-a254-07b067325ebe"
    },
    "partner_data": null,
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "slug": "firstname-lastnames-fundraiser-for-helpnow",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/fundraisers/1234567",
    "your_reference": "my-crm-project-reference-123456",
    "honoree": "Dorthe Jensen Hansen",
    "birth_date": "2012-01-01",
    "death_date": "2012-01-01",
    "funeral_date": "2012-01-01"
  }
]

Team List Donations

List all donations given via this Team

GET /teams/{team_id_or_slug}/donations

Curl Example

$ curl -n https://api.betternow.org/teams/$TEAM_ID_OR_SLUG/donations \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "amount": {
      "cents": 12345,
      "currency": "EUR"
    },
    "allow_organisation_contact": true,
    "comment": "Wow, what a great idea!",
    "created_at": "2012-01-01T12:00:00Z",
    "id": 1234567,
    "private_details_url": "https://api.betternow.org/donation-details/542e5f3b-7d8e-475c-8d25-5a2c0742672d",
    "name": "Joes Truck Stop",
    "updated_at": "2012-01-01T12:00:00Z",
    "fundraiser": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "team": {
      "id": 1234567,
      "name": "Team NOVO",
      "url": "https://api.betternow.org/team/1234567",
      "html_url": "https://dk.betternow.org/teams/team-novo"
    },
    "project": {
      "id": 1234567,
      "name": "HelpNows generelle arbejde",
      "url": "https://api.betternow.org/projects/1234567",
      "html_url": "https://dk.betternow.org/projects/helpnow-projekt"
    },
    "event": {
      "id": 1234567,
      "name": "Copenhagen Marathon 2013",
      "url": "https://api.betternow.org/events/1234567",
      "html_url": "https://dk.betternow.org/events/copenhagen-marathon-2013"
    },
    "your_reference": "my-crm-project-reference-123456"
  }
]

Team List Projects

List all Projects that team members are fundraising for

GET /teams/{team_id_or_slug}/projects

Curl Example

$ curl -n https://api.betternow.org/teams/$TEAM_ID_OR_SLUG/projects \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

[
  {
    "activity_score": 987654321,
    "cover_media": {
      "image": {
        "url": "https://cnd.example.net/image.jpg"
      },
      "video": {
        "url": "https://youtu.be/12345",
        "oembed_html": "<iframe width=\\\"480\\\" height=\\\"270\\\" src=\\\"https://www.youtube.com/embed/G1JBOSwjN6Q?feature=oembed\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>"
      },
      "thumb": {
        "url": "https://cnd.example.net/image.jpg"
      }
    },
    "created_at": "2012-01-01T12:00:00Z",
    "description": "We need your money for this <b>GREAT</b> project",
    "donations": {
      "count": 123,
      "total_donated": {
        "cents": 1234500,
        "currency": "EUR"
      },
      "url": "https://api.betternow.org/projects/1234567/donations"
    },
    "donate_url": "https://www.betternow.org/dk/fundraisers/helpnow-indsamling21/donations/new",
    "html_url": "https://dk.betternow.org/projects/helpnow-projekt",
    "id": 1234567,
    "fundraisers": {
      "count": 12,
      "url": "https://api.betternow.org/projects/1234567/fundraisers"
    },
    "name": "HelpNows generelle arbejde",
    "new_fundraiser_url": "https://www.betternow.org/dk/projects/helpnow-projekt/fundraisers/new",
    "updated_at": "2012-01-01T12:00:00Z",
    "url": "https://api.betternow.org/projects/1234567",
    "recipient": {
      "id": 1234567,
      "name": "HelpNow",
      "url": "https://api.betternow.org/organisations/1234567",
      "html_url": "https://dk.betternow.org/charities/helpnow"
    },
    "slug": "helpnow-project",
    "state": "published",
    "your_reference": "my-crm-project-reference-123456"
  }
]

Team Membership

Add or remove a fundraiser for a team

Team Membership Create

Add a fundraiser to a team

POST /team-memberships

Required Parameters

Name	Type	Description	Example
fundraiser_id	string	The unique identifier of the fundraising page	`1234567`
team_id	string	unique identifier of team	`1234567`

Curl Example

$ curl -n -X POST https://api.betternow.org/team-memberships \
  -d '{
  "team_id": 1234567,
  "fundraiser_id": 1234567
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

null

Team Membership Destroy

Delete the association with a team for a fundraiser

DELETE /team-memberships/fundraiser_id

Curl Example

$ curl -n -X DELETE https://api.betternow.org/team-memberships/fundraiser_id \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.betternow+json; version=1"

Response Example

HTTP/1.1 200 OK

null

User

A BetterNow user

Attributes

Name	Type	Description	Example
avatar_url	uri	The URL for the avatar image for the user. 92x92 pixels	`"https://cdn.example.net/avatar.jpg"`
created_at	date-time	when user was created	`"2012-01-01T12:00:00Z"`
first_name	string	The first name of the user	`"Firstname"`
id	integer	unique identifier of user	`1234567`
last_name	string	The last name of the user	`"Lastname"`
middle_name	string	The middle name of the user	`"Middlename"`
updated_at	date-time	when user was updated	`"2012-01-01T12:00:00Z"`

Webhooks

Webhooks are URL endpoints of your choice that receive notifications about activities for your charity on the BetterNow platform and any branded sites.

When you create a webhook, you can choose if it should receive notifications for activities relating to all projects for your charity (present and future) or only one specific project.

All activities for the project(s) configured for the webhook are sent to the endpoint. You can decide if you want to act on the activity or ignore it.

Webhooks Setup

You can add a webhook endpoint in the Integrations section of your charity dashboard.

Activity Types

The following activities will trigger a notification to your endpoint:

Test activity

Activity Type	Description
test	Sent when you create a new webhook or manually request a test notification

User activities

Activity Type	Description
user_deleted	The user has been deleted in the BetterNow system

Fundraiser page activities

Activity Type	Description
fundraiser_created_by_system	A fundraising page is created via an integration with a third-party-system
fundraiser_created_by_user	A fundraising page is created on the web site
fundraiser_edited	A fundraising page is edited
fundraiser_joined_team	A fundraiser page is connected with a team
fundraiser_left_team	A fundraiser page is disconnected from a team
fundraiser_seven_days_until_end_date_reached	There are seven days remaining until the end-date for a fundraiser
fundraiser_halfway_to_end_date	The fundraiser has reached the halfway point
between first publication date and end-date
fundraiser_end_date_reached	The fundraiser has reached its end-date
fundraiser_fifty_percent_goal_reached	The fundraiser has reached 50% of its goal
fundraiser_one_hundred_percent_goal_reached	The fundraiser has reached 100% of its goal

The end_date and goal can be changed by the fundraiser owner. The end date and goal -related activities will only be sent once per fundraising page, even if later the fundraiser owner increases the goal or extends the end date. The only exception to this is the ‘fundraiser_seven_days_until_end_date_reached’ event which may be sent multiple times if the end date is changed.

Team activities

Activity Type	Description
team_created_by_system	A team page is created via an integration with a third-party system
team_created_by_user	A team page is created on the web site
team_edited	A team page is edited

Donation activities

Activity Type	Description
donation_payment_captured	We have received a donation and payment has succeeded
donation_payment_refunded	We have refunded a donation payment. This will also be sent for partial refunds.

Notification request body

Notifications are sent to your endpoint via HTTP POST with an application/json body content-type, encoded as UTF-8.

Here is an example notification request body for a donation_payment_captured activity:

{
  "id": "xxx",
  "occurred_at": "2001-01-01T01:01:01.0001Z",
  "activity_type": "donation_payment_captured",
  "resources": {
    "donation": {
      "id": "xxx",
      "url": "https://api.betternow.org/donations/xxx"
    },
    "fundraiser": {
      "id": "xxx",
      "url": "https://api.betternow.org/fundraisers/xxx"
    },
    "team": {
      "id": "xxx",
      "url": "https://api.betternow.org/teams/xxx"
    },
    "event": {
      "id": "xxx",
      "url": "https://api.betternow.org/events/xxx"
    },
    "project": {
      "id": "xxx",
      "url": "https://api.betternow.org/projects/xxx"
    }
  }
}

A unique id for the activity, a timestamp in ISO8601 format (occurred_at) and the activity_type are sent with all notifications.

In addition, the resources that have been changed by the activity, which varies depending on the activity type, are included. You can use the API to request the full representation of these resources and update your systems.

The example donation above was received by a fundraiser that is participating in an event and is part of a team, so the Event and Team resources are included.

The webhook notification body is similar for all notification types. The resources that are included will change depending on the notification type - e.g. a Fundraiser notification will not include a donation resource, as the notification relates to the fundraiser as a whole, rather than one specific donation.

Requirements for your endpoint

Your endpoint should respond within 30 seconds with an HTTP 200 response.

If we receive any other response code, or we do not receive a response within 30 seconds, the system will retry sending the notification indefinently until we receive an HTTP 200 response within 30 seconds.

The system retries at exponentially-increasing intervals equal to (failure_count^4 + 3) seconds. This means that delivery will be retried 4 seconds after the first failure, 19 seconds after the second, 84 seconds after the third, 259 seconds after the fourth, and so on. When the retry interval hits one day the system will attempt sending once daily until it succeeds.

Responding to a webhook request

Due to the asynchronous and high availability nature of the system, you should be aware of the following:

Notifications may be delivered in a different order than the order the activities occurred. Your system should always use the API to request the most up-to-date representation of the resource during the processing of a notification.
Your endpoint may occasionally receive duplicate notifications for the same activity (duplicates will have the same id). Your processing logic should check to see if a notification with the given id has already been processed, and if so ignore the notification.

We encourage you to separate the steps of receiving/storing the webhook notification, from taking action on it.

We recommend storing the raw request body & headers and then enqueuing a job that processes the notification and updates your system outside of the HTTP request/response cycle.

Verifying the integrity of the request

When you add a new webhook endpoint, we will generate a shared secret that we use to generate a checksum of the request body using HMAC SHA256. We will send this checksum with the request in the BN-HMAC-SHA256 HTTP header.

We strongly encourage you to verify the integrity and authenticity of the request by computing your own checksum using the shared secret and comparing it with the value in the header before processing the request.

To the right is an example of verifying a webhook request using PHP.

<?php

$request_body     = file_get_contents("php://input");
$request_checksum = $_ENV["HTTP_BN_HMAC_SHA256"];
$shared_secret    = $_ENV["BETTERNOW_WEBHOOK_SHARED_SECRET"];

$our_checksum = hash_hmac("sha256", $request_body, $shared_secret);

if (hash_equals($our_checksum, $request_checksum)) {
  // Request is authenticated
} else {
  // Request is NOT authenticated
}

?>