Back to top

GivenGain API Version 2.5

Notes

1. Introduction

The goal of the API is to enable straightforward consumption and manipulation of data from the GivenGain platform for use elsewhere.

Restrictions

  • You will need an Activist or Cause account on GivenGain to get your API Client Secret Key

  • Once you have your API Client Secret Key, you will need to register your Application to get a Client ID

  • The majority of endpoints are still read-only.

2. Authentication & Security

Access to the API is governed by:

  • Client Secret Key You get one of these connected to your Activist or Cause account

  • Client IDs You get one of these for each Application that will access the API

  • Access Tokens One per user, when they explicitly authorize your application to access their GivenGain account

When making calls to read-only endpoints, all you’ll need to provide is a Client ID. When you make calls to endpoints that manipulate data in any way, you’ll need to gain authorization from the user of your application to access their GivenGain account. This is done via a pretty standard OAuth 2.0 flow, detailed in the Request Authorization from a User section below.

The GivenGain API supports secure connections over SSL only. Make sure your requests are made over https instead of http.

2.1 Get your Client Secret Key

In order to get access to the GivenGain API you will need to have an existing Activist or Cause account. Once logged in as either Activist or Cause, go to the API Client Page to generate your API Client Secret Key. If you’ve already gotten an API Client Secret key, you can return to that page to see what your key is, or to generate a new one.

Your API Client Secret Key will only be used in those cases where you need to request authorization from a user of your application to access their GivenGain account, but it is linked to each Application that you register for use with the GivenGain API, and it helps us identify where requests are coming from.

2.2 Register an Application

Now that you’ve gotten your API Client Secret Key, you can register an Application that will access the API. You also do this on the API Client Page. It’s pretty straightforward. All we need is the following:

  • Application Name

  • A callback URL

  • An application icon, which is a 100x100px PNG or JPG

  • An optional application description (encouraged)

Once you register an application, you will get a Client ID for that application.

2.3 Request Authorization from a User

If you’ve ever worked with OAuth, this should be familiar territory. You’ll be relieved to know that we’ve decided to use the OAuth 2.0 specification for user authorization, with simple Bearer authentication. After going through the authorization / authentication flow, you will end up with one Access Token per user (only valid for the registered application that requested it). You will use this access token, whenever you make a call to the API that manipulates data in any way.

You can provide the Access Token via GET, POST, or as an HTTP Authorization Request Header.

We suggest that you use HTTP Header Authorization, as it will work without any fuss for all endpoint methods:

Authorization: Bearer f3eeafd6a9f214ee3698377c92c184d2c6e91cb9

2.3.1 OAuth 2.0 Flow

We’re going to assume that you’ve gotten your Client Secret Key, and a Client ID to work with. This example uses bogus strings for the Client Secret Key, Client ID, Authentication Code and Access Token.

  1. Your application needs permission from a user to access and/or manipulate their account data, so you send them to the GivenGain API authorization page (remember to pass both the client_id and redirect_uri parameters): https://www.givengain.com/api/oauth/authorize?client_id=4bda182f3d6c924b19cf1b&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback

    The redirect_uri value must be URL encoded, and must match the callback url you supplied when creating your Client ID.

  2. The user is presented with a dialog, where they allow or deny access to their GivenGain account for your application

  3. The user is redirected to your callback URI with a code

    https://yourapp.com/callback?code=43423d76123a1124f2

  4. Your application makes a call to the access token endpoint with the Authentication Code acquired in the previous step, along with both your application’s Client ID and your Client Secret Key. You can do this with a GET or POST request, both will work:

    https://www.givengain.com/api/oauth/token?code=43423d76123a1124f2&client_id=4bda182f3d6c924b19cf1b&client_secret=43cfa21456s1245va235&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback

    The redirect_uri value must be URL encoded, and must match the callback url you supplied when creating your Client ID.

  5. The GivenGain API should give you a JSON response containing the Access Token itself (and its type):

    { "access_token": "f3eeafd6a9f214ee3698377c92c184d2c6e91cb9", "token_type": "Bearer" }

  6. On your side, you store the Access Token, and use it to authorize a call to the GivenGain API whenever you need to access or manipulate data of the user that is associated with the token.

3. Endpoints

Version 2.5 of the GivenGain API is located at:

https://www.givengain.com/api/v2.5/

The type of request you make to an endpoint depends on the HTTP Method you use to make the call.

  • GET to retrieve data

  • POST to add data

  • PUT to update data

  • DELETE to delete data

The API makes use of a combination of HTTP Response Codes and a JSON Response Body to let you know whether your request was successful or not:

  • 401 Not authorized

  • 404 Entity or endpoint does not exist

  • 400 Bad or malformed request

  • 200 Successful

Check the Response Body, which should always be in JSON format, for more detail.

Token Owner

Me

Get the details of an Access Token’s owner

Get token owner details
GET/me

Depending on whether the token owner is an activist or a cause, will return slightly different results.

Possible values for attributes in response:

  • visible: true or false

  • type: activist or cause

