NAV Navbar
Logo
shell

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:

We ♥︎ helping our customers build new integrations. Contact us at apisupport@betternow.org if you have any questions.

Availablity

The BetterNow API is available at no additional charge to charities with a Branded site. In addition, it can be enabled for charities on the BN platform sites or with a Branded Light site for an additional fee.

If you have an Integrations section in your charity dashboard, you have access to the API. Note that you must have Administrator permissions in order to manage access to the API.

To upgrade your plan to get access to the BetterNow API, please contact orgsupport@betternow.org.

Setup

In the Integrations section of your charity dashboard, you can create API keys that will grant you access to the API. If you don’t see an Integrations section, please see the Availablity section above.

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 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.

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.

Contact Permission Info

Info for existing donation.

GET /contact-permissions/{contact_permission_id}

Curl Example ->

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

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": null,
    "post": null,
    "sms": null,
    "phone": null
  },
  "site_contact_methods": {
    "email": null,
    "post": null,
    "sms": null,
    "phone": null
  },
  "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": null,
    "source_id": 1234567,
    "url": "https://url.example.net"
  },
  "url": "https://url.example.net"
}

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.
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.
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.
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.
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.
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.
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.
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.
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:middle_name string The middle name of the user "Middlename"
person:last_name string The last name of the user "Lastname"
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: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"
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"
source:source_type string
one of:"Donation" or "Fundraiser" or "Team"
source:source_id string unique identifier 1234567
source:url uri "https://url.example.net"
url uri "https://url.example.net"

Donation Details

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

Donation Details Info

Info for existing donation.

GET /donation-detail/{donation_id}

Curl Example ->

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

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": null,
  "first_name": "Firstname",
  "middle_name": "Middlename",
  "last_name": "Lastname",
  "company_name": "BetterNow Worldwide ApS",
  "legal_name": "BetterNow LTD",
  "donor_type": "personal",
  "tax_id": null,
  "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": null,
  "allow_site_contact": null,
  "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": null,
    "partner_reference": null,
    "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"
  }
}

Attributes

Name Type Description Example
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!"
name_shown string The name on the donation "Joes Truck Stop"
hidden_name boolean Has the donor requested to hide their name (donate anonymously on the public site)?
first_name string The first name of the user "Firstname"
middle_name string The middle name of the user "Middlename"
last_name string The last name of the user "Lastname"
company_name string "BetterNow Worldwide ApS"
legal_name string "BetterNow LTD"
donor_type string
one of:"unknown" or "personal" or "organisation"
"personal"
tax_id string country-specific tax identification number
tax_deduction_requested boolean whether the donor requested a tax deduction (or Gift Aid in UK) false
created_at date-time when donation was created "2012-01-01T12:00:00Z"
id integer unique identifier of donation 1234567
updated_at date-time when donation was updated "2012-01-01T12:00:00Z"
address:street_line_1 string "Danneskiold-Samsøes Allé 41"
address:street_line_2 string "Suite 103"
address:city string "Copenhagen K"
address:postal_code string "1434"
address:province string "Region Hovedstaden"
address:country string ISO alpha-2 country code
pattern: ^([A-Z]{2})$
"DK"
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"
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"
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"
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"
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"
team:html_url uri The url to the Team page on BetterNow "https://dk.betternow.org/teams/team-novo"
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"
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"
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"
event:html_url uri The url to the Event page on BetterNow "https://dk.betternow.org/events/copenhagen-marathon-2013"
donor_ip_address string "127.0.0.1"
allow_organisation_contact boolean Has the donor given permission for the recipient of the donation to contact them?
allow_site_contact boolean Has the donor given permission for the operator of the site on which the donation was given to contact them?
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"
donor:id string unique identifier of person "fdb6cd2a-3ca7-40db-8fae-135daebecdab"
donor:first_name string The first name of the user "Firstname"
donor:middle_name string The middle name of the user "Middlename"
donor:last_name string The last name of the user "Lastname"
donor:email string "user@example.com"
donor:phone string Phone number in E.164 format "+4510101010"
donor:title string "Director of Personal Fundraising"
donor:created_at date-time when user was created "2012-01-01T12:00:00Z"
donor:birth_month integer
Range: 1 <= value <= 12
1
donor:birth_day integer
Range: 1 <= value <= 31
1
donor:locale string ISO 639-1 locale code "en"
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.
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.
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: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: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: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"
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"
custom_form_values object An object containing values for custom form fields. Structure varies depending on the customer.
payment:processor_id string the payment processor’s id for the payment "123456789"
payment:payment_id_for_processor string the id we send to the payment processor and acquirer "12345-slyellei_0"
payment:settled_by_betternow boolean If BetterNow transfers the money to you false
payment:acquirer string What company acquires the payment "clearhaus"

Donation

The publicly available details about a donation

Donation Info

Info for existing donation.

GET /donation/{donation_id}

Curl Example ->

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

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"
}

Attributes

Name Type Description Example
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"
allow_organisation_contact boolean If the person has consented to be contacted by the organisation true
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"
id integer unique identifier of donation 1234567
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"
name string The name on the donation "Joes Truck Stop"
updated_at date-time when donation was updated "2012-01-01T12:00:00Z"
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"
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"
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"
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"
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"
team:html_url uri The url to the Team page on BetterNow "https://dk.betternow.org/teams/team-novo"
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"
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"
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"
event:html_url uri The url to the Event page on BetterNow "https://dk.betternow.org/events/copenhagen-marathon-2013"
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"

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

Event Info

Info for existing event.

GET /events/{event_id_or_slug}

Curl Example ->

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

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/events

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/events/$EVENT_ID_OR_SLUG/projects

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/events/$EVENT_ID_OR_SLUG/fundraisers

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-01T12:00:00Z",
    "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"
  }
]

