NAV Navbar
Logo
shell

Introduction

Welcome to the Advance by Gravyty API! You can use our HTTP API to perform basic Create, Read, Update and Delete (CRUD) actions on various Campaign related data points inside the Advance system.

The Advance API follows the JSON API Specification Format. If there are any discrepancies with compatibility, please report it by contacting support.

Rate Limits

The Advance API has an exponential backoff rate limit. Generally speaking, every API token will be allowed approximately 1 request per second. However, waiting 1 second between API requests isn’t always a realistic or convenient way to request data, so you will be able to make multiple simultaneous or back-to-back requests, as long as there’s a subsequent cooldown time such that it levels out to approximately 1 request per second over a longer period of time.

The exact rate limit depends heavily on usage patterns. To phrase this another way, the rate limit is built to discourage thousands of simultaneous requests that all occur at the same time (hourly, for example), and instead better support smaller activity patterns that occurs over shorter, more regular intervals.

Best practices here to prevent rate limiting issues would be to make use of the last_updated_* request parameters in order to ensure you’re only grabbing the data you need.

We do this in order to preserve the integrity of the donations coming into the system. We want to ensure system resources are going to the right place - ensuring your giving day is successful.

Authentication

curl "https://api.amploadvance.com/v1/campaigns"
  -H "Authorization: Token token=12345123451234512345"

Please contact support to have an API key provisioned for you.

Advance expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token token=12345123451234512345

Campaigns

List Campaigns

curl "https://api.amploadvance.com/v1/campaigns"
  -H "Authorization: Token token=12345123451234512345"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "asdfasdfasdfasdf",
      "type": "campaigns",
      "attributes": {
        "name": "Snap Advance University Campaign 1",
        "url": "https://amplouniversity.com/pages/campaign-1-page",
        "start_date": 1494278379,
        "end_date": 149428000,
        "status": "active",
        "total_votes": 10,
        "total_donations": 10,
        "total_raised": 300,
        "external_id": "abc_123"
      }
    },
    {
      "id": "111222333444555",
      "type": "campaigns",
      "attributes": {
        "name": "Snap Advance University Campaign 2",
        "url": "https://amplouniversity.com/pages/campaign-2-page",
        "start_date": 1494278379,
        "end_date": 149428000,
        "status": "active",
        "total_votes": 11,
        "total_donations": 11,
        "total_raised": 270,
        "external_id": "abc_123"
      }
    }
  ],
  "meta":{
    "pages": 1,
    "count": 2,
    "per_page": 100
  }
}

This endpoint retrieves all campaigns.

HTTP Request

GET https://api.amploadvance.com/v1/campaigns

GET Parameters

Parameter Default Required? Type Description
page 0 false integer Page number. Increment and call again to fetch more Campaigns if there are multiple pages in the results.

Default Sort Order: The object’s creation date, ascending.

Get a Specific Campaign

curl "https://api.amploadvance.com/v1/campaigns/abcdefabcedfabcedf"
  -H "Authorization: Token token=12345123451234512345"

The above command returns JSON structured like this:

{
  "data": {
    "id": "abcdefabcedfabcedf",
    "type": "campaigns",
    "attributes": {
      "name": "Snap Advance University Campaign 2",
      "url": "https://amplouniversity.com/pages/campaign-2-page",
      "logo": "https://amplouniversity.com/logo.png",
      "start_date": 1494278379,
      "end_date": 149428000,
      "status": "active",
      "category": "Student Clubs and Organizations",
      "campaign_type": "dollars",
      "allow_subscriptions": true,
      "total_votes": 11,
      "total_donations": 11,
      "total_raised": 270,
      "average_donation": 25,
      "join_code": 123456,
      "external_id": "abc_123",
      "goal": 1000,
      "member_goal": 20,
      "public": true
    }
  }
}

This endpoint retrieves a specific campaign.

HTTP Request

GET https://api.amploadvance.com/v1/campaigns/<ID>

URL Parameters

Parameter Description
ID The ID of the Campaign to retrieve

Users

Get a Specific User By Email

curl "https://api.amploadvance.com/v1/users/api@amploadvance.com"
  -H "Authorization: Token token=12345123451234512345"

The above command returns JSON structured like this:

{
  "data": {
    "id": "111222333444555",
    "type": "users",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Smith",
      "email": "api@amploadvance.com",
      "external_id": "1234_asdf",
      "donations": {
        "data": [{
          "id": "aabbccddeeffgg",
          "type": "donations",
          "attributes":{
            "beneficiary_type": "Campaign",
            "beneficiary_id": "111222333444555",
            "amount": 10,
            "status": "paid",
            "public": true,
            "donation_type": "cc",
            "external_id": "import_1234",
            "recurring": false,
            "auth_code": "123456",
            "transact_id": "abcdefg",
            "note": "I love Snap Advance U",
            "check_number": null,
            "credit_card_fingerprint": "aaaaabbbbbcccccdddddeeeee",
            "tickets": [],
            "refunded": false,
            "refundable": true,
            "refund_donation_ids": [],
            "appeal": null,
            "affinities": "alumni, parents",
            "grad_year": "1983",
            "on_behalf_of": null,    
            "donor_first_name": "John",
            "donor_last_name": "Smith",
            "donor_email": "test@test.com",
            "donor_phone": "123-123-1234",
            "donor_address1": "1234 Main St",
            "donor_address2": null,
            "donor_address3": null,
            "donor_city": "Chicago",
            "donor_region": "IL",
            "donor_zip": "12345",
            "donor_country": "United States",
            "donor_country_code": "USA",
            "card_last_4": "4242",
            "recurring": false,
            "created_at": 1498806295,
            "causes":{
              "data": [{
                "id": "000999888777",
                "type": "causes",
                "attributes": {
                  "name": "Cause Name 1",
                  "external_id": "0001234",
                  "amount": 10
                }
              }]
            }
          }
        }]
      }
    }
  }
}

This endpoint retrieves a specific User by email address. The purpose of this endpoint is User validation and existence checking.

The Donations array returned with this User provides the same fields that the Donation list endpoint provides. To find more detail on a Donation, use the Donation show endpoint.

HTTP Request

GET https://api.amploadvance.com/v1/users/<EMAIL>

URL Parameters

Parameter Description
EMAIL The full, unescaped email address for this User.

Create a New User

curl "https://api.amploadvance.com/v1/users"
  -XPOST
  -d 'first_name=Joe'
  -d 'last_name=Smith'
  -d 'email=api@amploadvance.com'
  -d 'external_id=1234_asdf'
  -H "Authorization: Token token=12345123451234512345"

The above command returns JSON structured like this:

{
  "data":{
    "id": "111222333444555",
    "type": "users",
    "attributes": {
      "first_name": "Joe",
      "last_name": "Smith",
      "email": "api@amploadvance.com",
      "external_id": "1234_asdf"
    }
  }
}

This endpoint retrieves a specific User by email address. The purpose of this endpoint is User validation and existence checking.

The Donations array returned with this User provides the same fields that the Donation list endpoint provides. To find more detail on a Donation, use the Donation show endpoint.

HTTP Request

POST https://api.amploadvance.com/v1/users

HTTP POST Parameters

Parameter Required? Type Description
email true string The full, unescaped email address for this User.
first_name true string User first name
last_name true string User last name
external_id false string External ID can be used to link this User to another external software system for record keeping purposes.

Donations

List Donations

curl "https://api.amploadvance.com/v1/donations"
  -H "Authorization: Token token=12345123451234512345"

curl "https://api.amploadvance.com/v1/campaigns/asdfasdfasdfasdf/donations"
  -H "Authorization: Token token=12345123451234512345"

The above commands returns JSON structured like this:

{
  "data":[
    {
      "id": "aabbccddeeffgg",
      "type": "donations",
      "attributes":{
        "beneficiary_type": "Campaign",
        "beneficiary_id": "111222333444555",
        "beneficiary_name": "campaign name",
        "parent_beneficiary_name": "campaign name of the parent campaign",
        "amount": 10,
        "status": "paid",
        "public": true,
        "donation_type": "cc",
        "external_id": "import_1234",
        "recurring": false,
        "auth_code": "123456",
        "transact_id": "abcdefg",
        "note": "I love Snap Advance U",
        "check_number": null,
        "credit_card_fingerprint": "aaaaabbbbbcccccdddddeeeee",
        "tickets": [],
        "refunded": false,
        "refundable": true,
        "refund_donation_ids": [],
        "appeal": null,
        "affinities": "alumni, parents",
        "grad_year": "1983",
        "on_behalf_of": null,    
        "company_name": "microsoft",    
        "joint_gift_name": null,    
        "in_memory_honor": null,    
        "in_memory_honor_notes": null,    
        "donor_first_name": "John",
        "donor_last_name": "Smith",
        "donor_email": "test@test.com",
        "donor_phone": "123-123-1234",
        "donor_address1": "1234 Main St",
        "donor_address2": null,
        "donor_address3": null,
        "donor_city": "Chicago",
        "donor_region": "IL",
        "donor_zip": "12345",
        "donor_country": "United States",
        "donor_country_code": "USA",
        "card_last_4": "4242",
        "recurring": false,
        "created_at": 1498806295,
        "causes":{
          "data": [{
            "id": "000999888777",
            "type": "causes",
            "attributes": {
              "name": "Cause Name 1",
              "external_id": "0001234",
              "amount": 10
            }
          }]
        }
      }
    },
    {
      "id": "11223344556677",
      "type": "donations",
      "attributes":{
        "beneficiary_type": "Campaign",
        "beneficiary_id": "111222333444555",
        "beneficiary_name": "campaign name",
        "parent_beneficiary_name": "campaign name of the parent campaign",
        "amount": 10,
        "status": "paid",
        "public": true,
        "donation_type": "cc",
        "external_id": "import_1234",
        "recurring": false,
        "auth_code": "123456",
        "transact_id": "abcdefg",
        "note": "I love Snap Advance U",
        "check_number": null,
        "credit_card_fingerprint": "aaaaabbbbbcccccdddddeeeee",
        "tickets": [],
        "refunded": false,
        "refundable": true,
        "refund_donation_ids": [],
        "appeal": null,
        "affinities": "alumni, parents",
        "grad_year": "1983",
        "on_behalf_of": null,    
        "company_name": "microsoft",    
        "joint_gift_name": null,    
        "in_memory_honor": null,    
        "in_memory_honor_notes": null,    
        "donor_first_name": "John",
        "donor_last_name": "Smith",
        "donor_email": "test@test.com",
        "donor_phone": "123-123-1234",
        "donor_address1": "1234 Main St",
        "donor_address2": null,
        "donor_address3": null,
        "donor_city": "Chicago",
        "donor_region": "IL",
        "donor_zip": "12345",
        "donor_country": "United States",
        "donor_country_code": "USA",
        "card_last_4": "4242",
        "recurring": false,
        "created_at": 1498806295,
        "causes":{
          "data": [{
            "id": "000999888777",
            "type": "causes",
            "attributes": {
              "name": "Cause Name 1",
              "external_id": "0001234",
              "amount": 10
            }
          }]
        }
      }
    }
  ],
  "meta":{
    "pages": 1,
    "count": 2,
    "per_page": 100
  }
}

These endpoint retrieves a paginated list of donations.

HTTP Request

This URL will fetch all donations for all Campaigns:

GET https://api.amploadvance.com/v1/donations

This URL will fetch only donations made towards a specific Campaign:

GET https://api.amploadvance.com/v1/campaigns/<CAMPAIGN_ID>/donations

URL Parameters

Campaign ID is only required when using the second URL.

Parameter Required? Type Description
CAMPAIGN_ID true string Campaign ID; obtained from Campaign list.

GET Parameters

The last_updated_* parameters are used to help reduce the number of API requests send to Advance’s API. Best practices here would be for you to track the timestamp of the last time a Donations list request was made, and only request donations that have been updated since then.

last_updated_end is not required and will always default to the timestamp at which the request was made, but to avoid any possibility of donations falling through the cracks that could be opened up in the few milliseconds of request round trip time, we suggest setting this to an explicit value.

Note that we are filtering Donations by their last updated at timestamp. This means that the list will not necessarily be full of new Donations. For example, if a Donation gets refunded, it will also show up in the list for you to possibly take action on.

The Donations lists will always only show the most recent 100 Donations and the response metadata will reflect only one page of results with only up to 100 entries. However, if both last_updated_start and last_updated_end are provided, you will be able to paginate through results using the page parameter if there are more than 100 entries.