Request  Token owner is an Activist
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "9000",
  "first_name": "John",
  "last_name": "Doe",
  "visible": "true",
  "link": "http://www.givengain.com/activist/9000/",
  "type": "activist"
}
Request  Token owner is a Cause
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "1860",
  "custom_url": "http://www.givengain.com/c/think/",
  "name": "Think GivenGain",
  "visible": "true",
  "link": "http://www.givengain.com/cause/1860/",
  "type": "cause"
}

Cause

List Causes

Retrieve Cause data

Retrieve a list of causes
GET/cause

Possible values for attributes in request:

  • visible: Y Yes, or N No

Possible values for attributes in response:

  • visible: true or false
URI Parameters
HideShow
visible
char (optional) 

Filter by cause visibility: (Y) to only show visible causes - both are returned by default

Choices: Y N

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total": 5000,
  "pages": 500,
  "current_page": 1,
  "causes": [
    {
      "id": "1860",
      "name": "Think GivenGain",
      "visible": "true",
      "link": "http://www.givengain.com/cause/1860/",
      "custom_url": "http://www.givengain.com/c/think/",
      "date": "2004-11-24"
    }
  ]
}

Retrieve a Cause

Retrieve a single Cause's details
GET/cause/{id}

Possible values for attributes in response:

  • visible: true or false

  • campaigns / status: P Draft, A Published, or W Archived

URI Parameters
HideShow
id
int (required) Example: 1860

The Causes’s unique ID

campaigns_page
int (optional) Default: 1 

Which page of the campaigns subset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id": 1860,
    "name": "Think GivenGain",
    "description": "<p><strong>think.givengain.org&nbsp;is the online manual for etc.<\/strong><\/p>\r\n",
    "web_address": "http://www.givengain.com",
    "visible": "true",
    "date": "2004-11-24",
    "campaigns": {
        "total": 13,
        "pages": 1,
        "current_page" : 1,
        "campaigns": [
            {
                "id": 3566,
                "title": "This is our campaign",
                "status": "P",
                "date": "2012-04-02"
            }
        ]
    },
    "images": {
        "28": "https://www.givengain.com/path/to/the/image_28x28.jpg",
        "48": "https://www.givengain.com/path/to/the/image_48x48.jpg",
        "72": "https://www.givengain.com/path/to/the/image_72x72.jpg",
        "96": "https://www.givengain.com/path/to/the/image_96x96.jpg",
        "144": "https://www.givengain.com/path/to/the/image_144x144.jpg",
        "288": "https://www.givengain.com/path/to/the/image_288x288.jpg"
    },
    "link": "http://www.givengain.com/cause/1860/",
    "custom_url": "http://www.givengain.com/c/think/",
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Cause not found"
}

Campaigns: List or Add

Retrieve a list of published campaigns
GET/campaign

This only returns campaigns with a status of P.

URI Parameters
HideShow
cause_id
int (optional) 

Filter by Cause ID

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total": 10000,
  "pages": 1000,
  "current_page": 1,
  "campaigns": [
    {
      "id": 3566,
      "cause_id": 1860,
      "title": "This is our campaign",
      "date": "2012-04-02",
      "link": "http://www.givengain.com/cause/1860/campaigns/3566/",
      "custom_url": "http://www.givengain.com/cc/ourcampaign/"
    }
  ]
}

Add a new campaign
POST/campaign

Requires a cause access token. To add a new campaign, send a JSON body containing the parameters.

Possible values for attributes in request:

  • status: P Draft, A Published, or W Archived

  • allow_comments: Y Yes, or N No

  • allow_fundraising: Y Yes, or N No

URI Parameters
HideShow
title
string (required) 

The campaign’s title

summary
text (required) 

A short summary of not more than 160 characters

description
text (required) 

A longer description, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

theme_id
int (required) 

The unique ID of one of the cause categories (refer to the /category endpoint for allowed values)

target
int (required) 
currency
string (required) 

The base ISO 4217 currency code for this campaign (refer to the /currency endpoint for allowed values)

thank_you_message
text (optional) 

An optional custom thank you message that will be included in donation receipts

status
char (optional) Default: P 

Set the status of the campaign

Choices: W P A

allow_comments
char (optional) Default: Y 

Allow comments on this campaign, or not

Choices: Y N

allow_fundraising
char (optional) Default: Y 

Allow activists to create projects that will raised funds for this campaign, or not

Choices: Y N

Request  New Campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A new campaign",
  "summary": "This is a short summary of the campaign",
  "description": "This will be a much longer description of the campaign, but this one is quite short.",
  "theme_id": 3,
  "target": 100000,
  "currency": "ZAR",
  "status": "W"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Campaign added",
  "status": "W",
  "id": 42355
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Required fields: title, summary, description, target, currency, theme_id"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error adding the campaign, please try again",
  "detail": "General error"
}

Campaigns: Detail or Manage

Retrieve a single campaign's details
GET/campaign/{id}

Possible values for attributes in response:

  • status: P Draft, A Published, or W Archived

  • allow_comments: true or false

  • allow_fundraising: true or false

  • projects / status: A Active, or C Closed

