Developer API Documentation

Version 0.1.2

1: Blue State Digital Trusted API

1.1: Overview

1.2: Common Record Formats

Certain types of data are returned by multiple API requests. These record formats are defined below. (note: All times returned by the API will be in the system timezone)

Error messages

Generic Graph API Errors

Error messages from the graph API will have error and error_description fields in their JSON response. Here is an example of an error caused by accessing a Graph page that requires HTTPS over an insecure connection:

{ "error":"invalid_request", "error_description":"Secure connection required" }
Permission denied

This error is returned when the Graph page requires the requester to be authenticated and they are not, or is for a resource that the authenticated user does not have permissions to.

{ "error":"permission_denied", "error_description":"You must be logged in to view this information" }
Rate limit exceeded

This error is returned when a user or IP address has exceeded the allowed rate limit for requests.

{ "error":"rate_limit_exceeded", "error_description":"Too many requests" }
Invalid parameters

This error is returned when the request is missing a required parameter, or one or more of the supplied parameters are invalid.

{ "error":"invalid_parameters", "error_description":"The path parameter 'foo' is required" }

Exported JSON Circle Records

Core: circle

The core circle record contains the circle's slug, name, description, circle type, member count, and creation and modified dates:

{ "slug":"test slug", "name":"test circle #1", "description":"description for circle #1", "circle_type":0, "member_count":1, "create_dt":"2008-10-10 11:14:50", "modified_dt":"2008-10-11 18:10:13" }

1.3: Common Query Parameters

Every Graph API request, unless otherwise noted, supports certain common query parameters.

callback

callback is an optional parameter that specifies the name of a JavaScript function to use as the JSON-P wrapper for the returned data. It implicitly makes the request a JSON-P request.

Example:

?callback=my_func
my_func({ "data":[ { "slug":"slug2", "name":"test circle #2", "description":"description for circle #2", "circle_type":0, "member_count":5, "create_dt":"2008-10-10 11:14:50", "modified_dt":"2008-10-11 18:10:13" } ] });

1.4: Graph API Reference

Circle Graph API

/circles/by_zip/$zip/$radius

Lists all circles within a given radius of a given center point, specified as a zip code (U.S. assumed). Results can also be filtered to be in a specific state by passing a state_cd query parameter.

Method: GET

URL: /page/graph/circles/by_zip/$zip/$radius

Path Parameters:

zip (required)
The U.S. zip code to use as a center for the radius search.
radius (required)
The distance to search from the center of zip.

Returns:

Returns one circle element (see Common Record Formats) for each circle that matches the radius search. In addition to the core record, each element also contains a distance element for the distance from the center point. The results are sorted by distance from closest to farthest.

Example:

http://XYZ/page/graph/circles/by_zip/12345/20
{ "data":[ { "slug":"slug2", "distance":1.5, "name":"test circle #2", "description":"description for circle #2", "circle_type":0, "member_count":5, "create_dt":"2008-10-10 11:14:50", "modified_dt":"2008-10-11 18:10:13" } ] }

Errors:

This request can return a rate_limit_exceeded error, or an invalid_parameters error if the zip code is invalid or the zip or radius path parameters are missing.

Constituent Graph API

/me/circles

Lists all circles that the currently-logged in constituent is a member of. If the requester is not logged in to the BSD Tools, then an access error is returned.

Method: GET

URL: /page/graph/me/circles

Returns:

Returns one circle element (see Common Record Formats) for each circle the currently logged in constituent is a member of.

Example:

http://XYZ/page/graph/me/circles
{ "data":[ { "slug":"test slug", "name":"test circle #1", "description":"description for circle #1", "circle_type":0, "member_count":1, "create_dt":"2008-10-10 11:14:50", "modified_dt":"2008-10-11 18:10:13" }, { "slug":"slug2", "name":"test circle #2", "description":"description for circle #2", "circle_type":0, "member_count":5, "create_dt":"2008-10-10 11:14:50", "modified_dt":"2008-10-11 18:10:13" } ] }

Errors:

This request can return a rate_limit_exceeded error, or a permission_denied error if there is no currently logged-in constituent.

Event RSVP Graph API

/graph/addrsvp

Allows creation or editing/overwriting of an individual RSVP to either a single event or multiple days of a single event, with or without shifts. event_id, will_attend, and either a guid or both an email address and zip are required for all adds.

Example with minimal information (guid):

/page/graph/rsvp/add?event_id=6&will_attend=1&guid=HASH

Alternate example with minimal information (email & zip):

/page/graph/rsvp/add?event_id=6&will_attend=1&email=hlevitin@bluestatedigital.com&zip=02210

Days of a multi-day event are specified by a coma-separated list in the event_id parameter. The api assumes the RSVP-er is not attending any day of a multi-day event not specified in the an RSVP to another day of the event, and automatically sets will_attend to 0 for upspecified days. The event in the example below lasts a full week, but the cons will attend exactly two day of the seven days.

Example of multiday event:

/page/graph/rsvp/add?event_id=10,11&will_attend=1&guid=HASH

Results in:

event_id9101112131415
will_attend0110000

shift_ids is simillarly specified by a comma-separted list and required for all shifted events.

If the shift_ids parameter is present, the guests parameter must be a comma-separated list with the same number of comma-separated elements. Each item in a coma-separated guests list coresponds to the elsement of shift_ids in the same position. The following example represents an rsvp to shift_ids 5, 8, and 9. The attendee will have 2 guests for shift_ids 5 and 8, and 3 guests for shift_ids 9.

Example of multiple shifts with guests:

/page/graph/rsvp/add?event_id=6&will_attend=1&guid=HASH&shift_ids=5,8,9,4&guests=2,2,0,2

If shift_ids is not present, the guest parameter matches the event_id parameter in the same way.

Example of multiday event:

/page/graph/rsvp/add?event_id=10,11&will_attend=1&guid=HASH&guests=0,1

Method: GET/POST

URL: /page/graph/rsvp/add?event_id=$event_id&will_attend=1& ...(etc. for all query parameters)

Required Parameters:

event_id (required)
Unique integer id of event. Must be specified as a comma-separated list for multiday events.
will_attend (reqired)
Boolean. 1 if RSVPer and his or her guests are attending, 0 if not. To cancel an RSVP, set will_attend=0.
guid (required unless both email and zip given)
Unique, encrytped cons_id
email (required unless GUID given)
Attendee's valid email address.
zip (required unless GUID given)
The U.S. zip code of the attendee's residence
shift_ids (required for shifted events)
Id(s) of shifts attending. Multiple shifts may be specified by a coma separated list.
phone (required if is_potential_volunteer=1)
Contact phone number.

Additional Parameters

addr1
Address line 1.
addr2
Address line 2.
addr3
Address line 3.
city
Attendee's city of residence.
comment
Comment to accompany rsvp on the event's page
country
Attendee's country of residence.
firstname
The attendee's first name.
guests
Number of guests to accompany the attendee. Does not include the attendee (so an RSVP-er coming alone would have guests=0). Comma separated list when multiple shifts or multiple days to be attended. For shifted events, each comma separated element corresponds the element in the same position in shift_ids. For multiday, unshifted events, each comma-separated element correspons to the element in the same position in event_id.
is_potential_volunteer
Is the attendee willing to volunteer for the event
is_reminder_sent
Has a reminder email been sent to the attendee
lastname
The attendee's last name.
pledge_amt
Amount pledged with RSVP
pledge_method
Method in which contribution will be made
state_cd
Two letter state code.
zip_4
Four digit ext. to zip

2: Blue State Digital XML API

2.1: Overview

The Blue State Digital API allows external access to data and functionality inside the Blue State Digital system. The API follows many REST design principles and can be accessed from any common web programming environment, including PHP, Ruby, Perl, Python, and .NET.

All API calls use either an HTTP GET or POST request. Some calls support both methods. In addition to the call-specific parameters, all API calls need to include four additional parameters (api_id, api_ts, api_mac, and api_ver), which are be used to validate the API request. These are documented in the Common API Parameters section below.

API calls will return standard HTTP error codes to indicate success or failure of a request. If a request fails, a message will be included in the failure providing a detailed reason for the failure. Different calls have different return formats on success. Some return XML or JSON, some simply numbers or strings. See the documentation for the API call to determine returned data format.

2.2: Common API Parameters

For security, all API calls will require an api_id, api_ts, and api_mac parameter. These serve to authenticate the request. The api_id parameter is configured via the Blue State Digital Control Panel. Each api_id has a corresponding api_secret associated with it. This api_secret is used to calculate the api_mac for a given request. The api_secret is stored on the server making the API call and is never sent over the network as part of an API request.

It is STRONGLY recommended that you issue a separate api_id/api_secret for each external application that will be accessing the API.

Parameters:

api_id
the API ID for this request
api_ts
Current time in epoch seconds. This must match the epoch seconds value used to calculate the api_mac. It is important that the server sending the request stay keep its clock up-to-date using ntpd. The BSD server will disallow any request that has a timestamp which is more than 30 seconds older or newer than the BSD server's current time.
api_mac
The message authentication code (MAC) for the request. See the Understanding the api_mac section for details on how to get this value.
api_ver
The version of the API that client code will work with. This allows changes to be made to the API without causing backwards compatibility issues.

These four common API parameters are ALWAYS included in the URL, even if the actual API call uses the POST method.

2.3: Deferred Results

Certain API functions may not return results right away. If the requested API call is too time consuming, it may return an HTTP response code of 202 (Accepted). The body of the response will contain a single, 32-byte string (the deferred_id). This ID can be used to retrieve the results when they are ready. The API documentation clearly indicates which calls may return deferred results. Any code that uses these calls MUST be capable of handling the deferred result set. The get_deferred_results function is used to retrieve the result set.

The following pseudo-code shows how to retrieve deferred results inline with the code making the initial API call. Of course, depending on how long the API call takes to return the results and the nature of your program, you may not want to have your code block while polling for results.

