In order to use the Donations API, you should first get the donor_id's (NationBuilder ID's) for the people to whom donations are to be attributed. You'll use our [People endpoints](http://nationbuilder.com/people_api) for this, such as Match, which supports a person lookup based on name, phone number or email address. If the person you'd like to attach a donation to does not already exist, you'll want to add them using the Create, Push, or Add endpoints.
Resources
Donation Resource
| Name | Description | Writable | Required | Example Value(s) |
amount |
amount of donation in the nation's currency | N | N | $10.00 |
amount_in_cents |
amount of donation in cents | Y | Y | 1000 |
author_id |
id of the person who created the donation | N | N1 | 67 |
billing_address |
an address resource representing the billing address | Y | N | (see Address Resource) |
canceled_at |
timestamp representing when the donation was canceled | Y | N | 2014-02-14T15:22:12-05:00 |
check_number |
check/wire/MO number | Y | N | 4747392947582 |
corporate_contribution |
true if the donation is a corporate contribution | Y | N | false |
created_at |
timestamp representing when the donation was created | N | N | 2014-02-14T14:36:29-05:00 |
donor_id |
the person id of the donor | Y | N2 | 8472 |
donor |
an abbreviated person resource representing the donor | N | N | (see Abbreviated Person Resource) |
email |
the donor's email address | Y | N3 | [email protected] |
employer |
the name of the donor's employer | Y | N3 | ABC Consulting Co |
failed_at |
timestamp representing when the donation failed | Y | N | 2014-02-14T15:22:12-05:00 |
first_name |
the donor's first name | Y | N3 | Sarah |
id |
id of the donation | N | N | 314 |
import_id |
id of the import job (if the donation was imported) | N | N | 890 |
is_private |
false if the donation should be posted publicly on the site | Y | N | false |
last_name |
the donor's last name | Y | N3 | Kerrigan |
mailing_slug |
slug of the mailing page | N | N | la_family |
membership |
a membership resource. The donation must be successful in order for the membership to be applied. | Y | N | (see Membership Resource) |
merchant_account_id |
id of the merchant account used for paying the donation | Y | N | 11 |
middle_name |
the donor's middle name | Y | N | Marie |
ngp_id |
an id which is present if the donor has been imported from NGP VAN | Y | N | 56 |
note |
a note for this donation | Y | N | very generous |
occupation |
the donor's occupation | Y | N3 | Consultant |
page_slug |
slug of the donation page | N | N | ticket_sales |
payment_type_name |
name of the payment type | Y | Y4 | Check |
payment_type_ngp_code |
code of the payment type | Y | Y4 | K |
pledge_id |
the id of the pledge this donation fulfills. Pledges are promises received from supporters to donate money in the future. | N | N | 129 |
recruiter_name_or_email |
recruiter's name or email address (will also be credited as the fundraiser for this donation) | Y | N5 | [email protected] |
recurring_donation_id |
an id present if the donation is recurring | N | N6 | 89 |
succeeded_at |
timestamp representing when the donation succeeded | Y | N7 | 2013-02-21T10:04:15-05:00 |
tracking_code_slug |
tracking code for this donation | Y | N | vip |
updated_at |
timestamp representing when the donation was last updated | N | N | 2014-02-14T14:36:29-05:00 |
work_address |
an address resource representing the work address | Y | N | (see Address Resource) |
[1]: on the Create endpoint this field will be set to the person id of the API access token's owner.
[2]: it is strongly recommended to specify this field. If omitted, email or first_name and last_name become required and a new Person may be created.
[3]: use the donor_id field instead to specify a donor. By specifying any of these fields you override the value of the same field on the donor.
[4]: default: Cash (C). It is strongly recommended to specify one of these fields.
[5]: if a recruiter already exists on the person this will not change that, the person included here would then be credited as only the fundraiser.
[6]: this field is for internal use only.
[7]: if omitted the donation will be considered failed.
These fields are always visible but contain null values unless the Voter addon is enabled:
| Name | Description | Writable | Required | Example Value(s) |
actblue_order_number |
ActBlue order number | Y | N | 543 |
fec_type |
FEC code name | Y | N1 | Contribution |
fec_type_ngp_code |
NGP FEC code | Y | N1 | C |
election |
an election resource representing an election | Y | N2 | (see Election Resource) |
[1]: default: Contribution (C). It is strongly recommended to specify one of these fields.
[2]: It is strongly recommended to specify this field.
Address Resource
| Name | Description | Writable | Required | Example Value(s) |
address1 |
first address line | Y | N1 | 1600 Pennsylvania Ave |
address2 |
second address line | Y | N | Suite 200 |
address3 |
third address line | Y | N | Apt. 207 |
city |
city | Y | N1 | Los Angeles |
state |
state | Y | N1 | CA |
zip |
zip code | Y | N1 | 90013 |
country_code |
country code | Y | N1 | US |
lat |
latitude (using WGS-84) | Y | N | 34.0204989 |
lng |
longitude (using WGS-84) | Y | N | -118.4117325 |
[1]: It is recommended to specify these fields.
Election Resource
| Name | Description | Writable | Required | Example Value(s) |
cycle |
election cycle | Y | N1,2 | 2012 |
period |
election period | Y | N1,3 | General |
period_ngp_code |
election period code | Y | N1,3 | G |
[1]: It is strongly recommended to specify cycle and either period or period_ngp_code.
[2]: default: the current election which is displayed on the Control Panel in the Political/Settings section.
[3]: default: Special (S) if cycle is defined, otherwise the value of the current election period which is displayed on the Control Panel in the Political/Settings section.
Index Endpoint
The index endpoint provides a paginated view of the donations in a nation.
GET /api/v1/donations
Parameters
-
limit- max number of results to show on each page of results (max 100) -
__nonce- generated pagination nonce. Do not modify. -
__token- generated pagination token. Do not modify.
Example
GET https://foobar.nationbuilder.com/api/v1/donations?limit=1
{
"next": "/api/v1/donations?__nonce=3OUjEzI6iyybc1F3sk6YrQ&__token=ADGvBW9wM69kUiss1KqTIyVeQ5M6OwiL6ttexRFnHK9m&limit=1",
"prev": null,
"results": [
{
"actblue_order_number": null,
"amount": "$77.00",
"amount_in_cents": 7700,
"authorization": null,
"author_id": 1,
"billing_address": {
"address1": "10 Hills St.",
"address2": null,
"address3": null,
"city": "",
"county": null,
"state": "IA",
"country_code": "US",
"zip": "40184-9188",
"lat": null,
"lng": null,
"fips": null,
"street_number": "10",
"street_prefix": null,
"street_name": "Hills",
"street_type": "St.",
"street_suffix": null,
"unit_number": null,
"zip4": "9188",
"zip5": "40184",
"sort_sequence": null,
"delivery_point": null,
"lot": null,
"carrier_route": null
},
"canceled_at": null,
"check_number": null,
"corporate_contribution": false,
"created_at": "2018-07-10T15:03:33-07:00",
"donor": {
"birthdate": null,
"city_district": null,
"civicrm_id": null,
"county_district": null,
"county_file_id": null,
"created_at": "2018-04-10T14:00:21-07:00",
"datatrust_id": null,
"do_not_call": false,
"do_not_contact": false,
"dw_id": null,
"email": "[email protected]",
"email_opt_in": true,
"employer": "",
"external_id": null,
"federal_district": null,
"fire_district": null,
"first_name": "Farz",
"has_facebook": false,
"id": 1561529,
"is_twitter_follower": false,
"is_volunteer": false,
"judicial_district": null,
"labour_region": null,
"last_name": "Smith",
"linkedin_id": null,
"mobile": null,
"mobile_opt_in": true,
"middle_name": "",
"nbec_guid": null,
"ngp_id": null,
"note": null,
"occupation": "Physicist",
"party": null,
"pf_strat_id": null,
"phone": null,
"precinct_id": null,
"primary_address": {
"address1": "10 Hills St",
"address2": null,
"address3": null,
"city": "",
"county": null,
"state": "IA",
"country_code": "US",
"zip": "40184-9188",
"lat": null,
"lng": null,
"fips": null,
"street_number": "10",
"street_prefix": null,
"street_name": "Hills",
"street_type": "St",
"street_suffix": null,
"unit_number": null,
"zip4": "9188",
"zip5": "40184",
"sort_sequence": null,
"delivery_point": null,
"lot": null,
"carrier_route": null
},
"profile_image_url_ssl": "",
"recruiter_id": null,
"rnc_id": null,
"rnc_regid": null,
"salesforce_id": null,
"school_district": null,
"school_sub_district": null,
"sex": null,
"signup_type": 0,
"state_file_id": null,
"state_lower_district": null,
"state_upper_district": null,
"support_level": null,
"supranational_district": null,
"tags": [
"Matched"
],
"twitter_id": null,
"twitter_name": null,
"updated_at": "2018-07-10T15:03:36-07:00",
"van_id": null,
"village_district": null,
"ward": null,
"work_phone_number": null,
"multiple_choice": null,
"voterockit_address_belong_to_": null,
"voterockit_address_belong_to": null,
"voter_circle_open": null,
"haystaq": null,
"hilary_supporter": null,
"testing": null,
"home_value": null,
"worth": null,
"vidyard": null,
"instagram_like_count": null,
"instagram_comment_count": null,
"instagram_username": null
},
"donor_id": 1561529,
"election": {
"cycle": "2018",
"period": "General",
"period_ngp_code": "G"
},
"email": "[email protected]",
"employer": "",
"failed_at": null,
"fec_type": "Contribution",
"fec_type_ngp_code": "C",
"first_name": "Farz",
"id": 3590,
"import_id": null,
"is_private": false,
"last_name": "Smith",
"mailing_slug": null,
"membership": {
"name": "premier",
"person_id": 1561529,
"expires_on": "2019-07-10T15:03:29-07:00",
"started_at": "2018-07-10T15:03:29-07:00",
"created_at": "2018-07-10T15:03:33-07:0",
"updated_at": "2018-07-10T15:03:33-07:00",
"status": "active",
"status_reason": null
},
"merchant_account_id": null,
"ngp_id": null,
"note": null,
"occupation": "Physicist",
"page_slug": null,
"payment_type_name": "Credit Card",
"payment_type_ngp_code": "D",
"pledge_id": null,
"recruiter_name_or_email": "Farz Smith",
"recurring_donation_id": null,
"succeeded_at": "2018-07-10T15:03:29-07:00",
"tracking_code_slug": null,
"updated_at": "2018-07-10T15:03:33-07:00",
"work_address": null
}
]
}
Search Endpoint
Use this endpoint to find donation records that have a certain attribute.
GET /api/v1/donations/search
Parameters
-
succeeded_since- donations succeeded since the given date -
created_since- donations created since the given date -
failed_since- donations that failed to process since the given date -
donor_id- the id of the donor, the response returns all donations made by this record
Example
Make the request
GET https://foobar.nationbuilder.com/api/v1/donations/search?succeeded_since=2016-11-09T10:39:38-08:00Should give you a response like this:
{
"results": [
{
"actblue_order_number": null,
"amount": "$345.00",
"amount_in_cents": 34500,
"authorization": null,
"author_id": 1,
"billing_address": {
"address1": "123 Main St Los Angeles CA 90028 USA ",
"address2": "",
"address3": null,
"city": "",
"county": null,
"state": null,
"country_code": "",
"zip": null,
"lat": null,
"lng": null,
"fips": null,
"street_number": "1231",
"street_prefix": null,
"street_name": "Main St. Los Angeles CA 90028 USA ",
"street_type": null,
"street_suffix": null,
"unit_number": null,
"zip4": null,
"zip5": null,
"sort_sequence": null,
"delivery_point": null,
"lot": null,
"carrier_route": null
},
"canceled_at": null,
"check_number": null,
"corporate_contribution": false,
"created_at": "2017-11-09T10:39:38-08:00",
"donor": {
"birthdate": "1990-12-21",
"city_district": "13",
"civicrm_id": null,
"county_district": "1",
"county_file_id": null,
"created_at": "2017-11-06T17:08:03-08:00",
"datatrust_id": null,
"do_not_call": false,
"do_not_contact": false,
"dw_id": null,
"email": "[email protected]",
"email_opt_in": true,
"employer": null,
"external_id": null,
"federal_district": "28",
"fire_district": null,
"first_name": "George",
"has_facebook": true,
"id": 1425180,
"is_twitter_follower": false,
"is_volunteer": false,
"judicial_district": null,
"labour_region": null,
"last_name": "Costanza",
"linkedin_id": null,
"mobile": null,
"mobile_opt_in": true,
"nbec_guid": null,
"ngp_id": null,
"note": null,
"occupation": null,
"party": null,
"pf_strat_id": null,
"phone": null,
"precinct_id": null,
"primary_address": {
"address1": "123 Main St.",
"address2": null,
"address3": null,
"city": "Los Angeles",
"county": "Los Angeles",
"state": "CA",
"country_code": "US",
"zip": "90028",
"lat": "34.094749",
"lng": "-118.2780302",
"fips": null,
"street_number": "123",
"street_prefix": null,
"street_name": "Main",
"street_type": "St",
"street_suffix": null,
"unit_number": null,
"zip4": null,
"zip5": "90028",
"sort_sequence": null,
"delivery_point": null,
"lot": null,
"carrier_route": null
},
"profile_image_url_ssl": "https://d3n8a8pro7vhmx.cloudfront.net/assets/icons/buddy.png",
"recruiter_id": null,
"rnc_id": null,
"rnc_regid": null,
"salesforce_id": null,
"school_district": "19647330000000",
"school_sub_district": "5",
"sex": "O",
"signup_type": 0,
"state_file_id": null,
"state_lower_district": "51",
"state_upper_district": "24",
"support_level": null,
"supranational_district": null,
"tags": [
"Matched"
],
"twitter_id": null,
"twitter_name": null,
"updated_at": "2017-11-13T06:24:22-08:00",
"van_id": null,
"village_district": null,
"ward": null,
"work_phone_number": null,
"multiple_choice": null,
"voterockit_address_belong_to_": null,
"voterockit_address_belong_to": null,
"voter_circle_open": null,
"haystaq": null,
"hilary_supporter": null,
"vidyard": null,
"instagram_like_count": null,
"instagram_comment_count": null,
"instagram_username": null
},
"donor_id": 1425180,
"election": {
"cycle": "2020",
"period": "Primary",
"period_ngp_code": "P"
},
"email": "[email protected]",
"employer": "",
"failed_at": null,
"fec_type": "Contribution",
"fec_type_ngp_code": "C",
"first_name": "George",
"id": 395,
"import_id": null,
"is_private": true,
"last_name": "Costanza",
"mailing_slug": null,
"membership": null,
"merchant_account_id": null,
"ngp_id": null,
"note": "",
"occupation": "",
"page_slug": null,
"payment_type_name": "Cash",
"payment_type_ngp_code": "C",
"pledge_id": null,
"recruiter_name_or_email": "George Costanza",
"recurring_donation_id": null,
"succeeded_at": "2017-11-09T10:39:00-08:00",
"tracking_code_slug": null,
"updated_at": "2017-11-09T10:39:38-08:00",
"work_address": null
}
],
"next": "/api/v1/donations/search?__nonce=APcxjqC717ztKJw-iwZ2Ng\u0026__token=ADR6Ed2YQdyEpM2YRgu7q_X0ZiJ0rSUNk8D-3IYvre6a\u0026limit=1\u0026succeeded_since=2016-11-09T10%3A39%3A38-08%3A00",
"prev": null
Create Endpoint
This endpoint creates a donation with the provided data. It returns a full representation of the donation that was created. If the creation step fails, it returns an error.
POST /api/v1/donations
Parameters
-
donation- the resource of the donation to be created
Note:
- A donation is always attached to a donor. Use the Create or Match endpoints on the People API to create or find the person who will act as the donor.
- When creating a donation, the
idof the donor should be specified in thedonor_idfield. - If
donor_idis specified the following fields are copied from the donor to the donation so there is no need to specify them:email,first_name,last_name,employer,occupation,recruiter_id. - Recurringdonationid should not be set when creating a new donation.
Example
Create or find a person to whom this donation should be attached. See the People API documentation Create and Match endpoints for examples.
Assuming you have a person with id 87, make the request:
POST /api/v1/donations
With attached body content like this:
{
"donation": {
"amount_in_cents": 1000,
"payment_type_name": "Cash",
"donor_id": 87,
"succeeded_at": "2013-02-21T10:04:15-04:00",
"fec_type": "Contribution",
"election": {
"cycle": "2014",
"period": "General",
"period_ngp_code": "G"
},
"membership": {
"name": "premier"
}
}
}
You will receive a response of status 200, with response body like this:
{
"donation": {
"actblue_order_number": null,
"amount": "$10.00",
"amount_in_cents": 1000,
"author_id": 67,
"billing_address": null,
"canceled_at": null,
"check_number": null,
"corporate_contribution": null,
"created_at": "2014-02-14T14:36:29-05:00",
"donor_id": 87,
"donor": {
"id": 87,
"external_id": null,
"support_level": null,
"first_name": "Sarah",
"last_name": "Kerrigan",
"email": null,
"phone": null,
"mobile": null,
"birthdate": null,
"sex": null,
"note": null,
"primary_address": null,
"tags": [],
"recruiter_id": 8472,
"created_at": "2014-02-14T14:36:29-05:00",
"updated_at": "2014-02-14T14:36:29-05:00",
"mobile_opt_in": true,
"email_opt_in": true,
"is_volunteer": false,
"is_twitter_follower": false,
"has_facebook": false,
"state_file_id": null,
"nbec_guid": null,
"van_id": null,
"dw_id": null,
"do_not_call": false,
"do_not_contact": false,
"ngp_id": null,
"pf_strat_id": null,
"county_file_id": null,
"twitter_name": null,
"twitter_id": null,
"salesforce_id": null,
"civicrm_id": null,
"linkedin_id": null,
"employer": null,
"occupation": null,
"supranational_district": null,
"federal_district": null,
"labour_region": null,
"state_upper_district": null,
"state_lower_district": null,
"city_district": null,
"county_district": null,
"judicial_district": null,
"school_district": null,
"school_sub_district": null,
"village_district": null,
"fire_district": null,
"precinct_id": null,
"party": null,
"rnc_id": null,
"rnc_regid": null
},
"election": {
"cycle": "2014",
"period": "General",
"period_ngp_code": "G"
},
"email": null,
"employer": null,
"failed_at": null,
"fec_type": "Contribution",
"fec_type_ngp_code": "C",
"first_name": "Sarah",
"id": 89,
"import_id": null,
"is_private": null,
"last_name": "Kerrigan",
"mailing_slug": null,
"membership": {
"name": "premier",
"person_id": 87,
"expires_on": null,
"started_at": "2014-02-14T14:36:29-05:00",
"created_at": "2014-02-14T14:36:29-05:00",
"updated_at": "2014-02-14T14:36:29-05:00",
"status": "active",
"status_reason": null
},
"merchant_account_id": null,
"ngp_id": null,
"note": null,
"occupation": null,
"page_slug": null,
"payment_type_name": "Cash",
"payment_type_ngp_code": "C",
"pledge_id": null,
"recruiter_name_or_email": "Sarah Kerrigan",
"recurring_donation_id": null,
"succeeded_at": "2013-02-21T10:04:15-04:00",
"tracking_code_slug": "foo_bar",
"updated_at": "2014-02-14T14:36:29-05:00",
"work_address": null
}
}
Update Endpoint
This endpoint updates a donation with the provided id and data. It returns a full representation of the updated donation. If the update step fails, it returns an error.
PUT /api/v1/donations/:id
Parameters
-
donation- the resource attributes of the donation to change
Example
Make this request (assuming you have a donation with id 89):
PUT /api/v1/donations/89
With request body like this:
{
"donation": {
"amount_in_cents": 2500
},
"membership": {
"name": "premier",
"expires_on": "2014-02-14T14:36:29-05:00"
}
}
You will receive a response of status 200 and body response like this:
{
"donation": {
"actblue_order_number": null,
"amount": "$25.00",
"amount_in_cents": 2500,
"author_id": 67,
"billing_address": null,
"canceled_at": null,
"check_number": null,
"corporate_contribution": null,
"created_at": "2014-02-14T14:36:29-05:00",
"donor_id": 87,
"donor": {
"id": 87,
"external_id": null,
"support_level": null,
"first_name": "Sarah",
"last_name": "Kerrigan",
"email": "[email protected]",
"phone": null,
"mobile": null,
"birthdate": null,
"sex": null,
"note": null,
"primary_address": {
"address1": "614 Zemlak Rds",
"address2": null,
"address3": null,
"city": "West Kale",
"state": "Massachusetts",
"country_code": "US",
"zip": "85212-7232",
"lat": null,
"lng": null
},
"tags": [],
"recruiter_id": 8472,
"created_at": "2014-02-14T14:36:29-05:00",
"updated_at": "2014-02-14T14:36:29-05:00",
"mobile_opt_in": true,
"email_opt_in": true,
"is_volunteer": false,
"is_twitter_follower": false,
"has_facebook": false,
"state_file_id": null,
"nbec_guid": null,
"van_id": null,
"dw_id": null,
"do_not_call": false,
"do_not_contact": false,
"ngp_id": null,
"pf_strat_id": null,
"county_file_id": null,
"twitter_name": null,
"twitter_id": null,
"salesforce_id": null,
"civicrm_id": null,
"linkedin_id": null,
"employer": null,
"occupation": null,
"supranational_district": null,
"federal_district": null,
"labour_region": null,
"state_upper_district": null,
"state_lower_district": null,
"city_district": null,
"county_district": null,
"judicial_district": null,
"school_district": null,
"school_sub_district": null,
"village_district": null,
"fire_district": null,
"precinct_id": null,
"party": null,
"rnc_id": null,
"rnc_regid": null
},
"election": null,
"email": "[email protected]",
"employer": null,
"failed_at": null,
"fec_type": null,
"fec_type_ngp_code": null,
"first_name": "Sarah",
"id": 89,
"import_id": null,
"is_private": null,
"last_name": "Kerrigan",
"mailing_slug": null,
"membership": {
"name": "premier",
"person_id": 87,
"expires_on": "2015-02-14T14:36:29-05:00",
"started_at": "2014-05-15T10:12:11-05:00",
"created_at": "2014-05-15T10:12:11-05:00",
"updated_at": "2014-05-15T10:12:11-05:00",
"status": "active",
"status_reason": null
},
"merchant_account_id": null,
"ngp_id": null,
"note": null,
"occupation": null,
"page_slug": null,
"payment_type_name": "Cash",
"payment_type_ngp_code": "C",
"pledge_id": null,
"recruiter_name_or_email": "Sarah Kerrigan",
"recurring_donation_id": null,
"succeeded_at": "2014-02-14T14:36:29-05:00",
"tracking_code_slug": "foo_bar",
"updated_at": "2014-05-15T10:12:11-05:00",
"work_address": null
}
}
Destroy Endpoint
This endpoint removes a donation with the provided id. It takes no parameters and returns response code 204 on success.
DELETE /api/v1/donations/:id
Custom Fields
Custom fields can be set in the API, and will also be included in all donation resource responses.
See documentation for custom fields on the API for more details.
If you have suggestions for these docs, they are public on Github and we accept pull requests.