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 https://secure.actblue.com/api/2009-08/contributions
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:
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.
|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.|
|contribution||Provides useful information about a contribution|
|@order-number||Unique, permanent identifier for the contribution|
|source||Describes the person who made the contribution|
|city||Mailing address city|
|state||Mailing address state|
|zip||Mailing address ZIP code|
|country||Mailing address country|
|empcity||Employer address city|
|empstate||Employer address state|
|empzip||Employer address ZIP code|
|empcountry||Employer address country|
|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|
|user||Contribution form owner|
|@user-key||Unique user account identifier|
|tickets||For event pages, collection of tickets associated with contribution|
|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|