Event List Teams

List all Teams associated with an Event

GET /events/{event_id_or_slug}/teams

Curl Example ->

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

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": {
      "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"
  }
]

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:video:url uri The url for the video. Currently only YouTube and Vimeo are supported. Could be blank. "https://youtu.be/12345"
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: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"
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"
name string the name of the Event "Copenhagen Marathon 2013"
logo_url uri The logo for the Event "https://cdn.example.net/logo.png"
updated_at date-time when event was updated "2012-01-01T12:00:00Z"
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"
url uri "https://api.betternow.org/events/1234567"

Fundraising Page

Detailed information about a single Fundraising Page on BetterNow.org

Fundraising Page Info

Info for existing fundraiser.

GET /fundraisers/{fundraiser_id_or_slug}

Curl Example ->

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

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-01T12:00:00Z",
  "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"
}

Fundraising Page List

List existing fundraisers.

GET /fundraisers

Curl Example ->

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

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-01T12:00:00Z",
    "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"
  }
]

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/fundraisers/$FUNDRAISER_ID_OR_SLUG/donations

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/fundraisers/$FUNDRAISER_ID_OR_SLUG/updates

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"
  }
]

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
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:video:url uri The url for the video. Currently only YouTube and Vimeo are supported. Could be blank. "https://youtu.be/12345"
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: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"
created_at date-time when resource was created "2012-01-01T12:00:00Z"
description string The text written by the fundraiser owner. Contains HTML. "<p>This is really, <b>REALLY</b> great</p> <br><br>"
state string The state of this fundraiser "published"
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 "other"
"birthday"
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-time The end date for a fundraiser. "2012-01-01T12:00:00Z"
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"
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:middle_name string The middle name of the user "Middlename"
owner:last_name string The last name of the user "Lastname"
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.
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"
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"
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"
team:html_url uri The url to the Team page on BetterNow "https://dk.betternow.org/teams/team-novo"
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"
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"
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"
event:html_url uri The url to the Event page on BetterNow "https://dk.betternow.org/events/copenhagen-marathon-2013"
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"
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"

Organisation

An Organisation can receive Donations on BetterNow

Organisation Info

Info for existing organisation.

GET /organisations/{organisation_id_or_slug}

Curl Example ->

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

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/organisations/$ORGANISATION_ID_OR_SLUG/projects

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/organisations/$ORGANISATION_ID_OR_SLUG/fundraisers

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-01T12:00:00Z",
    "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"
  }
]

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/organisations/$ORGANISATION_ID_OR_SLUG/donations

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"
  }
]

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:video:url uri The url for the video. Currently only YouTube and Vimeo are supported. Could be blank. "https://youtu.be/12345"
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: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"
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>"
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"
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"
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"

Person

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

Person Info

Info for existing person.

GET /people/{person_id}

Curl Example ->

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

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": null,
  "partner_reference": null,
  "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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/people/$PERSON_ID/donations

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/people/$PERSON_ID/fundraisers

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-01T12:00:00Z",
    "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"
  }
]

Person List Teams

List all Teams this person is a member of

GET /people/{person_id}/teams

Curl Example ->

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

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": {
      "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"
  }
]

Attributes

Name Type Description Example
id string unique identifier of person "fdb6cd2a-3ca7-40db-8fae-135daebecdab"
first_name string The first name of the user "Firstname"
middle_name string The middle name of the user "Middlename"
last_name string The last name of the user "Lastname"
email string "user@example.com"
phone string Phone number in E.164 format "+4510101010"
title string "Director of Personal Fundraising"
created_at date-time when user was created "2012-01-01T12:00:00Z"
birth_month integer
Range: 1 <= value <= 12
1
birth_day integer
Range: 1 <= value <= 31
1
locale string ISO 639-1 locale code "en"
allow_site_contact boolean true if the user has agreed to be contacted by the site they either donated via or signed up on.
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.
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"
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"
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"
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"

Project

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

Project Info

Info for existing project.

GET /projects/{project_id_or_slug}

Curl Example ->

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

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/projects/$PROJECT_ID_OR_SLUG/fundraisers

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-01T12:00:00Z",
    "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"
  }
]

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/projects/$PROJECT_ID_OR_SLUG/donations

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"
  }
]

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:video:url uri The url for the video. Currently only YouTube and Vimeo are supported. Could be blank. "https://youtu.be/12345"
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: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"
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"
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"
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"
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
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"
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"
updated_at date-time When project was updated "2012-01-01T12:00:00Z"
url uri "https://api.betternow.org/projects/1234567"
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"
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"
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"
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"

Team

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

Team Info

Info for existing team.

GET /teams/{team_id_or_slug}

Curl Example ->

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

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": {
    "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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/teams

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": {
      "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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/teams/$TEAM_ID_OR_SLUG/fundraisers

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-01T12:00:00Z",
    "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"
  }
]

Team List Donations

List all donations given via this Team

GET /teams/{team_id_or_slug}/donations

Curl Example ->

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

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 \
  -H "Accept: application/vnd.betternow+json; version=1" \
  https://api.betternow.org/teams/$TEAM_ID_OR_SLUG/projects

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"
  }
]

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:middle_name string The middle name of the user "Middlename"
captain:last_name string The last name of the user "Lastname"
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"
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:video:url uri The url for the video. Currently only YouTube and Vimeo are supported. Could be blank. "https://youtu.be/12345"
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: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"
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"
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"

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 Availabilty

If you have access to the API, you also have access to webhooks. For more information, see the Availablity section above.

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

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

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.

The system retrys 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 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:

  1. 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.
  2. 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
}

?>