Parameter Required? Default Type Description
last_updated_start false 0 timestamp UNIX Timestamp used to limit the list of Donations.
last_updated_end false current timestamp timestamp UNIX Timestamp used to limit the list of Donations.
page false 0 integer The results page; used to

Default Sort Order: The Object’s last updated at timestamp in descending order.

Get a Specific Donation

curl "https://api.amploadvance.com/v1/donations/abcdefabcedfabcedf"
  -H "Authorization: Token token=12345123451234512345"

The above command returns JSON structured like this:

{
  "data": {
    "id": "aabbccddeeffgg",
    "type": "donations",
    "attributes":{
      "beneficiary_type": "Campaign",
      "beneficiary_id": "111222333444555",
      "beneficiary_name": "campaign name",
      "parent_beneficiary_name": "campaign name of the parent campaign",
      "amount": 10,
      "status": "paid",
      "public": true,
      "donation_type": "cc",
      "external_id": "import_1234",
      "recurring": false,
      "auth_code": "123456",
      "transact_id": "abcdefg",
      "note": "I love Snap Advance U",
      "check_number": null,
      "credit_card_fingerprint": "aaaaabbbbbcccccdddddeeeee",
      "tickets": [],
      "refunded": false,
      "refundable": true,
      "refund_donation_ids": [],
      "appeal": null,
      "affinity": "alumni",
      "grad_year": "1983",
      "on_behalf_of": null,    
      "company_name": "microsoft",    
      "joint_gift_name": null,    
      "in_memory_honor": null,    
      "in_memory_honor_notes": null,    
      "donor_first_name": "John",
      "donor_last_name": "Smith",
      "donor_email": "test@test.com",
      "donor_phone": "123-123-1234",
      "donor_address1": "1234 Main St",
      "donor_address2": null,
      "donor_address3": null,
      "donor_city": "Chicago",
      "donor_region": "IL",
      "donor_zip": "12345",
      "donor_country": "United States",
      "donor_country_code": "USA",
      "card_last_4": "4242",
      "recurring": false,
      "created_at": 1498806295,
      "causes":{
        "data": [{
          "id": "000999888777",
          "type": "causes",
          "attributes": {
            "name": "Cause Name 1",
            "external_id": "0001234",
            "amount": 10
          }
        }]
      }
    }
  }

}

This endpoint retrieves a specific Donation.

HTTP Request

GET https://api.amploadvance.com/v1/donations/<ID>

URL Parameters

Parameter Description
ID The ID of the Campaign to retrieve

Create a New Donation

curl "https://api.amploadvance.com/v1/campaigns/111222333444555/donations"
  -XPOST
  -d 'user_id=aabbccddeeffgg'
  -d 'external_id=1234_asdf'
  -d 'amount=10'
  -d 'status=paid'
  -d 'donation_type=cash'
  -d 'public=true'
  -H "Authorization: Token token=12345123451234512345"

The above command returns JSON structured like this:

{
  "data": {
    "id": "09876543210987654321",
    "type": "donations",
    "attributes":{
      "beneficiary_type": "Campaign",
      "beneficiary_id": "111222333444555",
      "beneficiary_name": "campaign name",
      "parent_beneficiary_name": "campaign name of the parent campaign",
      "amount": 10,
      "status": "paid",
      "public": true,
      "donation_type": "cc",
      "external_id": "import_1234",
      "recurring": false,
      "auth_code": "123456",
      "transact_id": "abcdefg",
      "note": "I love Amplo U",
      "check_number": null,
      "credit_card_fingerprint": "aaaaabbbbbcccccdddddeeeee",
      "tickets": [],
      "refunded": false,
      "refundable": true,
      "refund_donation_ids": [],
      "appeal": null,
      "affinities": "alumni, parents",
      "grad_year": "1983",
      "on_behalf_of": null,    
      "company_name": "microsoft",    
      "joint_gift_name": null,    
      "in_memory_honor": null,    
      "in_memory_honor_notes": null,    
      "donor_first_name": "John",
      "donor_last_name": "Smith",
      "donor_email": "test@test.com",
      "donor_phone": "123-123-1234",
      "donor_address1": "1234 Main St",
      "donor_address2": null,
      "donor_address3": null,
      "donor_city": "Chicago",
      "donor_region": "IL",
      "donor_zip": "12345",
      "donor_country": "United States",
      "donor_country_code": "USA",
      "card_last_4": "4242",
      "recurring": false,
      "created_at": 1498806295,
      "causes":{
        "data": [{
          "id": "000999888777",
          "type": "causes",
          "attributes": {
            "name": "Cause Name 1",
            "external_id": "0001234",
            "amount": 10
          }
        }]
      }
    }
  }
}

