The ActBlue API

Current Version: 2009-08 (DRAFT)

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 fundraising pages listing one or more candidates; these pages allow donors to contribute to many candidates in a single action. Pages themselves can be organized into partnerships, allowing a larger organization to manage a community of fundraisers. 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 data model

Introduction

The ActBlue API covers three broad areas: entity information and fundraising page 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 committee.

Donations made using ActBlue are stored as contributions from sources to entities. A source represents an individual donor. It contains a donor's name, address, employer, and other personal information. An entity represents 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.

ActBlue allows users to create a fundraising page listing one or more entities.

A group of fundraising pages may be collected into a partner. Partnerships are managed by one or more authorized users, who have access to all fundraising pages belonging to the partnership. Those users have access to the list of contributions made through any page in the partnership. Partnership administrators also have the ability to modify fundraising pages that belong to the partnership.

Like many websites, ActBlue.com has user accounts. Users are identified by email address or by an ActBlue-assigned key of 8 characters.

Public contribution totals

A contribution (more correctly a lineitem) relates four attributes: the entity, the candidacy, the fundraising page, and the partnership. These four 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.

Details

A contribution represents a donation made by a source to one or more entities. The contribution record includes a source, links to the fundraising page, partnership, 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

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

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.

Fundraising Pages

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.

Partnerships

A set of pages may be gathered into a partner. A partnership is an umbrella account that groups certain pages. A page can only be a member of one partnership at any one time.

If a contribution was made on a page that was part of a partnership, the contribution's XML will reflect the partner relationship. Likewise, when querying pages, if a page is a member of a partnerhip this relationship will be reflected in the returned page XML.

Scoreboards

Connecting to the XML API

Public APIs

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.

Authenticated APIs

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/...
An example command line ActBlue API call using curl is shown below.
    curl -k --user user@domain.com:password    \
    --header "Accept: application/xml"     \
    "https://secure.actblue.com/api/2009-08/contributions?page=pagename"

Permissions

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 fundraising page, 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.

Pages API

API clients may create and modify fundraising pages. All pages that are created are owned by the API user.

To create a new fundraising page, POST the XML payload for a fundraising page to /pages. On success, ActBlue will return 201 Created with the fundraising page XML as its payload. Pages must specify a name, title, and author. The name must not already by used by another page. Pages default to a blank blurb and visible status -- either of these attributes may be optionally present in the XML payload. If the page is to include entity blocks, the page XML must contain one or more listentry stanzas.

If the page is invalid, ActBlue returns 403 Forbidden with an error stanza.

To update an existing page, PUT a replacement payload to /pages/pagename. If successful, ActBlue returns 200 OK and echoes the page XML. If the API user is not the owner of the page, ActBlue will return 401 Unauthorized. If the payload is invalid, ActBlue returns 403 Forbidden with error stanzas.

Examples

To return the public API description of an entity with an entity ID of 1245:

    curl -k --user user@domain.com:password    \
    --header "Accept: application/xml"     \
    "https://secure.actblue.com/api/2009-08/entities/1245"

To return all contributions for an entity with an entity ID of 1245:

    curl -k --user user@domain.com:password    \
    --header "Accept: application/xml"     \
    "https://secure.actblue.com/api/2009-08/contributions?destination=1245"

To return all contributions for a page with a name of joespage:

    curl -k --user user@domain.com:password    \
    --header "Accept: application/xml"     \
    "https://secure.actblue.com/api/2009-08/contributions?page=joespage"

To return contributions under $100 for an entity with an entity ID of 1245:

    curl -k --user user@domain.com:password    \
    --header "Accept: application/xml"     \
    "https://secure.actblue.com/api/2009-08/contributions?destination=1245&amount=/100.00"