$response_obj = make_api_call( "some_call_that_defers", "some=param&some_other=param"); if ($response_obj.get_status_code() == 202) { // we were deferred $deferred_id = $response_obj.get_response_body(); do { sleep(30); $response_obj = make_api_call( "get_deferred_results", "deferred_id=".$deferred_id); } while ($response_obj.get_status_code() == 503); } $actual_result = $response_obj.get_response_body();

If you make extensive use of API calls which may defer their results, you may consider using the above code on all of your API calls to save yourself the effort of implementing support in each location where you make a call. It should do the right thing whether the API call defers its results or not.

Deferred Result Callbacks

Instead of polling, you can also choose to have the API "call you back" when a deferred request is ready. In this case, when the deferred request completes, the API will make an HTTP POST request to the URL you have provided as the callback URL, with the POST body containing only the 32 character deferred id. You then proceed to use get_deferred_results as normal to retrieve the results of your call.

Callback URLS cannot be behind HTTP authentication or require any more authentication than they carry in their URL parameters, as the API will not know how to authenticate them and will not make anything more than a basic POST request to the supplied URL.

To use a deferred result callback, pass the deferred_callback parameter in your API request:

deferred_callback
the URL to call back to when this request is completed and ready for pickup

Deferred Results API Calls

get_deferred_results

Allows software to retrieve the results of a previously requested API call that was deferred (see the Deferred Results section for details).

Method: GET

URL: /page/api/get_deferred_results

Parameters:

deferred_id (required)
The ID string (32 characters) provided in response to a previous API call that was deferred.

Returns:

If the results are ready, returns the HTTP status code and response body for the original API call. Note that, once retrieved, the results are deleted from the system and are no longer available.

If the results are not yet ready, an HTTP status code 503 (Service Unavailable) is returned. This indicates that you should try back later to retrieve your results.

If the results have already been retrieved (and are therefore no longer available in the system), the HTTP status code 410 (Gone) is returned.

If there is no content to deliver, a 204 (No Content) is returned.

Deferred Results: Never

Example:

http://XYZ/page/api/cons/get_constituents_by_id?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&ext_type=van_id&ext_ids=12772,1129,1983321

2.4: Common Record Formats

Certain types of data are returned by multiple API calls. These record formats are defined below. (note: All times returned by the API will be in the system timezone)

Exported XML Circle Records

Core: circle

The core circle record contains the name, slug, description, circle type, member count and creation date:

<circle id="1" modified_dt="1223651690"> <name>test circle#1</name> <slug>test_slug</slug> <description>description for circle #1</description> <create_dt>2008-10-10 11:14:50</create_dt> <circle_type>0</circle_type> <member_count>0</member_count> </circle>

Exported XML Constituent Records

The constituent record is the basic identifier of a person. The core constituent record is remarkably slim, containing only the most basic information about a person (name and whether they have an account). When making an API call that returns a constituent record, you can specify one or more data bundles that enhance the constituent record with additional data. Both the core constituent record and each data bundle contain a modified_dt attribute. This contains the date and time (in epoch seconds) when a record (or bundle) was last modified.

Bundles are added to each <cons> XML element. If there a bundle has more than one data element associated with it, all elements will be included inside the <cons> XML element. For example, using the cons_addr bundle for a person with two addresses would result in two <cons_addr> elements inside their <cons> element.

Core: cons

The core constituent record contains only the GUID, name, account status, and account creation date:

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <middlename>Reginald</middlename> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <suffix>III</suffix> <prefix>Mr</prefix> <gender>M</gender> </cons>

All other information is added via data bundles.

Data Bundle: circle

The circle bundle provides information about all of the circles that a person is a member of.

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <circle id="2"> <name>People for Mr. Smith</name> <url>http://www.example.com/page/group/Smith</url> <joined_dt>1168146011</joined_dt> <is_private>0</is_private> <is_admin>1</is_admin> </circle> <circle id="43"> <name>Unions for Unions</name> <url>http://www.example.com/page/group/UfU</url> <joined_dt>1168146011</joined_dt> <is_private>1</is_private> <is_admin>0</is_admin> </circle> </cons>
Data Bundle: community_journal

The community_journal bundle provides information about a person's community blog participation. If a journal exists but does not contain any posts first_post_dt, latest_post_dt, and num_posts will return zero. If the journal posts (if any exist) do not have any comments first_comment_dt, latest_comment_dt, and num_comments will return zero.

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <community_journal id="45"> <url>http://www.example.com/page/community/blog/bob</url> <rss_url>http://www.example.com/page/community/blog_rss/bob</rss_url> <first_post_dt>1171861200</first_post_dt> <latest_post_dt>1208394744</first_post_dt> <num_posts>11</num_posts> <first_comment_dt>1171891200</first_comment_dt> <latest_comment_dt>1208394764</latest_comment_dt> <num_comments>243</num_comments> </community_journal> </cons>
Data Bundle: cons_addr and primary_cons_addr

The cons_addr and primary_cons_addr data bundles add address information to a constituent record. cons_addr will add zero or more address elements. primary_cons_addr will add zero or one address elements, choosing the most recently added address as the primary one. Example (with one address):

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_addr id="5733" modified_dt="1168146001"> <addr1>123 Fake St.</addr1> <addr2></addr2> <city>Anytown</city> <state_cd>CA</state_cd> <zip>92345</zip> <zip_4>8311</zip_4> <country>US</country> <is_primary>1</is_primary> <latitude>42.000</latitude> <longitude>71.000</longitude> </cons_addr> </cons>
Data Bundle: cons_email and primary_cons_email

The cons_email and primary_cons_email data bundles add email addresses to a constituent record. cons_email will add zero or more elements. primary_cons_email will add zero or one email elements, choosing the most recently added email address as the primary one. Example (with two email addresses):

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_email id="8991" modified_dt="1168146011"> <email>bsmith@somecompany.com</email> <email_type>work</email_type> <is_subscribed>0</is_subscribed> <is_primary>0</is_primary> </cons_email> <cons_email id="12702" modified_dt="1178510447"> <email>bob_smith@someisp.com</email> <email_type>personal</email_type> <is_subscribed>1</is_subscribed> <is_primary>1</is_primary> </cons_email> </cons>
Data Bundle: cons_field

The cons_field data bundle adds custom constituent fields to a constituent record. cons_field will add zero or more elements. Example (with two custom constituent fields):

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_field id="176"> <value>custom value 0</value> </cons_field> <cons_email id="177"> <value>custom value 1</value> </cons_field> </cons>
Data Bundle: cons_friends

The cons_friends bundle provides information about a person's socialnet relationships. If the constituent has any consummated socialnet relationships, then the socialnet element will contain one or more friend elements.

<cons id="4382"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <socialnet> <friend id="5321"> <invite_dt>1189111883</invite_dt> <consummated_dt>1189115528</consummated_dt> </friend> </socialnet> </cons>

Attribute Definitions:

id
integer
Data Bundle: cons_group

The cons_group bundle provides information about a person's constituent group membership.

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_group id="17" modified_dt="1168146011"/> <cons_group id="41" modified_dt="1163196031" /> </cons>
Data Bundle: cons_phone and primary_cons_phone

The cons_phone and primary_cons_phone data bundles add phone numbers to a constituent record. cons_addr will add zero or more elements. primary_cons_phone will add zero or one phone number elements, choosing the most recently added phone number as the primary one. Example (with two phone numbers):

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_phone id="6933" modified_dt="1168146030"> <phone>4082345678</phone> <phone_type>home</phone_type> <is_primary>0</is_primary> <is_subscribed>0</is_subscribed> </cons_phone> <cons_phone id="7322" modified_dt="1173243602"> <phone>4089876432</phone> <phone_type>mobile</phone_type> <is_primary>1</is_primary> <is_subscribed>1</is_subscribed> </cons_phone> </cons>
Data Bundle: event

The event bundle provides information about a person's event participation.

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <event> <num_attended>3</num_attended> <first_attended_dt>1163146011</first_attended_dt> <latest_attended_dt>1168147011</latest_attended_dt> <num_created>1</num_created> <first_created_dt>1168146011</first_created_dt> <latest_created_dt>1168146020</latest_created_dt> <attended_rss_url>http://www.example.com/page/events/</attended_rss_url> <created_rss_url>http://www.example.com/page/events/</created_rss_url> </event> </cons>
Data Bundle: ext_X

The ext_X bundle allows the inclusion of external IDs (as set with the set_ext_ids API call). X is to be replaced with the external ID type specified on the set_ext_ids call. The following example assumes that a data bundle of ext_van_id was specified and that an external ID of type van_id had been specified for the resulting constituent record:

<cons id="4382" modified_dt="1171861200"> <guid>ygdFPkyEdomzBhWEFZGREys</guid> <firstname>Bob</firstname> <lastname>Smith</lastname> <has_account>1</has_account> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <ext_id type="van_id" id="My_Ext_id_381128342" modified_dt="1168146011"/> </cons>

Incoming XML Constituent Records

The API allow for incoming bundle data in similar formats to outgoing data, with several changes for IDs. Incoming data must be encoded as UTF-8.

Core: cons

The core constituent record contains only the name, account status, and account creation date (GUID cannot be set by an external call; it will be generated when the constituent is created:

<cons id="4382" ext_id="ext_20034" ext_type="client_system"> <firstname>Bob</firstname> <lastname>Smith</lastname> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> </cons>

In incoming data, the id, ext_id, and ext_type attributes are optional. The following rules apply to these attributes:

  • If a record has an id attribute, it will be rejected if that id does not match.
  • If it has no id, ext_id, or ext_type attributes, it will be added.
  • If ext_id or ext_type are specified but not both, the record will be rejected.
  • If ext_id and ext_type are specified specified, the record will be added or updated depending on if the ext_id/ext_type combination provides a mapping to an existing constituent record. If the record is added, the ext_id/ext_type mapping will be added also.

Field Definitions:

firstname:
string, up to 128 characters
lastname:
string, up to 128 characters
is_banned:
integer, 0 or 1
create_dt:
unix timestamp
ext_id:
string, up to 255 characters
ext_type:
string, up to 100 characters

All other information is added via data bundles.

Data Bundle: cons_addr and primary_cons_addr

The cons_addr and primary_cons_addr data bundles add address information to a constituent record in BSD's database. cons_addr will add zero or more address elements. primary_cons_addr will add zero or one address elements, choosing the most recently added address as the primary one. Incoming cons_addr records do not contain IDs; they are automatically associated with the cons record they are nested in. Example (with one address):

<cons id="4382"> <firstname>Bob</firstname> <lastname>Smith</lastname> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_addr> <addr1>123 Fake St.</addr1> <addr2></addr2> <city>Anytown</city> <state_cd>CA</state_cd> <zip>92345</zip> <zip_4>8311</zip_4> <country>US</country> <is_primary>1</is_primary> <latitude>42.000</latitude> <longitude>71.000</longitude> </cons_addr> </cons>

Field Definitions:

addr1:
string, up to 255 characters
addr2:
string, up to 255 characters
city:
string, up to 64 characters
state_cd:
string, 2 characters
zip:
string, up to 16 characters
zip_4:
string, up to 4 characters
country:
string, two characters
is_primary:
integer, 0 or 1
Data Bundle: cons_email and primary_cons_email

The cons_email and primary_cons_email data bundles add email addresses to a constituent record. cons_email will add zero or more elements. primary_cons_email will add zero or one email elements, choosing the most recently added email address as the primary one. Incoming cons_email records do not contain IDs; they are automatically associated with the cons record they are nested in. Example (with two email addresses):

<cons id="4382"> <firstname>Bob</firstname> <lastname>Smith</lastname> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_email> <email>bsmith@somecompany.com</email> <email_type>work</email_type> <is_subscribed>0</is_subscribed> <is_primary>0</is_primary> </cons_email> <cons_email> <email>bob_smith@someisp.com</email> <email_type>personal</email_type> <is_subscribed>1</is_subscribed> <is_primary>1</is_primary> </cons_email> </cons>

Field Definitions:

email:
string, up to 128 characters
email_type:
constant string, personal or work
is_subscribed:
integer, 0 or 1
is_primary:
integer, 0 or 1
Data Bundle: cons_group

The cons_group bundle provides information about a person's constituent group membership.

<cons id="4382"> <firstname>Bob</firstname> <lastname>Smith</lastname> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_group id="17" /> <cons_group id="41" /> </cons>

Attribute Definitions:

id:
integer
name:
string, up to 255 characters
Data Bundle: cons_phone and primary_cons_phone

The cons_phone and primary_cons_phone data bundles add phone numbers to a constituent record. primary_cons_phone will add zero or one phone number elements, choosing the most recently added phone number as the primary one. Incoming cons_phone records do not contain IDs; they are automatically associated with the cons record they are nested in. Example (with two phone numbers):

<cons id="4382"> <firstname>Bob</firstname> <lastname>Smith</lastname> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_phone id="6933" modified_dt="1168146030"> <phone>4082345678</phone> <phone_type>home</phone_type> <is_primary>0</is_primary> <is_subscribed>0</is_subscribed> </cons_phone> <cons_phone id="7322" modified_dt="1173243602"> <phone>4089876432</phone> <phone_type>mobile</phone_type> <is_primary>1</is_primary> <is_subscribed>1</is_subscribed> </cons_phone> </cons>

Field Definitions:

phone:
string, up to 30 characters
phone_type:
constant string, home, work, mobile, fax, unknown, or empty
is_primary:
integer, 0 or 1
is_subscribed:
integer, 0 or 1
Data Bundle: ext_X

The ext_X bundle allows the inclusion of external IDs (as set with the set_ext_ids API call). X is to be replaced with the external ID type specified on the set_ext_ids call. The following example assumes that a data bundle of ext_van_id was specified and that an external ID of type van_id had been specified for the resulting constituent record:

<cons id="4382"> <firstname>Bob</firstname> <lastname>Smith</lastname> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <ext_id type="van_id" id="vfgw3811wf28342" /> </cons>

Attribute Definitions:

type:
string, up to 100 characters
id:
string, up to 255 characters

Exported XML Constituent Group Records

Constituent groups are sets of constituents with some common attribute or grouping. The core constituent group is small, similar to the core constituent record. Also like the core constituent record, the constituent group record contains a modified_dt attribute. This contains the date and time (in epoch seconds) when a constituent group (or its membership) was last modified.

Core: cons_group

The core constituent group record contains only the name, slug, group_type, and description.

<cons_group id="42" modified_dt="1171861200"> <name>First Quarter Donors</name> <slug>q1donors</slug> <description>People who donated in Q1 2007</description> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <group_type>manual</group_type> <members>162</members> <unique_emails>164</unique_emails> <unique_emails_subscribed>109</unique_emails_subscribed> <count_dt>1213861583</count_dt> </cons_group>

Incoming XML Constituent Group Records

The API allow for incoming constituent group data in similar formats to outgoing data. Incoming data must be encoded as UTF-8.

Core: cons_group

The core constituent group record contains only the name, slug, group type, and description.

<cons_group> <name>Third Quarter Fundraisers</name> <slug>q3fundraisers</slug> <description>People raising money for Q3 2007</description> <group_type>manual</group_type> <create_dt>1168146000</create_dt> </cons_group>
  • In incoming data, no id is specified. The cons_group_id that was assigned to the new group is returned on successful requests.
  • slug is optional; the default is no slug.
  • description is optional; the default is no description.
  • group_type is optional; the default is "manual".
  • create_dt is optional; the default is the current time.

Field Definitions:

name:
string, up to 255 characters
slug:
string, up to 32 characters
description:
text
group_type:
string, up to 32 characters
create_dt:
unix timestamp

Exported XML Signup Form Records

Core: count_by_field

The core count_by_field record contains the number of constituents that filled out a certain signup form field:

<signup_form_field> <value>form_value2</value> <count>2</count> </signup_form_field>
Core: signup_count

The core signup_count record contains the only the number of constituents that matched the query:

<count>6</count>
Core: signup_form

The core signup_form record contains the signup_form_name, slug, public title, and creation date:

<signup_form id="1" modified_dt="1267728690"> <signup_form_name>Default Signup Form</signup_form_name> <signup_form_slug>slug</signup_form_slug> <form_public_title>public title</form_public_title> <create_dt>2010-02-08 18:33:11</create_dt> </signup_form>
Core: signup_form_field

The core signup_form_field record contains the label, description, display_order, is_shown, is_required, is_custom_field, cons_field_id, and creation date:

<signup_form_field id="84"> <label>Last Name</label> <description>Last Name</description> <display_order>1</display_order> <is_shown>1</is_shown> <is_required>0</is_required> <is_custom_field>0</is_custom_field> <cons_field_id>0</cons_field_id> <create_dt>2010-02-08 18:33:11</create_dt> </signup_form_field>

Exported XML Wrapper Records

Core: wrappers

The core wrapper record contains the name, description, and creation date:

<wrapper id="1" modified_dt="1265250882"> <name>default wrapper</name> <description>This is the default wrapper</description> <create_dt>2010-02-04 02:34:42</create_dt> </wrapper>

JSON Event Blobs

Event: list_rsvps

An HTTP response code and a JSON array of objects, each of which represents an an RSVP (ie one row of the event_attendee table). The response will contains the all available parameters from the internal representaion of the attendee. A field's value is the empty string or null if it has not been set.

HTTP/1.0 200 OK date: Sun, 08 Jan 2012 16:46:51 GMT content-length: 1533 content-type: application/json; charset=utf-8 connection: close server: Apache/2.0.63 (Unix) mod_ssl/2.0.63 OpenSSL/0.9.8e-fips-rhel5 { "attendees": [ { "addr1": null, "addr2": null, "addr3": null, "attendee_cons_id": "12", "city": "winnetka", "comment": null, "country": null, "email": "hlevitin@bluestatedigital.com", "event_id": "11", "firstname": "Hanna", "guests": "0", "is_potential_volunteer": "0", "is_reminder_sent": "0", "lastname": null, "phone": null, "pledge_amt": null, "pledge_method": null, "shift_ids": "", "state_cd": "IL", "will_attend": "0", "zip": "60093", "zip_4": null } ] }

Bundle Specification

Most API calls that return constituent records have an optional bundles parameter. This parameter allows you to specify which data bundles you want included in the result set. Bundle names are separated by commas. If a bundle is required (e.g. constituent records without any data for that bundle should not be returned at all), the bundle name should have an asterisk appended to it.

The following bundles parameter would include all address, phone, email information, and an activist score for each constituent:

cons_addr,cons_phone,cons_email

The following bundles parameter would include all address, phone, and email information for each constituent, but would exclude any constituent records that did not have a phone number:

cons_addr,cons_phone*,cons_email

Filter Specification

Some constituent API calls can also take a filter parameter. This allows you to further limit the records returned by a particular API call. Filter parameters take the form of a comma-separated list of logical tests. These tests are ANDed together. Most logical tests involve an operator (=, >, <). Some Boolean tests have no operator and no right hand side.

If the = operator is used, multiple values can be specified on the right hand side of the logical test by separating them with commas and enclosing them in parentheses.

Note that the filter mechanism is not intended to provide sophisticated query building capabilities. Rather, it's purpose is to reduce the size of a result set to be more manageable. Further filtering and querying can be done by the code making the API call after the larger result set has been received and processed.

The following criteria are supported in a filter specification.

state_cd
Description:
The constituent has at least one address record in the state(s) specified.
Supported operators:
=
Example:
state_cd=(IA,NV,NH,SC)
primary_state_cd
Description:
The constituent's primary address record is in the state(s) specified.
Supported operators:
=
Example:
primary_state_cd=IA
is_subscribed
Description:
The constituent has at least one email address that is marked as subscribed.
Supported operators:
None
Example:
is_subscribed
has_account
Description:
The constituent has a login account/password set up.
Supported operators:
None
Example:
has_account
has_mobile_phone
Description:
The constituent has a mobile phone number.
Supported operators:
None
Example:
has_mobile_phone
signup_form_id
Description:
The constituents have filled out the signup form specified.
Supported operators:
=
Example:
signup_form_id=18
email
Description:
The constituent's email matches the email specified.
Supported operators:
=
Example:
email=username@gmail.com

The following example filter would return only constituent records in the state of California or Nevada that had a subscribed email address:

state_cd=(CA,NV),is_subscribed

Because filters contain the = sign and other characters which have significance in URLs, they must be encoded when being specified as a API call parameter. The above example when used in a URL and properly encoded, might look like:

http://XYZ/page/api/foo?filter=state_cd%3D%28CA%2CNV%29%2Cis_subscribed&api_id=X&api_mac=Y&api_ts=N

2.5: API Reference

Account API Calls

check_credentials

Allows a client to send user credentials to the API and see if those credentials are valid. If valid, the API will return a constituent record.

Important: because of the sensitive nature of accounts and passwords, this API method must always be accessed over HTTPS.

Method: GET or POST

URL: /page/api/account/check_credentials

Parameters:

userid (required)
The email address of the user to check
password (required)
The user's password

Returns:

Returns a constituent record with primary_cons_email and primary_cons_addr bundles if successful (see the Common Record Formats section for details). If not, HTTP status code 403 Forbidden returned.

Please note that the authentication checks are rate limited by IP address and userid. Three unsuccessful logins will lock the user/IP from any attempts for 30 seconds.

Deferred Results: Never

Example:

https://XYZ/page/api/account/check_credentials?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&userid=user1%40domain.com&password=password1
create_account

This method allows creating a new frontend user account. If a user with the same email already exists, the system will check to see if the submitted password matches the existing password. If it does, the existing constituent record will be returned. Otherwise an error will be returned noting the email address as already taken.

Important: because of the sensitive nature of accounts and passwords, this API method must always be accessed over HTTPS.

Method: GET or POST

URL: /page/api/account/create_account

Parameters:

firstname (required)
The user's first name
lastname (required)
The user's last name
email (required)
The user's email address. This will also be their username.
password (required)
The password to set for the new account
zip (required)
The user's zip or postal code

Returns:

Returns the new or existing constituent record with primary_cons_email and primary_cons_addr bundles (see the Common Record Formats section for details).

Deferred Results: Never

Example:

https://XYZ/page/api/account/create_account?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&firstname=joe&lastname=user&email=joe%40example.com&password=******&zip=01234
reset_password

Allows a client to request that a user's password be reset. If the userid is valid, the user will receive a new password via an email that is identical to the email sent when someone fills out the Forgot Password form on the website.

Method: GET

URL: /page/api/account/reset_password

Parameters:

userid (required)
The email address of the user requesting the password reset.

Returns:

Returns 204 No Content except in the case of general API errors (e.g. authentication or missing parameters).

Deferred Results: Never

Example:

http://XYZ/page/api/account_password?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&userid=user1%40domain.com
set_password

This method allows a client to set a user's password. If the userid is valid, the user will have their password reset, if the user is invalid no error will be thrown but nothing will be set.

Important: because of the sensitive nature of accounts and passwords, this API method must always be accessed over HTTPS.

Method: GET or POST

URL: /page/api/account/set_password

Parameters:

userid (required)
The email address of the user
password (required)
The user's new password

Returns:

Returns 204 No Content except in the case of general API errors (e.g. authentication or missing parameters).

Deferred Results: Never

Example:

https://XYZ/page/api/account/set_password?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&userid=user1%40domain.com&password=password1

Action API Calls

add

Allows a client to add an action with source codes and attributes for a particular guid (which may or may not represent an existing cons)

Method: GET or POST

URL: /page/api/action/add

Parameters:

Note: the parameters for this API are expected to be sent as JSON, not form-urlencoded. See the example request below.
guid (required)
String. The guid of the user performing the action, either from the cookie 'guid' value, the cons' guid or a newly created guid
name (required)
String. The name of the action
attributes (required)
JSON map. A set of key-value pairs representing attributes of the action performed
sourceCode (required)
JSON map. A set of key-value pairs representing the source of the action performed
timestamp (optional)
Integer. The time at which the action occurred, in UNIX timestamp format (seconds since Jan 1, 1970)

Returns:

The UUIDv1 of the action created

Deferred Results: Never

POST /page/api/action/add?api_ver=1&api_id=testfetch&api_ts=1317752440&api_mac=f4b0088409836fa79004c5cfdb7cff5ba6b4aea1 HTTP/1.1 Host: example.bluestatedigital.com Accept-Encoding: identity Content-Length: 149 Content-type: application/json { "guid":"36wQOB1IBoVOhIJVT73Xa4A", "name":"testActionName", "attributes":{"attrKey1":"attrValue1"}, "sourceCodes":{"sourceCodeKey1":"sourceCodeValue1"} }
reply: 'HTTP/1.1 200 OK' Date: Tue, 04 Oct 2011 18:20:40 GMT Server: Apache/2.0.63 (Unix) mod_ssl/2.0.63 OpenSSL/0.9.7g PHP/5.2.6 X-Powered-By: PHP/5.2.6 Content-Length: 36 Content-Type: application/json; charset=utf-8 24f250c0-1dd5-11b2-9773-49ed3101b68c
get

Allows a client to retrieve a list of actions performed by a particular guid

Method: GET or POST

URL: /page/api/action/get

Parameters:

guid (required)
String. The guid of the user performing the action, either from the cookie 'guid' value, the cons' guid or a newly created guid

Returns:

JSON list of actions, which are returned as JSON maps.

Deferred Results: Never

Example:

GET /page/api/action/get?guid=36wQOB1IBoVOhIJVT73Xa4A&api_ver=1&api_id=testfetch&api_ts=1317752808&api_mac=3939374b345a28c851316273ba297b7cf143b84f HTTP/1.1 Host: example.bluestatedigital.com
Date: Tue, 04 Oct 2011 18:26:48 GMT Server: Apache/2.0.63 (Unix) mod_ssl/2.0.63 OpenSSL/0.9.7g PHP/5.2.6 X-Powered-By: PHP/5.2.6 Content-Length: 2322 Content-Type: application/json; charset=utf-8 [ { "guid":"36wQOB1IBoVOhIJVT73Xa4A", "name":"testActionName", "attributes":{"attrKey1":"attrValue1"}, "sourceCodes":{"sourceCodeKey1":"sourceCodeValue1"}, "id":"24f0eff0-1dd5-11b2-8563-e5a8347227c7" } ]

Circle (circle) API Calls

list_circles

Fetches a list of all circles in the system.

Method: GET or POST

URL: /page/api/circle/list_circles

Parameters:

circle_type (optional)
If circle_type is present, list_circles will return all circles which are of type 'circle_type'. 'circle_type' can be '0', for basic circles; or '1', for field circles.
state_cd (optional)
If state_cd is present, list_circles will return all circles which have zip codes in the specified state_cd.

Returns:

Returns one <circle> element (see Common Record Formats) for each circle in the system.

Deferred Results: Never

Example:

http://XYZ/page/api/circle/list_circles?api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013
get_cons_ids_for_circle

This method takes a circle id and returns a list of the constituent ids in that circle. The result is a text file with one constituent id per line.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/get_cons_ids_for_circle

Parameters:

circle_id (required)
The numeric id of the circle to list membership of.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/get_cons_ids_for_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&circle_id=42

POST:

circle_id=42
get_ext_ids_for_circle

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows retrieving the members of a circle as a list of their external ids. Any circle members who do not have an external id of the requested type will not be included in the list.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/get_ext_ids_for_circle

Parameters:

circle_id (required)
The numeric id of the circle to list membership of.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/get_ext_ids_for_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&circle_id=42&ext_type=dwid
set_cons_ids_for_circle

This method takes a constituent circle id and a list of constituent ids and replaces the current circle members with the list of constituent ids.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/circle/set_cons_ids_for_circle

Parameters:

circle_id (required)
The numeric id of the circle to replace membership for.
cons_ids (required)
When using GET or POST, a comma-separated list of constituent ids to set as the members of the circle. When using PUT, the cons_ids should be one per line as the only PUT data, and circle_id must be passed as a GET parameter.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/set_cons_ids_for_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&cons_ids=13,47,521,1033,1045
set_ext_ids_for_circle

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows setting the membership of a constituent by specifying external ids instead of having to look up Blue State constituent ids first. The external ids must already exist in Blue State's system. Any external ids that are not found will be ignored and those constituents will not be added to the circle.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/circle/set_ext_ids_for_circle

Parameters:

circle_id (required)
The numeric id of the circle to replace membership for.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
ext_ids (required)
When using GET or POST, a comma-separated list of external ids to set as the members of the circle. When using PUT, the ext_ids should be one per line as the only PUT data, and circle_id and ext_type must be passed as GET parameters.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/set_ext_ids_for_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&ext_type=van_id&ext_ids=12772,1129,1983321,2008001,414456
add_cons_ids_to_circle

This method takes a circle id and a comma-separated list of constituent ids and adds those constituents to the circle.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/add_cons_ids_to_circle

Parameters:

circle_id (required)
The numeric id of the circle to add constituents to.
cons_ids (required)
A comma-separated list of constituent ids to add to the circle.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/add_cons_ids_to_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&cons_ids=13,47,521
add_ext_ids_to_circle

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows adding constituents to a circle by specifying their external id instead of having to look up their Blue State constituent id first. The external ids must already exist in Blue State's system. Any external ids that are not found will be ignored and those constituents will not be added to the circle.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/add_ext_ids_to_circle

Parameters:

circle_id (required)
The numeric id of the circle to add constituents to.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
ext_ids (required)
A comma-separated list of external ids to add to the circle.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/add_cons_ids_to_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=45&ext_type=van_id&ext_ids=12772,1129,1983321
remove_cons_ids_from_circle

This method takes a circle id and a comma-separated list of constituent ids and removes those constituents from the circle.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/remove_cons_ids_from_circle

Parameters:

circle_id (required)
The numeric id of the circle to remove constituents from.
cons_ids (required)
A comma-separated list of constituent ids to remove from the circle.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/remove_cons_ids_from_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&cons_ids=13,47,521
remove_ext_ids_from_circle

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows removing constituents from a circle by specifying their external id instead of having to look up their Blue State constituent id first. The external ids must already exist in Blue State's system. Any external ids that are not found will be ignored and those constituents will not be removed from the circle.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/remove_ext_ids_from_circle

Parameters:

circle_id (required)
The numeric id of the circle to remove constituents from.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
ext_ids (required)
A comma-separated list of external ids to remove from the circle.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/remove_ext_ids_from_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&ext_type=van_id&ext_ids=12772,1129,1983321
move_cons_ids_to_circle

This method allows moving constituents from the source circle to the target circle by specifying their constituent ids. Any constituent ids that are not found will be ignored and those constituents will not be moved from the source circle to the target circle.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/move_cons_ids_to_circle

Parameters:

from_circle_id (required)
The numeric id of the circle to remove constituents from.
to_circle_id (required)
The numeric id of the circle to add constituents to.
cons_ids (required)
A comma-separated list of constituent ids to move from the source circle to the target circle.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/move_cons_ids_to_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

from_circle_id=42&to_circle_id=45&cons_ids=12772,1129,1983321
move_ext_ids_to_circle

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows moving constituents from the source circle to the target circle by specifying their external id instead of having to look up their Blue State constituent id first. The external ids must already exist in Blue State's system. Any external ids that are not found will be ignored and those constituents will not be moved from the source circle to the target circle.

Important: because of the potential time involved in manipulating circles, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/circle/move_ext_ids_to_circle

Parameters:

from_circle_id (required)
The numeric id of the circle to remove constituents from.
to_circle_id (required)
The numeric id of the circle to add constituents to.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
ext_ids (required)
A comma-separated list of external ids to move from the source circle to the target circle.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/circle/move_ext_ids_to_circle?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

from_circle_id=42&to_circle_id=45&ext_type=van_id&ext_ids=12772,1129,1983321
set_circle_administrator

Takes a cons_id and promotes them to administrator of the given circle_id. If the cons_id is not yet a member of the circle, this method adds them to the circle before promoting them.

Method: GET or POST

URL: /page/api/circle/set_circle_administrator

Parameters:

circle_id (required)
The numeric id of the circle to set an administrator for.
cons_id (required)
The numeric id of the constituent to promote to administrator.

Returns:

Returns an HTTP status code indicating success or failure.

Example:

URL:

http://XYZ/page/api/circle/set_circle_administrator?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&cons_id=45
demote_circle_administrator

Takes a cons_id and demotes them from administrator of the given circle_id. If the cons_id is not yet a member of the circle, this method throws an api_exception. If the circle_id or the cons_id don't refer to actual cons or circles, then an api_exception is thrown as well.

Method: GET or POST

URL: /page/api/circle/demote_circle_administrator

Parameters:

circle_id (required)
The numeric id of the circle to demote an administrator from.
cons_id (required)
The numeric id of the constituent to demote from administrator.

Returns:

Returns an HTTP status code indicating success or failure.

Example:

URL:

http://XYZ/page/api/circle/demote_circle_administrator?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&cons_id=45
set_circle_owner

Takes a cons_id and sets them as the owner of the given circle_id. If the cons_id is not yet a member of the circle, this method adds them. If they are already a member, it promotes them to an admin. If the circle_id or the cons_id don't refer to actual cons or circles, then an api_exception is thrown. Note that there is only one owner per circle. Setting a new owner will overwrite the old owner.

Method: GET or POST

URL: /page/api/circle/set_circle_owner

Parameters:

circle_id (required)
The numeric id of the circle to set a new owner for.
cons_id (required)
The numeric id of the constituent to set as owner.

Returns:

Returns an HTTP status code indicating success or failure.

Example:

URL:

http://XYZ/page/api/circle/set_circle_owner?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

circle_id=42&cons_id=45

Constituent (cons) API Calls

get_constituents_by_id

Takes one or more constituent IDs as a parameter and returns the matching constituent records.

Method: GET or POST

URL: /page/api/cons/get_constituents_by_id

Parameters:

cons_ids (required)
One or more (comma separated) constituent IDs.
bundles (optional)
The data bundles to include in the records. See the Constituent Records->Bundle Specification section for details.
filter (optional)
The filter to apply to the resulting records. See the Constituent Records->Filter Specification section for details.

Returns:

Returns zero or more <cons> elements (see Common Record Formats), containing all of the constituent records that match the specified constituent IDs.

Deferred Results: Never

Example:

http://XYZ/page/api/cons/get_constituents_by_id?api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013&cons_ids=57,3882,31,132&bundles=cons_addr,cons_phone
get_constituents

Takes one or more filters as a parameter and returns the matching constituent records.

Method: GET

URL: /page/api/cons/get_constituents

Parameters:

filter (required)
At least one filter must be specified. See the Constituent Records->Filter Specification section for details.
bundles (optional)
The data bundles to include in the records. See the Constituent Records->Bundle Specification section for details.

Returns:

Returns zero or more <cons> elements (see Common Record Formats), containing all of the constituent records that match the specified constituent IDs.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons/get_constituents?filter=state_cd%3D%28MA%2CNY%29&api_ver=1&api_id=my_custom_app&api_ts=1274737903&api_mac=5edfe8bdb8483655339f05f73c3fcb18cc65aa5f
get_constituents_by_ext_id

Takes one or more external IDs (as previously set with the set_ext_ids API call) as a parameter and returns the matching constituent records.

Method: GET or POST

URL: /page/api/cons/get_constituents_by_ext_id

Parameters:

ext_type (required)
The type of the external ID (as passed to set_ext_ids).
ext_ids (required)
One or more (comma separated) external IDs.
bundles (optional)
The data bundles to include in the records. See the Constituent Records->Bundle Specification section for details.
filter (optional)
The filter to apply to the resulting records. See the Constituent Records->Filter Specification section for details.

Returns:

Returns zero or more <cons> elements (see Common Record Formats), containing all of the constituent records that match the specified external IDs.

Deferred Results: Never

Example:

http://XYZ/page/api/cons/get_constituents_by_ext_id?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&ext_type=van_id&ext_ids=f12772,l1129,1m983321&bundles=cons_addr,cons_phone
get_constituents_by_guid

Takes one or more GUIDs (non-sequential, random, unique identifiers for constituents) as a parameter and returns the matching constituent records.

Method: GET or POST

URL: /page/api/cons/get_constituents_by_guid

Parameters:

guids (required)
One or more (comma separated) GUIDs.
bundles (optional)
The data bundles to include in the records. See the Constituent Records->Bundle Specification section for details.
filter (optional)
The filter to apply to the resulting records. See the Constituent Records->Filter Specification section for details.

Returns:

Returns zero or more <cons> elements (see Common Record Formats), containing all of the constituent records that match the specified external IDs.

Deferred Results: Never

Example:

http://XYZ/page/api/cons/get_constituents_by_guid?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&guids=ygdFPkyEdomzBhWEFZGREys&bundles=cons_addr,cons_email
get_updated_constituents

Returns all constituent records that have been updated since a particular date and time. If a bundles parameter is specified, this API call will return look at the modified date on each bundle as well as the modified date on the main constituent record to determine which constituents to return. If, for example, the cons_addr bundle is included, records will be returned that have had a cons_addr record modified since the changed_since time, even if the core constituent record has not been updated.

Method: GET

URL: /page/api/cons/get_updated_constituents

Parameters:

changed_since (required)
All constituent records that have changed since this time (specified in epoch seconds) will be returned by the API call.
bundles (optional)
The data bundles to include in the records. See the Constituent Records->Bundle Specification section for details.
filter (optional)
The filter to apply to the resulting records. See the Constituent Records->Filter Specification section for details.

Returns:

Returns zero or more <cons> elements (see Common Record Formats), containing all of the constituent records that have been updated since the changed_since time.

Deferred Results: Never

Example:

http://XYZ/page/api/cons/get_updated_constituents?api_id=my_custom_app&api_ts=1179943123&api_mac=c1fd787ec5431781f1d601f6e3299fe083ca56c4&changed_since=1179856723&bundles=cons_email&filter=state_cd%3DIA
set_ext_ids

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. A given constituent record can only have one ext_id for a given ext_type. A given ext_type/ext_id pair can only apply to one specific constituent record. ext_ids can be numeric or alpha-numeric strings no longer than 255 characters.

Method: GET or POST

URL: /page/api/cons/set_ext_ids

Parameters:

ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
cons_id=ext_id (required)
Each cons_id=ext_id parameter sets a mapping for one BSD cons_id to one external ID. For example, 4322=12772 would associate the BSD cons_id 4322 with the external ID 12772. If the ext_id is 0, any existing external ID mapping with the BSD cons_id will be removed.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/set_ext_ids?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

ext_type=van_id&4322=12772&3321=1129&9217=1983321
delete_constituents_by_id

Takes one or more constituent IDs as a parameter and deletes the matching constituent records.

Method: GET or POST

URL: /page/api/cons/delete_constituents_by_id

Parameters:

cons_ids (required)
One or more (comma separated) constituent IDs.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

http://XYZ/page/api/cons/delete_constituents_by_id?api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013&cons_ids=57,3882,31,132
get_custom_constituent_fields

Returns all existing custom constituent fields.

Method: GET

URL: /page/api/cons/get_custom_constituent_fields

Parameters: None

Returns:

Returns zero or more <cons_field> elements (see Common Record Formats).

Deferred Results: Never

Example:

http://XYZ/page/api/cons/get_custom_constituent_fields?api_id=my_custom_app&api_ts=1179943123&api_mac=c1fd787ec5431781f1d601f6e3299fe083ca56c4&
upload_bulk_constituent_data

Allows constituents to be added in the same format as Upload Constituents on the Constituents control panel page. The file contents and column mappings must be part of the call.

The constituent information is merged into the the existing data; existing cons will have their records updated, multiple uploads of the same data will be combined.

Method: POST or PUT

URL: /page/api/cons/upload_bulk_constituent_data

Parameters:

CSV data (required)

The constituent data to add must be passed in either the csv_data PUT parameter or the POST request body. If passed in the POST body the entire request body is interpreted as the uploaded file. The format is the same as used for Upload Constituents via the control panel (CSV: rows of comma-separated values terminated with a newline).

column_map (required)

A comma-separated list of table column names in which to store the CSV fields. If a field in the data is not stored, leave the column name empty. The column names are the same as shown on the Upload Constituents page.

NOTE: It is important that every CSV data field be present in the column map. Fields not stored are represented by comma-separated blanks. For example, to extract the first name, last name, email address but skip affiliation and home state from the line John,Smith,Democrat,johnsmith@johnsmith.com,California use the mapping firstname,lastname,,email,. Note the un-mapped columns signified by the ,, and the trailing ,

has_header (optional)
If set to 1, the first row of the CSV data will be assumed to be a header row and will be ignored. If 0 or if not present all rows will be read as data.

Returns:

Returns an HTTP status code indicating success or failure. The upload is done in two phases: inserting the data and creating constituents. The returned status is for the data insertion phase; constituent creation is done as for signups and will take longer. The upload progress can be monitored on the Upload Constituents status page, /modules/constituent/admin/upload_status.php

Deferred Results: Always

Note: The deferred results become available once the data has been inserted, but possibly before constituent creation has completed.

Example:

Adds the constituent name and email address to the database from a CSV file containing other fields.

URL:

http://XYZ/page/api/cons/bulk_upload_constituent_data?has_header=1&column_map=firstname,lastname,,email,&api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013

POST:

FirstName,LastName,Affiliation,EmailAddress,Residence John,Smith,Democrat,johnsmith@johnsmith.com,California Johnny,Smithson,Independent,johnny_s@johnsmith.com,California
get_bulk_constituent_data

Provides an easy way to get bulk data about all or some of the constituents in the Blue State Digital database. Not every piece of information is available via this call and data is returned in a flat (CSV), rather than structured format. This is intended as a means of downloading large amounts of data for easy caching in a local database.

Method: POST or GET

URL: /page/api/cons/get_bulk_constituent_data

Parameters:

fields (required)

The fields to include in the data set. cons_id is always included and does not need to be specified. This should be one or more of following field IDs, separated by commas:

firstname
The first name of the constituent.
lastname
The last name of the constituent.
primary_addr1
The addr1 field of the constituent's primary address.
primary_addr2
The addr2 field of the constituent's primary address.
primary_city
The city field of the constituent's primary address.
primary_state_cd
The state field of the constituent's primary address.
primary_zip
The zip field of the constituent's primary address.
primary_zip_4
The zip+4 field of the constituent's primary address.
primary_country
The country field of the constituent's primary address.
primary_phone
The phone field of the constituent's primary address.
primary_email
The constituent's primary email address.
is_subscribed
1 if the constituent is subscribed to receive email. 0 if the constituent is NOT subscribed to receive email.
has_account
returns 1 or 0 depending on whether the user has a log in account.
ext_X
Where X is an external ID type (as set using the set_ext_ids API call). For example:
ext_van_id

If a field ID has an asterisk appended to it, the field will be treated as required. Any constituent record that does not have a value for that field will not be included in the resulting data set. For example, a fields value of

firstname, lastname, primary_zip*, ext_van_id

would only export recipients who had a valid primary_zip.

cons_ids (optional)
One or more (comma separated) constituent IDs. If not specified, data for all constituents will be returned (this may result in a VERY large data set).
filter (optional)
The filter to apply to the resulting records. See the Constituent Records->Filter Specification section for details.

Returns:

Returns data for zero or more constituent records in the format specified. If the format is CVS, the first row of the CSV will contain headers indicating which values are in which column. If the format is XML, the result will contain a series of <cons_bulk> elements, each containing one element for each requested field. The XML format returned by this function does NOT match the structured common <cons> element format returned by other constituent API calls.

Deferred Results: Always

Example:

http://XYZ/page/api/cons/get_bulk_constituent_data?api_id=my_custom_app&api_ts=1179943123&api_mac=88720bf92a70348cadf30c0cb375708fc9ab3911

POST:

format=csv&fields=firstname,lastname,primary_email,ext_van_id
set_constituent_data

This method allows creating or updating constituent records in BSD's system for one or more constituents. All fields described in the "Incoming Data" specifications can be set using this method, and it can be called for one or more constituents, as defined by top-level cons elements in the incoming XML. The XML data must be encoded in UTF-8.

Method: POST

URL: /page/api/cons/set_constituent_data

Parameters: POST data

Returns:

Returns an HTTP status code indicating success or failure. On success, an XML document is returned describing the results of each insert. For example:

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <cons is_new="0" id="22"/>
    <cons is_new="1" id="1090"/>
</api>
    

The "is_new" attribute tells if this constituent was created via this API call or 0 if it was simply modified and the "id" attribute is the the constituent's id. The records are returned in the order in which they were specified in the parameters.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/set_constituent_data?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

<?xml version="1.0" encoding="utf-8"?> <api> <cons id="4382" send_password="y"> <firstname>Bob</firstname> <lastname>Smith</lastname> <is_banned>0</is_banned> <create_dt>1168146000</create_dt> <cons_email> <email>bsmith@somecompany.com</email> <email_type>work</email_type> <is_subscribed>0</is_subscribed> <is_primary>0</is_primary> </cons_email> </cons> </api>

If a new cons is being created and send_password is set to y it will cause the system to generate a random password and email it to the new cons.

merge_constituents_by_email

Given an email address, this method will find all constituents who have that email and merge them into one constituent. All matching constituents are archived and a new constituent is created with all of the data of the matched constituents. The data is deduped and a primary field for records that require them (email, address, etc), is chosen amongst the merged results by always preferring the newest record.

Method: GET

URL: /page/api/cons/merge_constituents_by_email

Parameters:

email
Email address of constituents to be merged.

Returns:

Returns the constituent ID (cons_id) of the new, merged constituent in the following format:

    <?xml version="1.0" encoding="UTF-8"?>
    <api>
        <cons id="22"/>
    </api>
        

Deferred Results: Always

merge_constituents_by_id

Operates the same way that merge_constituents_by_email works, except instead of specifying an email address to match constituents, this API call takes a comma separated list of constituent IDs as POST data. All constituents specified will be merged into one constituent.

Method: GET

URL: /page/api/cons/merge_constituents_by_id

Parameters: POST data consisting of a comma separated list of constituent ids.

Returns:

Returns the constituent ID (cons_id) of the new, merged constituent in the following format:

    <?xml version="1.0" encoding="UTF-8"?>
    <api>
        <cons id="22"/>
    </api>
        

Deferred Results: Always

get_unsubscribed_constituents_by_group_id

This method allows getting a list of constituents that have been unsubscribed from a group by it's id.

Method: GET or POST

URL: /page/api/cons/get_unsubscribed_constituents_by_group_id

Parameters:

group_id (required)
The group_id of the group to look up unsubscribed constituents for
format (optional)
The format of the response, either json or xml. Defaults to xml.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the cons_ids of the unsubscribed constituents.

<?xml version="1.0" encoding="utf-8"?> <api> <cons> <cons_id>34</cons_id> </cons> <cons> <cons_id>121</cons_id> </cons> <cons> <cons_id>3435</cons_id> </cons> </api>

or

[ {"cons_id":34}, {"cons_id":121}, {"cons_id":3435} ]

Format depends on the format attribute passed the to the API

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/get_unsubscribed_constituents_by_group_id?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&group_id=5&format=json
email_register

This method allows creating constituent emails in BSD's system for a single constituent. If the email or constituent does not exist, they will be created, otherwise, they will be updated.

Method: GET or POST

URL: /page/api/cons/email_register

Parameters:

cons_id (optional)
The numeric id of the constituent to add the email to. If not supplied, a new constituent will be created.
email (required)
The email address to register or update.
is_subscribed (optional)
Set the email to subscribed or not (1 or 0)
guid (optional)
The guid to look up the constituent by.
format (optional)
The format of the response, either json or xml. Defaults to xml.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the cons_id and email_id for the email.

<?xml version="1.0" encoding="utf-8"?> <api> <cons_email> <cons_id>34</cons_id> <email_id>234</email_id> </cons_email> </api>

or

{ "cons_id" : 34, "email_id" : 234 }

Format depends on the format attribute passed the to the API

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/email_register?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&email=test@test.com&is_subscribed=0&format=json
email_unsubscribe

This method allows unsubscribing constituent emails in BSD's system.

Method: GET or POST

URL: /page/api/cons/email_register

Parameters:

email (required)
The email address to unsubscribe.
reason (optional)
The reason for unsubscribing the email.

Returns:

Returns an HTTP status code indicating success or failure.

Example:

URL:

http://XYZ/page/api/cons/email_unsubscribe?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&email=test@test.com&reason=User%20Requested
email_lookup

This method allows looking up constituent emails in BSD's system.

Method: GET or POST

URL: /page/api/cons/email_lookup

Parameters:

cons_id (required*)
The numeric id of the constituent.
email (optional)
The email address to lookup.
is_subscribed (optional)
Filter the email by subscribed or not (1 or 0)
guid (required*)
The guid to look up the constituent by.
format (optional)
The format of the response, either json or xml. Defaults to xml.

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the email records found.

<?xml version="1.0" encoding="utf-8"?> <api> <cons_email> <cons_id>34</cons_id> <email_id>234</email_id> <email>test@test.com</email> <is_subscribed>1</is_subscribed> </cons_email> <cons_email> <cons_id>31</cons_id> <email_id>24</email_id> <email>test2@gmail.com</email> <is_subscribed>1</is_subscribed> </cons_email> </api>

or

[ { "cons_id" : 34, "email_id" : 234, "email_id" : "test@test.com", "is_subscribed" : 1 }, { "cons_id" : 31, "email_id" : 24 "email_id" : "test2@gmail.com", "is_subscribed" : 1 } ]

Format depends on the format attribute passed the to the API

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/email_lookup?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&format=json
email_delete

This method allows deleting constituent emails in BSD's system.

Method: GET or POST

URL: /page/api/cons/email_delete

Parameters:

cons_id (required*)
The numeric id of the constituent.
email (required)
The email address to delete.
is_subscribed (optional)
Filter the email by subscribed or not (1 or 0)
guid (required*)
The guid to look up the constituent by.

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the email records found.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/email_delete?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&email=test@test.com
address_register

This method allows registering constituent addresses in the BSD system

Method: GET or POST

URL: /page/api/cons/address_register

Parameters:

cons_id (required*)
The numeric id of the constituent to add the address to.
addr1 (optional)
Line 1 of the address
addr2 (optional)
Line 2 of the address
city (optional)
City of the address
state (optional)
State of the address in 2 character uppercase. Ex MA
postcode (optional)
Postal code of the address. For the US, that is 9 digits, ex. 02021-2345
guid (required*)
The guid to look up the constituent by.

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/address_register?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=65&line1=280+Summer+Street&city=Boston&state=MA&zip=02145-0934
address_lookup

This method allows looking up constituent addresses in BSD's system.

Method: GET or POST

URL: /page/api/cons/address_lookup

Parameters:

cons_id (required*)
The numeric id of the constituent.
addr1 (optional)
Line 1 of the address
addr2 (optional)
Line 2 of the address
city (optional)
City of the address
state (optional)
State of the address in 2 character uppercase. Ex MA
postcode (optional)
Postal code of the address. For the US, that is 9 digits, ex. 02021-2345
guid (required*)
The guid to look up the constituent by.
format (optional)
Format of the API output, json or xml. The default is xml

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the address records found.

<?xml version="1.0" encoding="utf-8"?> <api> <cons_addr> <cons_id>34</cons_id> <cons_addr_id>234</cons_addr_id> <addr1>21 abc st</addr1> <addr2>Suite 102</addr2> <city>Boston</city> <state>MA</state> <postcode>02021-2345</postcode> </cons_addr> <cons_addr> <cons_id>34</cons_id> <cons_addr_id>224</cons_addr_id> <addr1>1 def st</addr1> <addr2>Suite 12</addr2> <city>Boston</city> <state>MA</state> <postcode>02022-5176</postcode> </cons_addr> </api>

or

[ { "cons_id" : 34, "cons_addr_id" : 234, "addr1" : "21 abc st", "addr2" : "Suite 102", "city" : "Boston", "state" : "MA", "postcode" : "02021-2345" }, { "cons_id" : 34, "cons_addr_id" : 224, "addr1" : "1 def st", "addr2" : "Suite 12", "city" : "Boston", "state" : "MA", "postcode" : "02022-5176" } ]

Format depends on the format attribute passed the to the API

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/address_lookup?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&state=MA&city=boston
address_delete

This method allows deleting constituent addresses in BSD's system.

Method: GET or POST

URL: /page/api/cons/address_delete

Parameters:

cons_id (required*)
The numeric id of the constituent.
addr1 (optional)
Line 1 of the address
addr2 (optional)
Line 2 of the address
city (optional)
City of the address
state (optional)
State of the address in 2 character uppercase. Ex MA
postcode (optional)
Postal code of the address. For the US, that is 9 digits, ex. 02021-2345
guid (required*)
The guid to look up the constituent by.

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the email records found.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/address_delete?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&email=test@test.com
phone_register

This method allows registering constituent phones in BSD's system.

Method: GET or POST

URL: /page/api/cons/phone_register

Parameters:

cons_id (required*)
The numeric id of the constituent.
phone (required)
The phone number.
type (optional)
The phone type. Valid types: home, work, fax, mobile
is_subscribed (optional)
Phone subscription status
guid (required*)
The guid to look up the constituent by.

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/phone_register?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&phone=7812341234&type=mobile&is_subscribed=1
phone_unsubscribe

This method allows unsubscribing constituent phones in BSD's system.

Method: GET or POST

URL: /page/api/cons/phone_unsubscribe

Parameters:

phone (required)
The phone number.

Returns:

Returns an HTTP status code indicating success or failure.

Example:

URL:

http://XYZ/page/api/cons/phone_unsubscribe?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&phone=5648974285
phone_lookup

This method allows looking up constituent phones in BSD's system.

Method: GET or POST

URL: /page/api/cons/phone_lookup

Parameters:

cons_id (required*)
The numeric id of the constituent.
phone (required)
The phone number.
type (optional)
The phone type. Valid types: home, work, fax, mobile
is_subscribed (optional)
Phone subscription status
guid (required*)
The guid to look up the constituent by.

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the phone records found.

<?xml version="1.0" encoding="utf-8"?> <api> <cons_phone> <cons_id>34</cons_id> <cons_phone_id>234</cons_phone_id> <phone>1234567890</phone> <type>home</type> <is_subscribed>1</is_subscribed> </cons_phone> <cons_phone> <cons_id>34</cons_id> <cons_phone_id>224</cons_phone_id> <phone>4569871235</phone> <type>mobile</type> <is_subscribed>1</is_subscribed> </cons_phone> </api>

or

[ { "cons_id" : 34, "cons_phone_id" : 234, "phone" : "1234567890", "type" : "home", "is_subscribed" : 1 }, { "cons_id" : 34, "cons_phone_id" : 224, "phone" : "4569871235", "type" : "mobile", "is_subscribed" : 1 } ]

Format depends on the format attribute passed the to the API

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/phone_lookup?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&format=json
phone_delete

This method allows deleting constituent phones in BSD's system.

Method: GET or POST

URL: /page/api/cons/phone_delete

Parameters:

cons_id (required*)
The numeric id of the constituent.
phone (required)
The phone number.
type (optional)
The phone type. Valid types: home, work, fax, mobile
is_subscribed (optional)
Phone subscription status
guid (required*)
The guid to look up the constituent by.

* Only one of cons_id or guid is required.

Returns:

Returns an HTTP status code indicating success or failure. On success, a document is returned containing the email records found.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/cons/phone_delete?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_id=34&phone=1234567890

Constituent Group (cons_group) API Calls

list_constituent_groups

Fetches a list of all constituent groups in the system.

Method: GET or POST

URL: /page/api/cons_group/list_constituent_groups

Parameters:

Returns:

Returns one <cons_group> element (see Common Record Formats) for each constituent group in the system.

Deferred Results: Never

Example:

http://XYZ/page/api/cons_group/list_constituent_groups?api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013
get_constituent_group

Returns a list (see list_constituent_groups) of one constituent group, or an error code if the group does not exist.

Method: GET or POST

URL: /page/api/cons_group/get_constituent_group

Parameters:

cons_group_id (required)
The constituent group id to get.

Returns:

Returns one <cons_group> element (see Common Record Formats) for each constituent group in the system.

Deferred Results: Never

Example:

http://XYZ/page/api/cons_group/get_constituent_group?cons_group_id=72&api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013
add_constituent_groups

Create one or more constituent groups.

Method: POST

URL: /page/api/cons_group/add_constituent_groups

Parameters: POST data

Returns:

Returns one <cons_group> element (see Common Record Formats) for each constituent group that was created, with its id and with all optional fields filled in with their defaults.

Deferred Results: Never

Example:

http://XYZ/page/api/cons_group/add_constituent_groups?api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013

POST:

<?xml version="1.0" encoding="utf-8"?> <api> <cons_group> <name>Star Canvassers</name> </cons_group> </api>
delete_constituent_groups

Delete one or more constituent groups.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/cons_group/delete_constituent_groups

Parameters:

cons_group_ids (required)
A comma-separated list of constituent group ids to delete.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

http://XYZ/page/api/cons_group/delete_constituent_groups?api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013&cons_group_ids=42,43
get_cons_ids_for_group

This method takes a constituent group id and returns a list of the constituent ids in that group. The result is a text file with one constituent id per line.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/cons_group/get_cons_ids_for_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to list membership of.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/get_cons_ids_for_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_group_id=42

POST:

cons_group_id=42
get_ext_ids_for_group

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows retrieving the members of a group as a list of their external ids. Any group members who do not have an external id of the requested type will not be included in the list.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/cons_group/get_ext_ids_for_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to list membership of.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/get_ext_ids_for_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_group_id=42&ext_type=dwid
set_cons_ids_for_group

This method takes a constituent group id and a list of constituent ids and replaces the current group members with the list of constituent ids.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/cons_group/set_cons_ids_for_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to replace membership for.
cons_ids (required)
When using GET or POST, a comma-separated list of constituent ids to set as the members of the group. When using PUT, the cons_ids should be one per line as the only PUT data, and cons_group_id must be passed as a GET parameter.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/set_cons_ids_for_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

cons_group_id=42&cons_ids=13,47,521,1033,1045
set_ext_ids_for_group

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows setting the membership of a constituent by specifying external ids instead of having to look up Blue State constituent ids first. The external ids must already exist in Blue State's system. Any external ids that are not found will be ignored and those constituents will not be added to the group.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/cons_group/set_ext_ids_for_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to replace membership for.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
ext_ids (required)
When using GET or POST, a comma-separated list of external ids to set as the members of the constituent group. When using PUT, the ext_ids should be one per line as the only PUT data, and cons_group_id and ext_type must be passed as GET parameters.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/set_ext_ids_for_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

cons_group_id=42&ext_type=van_id&ext_ids=12772,1129,1983321,2008001,414456
add_cons_ids_to_group

This method takes a constituent group id and a list of constituent ids and adds those constituents to the group.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/cons_group/add_cons_ids_to_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to add constituents to.
cons_ids (required)
When using GET or POST, a comma-separated list of constituent ids to add to the constituent group When using PUT, the cons_ids should be one per line as the only PUT data, and the cons_group_id must be passed as a GET parameter.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/add_cons_ids_to_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

cons_group_id=42&cons_ids=13,47,521
add_ext_ids_to_group

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows adding constituents to a constituent group by specifying their external id instead of having to look up their Blue State constituent id first. The external ids must already exist in Blue State's system. Any external ids that are not found will be ignored and those constituents will not be added to the group.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/cons_group/add_ext_ids_to_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to add constituents to.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
ext_ids (required)
When using GET or POST, a comma-separated list of external ids to add to the constituent group. When using PUT, the ext_ids should be one per line as the only PUT data, and cons_group_id and ext_type must be passed as GET parameters.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/add_cons_ids_to_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

cons_group_id=45&ext_type=van_id&ext_ids=12772,1129,1983321
remove_cons_ids_from_group

This method takes a constituent group id and a list of constituent ids and removes those constituents from the group.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/cons_group/remove_cons_ids_from_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to remove constituents from.
cons_ids (required)
When using GET or POST, a comma-separated list of constituent ids to remove from the constituent group. When using PUT, the cons_ids should be one per line as the only PUT data, and the cons_group_id must be passed as a GET parameter.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/remove_cons_ids_from_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

cons_group_id=42&cons_ids=13,47,521
remove_ext_ids_from_group

External IDs (ext_id) are primary key identifiers associated with an external system or service. These can be stored alongside their corresponding Blue State Digital constituent records for easy access and reference. The external ID type (ext_type) specifies which external service/system a given ID is associated with. This method allows removing constituents from a constituent group by specifying their external id instead of having to look up their Blue State constituent id first. The external ids must already exist in Blue State's system. Any external ids that are not found will be ignored and those constituents will not be removed from the group.

Important: because of the potential time involved in manipulating groups, the final result code of this call is always deferred.

Method: GET, POST, or PUT

URL: /page/api/cons_group/remove_ext_ids_from_group

Parameters:

cons_group_id (required)
The numeric id of the constituent group to remove constituents from.
ext_type (required)
External ID type. This is a string that identifies the external system with which the ext_ids values are associated. Must be a string containing only lowercase alphanumeric characters and underscores ([0-9a-z_]) and can be no more than 40 bytes in length.
ext_ids (required)
When using GET or POST, a comma-separated list of external ids to remove from the constituent group. When using PUT, the ext_ids should be one per line as the only PUT data, and cons_group_id and ext_type must be passed as GET parameters.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/cons_group/remove_ext_ids_from_group?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

POST:

cons_group_id=42&ext_type=van_id&ext_ids=12772,1129,1983321

Outreach (outreach) API Calls

get_page_by_id

This method gets the outreach page with the given id.

Method: GET

URL: /page/api/outreach/get_page_by_id

Parameters:

id (required)
The numeric id of the outreach page to get.

Returns:

Returns the outreach page record (see Common Record Formats).

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/outreach/get_page_by_id?api_ver=1&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6&id=123
set_page_data

This method creates a new or updates an existing outreach page. The data must be sent in the XML format as defined above (see Common Record Formats) and must be encoded in UTF-8.

Method: POST

URL: /page/api/outreach/set_page_data

Parameters: POST data

Returns:

Returns the outreach page record (see Common Record Formats).

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/outreach/set_page_data?api_ver=1&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6

POST:

<?xml version="1.0" encoding="utf-8"?> <outreach_page id="123"> <outreach_campaign_id>1</outreach_campaign_id> <cons_id>1</cons_id> <slug>shortname</slug> <goal_amt>500.00</goal_amt> <page_text>Some page text.</page_text> <page_title>Fundraising Page</page_title> <email_subject></email_subject> <email_body></email_body> <offline_contributions_number>0</offline_contributions_number> <offline_contributions_amount>0.00</offline_contributions_amount> </outreach_page>

When id is set the existing outreach page is updated, when it is not set a new outreach page is created.

Share (share) API Calls

list_top_recruiters

This method lists the top share recruiter's names and the number of users each has recruited

Method: GET

URL: /page/api/share/list_top_recruiters

Parameters:

limit (optional)
The maximum number of share recruiters to return (defaults to 25. Also, the limit cannot exceed 25)

Returns:

Returns zero or more recruitment records (see example response below).

<?xml version="1.0" encoding="UTF-8"?> <api> <shareRecruiter> <firstname>Barack</firstname> <lastname>Obama</lastname> <recruitCount>500</recruitCount> </shareRecruiter> <shareRecruiter> <firstname>Joe</firstname> <lastname>Biden</lastname> <recruitCount>375</recruitCount> </shareRecruiter> <shareRecruiter> <firstname>Jane</firstname> <lastname>Doe</lastname> <recruitCount>350</recruitCount> </shareRecruiter> <shareRecruiter> <firstname>John</firstname> <lastname>Doe</lastname> <recruitCount>12</recruitCount> </shareRecruiter> <shareRecruiter> <firstname>James</firstname> <lastname>Doe</lastname> <recruitCount>1</recruitCount> </shareRecruiter> </api>

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/share/list_top_recruiters?api_ver=1&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6&limit=10

Share API Calls

list_forms

This method retrieves information about all available signup forms.

Method: GET

URL: /page/api/share/list_forms

Returns:

An XML-formatted description of zero or more share forms:

<?xml version="1.0"?>
<api>
    <share_form id="1" title="Default Share Form" slug="default-share">
        <subject>Default subject for the Default Share Form</subject>
        <body editable="true">Default body for the Default Share Form</body>
    </share_form>
    <share_form id="2" title="Default Tell-a-Friend" slug="tell-a-friend">
        <subject editable="true">Default subject for the Default Tell-a-Friend Form</subject>
        <body>Default body for the Default Tell-a-Friend Form</body>
    </share_form>
</api>

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/share/list_forms?api_ver=1&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6
get_max_recipients

This method retrieves the maximum number of recipients that can be targetted by a single share submission.

Method: GET

URL: /page/api/share/get_max_recipients

Parameters: None

Returns:

An XML block containing the maximum number of allowable recipients:

<?xml version="1.0"?>
<api>
    <max_recipients_per_share>10</max_recipients_per_share>
</api>

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/share/get_max_recipients?api_ver=1&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6
send_share

This method sends share the specified share email to the specified recipients.

Method: POST

URL: /page/api/share/send_share

Parameters: POST Data

POST Data for the send_share call is structured as follows:

<?xml version="1.0"?>
<api>
    <share_form id="1">
        <from>
            <firstname>Jack</firstname>
            <lastname>Sprat</lastname>
            <email>jsprat@example.com</email>
            <replyto>jsprat@example.com</replyto>
        </from>
        <recipients>
            <email>llouie@example.com</email>
            <email>jjiminy@example.com</email>
        </recipients>
        <body>THE BODY OF THE SHARE</body>
        <ip_address>192.0.2.0</ip_address>
        <user_agent>NCSA_Mosaic/2.0 (Windows 3.1)</user_agent>
        <source>SOURCE</source>
        <subsource>SUB-SOURCE</subsource>
    </share_form>
</api>

Notes:

  1. If <replyto> is ommitted, the sender’s email will be used.
  2. If <subject> or <body> is ommitted, then the default for that form will be used.

Returns:

An HTTP 200 code on success, or an HTTP 400 code on failure with errors specified as follows:

<?xml version="1.0"?>
<api>
    <error>Missing share form ID</error>
    <error>No recipients specified</error>
    <error>Missing sender first name</error>
    <error>Missing sender last name</error>
    <error>Missing sender email</error>
    <error>Missing IP address</error>
    <error>Missing user agent</error>
</api>

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/share/send_share?api_ver=1&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6

Signup (signup) API Calls

list_forms

This method lists all signup forms and relevant data about those forms.

Method: GET

URL: /page/api/signup/list_forms

Parameters:

No parameters

Returns:

Returns zero or more signup form records (see Common Record Formats).

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/signup/list_forms?api_ver=1&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6
list_form_fields

Retrieves a list of all form fields associated with a specified signup form.

Method: GET

URL: /page/api/signup/list_form_fields

Parameters:

signup_form_id (required)
The ID of the signup form.

Returns:

Returns zero or more signup form field records (see Common Record Formats).

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/signup/list_form_fields?signup_form_id=9&api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
signup_count

Retrieves a list of all form fields associated with a specified signup form.

Method: GET

URL: /page/api/signup/signup_count

Parameters:

signup_form_id (required)
The ID of the signup form.
signup_form_field_ids (optional)
This works a lot like the bundles. For example, 1,4* would only count constituents that have filled out the signup form field with ID 1 and have NOT filled out the signup form field with ID 4

Returns:

Returns a count of the number of constituents that meet the criteria (see Common Record Formats).

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/signup/signup_count?signup_form_field_ids=93&signup_form_id=9&api_ver=1&api_id=my_custom_app&api_ts=1274300032&api_mac=29541021c4c929cdaed79404abb8375b395e708f
count_by_field

This API allows the user to specify a signup form and signup form field and then the API will return the number of signups per item in the specified signup form field.

Method: GET

URL: /page/api/signup/count_by_field

Parameters:

signup_form_id (required)
The ID of the signup form.
signup_form_field_id (required)
The ID of the signup form field to group by.

Returns:

Returns a list of form field values and number of constituents that have filled out that field

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/signup/count_by_field?signup_form_id=9&signup_form_field_id=93&api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
process_signup

Given an XML document that represents the fields of a signup form, this API will process the signup form in the same way that the web form works.

Method: POST

URL: /page/api/signup/process_signup

Parameters: POST Data

POST Data for each signup form is structured as follows:

<?xml version="1.0" encoding="utf-8"?>
<api>
  <signup_form id="9">
    <signup_form_field id="82">user@domain.com</signup_form_field>
    <signup_form_field id="83">First Name</signup_form_field>
    <signup_form_field id="84">Last Name</signup_form_field>
    <signup_form_field id="85">Address</signup_form_field>
    <signup_form_field id="86">City</signup_form_field>
    <signup_form_field id="87">MA</signup_form_field>
    <signup_form_field id="88">02135</signup_form_field>
    <signup_form_field id="89">USA</signup_form_field>
    <signup_form_field id="90">1112223333</signup_form_field>
    <signup_form_field id="108">custom-form-field</signup_form_field>
    <signup_form_field id="120">
        <items>
            <item>1</item>
            <item>2</item>
        </items>
    </signup_form_field>
    <signup_form_field id="123">custom-cons-field</signup_form_field>
    <signup_form_field id="124">
        <file>
            <filename>filename.jpg</filename>
            <data>[BASE64 encoded data]</data>
        </file>
    </signup_form_field>
  </signup_form>
</api>

All form field values are either specified as CDATA or if there is more than one item (in the event of a custom checkbox field), the <items> tag is used to specify an array of items. For file uploads, the <file> tag is used along with the tags for filename and the data encoded in base 64.

Multiple signup forms can be specified in one API call. Signups will be processed one at a time and the first signup form to have errors will abort all subsequent signups.

Returns:

Nothing on success (HTTP Status 200) or XML containing errors in the following format:

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <error>
        <signup_form_id>9</signup_form_id>
        <signup_form_field_id>108</signup_form_field_id>
        <description>The value for this radio button field is not valid.</description>
    </error>
    <error>
        <signup_form_id>9</signup_form_id>
        <signup_form_field_id>93</signup_form_field_id>
        <description>Required</description>
    </error>
</api>

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/signup/process_signup?api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

POST: see the parameters section for an example of the POST data

Event API Calls

list_rsvps

Returns list of all attendee's of a given event_id

Method: GET or POST

URL: /page/api/event/list_rsvps

Parameters:

event_id (required)
The numeric id of the event.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/list_rsvps?event_id=11&api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

Returns:

Returns an HTTP status code indicating success or failure and JSON blob with an array of all attendees.

VAN API Calls

pull_saved_list

This method tells BSD to pull the members of a saved list (in BSD's system the list is represented by a constituent group) from VAN by calling VAN's GetSavedList and GetSavedListData methods.

Method: GET or POST

URL: /page/api/van/pull_saved_list

Parameters:

cons_group_id (required)
The numeric id of the constituent group to update.
saved_list_id (required)
The numeric id of the saved list on VAN's side that should be pulled into the constituent group.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/van/pull_saved_list?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&cons_group_id=24&saved_list_id=819
sync_constituent_data

This method is identical to cons/set_constituent_data, except that the modifications are recorded as a synchronization, so that the record is not immediately pushed back to VAN via the MatchPerson API, sending back to VAN the same changes that were sent to BSD.

Method: POST

URL: /page/api/van/sync_constituent_data

Parameters: POST data

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/van/sync_constituent_data?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

VAN Campaign API Calls

load_campaign_data

This method allows creating or updating VAN campaign data in BSD's system. The data will be in the form of XML, which must be a valid instance of the VAN campaign schema, van_campaign.xsd. The XML data must be encoded in base64. The API will parse the data and insert or update records in the associated database tables.

Method: POST

URL: /page/api/van_campaign/load_campaign_data

Parameters:

xml_data (required)
Must be base64-encoded. XML data must conform to van_campaign.xsd.
refresh_universe
If "1" is specified, then the universe is always refereshed. If "2" is specified, then the universe will only be refreshed if it is a new universe. If "3" is specified, then the universe will not be refreshed. If this option is ommitted, then 2 is assumed.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/van_campaign/load_campaign_data?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&refresh_universe=1

POST:

XML

update_universe

This method allows the VAN to notify BSD when a universe file is ready for download. This call is intended for on-demand universe loading.

Method: GET or POST

URL: /page/api/van_campaign/update_universe

Parameters:

universe_id (required)
The universe ID that has been updated.
filename (required)
The filename will specifiy the zip file (containing a tab delimited file) can be retrieved from the VAN FTP.

Returns:

Returns 200 Success except in the case of general API errors (e.g. authentication).

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/van_campaign/update_universe?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&universe_id=123456-12345678&filename=file.ext
file_ready_for_download

This method allows the VAN to notify BSD when a file is ready for download. This call is intended to allow for the nightly/weekly transfers between VAN and BSD.

Method: GET or POST

URL: /page/api/van_campaign/file_ready_for_download

Parameters:

filename (required)
The filename will specifiy the zip file (containing a tab delimited file) can be retrieved from the VAN FTP

Returns:

Returns 200 Success except in the case of general API errors (e.g. authentication).

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/van_campaign/file_ready_for_download?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&filename=file.ext
get_van_campaign_id

This method allows the VAN to send BSD an unobfuscated van_campaign_id and receive the BSD obfucated id.

Method: GET or POST

URL: /page/api/van_campaign/get_van_campaign_id

Parameters:

van_campaign_id (required)
The VAN campaign id to be obfuscated.

Returns:

Returns the obfuscated id with status code 200 Success except in the case of general API errors

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/van_campaign/get_van_campaign_id?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&van_campaign_id=99

Wrappers API Calls

list_wrappers

This method lists all wrappers in the BSD system, ordered by internal id.

Method: GET

URL: /page/api/wrappers/list_wrappers

Parameters:

Returns:

Returns zero or more wrapper records (see Common Record Formats).

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/wrappers/list_wrappers?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171

Contribution API Calls

add_external_contribution

Given a JSON blob that includes the necessary information to record a contribution, this API will process an external contribution the same way that the offline contribution upload tool works. If a constituent does not exist for the given information, one will be created. If a matching constituent already exists, standard de-duping will apply.

Method: POST

URL: /page/api/contribution/add_external_contribution

Parameters: POST data

POST Data should be formatted as a JSON array of objects where each of the objects represents a single external contribution. The following parameters are defined for a single contribution object.

external_id (required)
A unique string associated with a given contribution. If a contribution with this external_id already exists in the system the contribution being submitted will be skipped and an error will be returned with an explanation. Uniqueness will only be enforced across external contributions.
firstname (required)
The first name of the contributor.
lastname (required)
The last name of the contributor.
transaction_dt (required)
The date and time of the contribution. Should be in 'YYYY-MM-DD HH:MM:SS' format. A timezone can also be specified at the end of the string. If a timezone is not specified the system's time zone setting will be used. A list of acceptable timezone names can be found on PHP's List of Supported Timezones page.
transaction_amt (required)
A number representing the total amount of the contribution. Note: this should be a JSON number, not a string.
cc_type_cd (required)
A string abbreviation of the payment type. The supported codes and the payment type they represent are shown here:
  • 'vs' - Visa
  • 'mc' - MasterCard
  • 'ax' - American Express
  • 'ds' - Discover
  • 'ma' - Maestro
  • 'ls' - Laser
  • 'vd' - Visa Debit
  • 'so' - Solo
  • 've' - Visa Electron
  • 'pp' - PayPal
  • 'ac' - Automated Clearing House
  • 'ck' - Check
gateway_transaction_id
A unique string associated with a given contribution generated by the payment gateway. If a contribution with this gateway_transaction_id already exists in the system then the contribution being submitted will be skipped and an error will be returned with an explanation. This holds true for external contributions as well as contributions made through the Framework Fundraising module.
contribution_page_id
A Framework contribution_page_id. The contribution will be attributed to this contribution page. Make sure when using this optional parameter that you are associating the correct contribution page and that you are passing a valid contribution_page_id.
contribution_page_slug
A Framework contribution_page slug. The contribution will be attributed to this contribution page. Make sure when using this optional parameter that you are associating the correct contribution page and that you are passing a valid slug.
outreach_page_id
A Framework outreach_page_id. The contribution will be attributed to this outreach page including being added to fundraising goals for the given outreach page. Make sure when using this optional parameter that you are associating the correct outreach page and that you are passing a valid outreach_page_id.
source
A list of strings of all source codes associated with this contribution. Example: ['source1','source2','source3']
addr1
The addr1 field of the contributor's address.
addr2
The addr2 field of the contributor's address.
city
The city of the contributor's address.
state_cd
The state field of the contributor's address.
zip
The zip field of the contributor's address.
country
The country field of the contributor's address.
phone
The contributor's phone number.
email
The contributor's email address
employer
The contributor's employer.
occupation
The contributor's occupation.

Returns:

A JSON object containg two properties: 'summary' and 'errors'. The 'summary' property is an object containing three properties 'sucesses', 'failures', and 'missing_ids'. The 'sucesses' and 'failures' properties are counts of the number of contributions which either passed or failed validation. The 'missing_ids' property is the number of contribution which were missing the expected 'external_id' parameter. The 'failures' property contains the total number of failed inserts whether because of errors or missing external_ids. The 'errors' object contains all errors for each contribution which failed to insert. The property names (or keys) in 'errors' are the 'external_id' parameter passed in for each contribution. If a contribution is missing an external_id it will get counted in 'missing_ids' and 'failures' but its errors will not appear in the 'errors' object.

Deferred Results: Always

URL:

http://XYZ/page/api/contribution/add_external_contribution?api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

Example:

[ { 'external_id':'UNIQUE_ID_111111111', 'firstname':'Jane', 'lastname':'Smith', 'transaction_dt':'2012-12-31 23:59:59', 'transaction_amt':20, 'cc_type_cd':'vs' }, { 'external_id':'UNIQUE_ID_222222222', 'firstname':'John', 'lastname':'Smith', 'transaction_dt':'2012-12-31 23:59:59', 'transaction_amt':10.50, 'cc_type_cd':'vs', 'gateway_reference_id':'GATEWAY_ID_123456789', 'addr1':'123 Fake Street', 'addr2':'Floor 7', 'city':'Boston', 'state_cd':'MA', 'zip':'02210', 'county':'Suffolk', 'country':'USA', 'phone':'5555551234', 'email':'jsmith@testperson.com', 'source':['page1','page2'], 'employer':'Acme Inc.', 'occupation':'Engineer' } ]

Response:

{ 'summary': { 'successes':40, 'failures':1, 'missing_ids':3 }, 'errors': { 'UNIQUE_ID_1234567890':['Parameter source is expected to be a list of strings', 'Parameter email does not appear to be a valid email address.'] } }
quick_donate_import

Requires an external id & type for each QuickDonate optin and uses the same logic as OpenID to match each import to a BSD cons record. Once a cons id matched or create this method will then either update or add a cons_charge_token record for that cons. All alert emails for new / updated QD enrollments are sent as if the cons opted in themselves.

Method: POST

URL: /page/api/contribution/quick_donate_import

Parameters: POST data

ext_type (required)
The external ID type.
ext_id (required)
The external ID value.
token_raw (required)
The raw payment token as generated by your payment gateway.
token_info (required)
JSON encoded hash of billing info passed to the gateway for the given payment token. This should be in the same format as what is passed back by the /ctl/Contribution/Quick/GetToken call.
mobile_optin (optional)
When this is set to "1" it will trigger a MobileCommons QuickDonate SMS optin.

Returns:

A JSON object containg four properties:

  • version - Version number of method call, this is currently "0.1"
  • status - Status of API call, 'success' or 'failure'
  • message - Extended message about the status code
  • payload - An array with extended info, currently will have 'cons_charge_token_id' set to the id of the new/updated charge token record.

It is also possible to get back a non 200 response if the request does not conform to the API, in those cases an error string will be returned.

Deferred Results: Never

URL:

http://XYZ/page/api/contribution/quick_donate_import?api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
create_recurring

Creates a recurring contribution record with the info passed in.

Method: POST

URL: /page/api/contribution/create_recurring

Parameters: POST data

slug (required)
The contribution page slug for the recurring contribution to associate this record to.
transaction_amt (required)
The contribution amount.
next_bill_dt (required)
The date in the format of 'YYYY-MM-DD' of the next charge to be run on this recurring contribution by BSD.
token_raw (required)
The raw payment token as generated by your payment gateway.
token_info (required)
JSON encoded hash of billing info passed to the gateway for the given payment token. This should be in the same format as what is passed back by the /ctl/Contribution/Quick/GetToken call.

Returns:

A JSON object containg four properties:

  • version - Version number of method call, this is currently "0.1"
  • status - Status of API call, 'success' or 'failure'
  • message - Extended message about the status code
  • payload - An array with extended info, currently will have 'stg_contribution_recurring_id' set to the id of the new/updated stg_contribution_recurring record.

It is also possible to get back a non 200 response if the request does not conform to the API, in those cases an error string will be returned.

Deferred Results: Never

URL:

http://XYZ/page/api/contribution/create_recurring?api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
quick_donate_sms_optin_get

Finds the QuickDonate record for a given cons GUID or cons_id and gets the MobileCommons (SMS) optin status.

Method: GET

URL: /page/api/contribution/quick_donate_sms_optin_get

Parameters: GET data

guid (optional)
The cons GUID, required if no cons_id is passed in.
cons_id (optional)
The cons_id, required if no cons GUID is passed in.

Returns:

A JSON object containg four properties:

  • version - Version number of method call, this is currently "0.1"
  • status - Status of API call, 'success' or 'failure'
  • message - Extended message about the status code
  • payload - An array with extended info, currently will return 3 elements:
    • cons_charge_token_id - The QuickDonate charge token record id
    • mobile_optin - The new QuickDonate SMS optin status
    • phone - The phone number associated with the SMS optin and token

It is also possible to get back a non 200 response if the request does not conform to the API, in those cases an error string will be returned.

Deferred Results: Never

URL:

http://XYZ/page/api/contribution/quick_donate_sms_optin_get?api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
quick_donate_sms_optin_set

Finds the QuickDonate record for a given cons GUID or cons_id and sets the MobileCommons (SMS) optin status to what is specified by the parameter 'mobile_optin'.

Method: POST

URL: /page/api/contribution/quick_donate_sms_optin_set

Parameters: POST data

guid (optional)
The cons GUID, required if no cons_id is passed in.
cons_id (optional)
The cons_id, required if no cons GUID is passed in.
mobile_optin (required)
When this is set to "1" it will trigger a MobileCommons QuickDonate SMS optin. A setting of "0" will optout the matching cons from QuickDonate SMS.
phone (optional)
When set the phone number associated with the QuickDonate token will be updated to this otherwise the existing phone number in the token will be used for SMS optin.

Returns:

A JSON object containg four properties:

  • version - Version number of method call, this is currently "0.1"
  • status - Status of API call, 'success' or 'failure'
  • message - Extended message about the status code
  • payload - An array with extended info, currently will return 3 elements:
    • cons_charge_token_id - The QuickDonate charge token record id
    • mobile_optin - The new QuickDonate SMS optin status
    • phone - The phone number associated with the SMS optin and token

It is also possible to get back a non 200 response if the request does not conform to the API, in those cases an error string will be returned.

Deferred Results: Never

URL:

http://XYZ/page/api/contribution/quick_donate_sms_optin_set?api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_quickdonate_token

Finds the QuickDonate record for a given cons_id or GUID and returns the response that the given cons would have gotten if they were authenticated and hits the QuickDonate get token URL. (/ctl/Contribution/Quick/GetToken)

Method: GET

URL: /page/api/contribution/get_quickdonate_token

Parameters: GET data

guid (optional)
The cons GUID, required if no cons_id is passed in.
cons_id (optional)
The cons_id, required if no cons GUID is passed in.

Returns:

A JSON string that is a mirror or what is returned by /ctl/Contribution/Quick/GetToken

Deferred Results: Never

URL:

http://XYZ/page/api/contribution/get_quickdonate_token?api_ver=1&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf767

2.6: Understanding the api_mac

Purpose

It is dangerous to send passwords and API keys over the internet. If they are intercepted in transit, they create an enormous security risk. To reduce this risk, the actual "secret code" (also known as the api_secret) is never transmitted during an API call. Instead, the calling party generates a message and uses the api_secret to create a cryptographically secure "signature" of the message. When the server receives the API call, it verifies that the signature was actually generated using the correct api_secret. If it was not, the request is rejected.

Generating an api_mac

There are three steps to generating an api_mac. The first is to create the "signing_string". This string is a reformatted version of the request you are making. The second step is to sign the "signing string" using the api_secret and the HMAC-SHA1 algorithm. The result is the api_mac. The third step is simply to assemble the request, including the newly generated api_mac.

Step 1: Create the signing string

The signing string consists of four pieces of data, each separated by new lines:

  1. The api_id is the id created in the Blue State Digital Control Panel. Each api_id has a corresponding api_secret.

    Example:

    my_custom_app
  2. The api_ts is a UNIX timestamp value (epoch seconds) that is sent along with the request. It is used to prevent replay attackes wherein someone resends a previously issued API call at a later date. The api_ts value used in the signing string must be identical to the api_ts sent along with the request.

    Example:

    1179962001
  3. The URL of the requested API call, without the http:// or the host name.

    Example:

    /page/api/cons/get_constituents_by_ext_id
  4. The parameters for the API call. These are the standard parameters (api_id, api_ts, and api_ver) as well as any call-specific parameters that will be sent in the URL (if the call uses GET) or as POST data (if the call uses POST). These parameters must not have URL encoding applied when building the signing string (However, they should be encoded in the actual API call). When generating the signing string, it is critical that the parameters be supplied in exactly the same order as they will be supplied in the actual request.

    Example:

    api_ver=1&api_id=my_custom_app&api_ts=1179962001&ext_type=van_id&ext_ids=12772,1129,1983321

Taking the four pieces above, we put them together into a single string, separated by newlines (note that your signing string should contain actual newline characters, not the text "\n"):

my_custom_app\n1179962001\n/page/api/cons/get_constituents_by_ext_id\napi_ver=1&api_id=my_custom_app&api_ts=1179962001&ext_type=van_id&ext_ids=12772,1129,1983321

The signing string will be the same regardless of whether the API call uses GET or POST.

Step 2: Use HMAC-SHA1 to get the api_mac

Once you have the signing string, you need to use the HMAC-SHA1 algorithm and the api_secret to generate the api_mac. Most languages have a simple function or class that implements the algorithm. The following examples show how to generate an api_secret in PHP, Perl, and Python. See the section Code Samples and Libraries for details of package requirements for various languages.

PHP 5.1.2+:
$api_mac = hash_hmac('sha1', $signing_string, $api_secret);
PHP 5.1.1 and earlier:
require_once 'Crypt/HMAC.php'; $signer = new Crypt_HMAC($api_secret, "sha1"); $api_mac = $signer->hash($signing_string);
Perl:
use Digest::HMAC_SHA1; $api_mac = hmac_sha1_hex($signing_string, $api_secret);
Python 3:
import hmac, hashlib api_mac = hmac.new(api_secret.encode(), signing_string.encode(), hashlib.sha1).hexdigest()
Ruby:
require 'openssl' api_mac = OpenSSL::HMAC.hexdigest('sha1', api_secret, signing_string)

Different HMAC-SHA1 implementations return the digest in different formats. The BSD API can support either hexadecimal (40 character hex string) or base64 encoding. If you use base64 encoding, be sure to escape any special characters before putting the string into a URL. Do not attempt to use a binary (unencoded) digest in a URL.

Step 3: Assemble the request

Finally, assemble the full request. The api_id, api_ts, and api_mac parameters ALWAYS go into the URL of the API request, even if the other API call parameters are sent via POST variables. For the purposes of our example, we'll assume that the api_mac generated by the above process was 955e6266d18921a25feb2bebeaa8d5e2bfb518c4. In this case, the final URL for the API call would be:

http://XYZ/page/api/cons/get_constituents_by_ext_id?api_ver=1&api_id=my_custom_app&api_ts=1179962001&api_mac=955e6266d18921a25feb2bebeaa8d5e2bfb518c4&ext_type=van_id&ext_ids=12772,1129,1983321

Code Samples and Libraries

The authentication system of the BSD API requires the use of the HMAC-SHA1 algorithm. This is available natively or with an add-on module in all major web programming environments.

PHP
Use hash_hmac with PHP 5.1.2+, or the Crypt_HMAC PEAR module.
Perl
Use the Digest::HMAC CPAN module
.NET
Use the System.Security.Cryptography.HMACSHA1 class.
Ruby
Use the 'openssl' module.
Python
Use the 'hmac' and 'hashlib' modules.

[TODO: Provide simple functions for generating an api_mac from the component pieces]

2.7: Common HTTP Status Codes

The following HTTP status codes may be returned by an API call:

200 OK
The API call was successfully processed. The results of the call are contained in the body of the HTTP response.
202 Accepted
The API call was accepted, but results are not immediately available. The body of the HTTP response will contain a deferred_id which can be used to retrieve the results. See the Deferred Results section for details.
204 No Content
The deferred result API call succeeded but produced no output.
403 Forbidden
The api_key you are using does not have permission to access the requested API call. Use the Blue State Digital Control Panel to grant access to the desired API call to the api_key you are using.
404 Not Found
You attempted to access an unknown API call. This could be due to an invalid URL, or you may have attempted to access an API function that relates to software that is not installed in your Control Panel. If you receive this error and are certain that you are using the correct URL syntax, contact Blue State Digital for assistance.
405 Method Not Allowed
You attempted to access an API call that supports only GET using a POST request, or a call that supports only POST using a GET request.
409 Conflict
The parameters required by the method call are either missing, malformed, or otherwise rejected.
410 Gone
The results produced by the deferred result API call have already been retrieved and are no longer stored on the server.
500 Internal Server Error
The system encountered a fatal error while processing your API call. The body of the response may contain more detailed information as well as a Problem ID that can be used to report the issue to Blue State Digital.