Back to top

ImRaising Public API is a way to retreive & test ImRaising donations.

Authentication 

How to authenticate with the ImRaising Public API

The API uses an api key based authentication with two levels of access.

  • Limited API Key
  • Advanced API Key

Both are handled in exactly the same way and the Advanced key is a superset of the Limited key, so an advanced key can do anything a limited key can.

It is reccomended that you avoid using the advanced key unless you absolutely need it.

All endpoints require an API Key

The API Key must be sent in the Authorization header as such:

authorization: APIKey apikey="Your-API-Key-Goes-Here"

Please note for cross-origin requests the header is case-sensitive and should be lowercase.

Or as a query parameter: (This is highly discouraged and may be removed in the future)

https://imraising.tv/api/v1/endpoint?apikey=Your-API-Key-Goes-Here

An API Key is 22 alphanumeric characters including dashes and underscores.

Any malformed API Key may result in a regular HTTP 401 Unauthorized error rather than a notification of a malformed key or an invalid key error. A invalid API key (one that has expired or does not exist) will result in a Authentication.InvalidAPIKey error.

API Errors 

All expected errors are in JSON/JSONP format and encapsulated as such:

{
     name: 'errorName',
     message: 'Optional error message'
}

Standard Errors

HTTP StatusError NameExplanation
401UnauthorizedAn authentication error occured, did you remember to provide the API Key?
401Authentication.InvalidAPIKeyThe API Key provided was formatted correctly but could not be found (the user may have refreshed their API Key, deleted their account, or this key may simply not exist)
403Authentication.ModeUnacceptableThe requested API endpoint is not permitted for this authentication mode, i.e., using a Limited API Key where an Advanced API Key is required.
405MethodNotAllowedThe requested HTTP method is not allowed on this URL. For example, using POST where only GET is allowed.
406NotAcceptableThe requested content type is not acceptable, such as requesting application/json where text/event-stream is required.
400InvalidParameterA bad request was made, see the message for details.

Endpoints 

Notification Stream 

Listen for notifications
/api/v1/listen

A Server Sent Events stream for receiving donation events.

Events

  • Any event not in this list should be ignored
  • donation.add event
    • A new donation was added, either manually or through PayPal
    • You will receive the following information in the event data:
    • "_id":      "ffffffffffffffffffffffff",
      "nickname": String,
      "message":  String,                     // Optional
      "time":     "1970-01-01T00:00:00.000Z", // ISO-8601 Date
      "amount": {
          "display": {
              "total":    "Float",
              "currency": "XTS"
          }
      }
      
  • donation.delete event
    • A donation was deleted, either by a refund/chargeback or by the user deleting it from the dashboard
    • If your application keeps a log of donations this event should be handled.
    • You will only receive the donation id in the event data:
    • "_id":      "ffffffffffffffffffffffff"
      

Code Example

var sse = new EventSource('https://imraising.tv/api/v1/listen?apikey=Your-API-Key-Goes-Here');

sse.addEventListener('donation.add', function(e)
{
    console.log('new donation');
    console.log(JSON.parse(e.data));
});

sse.addEventListener('donation.delete', function(e)
{
    console.log('donation deleted')
    console.log(JSON.parse(e.data));
});

Simple as that! Though we suggest using an EventSource polyfill to ensure your code works on all browsers, we use Yaffle’s EventSource in our widgets.

  • Request
  • Headers
    Content-Type: text/event-stream
    Authorization: APIKey apikey="Your-API-Key-Goes-Here"
  • Response  200
  • Headers
    Content-Type: text/event-stream
    Cache-Control: no-cache
    Connection: keep-alive
    Access-Control-Allow-Origin: *
    Body
    :
    retry: 10000
    
    event: donation.add
    data: {
        "_id": "ffffffffffffffffffffffff",
        "nickname": String,
        "message": String,
        "time": "1970-01-01T00:00:00.000Z",
        "amount": {
            "display": {
                "total":    "Float",
                "currency": "XTS"
            }
        }
    }
    

