ActBlue helps individuals and organizations raise money for Democratic candidates and committees across the country. Since 2004, thousands of ActBlue fundraisers have raised in excess of $100 million dollars using our unique platform. ActBlue maintains a directory of eligible candidates and committees, securely handles donor credit cards, enforces campaign finance limits and eligibility requirements in all 50 states, and provides campaigns with real-time access to donor information.
Besides managing the flow of money from donors to committees, ActBlue offers a rich framework for allowing individuals and group to organize committees and track their contributions. Users may create contribution forms listing one or more candidates; these pages allow donors to contribute to many candidates in a single action. And individual donors can use a tell-a-friend tool to solicit contributions from their own circles.
This document describes the ActBlue API, which provides programmatic access to much of ActBlue's data. It includes an introduction to the our data model, XML specifications, and programming notes covering security and access control.
If you are using the API, we encourage you to join the ActBlue API Developers google group.
The ActBlue API covers three broad areas: entity information and contribution form management, access to public fundraising totals broken out in various ways, and access to detailed contribution records.
Donations made using ActBlue are stored as contributions from sources to entities. The contribution source contains the donor's name, address, employer, and other personal information. Contributions have one or more lineitems, akin to an item in a shopping cart, each of which specifies a date, a dollar amount, and the destination entity: a candidate or other political committee that accepts funds through ActBlue.
Entities representing candidates for office will refer to one or more candidacies, which in turn refer to a particular election (November 2006) for an office (Massachusetts Governor). Some entities, such as party committees, do not list any candidacies.
Like many websites, ActBlue.com has user accounts. Users are identified by email address or by an ActBlue-assigned key of 8 characters.
A contribution (more correctly a lineitem) relates these attributes: the entity, the candidacy, and the contribution form. These dimensions are collected into scoreboards, which for each combination describe the total number of contributors and the total dollar figure raised.
Fundraising pages include a scoreboard showing a grand total for the entire page, another breaking totals out by entity, and a third showing entity totals across the website as a whole. Entity hubs include a scoreboard showing a grand total for the entity, another breaking totals out by page, a third breaking out totals by candidacy, and a fourth breaking totals out by page and candidacy.
A contribution represents a donation made by a source to one or more entities. The contribution record includes a source, links to the contribution form, tickets, refcodes, and other items.
A contribution contains one or more lineitems, which each refer to an entity. Lineitems have four important components: the contribution they belong to, an entity, a sequence number, and a dollar amount. They also have a timestamp.
Recurring contributions are presented as a single contribution whose lineitems span multiple dates. The sequence number indicates which recurrence, beginning with 1.
See the Contribution API Specification for the XML schema and allowed query attributes.
Entities represent the destination of all contributions in the system. For example, a campaign is an entity.
All entities have an ID number. Each entity ID number is an integer that is unique to that entity. You will use the entity ID number any time you reference an entity while using the API. If you need help determining an entity ID number, please contact ActBlue.
API clients can retrieve information about entities. See the Entity API Specification for more information.
Sources are individual donor records stored in the system. They are the originator of all funds sent through ActBlue.
You cannot query for specific sources uing the API, but a source will be returned in each contribution record.
Optionally, a contribution may be credited to a page, which is a way of tracking who is responsible for a given action. Pages are generally visible to the public on the website.
Each page can have multiple entities on it. When an entity is on a page it will be listed in the page XML as a Listentry. Entities can be added or removed at any time by the page owner.
Each page has a Name which is visible on the website as the last URL component. The Name can be changed at any time by the page owner
See the Page API Specification for the XML schema and allowed query attributes.
Queries for entities and for public pages are available to any valid ActBlue account, without any particular access requirement. Please note that a valid account must be specified with the request -- The ActBlue API does not permit any form of anonymous API access.
Clients using authenticated APIs must supply a username/password pair with each request, using HTTP's standard basic-auth facility, and connect over SSL to secure.actblue.com. Access to the API is controlled with username/password pairs indentical to those used to log in to ActBlue interactively. (In production, typically API clients will create an account to be used exclusively for API access, but this is not strictly necessary.) You may create a username and password by signing up for an ActBlue 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.
The authenticated 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/...Examples of ActBlue API calls using
curl \ --user-agent "YourBot/1.0 +http://example.com/about-your-bot" \ --user "email@example.com:password" \ --header "Accept: application/xml" \ "https://secure.actblue.com/api/2009-08/pages/page_name" curl \ --user-agent "YourBot/1.0 +http://example.com/about-your-bot" \ --user "firstname.lastname@example.org:password" \ --header "Accept: application/xml" \ "https://secure.actblue.com/api/2009-08/contributions?destination=1234" curl \ --user-agent "YourBot/1.0 +http://example.com/about-your-bot" \ --user "email@example.com:password" \ --header "Accept: application/json" \ "https://firstname.lastname@example.org"
API clients may use the query service to request various subsets of contributions from the ActBlue system. If the query result is compatible with the client's query rights, it is returned. If not, ActBlue returns a 401 Unauthorized Access error.
When requesting particular contribution records, results are limited by the permissions of the API account holder. Records associated with a contribution form, for example, are restricted to the account of the page's owner. Records associated with an entity are visible only to accounts that have been specifically authorized to access that entity. Contributions submitted by API key may always be retrieved by the same API key.
It is important to note that 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, ActBlue will return an error if the request is not isolated to the proper entity, submitter, or both.
Current Version: 2009-08