URI Parameters
HideShow
id
int (required) Example: 3456

The Campaign’s unique ID

projects_page
int (optional) Default: 1 

Which page of the projects subset to return

donations_page
int (optional) Default: 1 

Which page of the donations subset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id": 3456,
    "cause_id": 1860,
    "title": "Help Build Houses",
    "summary": "This is a short summary of the campaign",
    "description": "This will be a much longer description of the campaign, but this one is quite short.",
    "date": "2013-04-21",
    "currency": "EUR",
    "target": 1000000,
    "raised": 15000,
    "image": "http://www.givengain.com/content_cause/images/projects/3456-ASFGE.jpg",
    "status": "P",
    "allow_comments": "true",
    "allow_fundraising": "true",
    "projects": {
        "total": 34,
        "pages": 2,
        "current_page": 1,
        "projects": [
            {
                "id": 2345,
                "title": "I am helping to build homes",
                "status": "A"
                "date": "2014-02-02",
                "deadline": "2014-03-02",
                "days": 18
            }
        ]
    },
    "donations": {
        "total": 1235,
        "pages": 50,
        "current_page": 1,
        "donations": [
            {
                "id": 39345,
                "amount": 500,
                "currency": "EUR",
                "donor_id": 36267,
                "project_id": 2345,
                "date": "2014-02-24"
            }
        ]
    },
    "amounts": [
        {
            "id": 233,
            "amount": 10,
            "label": "100 bricks",
            "currency": "EUR"
        },
        {
            "id": 234,
            "amount": 100,
            "label": "1000 bricks",
            "currency": "EUR"
        }
    ],
    "media": [
        {
            "id": 2445,
            "type": "youtube",
            "external_id": "gy1B3agGNxw"
        }
    ],
    "tags": [
        {
            "id": 453,
            "tag": "build"
        },
        {
            "id": 235,
            "tag": "house"
        },
        {
            "id": 643,
            "tag": "africa"
        },
    ],
    "location": {
        "name": "Geneva, Switzerland",
        "country": "CH",
        "longitude": "6.142296099999999",
        "latitude": "46.1983922"
    },
    "link": "http://www.givengain.com/cause/1860/campaigns/3456/",
    "custom_url": "http://www.givengain.com/cc/ourcampaign/"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Campaign not found"
}

Edit an existing campaign
PUT/campaign/{id}

Requires a cause access token.

To edit an existing campaign, send a JSON body containing the parameters.

Possible values for attributes in request:

  • status: P Draft, A Published, or W Archived

  • allow_comments: Y Yes, or N No

  • allow_fundraising: Y Yes, or N No

URI Parameters
HideShow
id
int (required) 

The unique ID of the campaign to be edited

title
string (optional) 

The campaign’s title

summary
text (optional) 

A short summary of not more than 160 characters

description
text (optional) 

A longer description, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

theme_id
int (optional) 

The unique ID of one of the cause categories (refer to the /category endpoint for allowed values)

target
int (optional) 
currency
string (optional) 

The base ISO 4217 currency code for this campaign (refer to the /currency endpoint for allowed values)

thank_you_message
text (optional) 

An optional custom thank you message that will be included in donation receipts

status
char (optional) Default: P 

Set the status of the campaign

Choices: W P A

allow_comments
char (optional) Default: Y 

Allow comments on this campaign, or not

Choices: Y N

allow_fundraising
char (optional) Default: Y 

Allow activist to create projects that will raised funds for this campaign, or not

Choices: Y N

Request  Edit Campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A Better Title",
  "target": 1500000,
  "currency": "ZAR",
  "status": "P"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Campaign updated",
  "id": 42355
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Campaign not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Campaign does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error updating this campaign, please try again"
}

Delete a campaign
DELETE/campaign/{id}

Requires a cause access token.

URI Parameters
HideShow
id
int (required) 

The unique ID of the campaign to be deleted

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Campaign deleted",
  "id": 42355
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Campaign not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Campaign does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error deleting this campaign, please try again"
}

Campaign Updates: List or Add

Retrieve a list of campaign updates
GET/campaign/update

Possible values for attributes in request:

  • status: W Draft, or P Published

Possible values for attributes in response:

  • status: W Draft, or P Published
URI Parameters
HideShow
status
char (optional) Default: P 

Filter by update status

cause_id
int (optional) 

Filter by cause ID

campaign_id
int (optional) 

Filter by campaign ID

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total": 10000,
  "pages": 1000,
  "current_page": 1,
  "updates": [
    {
      "id": 75433,
      "cause_id": 1860,
      "campaign_id": 2356,
      "title": "Quite a nice surprise!",
      "date": "2014-04-11",
      "status": "P",
      "link": "http://www.givengain.com/cause/1860/campaigns/2356/updates/75433/"
    }
  ]
}

Add a new campaign update
POST/campaign/update

Requires a cause access token. To add a new update, send a JSON body containing the parameters.

Possible values for attributes in request:

  • status: W Draft, or P Published

  • allow_comments: Y Yes, or N No

