API Documentation - Campaigns (V2)

The Tiltify API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs. JSON will be returned in all API responses, including errors.

API Endpoint

https://tiltify.com/api/v2/

Authentication

You authenticate to the Tiltify API by providing one of your API keys in the request. Your API key should only be known by you, so be sure to keep it secret!

Authentication to the API occurs using an access token. 

All API requests must be made over HTTPS.

curl https://tiltify.com/api/v2/<request> -H 'Authorization: Token token="<API Key>"'

curl uses the -H flag to allow for custom headers.

A sample test API key has been provided so you can test out an example right away. 

Errors

Tiltify uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information.

HTTP Status Code Summary

  • 200 OK - Everything worked as expected.
  • 401 Bad Credentials - No valid API key provided.
  • 404 Bad Path – Path does not exist.

Versioning

When we make backwards-incompatible changes to the API, we release new versions.  This will allow you to continue to use the prior version.


Campaign

Retrieve detail information and all donations regarding a Campaign.  A unique key is generated for each campaign.  The API Key can be found on the Campaign Edit page under Streaming Media.  Use this KEY to access campaign and donation data.  Below is the curl call to access the campaign detail. 

curl https://tiltify.com/api/v2/campaign -H 'Authorization: Token token="<API_KEY>"'


There are 4 options available with this call.


  1. donations=(true/false) * indicate whether or not you want associated donations.
  2. donation_limit=<number> * maximum returned donations
  3. donation_order_by=amount * the default order is by date.  Set this option to order by amount.
  4. donation_order=(asc,desc) * desc is default. This applies to the donation_order_by option.

You can also request a subset of your campaign:


Return only rewards: /api/v2/campaign/rewards

Return only donations: /api/v2/campaign/donations
  • These options are also available with the donations call:
  1. donation_limit=10
  2. donation_order_by=amount
  3. donation_order=desc
As an example, the following will return the top ten donations for a campaign.
?donation_limit=10&donation_order_by=amount&donation_order=desc

Return only levels: /api/v2/campaign/levels

Return only activities: /api/v2/campaign/activities


Responses

JSON will be returned in all responses. The campaign and child levels, rewards, activites and donations are described below:

The campaign object

Attributes

campaign_id

string

Unique identifier for the campaign.

owner

string

Username or Team Name of the campaign owner.

mission

string

Name of the Mission being supported.

owner_img

string

Url to avatar of campaign owner.

campaign

string

Name of the Campaign.

cause

string

Name of the Charity being supported.

cause_logo_url

string

Url to display cause logo.

donation_url

string

Url to donation page of the campaign.

campaign_url

string

Url to campaign on Tiltify.

banner_url

string

Url to uploaded banner.

thumbnail

string

Url to thumbnail image uploaded for campaign.

description

string

Campaign description.

goal

string

Total amount the campaign wants to raise.

total_raised

string

Total amount the campaign has raised.

percent_raised

string

Percent of the Total Raised. (total_raised/goal)

top_donor

string

Name of the campaign top donor.

top_donor_amount

string

amount of the campaign top donation.

starts

date/time

Date/Time the campaign starts.

ends

date/time

Date/Time the campaign ends.

currency_code

string

Currency Type.

levels

array

Donation Levels object associated with the Campaign.

activities

array

Campaign Activities object of associated activities during the campaign.

supporting_parent_name

string

If the campaign is supporting another parent campaign the name will be returned here.  If no parent campaign exists, nil is returned.

donations

array

Donation object of all donations associated with the Campaign.

The levels hash (child parameters)

Attributes

title

string

The title given to the level.

amount

number

The donation level amount.

The activities hash (child parameters)

Attributes

name

string

The title given to the activity.

starts_at

date/time

Date/Time the activity starts.

ends_at

date/time

Date/Time the activity ends.

description

string

Activity description.

image_url

string

Url associated with the activity.

The rewards hash (child parameters)

Attributes

reward_id

number

unique reward identifier.

name

string

Title of the reward.

amount

number

Donation amount for reward.

quantity

number

Quantity available.

remaining

number

If there is a limited quantity, returns how many more are remaining.

fmv

number

Fair Market Value.  Must be included with rewards

starts_at

date/time

Date/Time the reward starts.

ends_at

date/time

Date/Time the reward ends.

description

string

Reward description.

rules_url

string

Url to rules page if sweepstakes.

shipping_address_required

boolean

Does this reward need a shipping address?.

image_url

string

Url associated with the reward.

currency_code

string

Currency code.

donate_url

string

Url to campaign donation page with reward selected.

created

date/time

When the reward was created.

The donation hash (child parameters)

Attributes

name

string

Name of the donor. Anonymous is returned if the donor wishes to remain anonymous.

comment

string

Comment from the donor.

amount

number

Amount donated.

currency_code

string

Currency Type.

created

date/time

Date/Time the donation was created.

reward

string

Reward associated with the donation.

reward_id

string

Unique reward id.

challenge

string

Challenge associated with the donation.

challenge_id

string

Unique challenge id.

id

number

Unique identifier for the donation.

The challenge hash (child parameters)

Attributes

name

string

Name of the challenge. 

amount

string

.Dollar amount to complete the challenge.

total_raised

string

Amount donated to the challenge.

activated_at

date/time

Date/Time challenge was activated.

ends_at

date/time

Date/Time the challenge ends.

Test Data


In order to develop against this API, we supply you a set of live test data.

From a terminal you can enter the following curl:

Input

curl https://tiltify.com/api_test/v2/campaign?donations=true -H 'Authorization: Token token="test_479c924413fe9168952891e9a36"'

And the API will return:

Output

{
  "owner":"Tilty",
  "mission":"A Perfect Mission",
  "campaign":"My Awesome Campaign",
  "cause":"A Great Cause",
  "goal":"6000.00",
  "total_raised":"$890.00",
  "percent_raised":"30%",
  "top_donor":"Mickey",
  "top_donor_amount":"$730.00",
  "starts":"09/16 12:45PM",
  "ends":"09/30 02:00PM",
  "currency_code":"USD",
  "donations":
  [
    { 
      "name":"Mickey", 
      "comment":"Awesome game!!", 
      "amount":730.0, 
      "created":"2014-09-17 16:06:21 -0400",
      "currency_code":"USD",
      "id": 10003
    },
    { "name":"Anonymous", 
      "comment":null, 
      "amount":50.0, 
      "created":"2014-09-17 20:22:47 -0400",
      "currency_code":"USD",
      "id": 10002
    },
    { 
      "name":"Anonymous", 
      "comment":null, 
      "amount":100.0, 
      "created":"2014-09-17 20:51:12 -0400",
      "currency_code":"USD",
      "id": 10001
    },
    { 
      "name":"Anonymous", 
      "comment":null, 
      "amount":10.0, 
      "created":"2014-09-18 15:20:42 - 400",
      "currency_code":"USD",
      "id": 10000
    }
  ]
}

Questions

If you have any problem or questions please feel free to reach out to us at: support@tiltify.com

Feedback and Knowledge Base