Donations Version 1

Note: This documentation describes Version 1 of our API, which is now depreciated. It will continue to work, but it will not reveive any updates or bug fixes. We recommend you use Version 2 instead. Documentation for this resource for Version 2 of our API is available here.

This document describes the OSDI donations collection and donation resource as implemented by the Action Network.

Donations represent the action an activist took when they donated on a specific fundraising page.

Donations have recipients indicating who the money went to, and are linked to the person resource corresponding to the activist who made the donation.

Note: Donations are not deduplicated based on person, unlike other similar resources in the Action Network API, so a specific person can donate more than once on a fundraising page.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v1/fundraising_pages/[fundraising_page_id]/donations

https://actionnetwork.org/api/v1/people/[person_id]/donations

https://actionnetwork.org/api/v1/donations

Donation resources live at endpoints relating to the person who donated and the fundraising page they donated on, as well as the top level API entry point. The endpoints return a collection of all donations associated with either that person or that fundraising page, or all donations associated with your API key.

URL Structures:

https://actionnetwork.org/api/v1/fundraising_pages/[fundraising_page_id]/donations/[donation_id]

https://actionnetwork.org/api/v1/people/[person_id]/donations/[donation_id]

https://actionnetwork.org/api/v1/donations/[donation_id]

To address a specific donation, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v1/fundraising_pages/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/donations/167ce1d2-70b7-423e-b480-914981cbeaff

Back To Top ↑

Field names and descriptions

Field Name Type Required on POST Description
identifiers array[] An array of identifiers in the format [system name]:[id]. See the general concepts document for more information about identifiers.
originating_system string Yes A human readable string identifying where this donation originated. May be used in the user interface for this purpose.
created_at datetime The date and time the resource was created. System generated, not editable.
modified_at datetime The date and time the resource was last modified. System generated, not editable.
total_amount float A system generated count of the total amount of money for this donation. Not editable.
currency string ISO 4217 designation of currency. System generated, will always be "USD", not editable.
recipients array[] Yes An array of hashes identifying the recipients of the donation. At least one recipient is required.
recipients.name string Yes The name of the recipient of this part of the donation.
recipients.amount float Yes The amount donated to this recipient. Will be added together with other recipient amounts to come up with the total_amount field above.
payment hash A hash of payment information about this donation for reporting purposes.
payment.method enum The method of payment. One of ["Credit Card" "Check" "Cash" "Electronic Funds Transfer"]. System generated, always Credit Card, not editable.
payment.reference_number string A check number, transaction ID, or some other information referencing the payment. System generated, not editable.
payment.authorization_stored boolean Indicates if payment information has been stored for future automatic payments. System generated, not editable.
action_network:recurrence hash A hash of details about the recurring nature of this donation. An Action Network-only feature.
action_network:recurrence.recurring boolean Indicates whether this is a recurring donation or not.
action_network:recurrence.period enum Indicates the frequency with which this donation recurs. One of ["Weekly" "Monthly" "Quarterly" "Yearly"].
action_network:person_id string The native Action Network identifier associated with the person who donated. Action Network-only feature. System generated, not editable.
action_network:fundraising_page string The native Action Network identifier associated with the fundraising page this signature was left on. Action Network-only feature. System generated, not editable.
action_network:referrer_data hash A hash of referrer data such as source code and referrer code. Action Network-only.
action_network:referrer_data.source string The source code of this donation. Equivalent to someone taking action with the url argument ?source=[your source]. Corresponds to the sources chart in this action's manage page. Action Network-only.
action_network:referrer_data.referrer string The referrer code of this donation. Equivalent to someone taking action with the url argument ?referrer=[your referrer code]. Must be a valid Action Network referrer code. Read-only. Corresponds to the referrers chart in this action's manage page. Action Network-only.
action_network:referrer_data.website string The website referrer for this donation. Equivalent to someone taking action after clicking a link on the listed website. Corresponds to the websites chart in this action's manage page. Action Network-only.
Back To Top ↑

Links

Link Name Description
self A link to this individual donation resource.
osdi:person A link to the person who made this donation. Click here for people documentation.
osdi:fundraising_page A link to the fundraising page this donation was left on. Note: If this donation was created via a referral code, this link may not be accessible because your API key does not give you permission to access the fundraising page itself. Click here for fundraising page documentation.
Back To Top ↑

Scenario: Retrieving a collection of donation resources (GET)

Donation resources are sometimes presented as collections of donations. For example, calling the donations endpoint on a specific fundraising page will return a collection of all the donations associated with that fundraising page.