URI Parameters
HideShow
title
string (required) 

The campaign’s title

post
text (required) 

The body of the update, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

campaign_id
int (required) 

The unique ID of one of the cause campaign that this update belongs to

status
char (optional) Default: P 

Set the status of the update

Choices: W P

allow_comments
char (optional) Default: Y 

Allow comments on this campaign, or not

Choices: Y N

Request  New Campaign Update
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A new update",
  "post": "This will be a much longer description of the update, but this one is quite short.",
  "campaign_id": 2135
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Update added",
  "status": "P",
  "id": 23551
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Required fields: campaign_id, title, summary, post"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Token owner is not a cause"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error adding the update, please try again",
  "detail": "General error"
}

Campaign Updates: Detail or Manage

Retrieve a single campaign update's details
GET/campaign/update/{id}

Possible values for attributes in response:

  • status: W Draft, or P Published

  • author_type: cause, or admin

  • allow_comments: true or false

URI Parameters
HideShow
id
int (required) Example: 3456

The Campaign Update’s unique ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 23551,
  "cause_id": 1860,
  "campaign_id": 2135,
  "author_type": "cause",
  "author_id": 1860,
  "title": "Thus is a new campaign update",
  "post": "This will be a much longer description of the update, but this one is quite short.",
  "status": "P",
  "image": "http://www.givengain.com/content_cause/images/updates/23551-AFDEX.jpg",
  "date": "2014-12-12",
  "allow_comments": "true",
  "link": "http://www.givengain.com/cause/1860/campaigns/2356/updates/75433/"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Campaign Update not found"
}

Edit an existing campaign update
PUT/campaign/update/{id}

Requires a cause access token.

To edit an existing update, send a JSON body containing the parameters.

Possible values for attributes in request:

  • status: W Draft, or P Published

  • allow_comments: Y Yes, or N No

URI Parameters
HideShow
id
int (required) 

The unique ID of the update to be edited

title
string (optional) 

The update’s title

post
text (optional) 

The body of the update, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

status
char (optional) Default: P 

Set the status of the update

Choices: W P

allow_comments
char (optional) Default: Y 

Allow comments on this campaign, or not

Choices: Y N

Request  Edit Update
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A Better Title",
  "status": "P",
  "allow_comments": "N"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Update updated",
  "id": 7357
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error updating this update, please try again"
}

Delete a campaign update
DELETE/campaign/update/{id}

Requires a cause access token.

URI Parameters
HideShow
id
int (required) 

The unique ID of the update to be deleted

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Update deleted",
  "id": 7357
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error deleting this update, please try again"
}

Categories: List

Retrieve a list of available categories
GET/category

Example URI

GET /category
URI Parameters
HideShow
locale
string (optional) Default: en 

Get the titles of the categories in one of the supported languages

Choices: af de en es fr hr it

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "categories": [
    {
      "title": "Arts and Culture",
      "id": "13"
    },
    {
      "title": "Children and Youth",
      "id": "12"
    },
    {
      "title": "Community Building and Renewal",
      "id": "10"
    }
  ]
}

Activist

List Activists

Retrieve Activist data

Retrieve the list of the latest activists
GET/activist

Possible values for attributes in request:

  • visible: Y Yes, or N No

Possible values for attributes in response:

  • visible: true or false
URI Parameters
HideShow
visible
char (optional) 

Filter by activist visibility: (Y) to only show visible activists - both are returned by default

Choices: Y N

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "total": 5000,
    "pages": 500,
    "current_page" : 1,
    "activists": [
        {
            "id": "9000",
            "first_name": "John",
            "last_name": "Doe",
            "visible": "true",
            "date": "2009-06-01",
            "link": "http://www.givengain.com/activist/9000/",
            "custom_url": "http://www.givengain.com/a/johnnyfive/",
        }
    ]
}

Retrieve an Activist

Retrieve a single Activist's details
GET/activist/{id}

Possible values for attributes in response:

  • visible: true or false

  • projects / status: A Active, or C Closed

URI Parameters
HideShow
id
int (required) Example: 9000

The Activist’s unique ID

projects_page
int (optional) Default: 1 

Which page of the projects subset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id": 9000,
    "first_name": "John",
    "last_name": "Doe",
    "bio": "I'm just this guy, you know?",
    "web_address": "http://www.johndoe.com",
    "visible": "true",
    "influence_points": 500234,
    "date": "2004-11-24",
    "raised": {
        "TOTAL": 3000,
        "USD": 3000
    },
        "projects":
        "total": 5,
        "pages": 1,
        "current_page" : 1,
        "projects": [
            {
                "id": 3246,
                "title": "I'm building a house!",
                "status": "A",
                "campaign_id": 4563,
                "cause_id": 1860,
                "date": "2012-04-02",
                "deadline": "2015-12-12"
            }
        ]
    },
    "location": {
        "id": 3567,
        "name": "Stellenbosch, South Africa"
    },
    "images": {
        "28": "https://www.givengain.com/path/to/the/image_28x28.jpg",
        "48": "https://www.givengain.com/path/to/the/image_48x48.jpg",
        "72": "https://www.givengain.com/path/to/the/image_72x72.jpg",
        "96": "https://www.givengain.com/path/to/the/image_96x96.jpg",
        "144": "https://www.givengain.com/path/to/the/image_144x144.jpg",
        "288": "https://www.givengain.com/path/to/the/image_288x288.jpg"
    },
    "thumbnail": "http://www.givengain.com/content_members/images/profiles/9000-XKCD_mini.gif",
    "link": "http://www.givengain.com/activist/9000/",
    "custom_url": "http://www.givengain.com/a/johnnyfive/"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Activist not found"
}

