Please upgrade to a modern web browser so we can make sure you have the Rally experience you deserve.
s
Learn Sign in

Rally.org API Documentation

Introduction

A basic request to the rally api would take the form of https://rally.org/api/causes/QWERTY?access_token=ABCDEFGHIJKLMNOP.

  1. The QWERTY in this case references the cause ID that this request is trying to get information about.
  2. The ?access_token=... part is the inclusion of your unique oauth token that we can use to identify your Rally user. It must be present in all API requests. Using the access token allows you to make as many requests as you like and ensures you have permissions for the requests you are making. Keep your access token secret and never share your access token! See the Authorization section on obtaining this token.
  3. The API only accepts GET requests. This means that cause & fundraiser information from the API is read-only and cannot be added, updated, or deleted.
  4. The API returns all requests in a standard JSON format (see below).

Authorization

This implements the OAuth2 Provider flow.

Prior to beginning this, a user should have three pieces of information 1. client_key 2. client_secret 3. redirect_url These three things should be substituted in the urls in the following steps.

Authorize a user to your app:

  1. visit http://rally.org/oauth/authorize?client_id=<client key>&response_type=code&redirect_uri=<redirect_url>
  2. Sign in and be redirected to an access page
  3. Check box and click button
  4. Get redirected to <redirect_url>?code=<auth_code>&state=<optional_junk>
  5. The auth_code above should be kept

Get access_token for user:

  1. visit https://rally.org/oauth/token/?client_id=<client_key>&client_secret=<client_secret>&code=<auth_code from above>&grant_type=authorization_code&redirect_uri=<redirect_url>
  2. Save successful response that looks like: {"token_type":"bearer","access_token":"YOUR ACCESS TOKEN"}

Save your access token from this response. This will be used in every API request.

Endpoints overview

The Rally API offers access to information about a user's causes and fundraisers through 4 types of requests (endpoints).

/drives/:NAME return details about a specific drive

/drives/:NAME/causes return the details of causes associated with the drive

/discover return all recent rallys for all users

/causes returns all rallys owned by the user

/causes/:ID returns details about a specific rally

/causes/:ID/recent_donor [deprecated] returns information about the last non-anonymous contribution for the rally

/causes/:ID/top_donors returns the top 100 non-anonymous donors for this rally, sorted by amount contributed

/causes/:ID/recent_fundraiser_posts [deprecated] returns the last 20 posts for this rally's fan fundraisers

/causes/:ID/fundraisers returns all fundraisers for the rally

/causes/:ID/donations returns all donations for this rally

/fundraisers returns all fundraisers owned by the user

/fundraisers/:ID returns details about a specific fundraiser

/fundraisers/:ID/top_donors returns the top 100 non-anonymous donors for this fundraiser, sorted by amount contributed

Endpoint details

/drives/:NAME

  1. returns details about a single drive, specified by :NAME.
  2. Sample request for drive with name, "collection-vanity". (The name can be found in the url of a drive. For example, "https://rally.org/for/collection-vanity/drive") 
    $ curl http://rally.org/api/drives/collection-vanity?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
{ "name" : "collection-vanity",
  "title" : "Support for bread cat to buy a boat",
  "subtitle" : "He would really love a boat",
  "description_title" : "Finally I will get a boat",
  "description_body" : "We should buy him a boat",
  "goal_cents" : 89900,
  "hashtags" : ["breadcat", "ishouldbuyaboat"],
  "featured_cause_id" : "DeAdBeeF",
  "starts_at" : "01/01/2013",
  "ends_at" : "10/10/2014",
  "total_raised_in_cents" : 30052539
}

/drives/:NAME/causes

  1. returns the details of causes associated with the drive
  2. Sample request for drive with name, "collection-vanity". 
    $ curl http://rally.org/api/drives/collection-vanity/causes?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