Donations 

Donation Listing/History
/api/v1/donations{?offset,limit,startDate,endDate,sort}

Advanced API Key

  • Parameters
  • offset
    non-negative integer (optional) 
    limit
    non-negative non-zero integer <= 100 (optional) 

    Specify how many donations to request, must be less than or equal to 100

    startDate
    ISO-8601 Date (optional) 
    endDate
    ISO-8601 Date (optional) 
    sort
    string (optional) 

    A field to sort by, valid fields are: nickname, amount, time. Placing a - infront will sort in reverse order.

  • Request
  • Headers
    Content-Type: application/json
    Authorization: APIKey apikey="Your-API-Key-Goes-Here"
  • Response  200
  • Headers
    Content-Type: application/json
    Access-Control-Allow-Origin: *
    Body
    [
        {
            "_id": "ffffffffffffffffffffffff",
            "nickname": String,
            "message": String,
            "time": "1970-01-01T00:00:00.000Z",
            "amount": {
                "display": {
                    "total":    "Float",
                    "currency": "XTS"
                }
            }
        },
        ...
    ]
    

Donation Totals 

Get donation totals
/api/v1/donations/total{?startDate,endDate}

Advanced API Key

  • Parameters
  • startDate
    ISO-8601 Date (optional) 
    endDate
    ISO-8601 Date (optional) 
  • Request
  • Headers
    Content-Type: application/json
    Authorization: APIKey apikey="Your-API-Key-Goes-Here"
  • Response  200
  • Headers
    Content-Type: application/json
    Access-Control-Allow-Origin: *
    Body
    [
        {
        "total": "Float",
    "currency": "XTS"
        },
        ...
    ]
    

Donation Totals per Donor 

Get the total of donations for a specific donor
/api/v1/donations/total/donor{?nickname,startDate,endDate}

Advanced API Key

  • Parameters
  • startDate
    ISO-8601 Date (optional) 
    endDate
    ISO-8601 Date (optional) 
    nickname
    string (required) 

    maximum 27 characters case-sensitive

  • Request
  • Headers
    Content-Type: application/json
    Authorization: APIKey apikey="Your-API-Key-Goes-Here"
  • Response  200
  • Headers
    Content-Type: application/json
    Access-Control-Allow-Origin: *
    Body
    [
        {
            "nickname": String,
            "amount": {    
                "total": "Float",
                "currency": "XTS"
            }
        },
        ...
    ]
    

Top Donors 

Top Donors Listing
/api/v1/topDonors{?offset,limit,startDate,endDate}

Advanced API Key

  • Parameters
  • offset
    non-negative integer (optional) 
    limit
    non-negative non-zero integer <= 100 (optional) 

    Specify how many top donors to request, must be less than or equal to 100, default is 10

    startDate
    ISO-8601 Date (optional) 
    endDate
    ISO-8601 Date (optional) 
  • Request
  • Headers
    Content-Type: application/json
    Authorization: APIKey apikey="Your-API-Key-Goes-Here"
  • Response  200
  • Headers
    Content-Type: application/json
    Access-Control-Allow-Origin: *
    Body
    [
        {
            "nickname": String,
            "amount": {    
                "total": "Float",
                "currency": "XTS"
            },
            "latestMessage": String
        },
        ...
    ]
    

Test Donation 

Send test donation
/api/v1/donations

This allows you to broadcast a test donation into the system, it does not save the donation and the donation will not appear in the report. However, it will trigger all widgets, ImRaising Sync, and all other systems listening to /listen. The donation will be broadcast with the currency code XTS (testing code) and may be ignored by some systems like the Dashboard.

  • Request
  • Headers
    Content-Type: application/json
    Authorization: APIKey apikey="Your-API-Key-Goes-Here"
    Body
    {
        amount: Float,
        message: String // Optional, 300 characters max
    }
    
  • Response  204
  • Headers
    Content-Type: application/json

© 2015 ImRaising, LLC. 
Updated on May 09, 2015