Projects: List or Add

Retrieve a list of projects
GET/project

Possible values for attributes in response:

  • status: A Active, or C Closed
URI Parameters
HideShow
activist_id
int (optional) 

Filter by Activist ID

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total": 10000,
  "pages": 1000,
  "current_page": 1,
  "projects": [
    {
      "id": 21466,
      "activist_id": 9000,
      "campaign_id": 3566,
      "cause_id": 1860,
      "title": "This is my project",
      "date": "2009-09-16",
      "deadline": "2010-09-16",
      "status": "C",
      "link": "http://www.givengain.com/activist/9000/projects/21466/",
      "custom_url": "http://www.givengain.com/ap/theproject/"
    }
  ]
}

Add a new project
POST/project

Requires an activist access token. To add a new project, send a JSON body containing the parameters.

URI Parameters
HideShow
title
string (required) 

The project’s title

summary
text (required) 

A short summary of not more than 160 characters

description
text (required) 

A longer description, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

campaign_id
int (required) 

The unique ID of one of the campaign that this project will be raising funds for

target
int (required) 
currency
string (required) 

The base ISO 4217 currency code for this campaign (refer to the /currency endpoint for allowed values)

deadline
date (required) 

The ISO 9075 format date for the project deadline

thank_you_message
text (optional) 

An optional custom thank you message that will be included in donation receipts

Request  New Campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A new project",
  "summary": "This is a short summary of the project",
  "description": "This will be a much longer description of the project, but this one is quite short.",
  "campaign_id": 3456,
  "target": 12000,
  "currency": "USD",
  "deadline": "2015-01-01"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Project added",
  "id": 701245
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Required fields: title, summary, description, campaign_id, currency, target, deadline"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Token owner is not an activist"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error adding the project, please try again",
  "detail": "General error"
}

Projects: Detail or Manage

Retrieve a single project's details
GET/project/{id}

Possible values for attributes in response:

  • status: A Active, or C Closed
URI Parameters
HideShow
id
int (required) Example: 3456

The Project’s unique ID

donations_page
int (optional) Default: 1 

Which page of the donations subset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 21466,
  "cause_id": 1860,
  "campaign_id": 3566,
  "title": "This is my project",
  "summary": "This is a short summary of my project.",
  "description": "And, of course, this is supposed to a much longer description, but it's pretty short too.",
  "date": "2009-09-16",
  "deadline": "2010-09-16",
  "currency": "ZAR",
  "target": 15000,
  "raised": 23200,
  "status": "C",
  "donations": {
    "total": 21,
    "pages": 1,
    "current_page": 1,
    "donations": [
      {
        "id": 39364,
        "amount": 100,
        "currency": "ZAR",
        "donor_id": 36267,
        "date": "2012-12-24"
      }
    ]
  },
  "media": [
    {
      "id": 3515,
      "type": "vimeo",
      "external_id": "87169386"
    }
  ],
  "tags": [
    {
      "id": 453,
      "tag": "marathon"
    },
    {
      "id": 235,
      "tag": "running"
    }
  ],
  "location": {
    "name": "Stellenbosch, South Africa",
    "country": "ZA",
    "longitude": "18.85",
    "latitude": "-33.9333333"
  },
  "link": "http://www.givengain.com/activist/9000/projects/21466/",
  "custom_url": "http://www.givengain.com/ap/theproject/"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Project not found"
}

Edit an existing project
PUT/project/{id}

Requires aan activist access token.

To edit an existing project, send a JSON body containing the parameters.

URI Parameters
HideShow
id
int (required) 

The unique ID of the project to be edited

title
string (optional) 

The campaign’s title

summary
text (optional) 

A short summary of not more than 160 characters

description
text (optional) 

A longer description, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

target
int (optional) 
thank_you_message
text (optional) 

An optional custom thank you message that will be included in donation receipts

Request  Edit Campaign
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A Much Better Title",
  "target": 15000,
  "description": "A much more descriptive description. Probably."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Project updated",
  "id": 701245
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Project not found"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Invalid date format for deadline, or deadline is in the past"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Project does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error updating this project, please try again"
}

Delete a project
DELETE/project/{id}

Requires an activist access token.

URI Parameters
HideShow
id
int (required) 

The unique ID of the project to be deleted

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Project deleted",
  "id": 701245
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Project not found"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "This project has donations"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Project does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error deleting this project, please try again"
}