[
  {
    "name":"An great cause",
    "website_url":null,
    "created_at":"2013-12-06T13:34:02.000-08:00",
    "id":"2xCCaLa00T9",
    "rally_url":"http://rally.org/pizzacat",
    "supporter_count":0,
    "cause_type":"Animal, Wildlife, Environment",
    "cause_type_category":"Other",
    "location":"Anytown, DE",
    "location_zip":"12345",
    "total_raised":0,
    "donation_count":0,
    "current_fundraising_goal":null,
    "headline":"Help Support My Rally",
    "blurb":"buy pizzas for all starving cats",
    "image_url":"https://s3.aws.amazon.com/rallycall/covers/12/images/original/bg.jpg?1375997306",
    "raised_toward_fundraising_goal":null
  },
  {
    "name":"Another photo cause",
    "website_url":null,
    "created_at":"2013-12-06T13:34:01.000-08:00",
    "id":"j600QI66Oe",
    "rally_url":"http://localhost:3000/f/5JWU6YcaLsQ",
    "supporter_count":0,
    "cause_type":"Animal, Wildlife, Environment",
    "cause_type_category":"Other",
    "location":null,
    "location_zip":null,
    "total_raised":0,
    "donation_count":0,
    "current_fundraising_goal":null,
    "headline":"Help Support My Rally",
    "blurb":"I'm rallying for my friends to buy all starving cats unlimited pizzas",
    "image_url":"https://s3.aws.amazon.com/rallycall/covers/12/images/original/bg.jpg?1375997306",
    "raised_toward_fundraising_goal":null
  }
]

/discover

  1. This returns a list of the newest rally objects across the entire platform.
  2. Sample request 
    $ curl https://rally.org/api/discover?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
[
  {
    "blurb": null,
    "cause_type": "Arts, Culture, Humanities",
    "cause_type_category": "Other",
    "created_at": "2013-08-08 14:30:26",
    "current_fundraising_goal": null,
    "headline": null,
    "id": "7jl7Xu5aGRI",
    "image_url": "https://s3.aws.amazon.com/rallycall/covers/12/images/original/bg.jpg?1375997306",
    "name": "Banksy4Life",
    "raised_toward_fundraising_goal": null,
    "rally_url": "https://rally.org/banksy",
    "supporter_count": 1,
    "website_url": null,
    "location": "Berlin, Germany",
    "location_zip", "12345"
  },
  {
    "blurb": null,
    "cause_type": "Animal, Wildlife, Environment",
    "cause_type_category": "Other",
    "created_at": "2013-08-08 14:28:26",
    "current_fundraising_goal": null,
    "headline": null,
    "id": "7jl7Xu5aGRI",
    "image_url": "https://s3.aws.amazon.com/rallycall/covers/11/images/original/bg.jpg?1375997306",
    "name": "Fennec Fox Breeding",
    "raised_toward_fundraising_goal": null,
    "rally_url": "https://rally.org/foxes",
    "supporter_count": 1,
    "website_url": null,
    "location": "San Francisco, CA",
    "location_zip": "94105"
  },
]
  3. The cause object contains the follow fields:
    1. id : The unique identifier that references the cause
    2. name : The cause name as a string
    3. created_at : The timestamp when the cause was created (result will be sorted descending on this value).
    4. current_fundraising_goal : The number, in cents, of the current fundraising goal or null.
    5. raised_toward_fundraising_goal : The number, in cents, of the unrefunded amount raised for the current fundraising goal or null.
    6. cause_type : The self selected type, eg. "Education"
    7. cause_type_category : The self selected category, pretty sure this is always "Other"
    8. image_url : The url of their uploaded cover image or youtube thumbnail image from the video.
    9. supporter_count : The number of supporters for a cause
    10. website_url : A string of the cause's personal URL or an empty string, ""
    11. rally_url : A string of the cause's rally page
    12. headline : A string of the cause's headline or an empty string, ""
    13. blurb : A string of the cause's blurb or null
    14. location : The city/state (for US rallys) or city/country (for international rallies)
    15. location_zip : The zip code where the rally is registered

/causes

  1. This returns a list of the rally objects owned by the currently authenticated user.
  2. Sample request 
    $ curl https://rally.org/api/causes?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
