Introduction to the ActBlue Contributions API

A contribution captures a single event that takes place as a result of a source contributing to one or more entities. It is the root object that API clients may query against. It represents a financial transfer from a source to one or more entities, credited to various intermediaries. Contributions made to multiple entities include one lineitem per entity. Multiple lineitems are also used to represent a sequence of recurring contributions to an entity. In the case of a contribution to m candidates for n months, there are m * n lineitems.

The contribution query API provides a simple interface for requesting collections of contributions that match some set of critera.

All contribution queries are made over secure HTTP (HTTPS) on port 443.

Clients must supply a username/password pair with each request, using HTTP's standard basic-auth facility. You may create a username and password by signing up for an account in the usual fashion. Basic auth's base64 algorithm does not encrypt the username or password, but since the entire exchange is protected by SSL, the API key is kept secure. Most client-side HTTP libraries provide a means to encode a username and password into the HTTP request header. Attempts to access the API with a missing or invalid username/password pair result in an HTTP 401 (Unauthorized) error.

All requests must include an Accept: application/xml header.

The API is versioned by date. See the top of this document for the current version. The version string is the first component of the service URL, as shown below

Access to the API is controlled with username/password pairs identical to those used to log in to the interactive site.

API clients may use the query service to request various subsets of contributions. All queries must filter by at least one of the destination entity, express account, or contribution form. If the query result is compatible with the client's query rights, it is returned. If not, the API returns a 401 Unauthorized Access error.

When requesting particular contribution records, results are limited by the permissions of the API account holder. Destination entity queries require access to entity contribution reports. Express queries may only be made by the express account holder. Records associated with a contribution form are restricted to the account of the page's owner.

Additional filters may be added without the need for specific permissions. These may include the four listed above, as well as filters on amounts, timestamps, and other fields that do not carry any permissions requirements. For example, a contribution form owner may query for contributions to their page made to a specific entity, or contribuitons made to the page made on a particular date. Conversely, an account with access to a report may query for contributions made to that entity through a particular fundraising page.

Access control and query results are decoupled. Query results are not implicitly restricted according to the permissions of the API client. Rather, results are strictly a function of the query parameters, while the client's permissions simply determine whether a particular query should succeed or return a 401 error. Even if the results are entirely covered by the permissions of a client, the API will return an error if the request is not isolated to the proper entity, submitter, or both.

To query contributions, a client connects to the API server and requests the following URL:

GET /api/2009-08/contributions?q1=v1&q2=v2&...

... where q1=v1, q2=v2 and so on are conditions in the usual HTTP query string format. Again, at least one query parameter must restrict by page, destination, or express account.

Query results are limited to 500 contribution records. Add filters (for example a time filter) to get different records.

Request Parameters

Parameter Format Description
destination integer Restrict results to destination (entity). Requestor must have access to entity contribution report.
payment_timestamp [timestamp] / [timestamp] Restrict results to lineitems paid between two times, inclusive. Omit value prior to solidus to match all earlier times. Omit value following solidus to match all later times. Timestamps in ISO-8601 format.

Response Details

Parameter Description
contribution Provides useful information about a contribution
@order-number Unique, permanent identifier for the contribution
source Describes the person who made the contribution
firstname First name
lastname Last name
addr1 Mailing address
city Mailing address city
state Mailing address state
zip Mailing address ZIP code
country Mailing address country
occupation Occupation
employer Employer name
empaddr1 Employer address
empcity Employer address city
empstate Employer address state
empzip Employer address ZIP code
empcountry Employer address country
email Source email address
phone Source phone number
email-preferred True if donor prefers contact by email, false if source prefers contact by postal mail
recurringtimes Number of times this contribution is initially set to recur. This value does not change with time. Non-recurring contributions are indicated with 1.
refcode An opaque alphanumeric string that API clients or interactive users may use to segment contribution data.
lineitems Collection of donations to individual candidates or committees that are part of this contribution
lineitem A donation to an individual candidate or committee as part of a contribution
@effective-at ISO-8601 timestamp when payment was processed for this lineitem
amount The amount of the lineitem as two-place fixed demical (1.23) in dollars (USD).
sequence The sequence number of the lineitem. The first month of a recurring contribution generates lineitems with sequence 1. As each following month is processed, a new lineitem with an incremented sequence is added to the contribution.
entity Abbreviated representation of the lineitem's destination
@id The system ID for the destination entity
legalname The legal name (Obama for America) of the destination
displayname The display name (Barack Obama) of the destination
page Abbreviated XML for this contribution's form
@name Name (final URL component) of contribution form
title Page title
author Page author
user Contribution form owner
@user-key Unique user account identifier
email Email address
tickets For event pages, collection of tickets associated with contribution
ticket Individual ticket
type Name of the ticket type. Set by the contribution form owner.
amount Price of this ticket type, as two-place fixed demical (1.23) in dollars (USD). Set by the contribution form owner.
name Name of person on ticket, assigned by contributor
notes Freeform notes for this ticket, assigned by contributor