Project Updates: List or Add

Retrieve a list of project updates
GET/project/update

Possible values for attributes in request:

  • status: W Draft, or P Published

Possible values for attributes in response:

  • status: W Draft, or P Published
URI Parameters
HideShow
status
char (optional) Default: P 

Filter by update status

activist_id
int (optional) 

Filter by activist ID

project_id
int (optional) 

Filter by project ID

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total": 10000,
  "pages": 1000,
  "current_page": 1,
  "updates": [
    {
      "id": 993,
      "activist_id": 9000,
      "project_id": 22356,
      "title": "Around the world in a little more than 80 days...",
      "date": "2015-01-22",
      "status": "P",
      "link": "http://www.givengain.com/activist/9000/projects/22356/updates/993/"
    }
  ]
}

Add a new project update
POST/project/update

Requires an activist access token. To add a new update, send a JSON body containing the parameters.

Possible values for attributes in request:

  • status: W Draft, or P Published
URI Parameters
HideShow
title
string (required) 

The campaign’s title

post
text (required) 

The body of the update, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

project_id
int (required) 

The unique ID of one of the activist project that this update belongs to

status
char (optional) Default: P 

Set the status of the update

Choices: W P

Request  New Project Update
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "This is an update",
  "post": "This will be a much longer description of the update, but this one is quite short.",
  "project_id": 22356
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Update added",
  "status": "P",
  "id": 995
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Required fields: project_id, title, summary, post"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Token owner is not an activist"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error adding the update, please try again",
  "detail": "General error"
}

Project Updates: Detail or Manage

Retrieve a single project update's details
GET/project/update/{id}

Possible values for attributes in response:

  • status: W Draft, or P Published
URI Parameters
HideShow
id
int (required) 

The Campaign Update’s unique ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 9953,
  "activist_id": 9000,
  "project_id": 23566,
  "title": "This is an existing project update",
  "post": "This will be a much longer description of the update, but this one is quite short.",
  "status": "P",
  "image": "http://www.givengain.com/content_membert/images/updates/9953-OPDEX.jpg",
  "date": "2014-07-03",
  "link": "http://www.givengain.com/activist/9000/projects/23566/updates/9953/"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Project Update not found"
}

Edit an existing project update
PUT/project/update/{id}

Requires an activist access token.

To edit an existing update, send a JSON body containing the parameters.

Possible values for attributes in request:

  • status: W Draft, or P Published
URI Parameters
HideShow
id
int (required) 

The unique ID of the update to be edited

title
string (optional) 

The update’s title

post
text (optional) 

The body of the update, may contain some HTML: <strong> <em> <ol> <ul> <li> <br> <p>

status
char (optional) Default: P 

Set the status of the update

Choices: W P

Request  Edit Update
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "A Better Title",
  "status": "P",
  "allow_comments": "N"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Update updated",
  "id": 7357
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error updating this update, please try again"
}

Delete a project update
DELETE/project/update/{id}

Requires an activist access token.

URI Parameters
HideShow
id
int (required) 

The unique ID of the update to be deleted

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Update deleted",
  "id": 7357
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Update does not belong to token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error deleting this update, please try again"
}

Donations

Access tokens are optional

  • No access token: A list of donations that are publicly visible (donations to activist projects only)

  • Activist access token: A list of all the donations the owner of the access token has made (donations both to cause projects, and activist projects)

  • Cause access token: A list of the donations received by the owner of the access token (donations both to cause projects, and activist projects)

Using the API Recon ID

You may want to reconcile donations made on GivenGain in your application, to check on validity of amounts, whether the donation was successful, or for other reasons. This is possible by adding an extra GET variable to the donation page.

At the moment, the urls for donation pages follow this structure:

  • Donate to a cause https://www.givengain.com/cause/[cause_id]/donate

  • Donate to a cause campaign https://www.givengain.com/cause/[cause_id]/campaigns/[campaign_id]/donate

  • Donate to an activist project https://www.givengain.com/activist/[activist_id]/projects/[project_id]/donate

Appending &api_recon_id=[your_unique_id] to any of the above URLs will attach the unique ID your application generates to the resulting donation. These IDs from your application will be available in the results returned by the API.

Enabling donation form redirects

If you want to link to your donation form from your website, and have the user returned after the transaction completes, it’s pretty simple to set up.

  1. Make sure you are logged in and visit the setup page at https://www.givengain.com/api/donation_redirect

  2. Enter the name of your website (we’ll display this when the user is redirected), the URL they will be redirected to, and choose whether redirect is enabled or not

  3. Now, when linking the user to the donation form on GivenGain, append the redirect_url (make sure it matches the one you used in setting it up, or the redirect won’t happen) and api_recon_id parameters.

  4. The user will be redirected back to your site, and we’ll append the instruction ID instruction_id and api_recon_id so that you can make a call to the relevant instruction endpoint to check whether the donation was successful or not. Detailed documentation is available on the setup page.

Donations: List

Retrieve a list of donations
GET/donation