[
  {
    "blurb": null,
    "cause_type": "Arts, Culture, Humanities",
    "cause_type_category": "Other",
    "created_at": "2013-08-08 14:30:26",
    "current_fundraising_goal": null,
    "donation_count": 5,
    "headline": null,
    "id": "7jl7Xu5aGRI",
    "image_url": "https://s3.aws.amazon.com/rallycall/covers/12/images/original/bg.jpg?1375997306",
    "name": "Banksy4Life",
    "raised_toward_fundraising_goal": null,
    "rally_url": "https://rally.org/banksy",
    "supporter_count": 1,
    "total_raised": 25000,
    "website_url": null,
    "location": "Berlin, Germany",
    "location_zip", "12345"
  },
  {
    "blurb": null,
    "cause_type": "Animal, Wildlife, Environment",
    "cause_type_category": "Other",
    "created_at": "2013-08-08 14:28:26",
    "current_fundraising_goal": null,
    "donation_count": 1,
    "headline": null,
    "id": "7jl7Xu5aGRI",
    "image_url": "https://s3.aws.amazon.com/rallycall/covers/11/images/original/bg.jpg?1375997306",
    "name": "Fennec Fox Breeding",
    "raised_toward_fundraising_goal": null,
    "rally_url": "https://rally.org/foxes",
    "supporter_count": 1,
    "total_raised": 1000,
    "website_url": null,
    "location": "San Francisco, CA",
    "location_zip": "94105"
  },
]
  3. The cause object contains the follow fields:
    1. id : The unique identifier that references the cause
    2. name : The cause name as a string
    3. created_at : The timestamp when the cause was created (result will be sorted descending on this value).
    4. total_raised : The number of the total unrefunded amount raised in cents.
    5. donation_count : The number of unrefunded donations made to the cause.
    6. current_fundraising_goal : The number, in cents, of the current fundraising goal or null.
    7. raised_toward_fundraising_goal : The number, in cents, of the unrefunded amount raised for the current fundraising goal or null.
    8. cause_type : The self selected type, eg. "Education"
    9. cause_type_category : The self selected category, pretty sure this is always "Other"
    10. image_url : The url of their uploaded cover image or youtube thumbnail image from the video.
    11. supporter_count : The number of supporters for a cause
    12. website_url : A string of the cause's personal URL or an empty string, ""
    13. rally_url : A string of the cause's rally page
    14. headline : A string of the cause's headline or an empty string, ""
    15. blurb : A string of the cause's blurb or null
    16. location : The city/state (for US rallys) or city/country (for international rallies)
    17. location_zip : The zip code where the rally is registered

/causes/:ID

  1. returns details about a single cause, specified by :ID.
  2. Sample request for cause with ID, ABCDEFGH. 
    $ curl https://rally.org/api/causes/ABCDEFGH?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
{
  "blurb": null,
  "cause_type": "Animal, Wildlife, Environment",
  "cause_type_category": "Other",
  "created_at": "2013-08-08 14:28:26",
  "current_fundraising_goal": null,
  "donation_count": 1,
  "headline": null,
  "id": "7jl7Xu5aGRI",
  "image_url": "https://s3.aws.amazon.com/rallycall/covers/11/images/original/bg.jpg?1375997306",
  "name": "Fennec Fox Breeding",
  "raised_toward_fundraising_goal": null,
  "rally_url": "https://rally.org/foxes",
  "supporter_count": 1,
  "total_raised": 1000,
  "website_url": null
}

/causes/:ID/fundraisers

  1. This returns a list, which can be empty, of all the fan-fundraisers for the cause specified by ID.
  2. Sample request 
    $ curl https://rally.org/api/causes/ABCDEFGH/fundraisers?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
[
  {
    "fundraiser": {
      "current_fundraising_goal": null,
      "donation_count": 13,
      "created_at": "2012-07-12T11:50:56-07:00",
      "total_raised": 4500,
      "supporter_count": 7,
      "rally_url": "https://rally.org/cuteanimalpictures/POLIKUJJ/billymays",
      "id": "POLIKUJJ",
      "raised_toward_fundraising_goal": null,
      "cause_id": "ABCDEFGH",
      "user": {
        "name": "Billy Mays",
        "icon_url": "https://some.url/here/pops.jpg",
        "id": "nsbhdyfs"
      }
    }
  },
  {
    "fundraiser": {
      "current_fundraising_goal": null,
      "donation_count": 0,
      "created_at": "2012-08-23T16:52:26-07:00",
      "total_raised": 0,
      "supporter_count": 0,
      "rally_url": "https://rally.org/cuteanimalpictures/YUKYUKYUK/sally",
      "id": "YUKYUKYUK",
      "raised_toward_fundraising_goal": null,
      "cause_id": "ABCDEFGH",
      "user": {
        "name": "Sally Heaps",
        "icon_url": "https://some.url/here/pops.jpg",
        "id": "baMBaMbAm"
      }
    }
  }
]
  3. The fundraiser objects uses many of the same fields as cause objects do, the additions are
    1. cause_id : The unique id for the cause.
    2. user : The user object who started that fan-fundraiser.
    3. name : A string of the name of the user
    4. icon_url : A string of the url for that user's icon
    5. id : A unique id for that user.

/causes/:ID/top_donors

  1. Sample request 
    $ curl https://rally.org/api/causes/POLIKUJJ/top_donors?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