Request

						
GET https://actionnetwork.org/api/v1/fundraisers/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations

Header:
api-key:[your api key here]

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "total_pages": 1,
  "per_page": 25,
  "page": 1,
  "total_records": 6,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations"
    },
    "record_donations_helper": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations"
    },
    "osdi:donations": [
      {
        "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
      },
      {
        "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/d86538c1-e8f7-46e1-8320-552da81bd48d"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "osdi:donations": [
      {
        "identifiers": [
          "action_network:f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
        ],
        "originating_system":"Action Network",
        "created_at": "2014-03-27T17:42:21Z",
        "modified_at": "2014-03-27T17:42:24Z",
        "currency": "USD",
        "total_amount": 20.01,
        "recipients": [
          {
            "name": "John Doe",
            "amount": 6.67
          },
          {
            "name": "Progressive Action Now",
            "amount": 6.67
          },
          {
            "name": "Jane Black",
            "amount": 6.67
          }
        ],
        "payment": {
          "method": "Credit Card",
          "reference_number": "f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16",
          "authorization_stored": false
        },
        "action_network:recurrence": {
          "recurring": true,
          "period": "Monthly"
        },
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:fundraiser_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
          },
          "osdi:fundraiser": {
            "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      {
        "identifiers": [
          "action_network:d86538c1-e8f7-46e1-8320-552da81bd48d"
        ],
        "originating_system":"Action Network",
        "created_at": "2014-03-27T17:40:56Z",
        "modified_at": "2014-03-27T17:41:11Z",
        "currency": "USD",
        "total_amount": 20.00,
        "recipients": [
          {
            "name": "John Doe",
            "amount": 10.00
          },
          {
            "name": "Progressive Action Now",
            "amount": 10.00
          }
        ],
        "payment": {
          "method": "Credit Card",
          "reference_number": "d86538c1-e8f7-46e1-8320-552da81bd48d",
          "authorization_stored": false
        },
        "action_network:recurrence": {
          "recurring": false
        },
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:fundraiser_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/d86538c1-e8f7-46e1-8320-552da81bd48d"
          },
          "osdi:fundraiser": {
            "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual donation resource (GET)

Calling an individual donation resource will return the resource directly, along with all associated fields and appropriate links to additional information about the donation.

Request

						
GET https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16

Header:
api-key:[your api key here]

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "action_network:f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
  ],
  "created_at": "2014-03-27T17:42:21Z",
  "modified_at": "2014-03-27T17:42:24Z",
  "originating_system":"Action Network",
  "currency": "USD",
  "total_amount": 20.01,
  "recipients": [
    {
      "name": "John Doe",
      "amount": 6.67
    },
    {
      "name": "Progressive Action Now",
      "amount": 6.67
    },
    {
      "name": "Jane Black",
      "amount": 6.67
    }
  ],
  "payment": {
    "method": "Credit Card",
    "reference_number": "f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16",
    "authorization_stored": false
  },
  "action_network:recurrence": {
    "recurring": true,
    "period": "Monthly"
  },
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:fundraiser_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
    },
    "osdi:fundraiser": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new donation (POST)

You can post a new donation to a fundraising page with that fundraising page's donations endpoint and a donation resource will be created in our system.

Note: Unlike other action types, you may only post donations to fundraising pages that have been created via the API. You cannot add a donation to a fundraising page created using our user interface.

When you post a donation, you can either link to an existing person to register that this person donated on this fundraising page, or you can post information about a new person inline to the special record_donations_helper endpoint, to both create a new person and register that they donated on this fundraising page at the same time.

Unlike other similar resources, donations are not deduplicated by person. A person may donate to a fundraising page more than once. Posting a new donation by a person who previously donated will create a new donation resource.

Here is an example of posting a donation linking to an existing person:

Request

						
POST https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523/donations

Header:
Content-Type: application/json
api-key:[your api key here]
						

{
  "identifiers": [
    "free_fundraisers:1"
  ],
  "originating_system" : "FreeFundraisers.com",
  "recipients": [
    {
      "name": "Campaign To Elect Tom",
      "amount": 3.00
    }
  ],
  "_links" : {
    "osdi:person" : { "href" : "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }
  }
}

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "free_fundraisers:1",
    "action_network:c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5"
  ],
  "originating_system": "FreeFundraisers.com",
  "created_at": "2014-03-27T17:53:55Z",
  "modified_at": "2014-03-27T17:57:02Z",
  "currency": "USD",
  "total_amount": 3.00,
  "recipients": [
    {
      "name": "Campaign To Elect Tom",
      "amount": 3.00
    }
  ],
  "payment": {
    "method": "Credit Card",
    "reference_number": "c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5",
    "authorization_stored": false
  },
  "action_network:recurrence": {
    "recurring": false
  },
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:fundraiser_id": "f77e736b-d295-4e68-96ec-a765090c6523",
  "_links": {
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523/donations/c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5"
    },
    "osdi:fundraiser": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}

And here is an example of posting a donation with person data inlined to the special record_donations_helper link on the donations collection:

Request

						
POST https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523/donations

Header:
Content-Type: application/json
api-key:[your api key here]
						

{
  "identifiers": [
    "free_fundraisers:2"
  ],
  "originating_system" : "FreeFundraisers.com",
  "recipients": [
    {
      "name": "Campaign To Elect Tom",
      "amount": 3.00
    }
  ],
  "person" : {
    "family_name" : "Smith",
    "given_name" : "John",
    "postal_addresses" : [ { "postal_code" : "20009" }],
    "email_addresses" : [ { "address" : "jsmith@mail.com" }]
  }
}

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "free_fundraisers:2",
    "action_network:38ec0365-f996-42a0-b26a-dbed24cf927f"
  ],
  "originating_system": "FreeFundraisers.com",
  "created_at": "2014-03-27T17:58:45Z",
  "modified_at": "2014-03-27T17:58:45Z",
  "currency": "USD",
  "total_amount": 3.00,
  "recipients": [
    {
      "name": "Campaign To Elect Tom",
      "amount": 3.00
    }
  ],
  "payment": {
    "method": "Credit Card",
    "reference_number": "38ec0365-f996-42a0-b26a-dbed24cf927f",
    "authorization_stored": false
  },
  "action_network:recurrence": {
    "recurring": false
  },
  "action_network:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "action_network:fundraiser_id": "f77e736b-d295-4e68-96ec-a765090c6523",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523/donations/38ec0365-f996-42a0-b26a-dbed24cf927f"
    },
    "osdi:fundraiser": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v1/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}