Possible values for attributes in request:

  • successful: Y Yes, or N No

Possible values for attributes in response:

  • successful: true or false

  • frequency: O Single, W Weekly, 2W Every 2 Weeks, M Monthly, 2M Every 2 Months, Q Every 3 Months, 6M Every 6 Months, A Annually

URI Parameters
HideShow
successful
char (optional) Default: Y 

Filter by successful (or unsuccesful) donations - only available if a token is passed

Choices: Y N

cause_id
int (optional) 

Filter by Cause ID

campaign_id
int (optional) 

Filter by Campaign ID

project_id
int (optional) 

Filter by Project ID

api_recon_id
string (optional) 
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "total": 5000000,
    "pages": 50000,
    "current_page:" 1,
    "donations": [
        {
            "id": 429000,
            "currency": "CHF",
            "amount": 500,
            "donor_id": 32627,
            "cause_id": 1860,
            "campaign_id": 3569,
            "project_id": 235673,
            "api_recon_id": "23345-EXTERNAL-APP-220",
            "successful": "true",
            "frequency": "O",
            "date": "2014-07-29"
        }
    ]
}

Donations: Detail

Retrieve single donation's details
GET/donation/{id}

If the donation is not publicly visible (donation is not to an activist project), the activist access token for the donor, or the cause access token is required.

Possible values for attributes in response:

  • successful: true or false

  • frequency: O Single, W Weekly, 2W Every 2 Weeks, M Monthly, 2M Every 2 Months, Q Every 3 Months, 6M Every 6 Months, A Annually

URI Parameters
HideShow
id
int (required) 

The donation’s unique ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 429000,
  "currency": "CHF",
  "amount": 500,
  "message": "This is for you!",
  "donor_id": 32627,
  "cause_id": 1860,
  "campaign_id": 3569,
  "project_id": 235673,
  "api_recon_id": "23345-EXTERNAL-APP-220",
  "successful": "true",
  "frequency": "O",
  "date": "2014-07-29"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Donation not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Access token belonging to the donor or cause for this donation required"
}

Instruction: List

Retrieve a list of instructions
GET/instruction

If the instruction is not to an activist project, the activist access token for the donor, or the cause access token is required.

Possible values for attributes in request:

  • status: all All instructions (default), active Only active instructions, stopped Only stopped instructions

Possible values for attributes in response:

  • successful: active Active instruction - either a bank donation still to be processed / or a recurring donation, stopped Stopped donation - Once off donation / or a stopped recurring donation

  • frequency: O Single, W Weekly, 2W Every 2 Weeks, M Monthly, 2M Every 2 Months, Q Every 3 Months, 6M Every 6 Months, A Annually

  • account_type: card Card transaction, bank Bank transaction, unknown previously used deprecated payment method transaction

URI Parameters
HideShow
status
string (optional) Default: all 

Filter by active (or stopped) instructions

Choices: all active stopped

cause_id
int (optional) 

Filter by Cause ID

campaign_id
int (optional) 

Filter by Campaign ID

project_id
int (optional) 

Filter by Project ID

api_recon_id
string (optional) 
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "total": 5000000,
    "pages": 50000,
    "current_page:" 1,
    "instructions": [
        {
            "id": 234456,
            "currency": "GBP",
            "amount": 200,
            "total_amount": 200,
            "donor_id": 32627,
            "cause_id": 1860,
            "campaign_id": 3569,
            "project_id": 235673,
            "api_recon_id": "23345-EXTERNAL-APP-220",
            "frequency": "O",
            "payment_day": 15,
            "account_type": "card",
            "status": "stopped",
            "message": "Great job!",
            "date": "2014-07-29",
            "donations": [
                {
                    "id": 44112,
                    "successful": "true",
                    "date": "2014-07-29"
                }
            ]
        }
    ]
}

Instructions: Detail

Retrieve single instruction's details
GET/instruction/{id}

If the instruction is not to an activist project, the activist access token for the donor, or the cause access token is required.

Possible values for attributes in response:

  • successful: active Active instruction - either a bank donation still to be processed / or a recurring donation, stopped Stopped donation - Once off donation / or a stopped recurring donation

  • frequency: O Single, W Weekly, 2W Every 2 Weeks, M Monthly, 2M Every 2 Months, Q Every 3 Months, 6M Every 6 Months, A Annually

  • account_type: card Card transaction, bank Bank transaction, unknown previously used deprecated payment method transaction

URI Parameters
HideShow
id
int (required) 