[
  {
    "first_name": "Billy",
    "last_name": "Mays",
    "id": "nsbhdyfs",
    "amount": 900,
  },
  {
    "first_name": "Sally",
    "last_name": "Heaps",
    "id": "nsbhdyfs",
    "amount": 800,
  },
  {
    "first_name": "Jeffery",
    "last_name": "Giant",
    "id": "nsbhdyfs",
    "amount": 700,
  }
]

/fundraisers/:ID

  1. Sample request 
    $ curl https://rally.org/api/fundraisers/POLIKUJJ?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
{
    "fundraiser": {
      "current_fundraising_goal": null,
      "donation_count": 13,
      "created_at": "2012-07-12T11:50:56-07:00",
      "total_raised": 4500,
      "supporter_count": 7,
      "rally_url": "https://rally.org/cuteanimalpictures/POLIKUJJ/billymays",
      "id": "POLIKUJJ",
      "raised_toward_fundraising_goal": null,
      "cause_id": "ABCDEFGH",
      "user": {
        "name": "Billy Mays",
        "icon_url": "https://some.url/here/pops.jpg",
        "id": "nsbhdyfs"
      }
    }
}

/fundraisers/:ID/top_donors

  1. Sample request 
    $ curl https://rally.org/api/fundraisers/POLIKUJJ/top_donors?access_token=ZXCVBNMLKJHGFDSAQWERTYUIOP
[
  {
    "first_name": "Billy",
    "last_name": "Mays",
    "id": "nsbhdyfs",
    "amount": 900,
  },
  {
    "first_name": "Sally",
    "last_name": "Heaps",
    "id": "nsbhdyfs",
    "amount": 800,
  },
  {
    "first_name": "Jeffery",
    "last_name": "Giant",
    "id": "nsbhdyfs",
    "amount": 700,
  }
]

/causes/:ID/donations

  1. This returns a list, which can be empty, of all the donations for a cause (specified by ID).
  2. Since lists of donations can be very long, the donations endpoint is paginated. The default result set will be 25 donations and additional donations can be retrieved using the page parameter. Each page will return a set of 25 donations, ordered by created_at date.
  3. Optional parameters start_date and end_date may also be used. The result will include donations with created_at date between start_date and end_date Date should be in the format of "YYYY-MM-DD"
  4. Sample request 
    $ curl https://rally.org/api/causes/SSOTORP/donations?access_token=PUUOYEVIGANNOGREVEN&page=7&start_date=2013-01-01&end_date=2013-02-01
[
  {
    "id"=>"8GU4ICC33TL",
    "private"=>false,
    "first_name"=>"Sarah",
    "last_name"=>"Kerrigan",
    "email"=>"somebody-2@example.com",
    "amount_cents"=>1000,
    "currency"=>"usd",
    "transaction_fee"=>57,
    "payment_type"=>"cc",
    "payment_method"=>"visa",
    "phone_number"=>"5551234567",
    "occupation"=>"Nurse",
    "employer"=>"Acme Widgets",
    "gender"=>"F",
    "address_country"=>"US",
    "address_address1"=>"123 Mar Sara street",
    "address_city"=>"San Francisco",
    "address_state"=>"CA",
    "address_zip"=>"94110",
    "refunded"=>false,
    "created_at"=>"2013-03-14 11:28:33",
    "birthdate"=>"1980-07-09",
    "custom_field_values"=>[{"A Name"=>"whatever"}],
    "fundraiser_id"=>"3MGmTYb9KQF"
    },

   {
    "id"=>"kauwjI02gFX",
    "private"=>false,
    "first_name"=>"James",
    "last_name"=>"Raynor",
    "email"=>"somebody-3@example.com",
    "amount_cents"=>1000,
    "currency"=>"usd",
    "transaction_fee"=>57,
    "payment_type"=>"cc",
    "payment_method"=>"visa",
    "phone_number"=>"5928372222",
    "occupation"=>"Professional gamer",
    "employer"=>"Acme Widgets",
    "gender"=>"M",
    "address_country"=>"US",
    "address_address1"=>"999 Aiur road",
    "address_city"=>"San Francisco",
    "address_state"=>"CA",
    "address_zip"=>"94110",
    "refunded"=>false,
    "created_at"=>"2013-03-14 11:28:33",
    "birthdate"=>"1980-07-09",
    "custom_field_values"=>[],
    "fundraiser_id"=>"3MGmTYb9KQF",
    "cover_id"=>"aY3IEHPU1iY"
    }
  ]
    1. id : The unique id for the donation.
    2. custom_field values : A list of custom fields and values
    3. cover_id : The cover which the donation is donated from
    4. refunded : Indicates if donation has been refunded