This endpoint creates a new Donation in Advance. A few assumptions are made:

HTTP Request

POST https://api.amploadvance.com/v1/donations

HTTP POST Parameters

Parameter Required? Type Description
user_id true string The Advance User ID associated with the User who made this Donation.
campaign_id true string The Advance Campaign ID associated with the Campaign to which this Donation was made.
amount true float Donation amount in dollars
public false boolean Is this Donation public? Defaults to true.
external_id false string External ID can be used to link this Donation to another external software system for recordkeeping purposes.

Webhooks

The following is an example of JSON that would be POSTed to your webhook URL

{
  "data": {
    "id": "aabbccddeeffgg",
    "type": "donations",
    "attributes":{
      "user_id": "1122334455667788",
      "beneficiary_type": "Campaign",
      "beneficiary_id": "111222333444555",
      "amount": 10,
      "status": "paid",
      "public": true,
      "donation_type": "cc",
      "external_id": "import_1234",
      "recurring": false,
      "auth_code": "123456",
      "transact_id": "abcdefg",
      "note": "I love Snap Advance U",
      "check_number": null,
      "credit_card_fingerprint": "aaaaabbbbbcccccdddddeeeee",
      "tickets": [],
      "refunded": false,
      "refundable": true,
      "refund_donation_ids": [],
      "appeal": null,
      "causes_allocated_to": []
    }
  }
}

The following is an example of JSON that would be POSTed to your Webhook URL after an object deletion occurs 

{
  "data": {
    "id": "aabbccddeeffgg",
    "type": "donations",
    "attributes":{
      "deleted_at": 1494355936,
    }
  }
}

Webhooks allow Advance to push data into your system in a near real-time capacity. This allows you to supplement your API usage or fully change the dynamic of your API usage from primarily pull-based (you make a request, we send the data back) to push-based (when something interesting in the system happens, we let you know).

For example, when a Donation happens in Advance’s system, the Advance API will POST related JSON data to your registered Webhook URL for your immediate consumption (a.k.a. a callback).

Webhook URLs can be registered on the Entity level. SSL is required. The endpoint provided must directly consume the data without redirection, and return a 200 OK upon success.

Contact support to set one up.

Events

Create, update and delete actions trigger Webhook callbacks. This includes actions performed through the API itself. The following objects are Webhook enabled:

Object Conditions
Campaign Core Campaign attributes (rollup stats changes won’t trigger callbacks)
Donation Any modification to a Donation object triggers a callback

Format

The POSTed JSON data will largely follow the same format as the main API. The data will be equivalent to what you would get on a single object GET request. ID and Type fields can be used to distinguish the nature of the data, since all objects are posted to the same single Webhook URL.

Rate Limits

Webhook callbacks do not count towards the regular API rate limits. However, Webhook callbacks are processed in near real-time, which means that while Webhook callbacks are initiated at the time of the event, there might be some delay before a Webhook callback fully completes and POSTs to the URL. This is because Advance will always process Webhook callbacks at a lower priority level to anything core to ensuring a successful Giving Day.

Errors

curl "https://api.amploadvance.com/v1/campaigns"

The above command, missing a header on the request, will return a 401 response with the following JSON:

{
  "errors": [{
    "status": 401,
    "title": "Unauthorized - Incorrect API Key provided"
  }]
}

The Advance API uses the following error codes:

Error Code Meaning
400 Bad Request – The parameters of your request were incorrect or malformed
401 Unauthorized – Incorrect API Key provided
403 Forbidden – The API Key is correct, but the request is for something the Key does not have permission to view.
404 Not Found – The specified object could not be found
405 Method Not Allowed – The action requested could not be performed
406 Not Acceptable – The request was not correctly formatted JSON
410 Gone – The object requested has been removed from our servers
429 Too Many Requests – Rate limit exceeded.
500 Internal Server Error – An error occurred on our servers. Please wait and try again later, or contact support.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.
shell