The instruction’s unique ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 224456,
  "currency": "ZAR",
  "amount": 50,
  "total_amount": 100,
  "donor_id": 32627,
  "cause_id": 1860,
  "campaign_id": 3569,
  "project_id": 5533,
  "api_recon_id": "2345-EXTERNAL-APP-221",
  "frequency": "M",
  "payment_day": 15,
  "account_type": "card",
  "status": "active",
  "message": "Monthly show of gratitude",
  "date": "2014-10-30",
  "donations": [
    {
      "id": 43112,
      "successful": "true",
      "date": "2014-10-15"
    },
    {
      "id": 54173,
      "successful": "true",
      "date": "2014-11-15"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Instruction not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Access token belonging to the donor or cause for this instruction required"
}

Comments

Comments: List or Add

Retrieve a list of comments
GET/comment

Possible values for attributes in response:

  • source: cause or activist

  • target: project, campaign, campaign_update, or project_update

  • status: P Pending Moderation, S Marked as Spam, A Published

You can retrieve a list of comments made by / on certain entities by using these additional endpoints:

  • By a Cause: /cause/{cause_id}/comment

  • By an Activist: /activist/{activist_id}/comment

  • On a Project: /project/{project_id}/comment

  • On a Campaign: /campaign/{campaign_id}/comment

  • On a Project Update /project/update/{project_update_id}/comment

  • On a Campaign Update /campaign/update/{campaign_update_id}/comment

URI Parameters
HideShow
parent_id
int (optional) 

Get child comments by specifying a comment’s unique ID

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total": 23567,
  "pages": 236,
  "current_page": 1,
  "comments": [
    {
      "id": 19345,
      "parent_id": 0,
      "source": "U",
      "source_id": 36267,
      "target": "P",
      "target_id": 18235,
      "comment": "This is a comment, on a project.",
      "status": "A",
      "date": "2013-04-15"
    }
  ]
}

Add a new comment
POST/comment

Requires a cause or activist token. To add a new update, send a JSON body containing the parameters.

Possible values for attributes in request:

  • target: project, campaign, campaign_update, or project_update

Possible values for attributes in response:

  • status: P Pending Moderation, S Marked as Spam, A Published
URI Parameters
HideShow
target
string (required) 

The target that the comment will be attached to

Choices: project campaign campaign_update project_update

target_id
int (required) 

The unique ID for the target that the comment will be attached to

comment
text (required) 

The actual comment text / content

parent_id
int (optional) 

If this is to be a child comment, the unique ID of the parent comment - only valid for non-nested comments

Request  Add A New Comment
HideShow
Headers
Content-Type: application/json
Body
{
  "target": "campaign_update",
  "target_id": 362,
  "comment": "Well done. This is incredible!"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Comment added",
  "status": "P",
  "id": 7632
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Target not found"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Required fields: target, target_id, and comment"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error adding the comment, please try again"
}

Comments: Detail or Manage

Retrieve a single comment's details
GET/comment/{id}

Possible values for attributes in response:

  • source: cause or activist

  • target: project, campaign, campaign_update, or project_update

  • status: P Pending Moderation, S Marked as Spam, A Published

URI Parameters
HideShow
id
int (required) 

The unique ID of the comment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 19345,
  "parent_id": 0,
  "source": "U",
  "source_id": 36267,
  "target": "P",
  "target_id": 18235,
  "comment": "This is a comment, on a project.",
  "status": "A",
  "date": "2013-04-15"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Comment not found"
}

Delete a comment
DELETE/comment/{id}

Requires a cause or activist token.

URI Parameters
HideShow
id
int (required) 

The unique ID of the comment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": "Comment deleted",
  "id": 336
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Comment not found"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "Comment owner does not match access token owner"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "There was an error deleting the comment, please try again"
}

Location

Location: List

Retrieve a list of locations
GET/location

Example URI

GET /location
URI Parameters
HideShow
country
string (optional) 

Filter by ISO 3166-1 alpha-2 country code

limit
int (optional) Default: 100 

Number of records per page, with a limit of 100

page
int (optional) Default: 1 

Which page of the resultset to return

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total": 5234,
  "pages": 53,
  "current_page": 1,
  "locations": [
    {
      "id": 215,
      "formatted_name": "Hascombe, Godalming, Surrey GU8, UK",
      "country": "GB",
      "latitude": "51.27241000000001",
      "longitude": "0.190898",
      "street_number": "6",
      "route": null,
      "sublocality": null,
      "locality": "Hascombe",
      "administrative_area_level_1": "England",
      "administrative_area_level_2": "Surrey",
      "postal_code": "GU8",
      "language": "en",
      "friendly_name": "Hascombe, England"
    }
  ]
}

Location: Detail

Retrieve a single location's details
GET/location/{id}

URI Parameters
HideShow
id
int (required) 

The location’s unique ID

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 215,
  "formatted_name": "Hascombe, Godalming, Surrey GU8, UK",
  "country": "GB",
  "latitude": "51.27241000000001",
  "longitude": "0.190898",
  "street_number": "6",
  "route": null,
  "sublocality": null,
  "locality": "Hascombe",
  "administrative_area_level_1": "England",
  "administrative_area_level_2": "Surrey",
  "postal_code": "GU8",
  "language": "en",
  "friendly_name": "Hascombe, England"
}

Currency

Currencies: List

Retrieve a list of available currencies
GET/currency

Example URI

GET /currency
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "currencies": [
        {
            "code": "USD",
            "description": "United States Dollar"
        },
        {
            "code": "ZAR",
            "description": "South African Rand"
        },
    ]
}

Generated by aglio on 16 May 2016