In the above example, a new person was created and their donation added to the fundraising page at the same time. We deduplicate new people added this way by email address, so if the email posted corresponded with a person already in the system, we would update their record instead of creating a new person. The required fields for person remain the same -- email address and postal code -- and any posts missing that information will fail.

Note: The record_donations_helper link is currently the same as the donations collection, but that may not always be the case. Check the link to know exactly where to post.

And of course you can post a donation with more fields (such as address lines for your inline person data) if you'd like, but they are not required.

Back To Top ↑

Scenario: Modifying a donation (PUT)

You can modify an existing donation by using PUT on its individual endpoint. You cannot modify donations created by our system, only ones you create via the API.

Request

						
PUT https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523/donations/38ec0365-f996-42a0-b26a-dbed24cf927f

Header:
Content-Type: application/json
api-key:[your api key here]
						

{	
  "identifiers": [
    "free_donations:5"
  ]
}

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "free_fundraisers:2",
    "action_network:38ec0365-f996-42a0-b26a-dbed24cf927f",
    "free_donations:5"
  ],
  "originating_system": "FreeFundraisers.com",
  "created_at": "2014-03-27T17:58:45Z",
  "modified_at": "2014-03-27T18:00:49Z",
  "currency": "USD",
  "total_amount": 3.00,
  "recipients": [
    {
      "name": "Campaign To Elect Tom",
      "amount": 3.00
    }
  ],
  "payment": {
    "method": "Credit Card",
    "reference_number": "38ec0365-f996-42a0-b26a-dbed24cf927f",
    "authorization_stored": false
  },
  "action_network:recurrence": {
    "recurring": false
  },
  "action_network:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "action_network:fundraiser_id": "f77e736b-d295-4e68-96ec-a765090c6523",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523/donations/38ec0365-f996-42a0-b26a-dbed24cf927f"
    },
    "osdi:fundraiser": {
      "href": "https://actionnetwork.org/api/v1/fundraising_page/f77e736b-d295-4e68-96ec-a765090c6523"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v1/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}

The above example added a new identifier to the donation.

Editing of certain fields via PUT is not allowed, and is noted in the field names table above. For example, you can't change the person who is associated with this donation. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting a donation (DELETE)

Deleting donations is not allowed via the API. DELETE requests will return an error.

Back To Top ↑