Blue State Digital API (v2)

NOTICE: you must specify "api_ver=2" in your request parameters to use any methods in this documentation! If you do not the version will default to "1".

Blue State Digital Trusted API

Overview

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"
}

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":[
      {
...
      }
   ]
});

Graph API Reference

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 or event_id_obfuscated, 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/addrsvp?event_id=6&will_attend=1&guid=HASH

Alternate example with minimal information (email & zip):


/page/graph/addrsvp?event_id=6&will_attend=1&email=user@example.com&zip=02210

Days of a multi-day event are specified by a coma-separated list in the event_id or event_id_obfuscated 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/addrsvp?event_id=10,11&will_attend=1&guid=HASH

Results in:

event_id 9 10 11 12 13 14 15
will_attend 0 1 1 0 0 0 0

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/addrsvp?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 (or the event_ids that correspond to the passed event_id_obfuscated parameter).

Example of multiday event:


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

Method: GET/POST

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

Query Parameters:

event_id (required or pass event_id_obfuscated)
Unique integer id of event. Must be specified as a comma-separated list for multiday events.
event_id_obfuscated (required or pass event_id)
Unique obfuscated 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 zip or postal code of the attendee's residence.
country (required unless GUID given)
Attendee's country of residence. (2 letter Country code or ISO 3166-1 alpha-2 code)
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.
employer (required if $event_type->rsvp_require_employer_occupation=1)
occupation (required if $event_type->rsvp_require_employer_occupation=1)

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
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 (or the corresponding event_id_obfuscated).
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

Ladder of Engagement Graph API

/loe/$GUID

Returns a set of attributes associated with the $GUID indicating the constituent's past level of engagement with the site. This information can be used to tailor or target content with the goal of increasing interest and engagement.

Method: GET

URL: /page/graph/loe/$GUID

Query Parameters: none

Returns:

A set of key-value pairs indicating whether or not certain data are present in the constituent's account, or certain actions have been taken, and in some cases actual information about those actions. These include:

email
Boolean, whether or not we have an email address on file
location
Boolean, whether or not we have a location (latitude and longitude, from a valid address or zip code) on file
phone
The actual phone number associated with the guid, or false if none is on file (if the constituent has multiple phone numbers, the primary phone will be returned; if they're subscribed to QD SMS, the phone number is the one under which they are subscribed)
donor
Boolean, whether or not the constituent has ever made a donation
qd_enrolled
Boolean, whether or not the constituent is enrolled in Quick Donate (i.e. has saved payment information)
qd_sms_subscribed
Boolean, whether or not the constituent is subscribed to Quick Donate text messages and has connected their phone number to their saved payment information
last_donation
Date and time (YYYY-MM-DD HH:MM:SS) of the last donation made by the constituent, if any
outreach
Boolean, whether or not the constituent has set up a grassroots fundraising page
highest_previous_contribution
Float, the amount of this constituent's highest previous contribution. If no contributions, will return 0.

Example:


http://XYZ/page/graph/loe/abcdefghij1234567


{
    "email":true,
    "location":true,
    "phone":"6175551234",
    "donor":true,
    "qd_enrolled":true,
    "qd_sms_subscribed":true,
    "last_donation":"2012-07-26 19:16:15",
    "outreach":true,
    "highest_previous_contribution":25
}

Errors:

If the GUID is not found, the following error will be returned:


{
    "error":"invalid_cons_id",
    "error_description":"Constituent ID does not exist"
}

Blue State Digital XML API

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.

Common API Parameters

NOTICE: you must specify "api_ver=2" in your request parameters to use any methods in this documentation! If you do not the version will default to "1".

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. Additionally, the api_ver is required in order to handle backwards compatiblity.

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.

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() == 202);
}

$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 202 (Accepted) 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/get_deferred_results?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&ext_type=van_id&deferred_id=12345

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 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>
    <source>default</source>
    <subsource>default</subsource>
</cons>

All other information is added via data bundles.

Data Bundle: cons_addr

The cons_addr data bundles add address information to a constituent record. cons_addr will add zero or more address elements. 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_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. The is_subscribed field is used to track mobile opt-in. 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 the name, gender, prefix, suffix, 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>
    <middlename>Smith</middlename>
    <lastname>Smith</lastname>
    <prefix>Mr.</prefix>
    <suffix>Jr.</suffix>
    <gender>M</gender>
    <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:

Field Definitions:

firstname:
string, up to 128 characters
middlename:
string, up to 128 characters
lastname:
string, up to 128 characters
prefix:
string, up to 16 characters
suffix:
string, up to 16 characters
gender:
string, 1 character
is_banned:
integer, 0 or 1
create_dt:
unix timestamp
ext_id:
string, up to 255 characters
ext_type:
string, up to 100 characters
employer:
string, up to 128 characters
occupation:
string, up to 128 characters

All other information is added via data bundles.

Data Bundle: cons_addr and primary_cons_addr

The cons_addr data bundles add address information to a constituent record in BSD's database. cons_addr will add zero or more address elements. 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_type>home</cons_addr_type>
    </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
cons_addr_type:
string, home or work
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>

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">
    <format>1</format>
    <label>Last Name</label>
    <description>Last Name</description>
    <display_order>1</display_order>
    <is_shown>1</is_shown>
    <is_required>0</is_required>
    <break_after>0</break_after>
    <is_custom_field>0</is_custom_field>
    <cons_field_id>0</cons_field_id>
    <create_dt>2010-02-08 18:33:11</create_dt>
    <extra_def></extra_def>
</signup_form_field>

Extra_def will have the following elements inside of it:

For textboxes


<size>10</size>
<maxlength>10</maxlength>
<rule>10</rule>

For textareas


<cols>10</cols>
<rows>10</rows>

For dropdown lists


<options>one|1
two|2</options>
<columns>10</columns>

For checkbox lists


<options>one|1
two|2</options>
<columns>10</columns>

For radio button lists


<options>one|1
two|2</options>
<columns>10</columns>

For static fields


<text>hi</text>

For binary checkboxes get "binarycheckbox_email" added to the main bundle, along with:


<desc>user facing description</desc>
<default>0</default>
<cons_group_id>0</cons_group_id>

For upload fields


<file_size>100</file_size>
<file_types>
    <file_type>application/msword:doc<file_type>
</file_types>

For autocomplete fields


<size>3</size>
<maxlength>100</maxlength>
<source>http://www.bluestatedigital.com/source/to/text/file</source>
<must_match>1</must_match>

For hidden fields, nothing is added

Exported XML Signup Records

Core: stg_signups

The stg_signups includes stg_signup records. If there are stg_signup_extras associated with the stg_signup record they are included as children of the stg_signup record. If there are associated stg_signup_extra_values associated with the stg_signup_extra records they are included as children of the stg_signup_extra record.


<stg_signups>
    <stg_signup stg_signup_id="1">
        <stg_signup_id>1</stg_signup_id>
        <signup_form_id/>
        <cons_upload_id>1</cons_upload_id>
        <stg_invitation_id/>
        <cons_source_id>6</cons_source_id>
        <ext_id/>
        <ext_type/>
        <mailing_recipient_id/>
        <mailing_link_id/>
        <stg_contribution_id/>
        <spk_letter_id/>
        <email>email@email.com</email>
        <work_email/>
        <email_opt_in>1</email_opt_in>
        <prefix/>
        <firstname>First</firstname>
        <middlename/>
        <lastname>Last</lastname>
        <suffix/>
        <salutation/>
        <gender/>
        <birth_dt/>
        <title/>
        <employer/>
        <occupation/>
        <income/>
        <mobile_opt_in/>
        <mobile/>
        <phone/>
        <work_phone/>
        <fax/>
        <addr1>1 Some Street</addr1>
        <addr2/>
        <addr3/>
        <city>Somewhere</city>
        <state_cd>XX</state_cd>
        <zip>00000</zip>
        <zip_4>0000</zip_4>
        <country/>
        <transaction_amt/>
        <transaction_dt/>
        <contribution_status/>
        <source/>
        <subsource/>
        <is_contrib_recurring/>
        <opt_in/>
        <create_dt>2012-07-30 03:12:13</create_dt>
        <chapter_id>1</chapter_id>
        <note>1</note>
        <stg_signup_extra stg_signup_extra_id="1">
            <stg_signup_extra_id>1</stg_signup_extra_id>
            <stg_signup_id>1</stg_signup_id>
            <signup_form_field_id>0</signup_form_field_id>
            <nonsignup_cons_field_id>1</nonsignup_cons_field_id>
            <create_dt>2012-07-30 03:12:14</create_dt>
            <create_app>constituent upload</create_app>
            <create_user/>
            <modified_dt/>
            <modified_app/>
            <modified_user/>
            <status>1</status>
            <note/>
            <stg_signup_extra_value stg_signup_extra_value_id="1">
                <stg_signup_extra_value_id>1</stg_signup_extra_value_id>
                <stg_signup_extra_id>1</stg_signup_extra_id>
                <value_varchar>Test</value_varchar>
                <value_text/>
                <value_storage_key/>
                <create_dt>2012-07-30 03:12:15</create_dt>
                <create_app>constituent upload</create_app>
                <create_user/>
                <modified_dt/>
                <modified_app/>
                <modified_user/>
                <status>1</status>
                <note/>
            </stg_signup_extra_value>
        </stg_signup_extra>
    </stg_signup>
</stg_signups>

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": "user@example.com",
            "event_id": "11",
            "firstname": "User",
            "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,
            "employer": "Blue State Digital",
            "occupation": "Software Engineer"
        }
    ]
}


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
cons_group
Description:
The constituent is part of one of the specified cons_groups.
Supported operators:
=
Example:
cons_group=(1,20,300)
not_cons_group
Description:
The constituent has to not be part of one of the specified cons_groups.
Supported operators:
=
Example:
not_cons_group=(1,20,300)

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,cons_group=20

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%2Ccons_group%3D20&api_id=X&api_mac=Y&api_ts=N

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 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 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

Advocacy API Calls

list_targets_by_address

List all targets for a given advocacy campaign for a particular location.

Method: GET or POST

URL: /page/api/spk/list_targets_by_address

Parameters:

spk_campaign_id (required)
The id of the advocacy campaign
search_addr (required)
The search address to be looked up. This is a semi-free form field that can accept any string that the front-end advocacy campaign can accept. (post code, full addr, post code+4 etc.)

Returns:

Returns a JSON array of recipient objects that are found for the given campaign for the particular search address.

Deferred Results: Never

Example:


https://XYZ/page/api/spk/list_targets_by_address?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&spk_campaign_id=12&search_addr=02148-4161


https://XYZ/page/api/spk/list_targets_by_address?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&spk_campaign_id=6&search_addr='123 street, Boston, MA, 02174'

Response (of a MA State Senate recipient type):

			
[
	{
		"spk_recipient_state_leg_id": "7348",
		"is_editable": 0,
		"updateid": null,
		"pid": 0,
		"chamber": "S",
		"state_cd": "MA",
		"district": "28",
		"district_desc": "Massachusetts Senate 28 - Second Suffolk and Middl",
		"district_code": null,
		"party": "D",
		"title": "Senator",
		"firstname": "William",
		"lastname": "Brownsberger",
		"email": "William.Brownsberger@masenate.gov",
		"phone": null,
		"website": null,
		"webform": null,
		"fax": "(617) 722-1055",
		"active": "1",
		"create_dt": null,
		"create_app": null,
		"create_user": null,
		"modified_dt": null,
		"modified_app": null,
		"modified_user": null,
		"status": 1,
		"note": "0",
		"category": "MA Senate",
		"stat_with_goals": {
			"District.": "Massachusetts Senate 28 - Second Suffolk and Middl",
			"Sent": "0"
		},
		"stat_without_goals": {
			"District.": "Massachusetts Senate 28 - Second Suffolk and Middl"
		},
		"spk_recipient_type_id": "67"
	}
]
			
			
list_all_targets_by_campaign

List all targets for a given advocacy campaign.

Method: GET or POST

URL: /page/api/spk/list_all_targets_by_campaign

Parameters:

spk_campaign_id (required)
The id of the advocacy campaign

Returns:

Returns a JSON array of recipient objects that are found for the given campaign.

Deferred Results: Never

Example:


https://XYZ/page/api/spk/list_all_targets_by_campaign?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&spk_campaign_id=12

Response (list of MA state senators - shortened):

				
[
	{
		"spk_recipient_state_leg_id": "7244",
		"is_editable": "0",
		"updateid": "1414014451",
		"pid": "228418",
		"chamber": "S",
		"state_cd": "MA",
		"district": "3",
		"district_desc": "Massachusetts Senate 03 - Hampden",
		"district_code": "MA3",
		"party": "D",
		"title": "Senator",
		"firstname": "James",
		"lastname": "Welch",
		"email": "James.Welch@masenate.gov",
		"phone": "(617) 722-1660",
		"website": "http://malegislature.gov/People/Profile/JTW0",
		"webform": "",
		"fax": "(617) 722-1020",
		"active": "1",
		"create_dt": "2012-03-22 13:03:28",
		"create_app": null,
		"create_user": "meskin",
		"modified_dt": "2014-10-22 17:47:31",
		"modified_app": null,
		"modified_user": "meskin",
		"status": "1",
		"note": null,
        "spk_recipient_type_id": 1
	},
	{
		"spk_recipient_state_leg_id": "7250",
		"is_editable": "0",
		"updateid": "1414014451",
		"pid": "201935",
		"chamber": "S",
		"state_cd": "MA",
		"district": "5",
		"district_desc": "Massachusetts Senate 05 - Second Hampden and Hamps",
		"district_code": "MA5",
		"party": "R",
		"title": "Senator",
		"firstname": "Donald",
		"lastname": "Humason",
		"email": "Donald.Humason@masenate.gov",
		"phone": "(617) 722-1415",
		"website": "https://malegislature.gov/People/Profile/DFH0",
		"webform": "",
		"fax": "(617) 722-1506",
		"active": "1",
		"create_dt": "2012-03-22 13:03:28",
		"create_app": null,
		"create_user": "meskin",
		"modified_dt": "2014-10-22 17:47:31",
		"modified_app": null,
		"modified_user": "meskin",
		"status": "1",
		"note": null,
        "spk_recipient_type_id": 1
	}
]
				
				
list_campaigns

List all of the campaigns that are active for this url

Method: GET or POST

URL: /page/api/spk/list_campaigns

Parameters:

start_dt_after (optional)
Return only campaigns that have a start date after the given date (inclusive).
start_dt_before (optional)
Return only campaigns that have a start date before the given date (inclusive).

Returns:

Returns a JSON array of campaign objects

Deferred Results: Never

Example:


https://XYZ/page/api/spk/list_campaigns?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1


https://XYZ/page/api/spk/list_campaigns?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&spk_campaign_id=6&start_dt_after=2014-01-01&start_dt_before=2015-01-01

Response:

				
[
	{
		"spk_campaign_id": "1",
		"is_active": "1",
		"is_searchable": "1",
		"for_widget": "0",
		"is_multiple": "1",
		"checked_by_default": "0",
		"start_dt": null,
		"end_dt": null,
		"cons_group_id": null,
		"needs_user_addr": "1",
		"needs_phone": "0",
		"title": "Daily Newspapers",
		"description": "Write to the editors of local and national newspapers",
		"short_description": "Write to the editors of local and national newspapers",
		"slug": "dailies",
		"page_wrapper_id": "0",
		"talking_point": null,
		"recipient_splash_text": null,
		"splash_text": null,
		"default_subject": "My Thoughts",   *Randomly selected letter
		"default_letter": "",               *Randomly selected letter
		"default_letters": [
                    {
                    "id":"1",
                    "subject":"Letter 1 ",
                    "letter":"Letter 1 body"
                    },
                    {
                    "id":"2",
                    "subject":"Letter 2",
                    "letter":"Letter 2 body"
                    }],
		"require_customized_letter": "0",
		"send_thanks_email": "1",
		"include_cc_in_thanks_email": "1",
		"thank_you_text": "Thank you for participating",
		"thank_you_email_subject": "Thanks email subject",
		"thank_you_email_body": "Thanks email body",
		"thank_you_redirect": null,
		"thank_you_id": null,
		"thank_you_type": "2",
		"spk_recipient_type_id": "0",
		"goal_display_percent": null,
		"goal_display_boolean": "1",
		"letter_goal": "1000",
		"recipient_letter_limit": "100",
		"at_letter_limit_behavior": "1",
		"recipient_goal": "100",
		"default_country": "US",
		"chapter_id": "1",
		"base_campaign_id": null,
		"activated_dt": null,
		"create_dt": "2014-12-18 19:01:16",
		"create_app": null,
		"create_user": null,
		"modified_dt": "2014-12-18 19:01:16",
		"modified_app": null,
		"modified_user": null,
		"status": "1",
		"note": null,
		"enable_addr_autofill": "0"
	},
	{
		"spk_campaign_id": "2",
		"is_active": "1",
		"is_searchable": "0",
		"for_widget": "1",
		"is_multiple": "1",
		"checked_by_default": "1",
		"start_dt": "0000-00-00",
		"end_dt": "0000-00-00",
		"cons_group_id": null,
		"needs_user_addr": "1",
		"needs_phone": "1",
		"title": "Test Newspapers Campaign",
		"description": "Test Campaign Description",
		"short_description": "Test Campaign Description",
		"slug": "test-newspapers-campaign",
		"page_wrapper_id": "1",
		"talking_point": "",
		"recipient_splash_text": "",
		"splash_text": null,
		"default_subject": null,        *Randomly selected letter
		"default_letter": null,         *Randomly selected letter
		"default_letters": [
                    {
                    "id":"1",
                    "subject":"Letter 1 ",
                    "letter":"Letter 1 body"
                    },
                    {
                    "id":"2",
                    "subject":"Letter 2",
                    "letter":"Letter 2 body"
                    }],
		"require_customized_letter": "0",
		"send_thanks_email": "0",
		"include_cc_in_thanks_email": "0",
		"thank_you_text": "",
		"thank_you_email_subject": "",
		"thank_you_email_body": "",
		"thank_you_redirect": null,
		"thank_you_id": null,
		"thank_you_type": "1",
		"spk_recipient_type_id": null,
		"goal_display_percent": "0",
		"goal_display_boolean": "0",
		"letter_goal": "0",
		"recipient_letter_limit": "0",
		"at_letter_limit_behavior": "1",
		"recipient_goal": "0",
		"default_country": "US",
		"chapter_id": "1",
		"base_campaign_id": null,
		"activated_dt": null,
		"create_dt": "2015-03-24 19:02:41",
		"create_app": null,
		"create_user": null,
		"modified_dt": "2015-03-24 19:12:57",
		"modified_app": null,
		"modified_user": null,
		"status": "1",
		"note": null,
		"enable_addr_autofill": "0"
	},
	{
		"spk_campaign_id": "3",
		"is_active": "1",
		"is_searchable": "0",
		"for_widget": "1",
		"is_multiple": "1",
		"checked_by_default": "1",
		"start_dt": "0000-00-00",
		"end_dt": "0000-00-00",
		"cons_group_id": null,
		"needs_user_addr": "1",
		"needs_phone": "1",
		"title": "Test MA State Senate",
		"description": "Test MA State Senate",
		"short_description": "Test MA State Senate",
		"slug": "test-ma-state-senate",
		"page_wrapper_id": "1",
		"talking_point": "",
		"recipient_splash_text": "",
		"splash_text": null,
		"default_subject": null,        *Randomly selected letter
		"default_letter": null,         *Randomly selected letter
		"default_letters": [
                    {
                    "id":"1",
                    "subject":"Letter 1 ",
                    "letter":"Letter 1 body"
                    },
                    {
                    "id":"2",
                    "subject":"Letter 2",
                    "letter":"Letter 2 body"
                    }],
		"require_customized_letter": "0",
		"send_thanks_email": "0",
		"include_cc_in_thanks_email": "0",
		"thank_you_text": "",
		"thank_you_email_subject": "",
		"thank_you_email_body": "",
		"thank_you_redirect": null,
		"thank_you_id": null,
		"thank_you_type": "1",
		"spk_recipient_type_id": null,
		"goal_display_percent": "0",
		"goal_display_boolean": "0",
		"letter_goal": "0",
		"recipient_letter_limit": "0",
		"at_letter_limit_behavior": "1",
		"recipient_goal": "0",
		"default_country": "US",
		"chapter_id": "1",
		"base_campaign_id": null,
		"activated_dt": null,
		"create_dt": "2015-03-24 19:39:14",
		"create_app": null,
		"create_user": null,
		"modified_dt": "2015-03-24 19:41:34",
		"modified_app": null,
		"modified_user": null,
		"status": "1",
		"note": null,
		"enable_addr_autofill": "0"
	}
]
				
				
get_campaign_details

List all of the details from a given campaign_id

Method: GET or POST

URL: /page/api/spk/get_campaign_details

Parameters:

spk_campaign_id (required)
The id of the advocacy campaign

Returns:

Returns a JSON array of a single campaign object

Deferred Results: Never

Example:


https://XYZ/page/api/spk/get_campaign_details?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&spk_campaign_id=12

Response:

				
[
	{
		"spk_campaign_id": "3",
		"is_active": "1",
		"is_searchable": "0",
		"for_widget": "1",
		"is_multiple": "1",
		"checked_by_default": "1",
		"start_dt": "0000-00-00",
		"end_dt": "0000-00-00",
		"cons_group_id": null,
		"needs_user_addr": "1",
		"needs_phone": "1",
		"title": "Test MA State Senate",
		"description": "Test MA State Senate",
		"short_description": "Test MA State Senate",
		"slug": "test-ma-state-senate",
		"page_wrapper_id": "1",
		"talking_point": "",
		"recipient_splash_text": "",
		"splash_text": null,
		"default_subject": null,        *Randomly selected letter
		"default_letter": null,         *Randomly selected letter
		"default_letters": [
                    {
                    "id":"1",
                    "subject":"Letter 1 ",
                    "letter":"Letter 1 body"
                    },
                    {
                    "id":"2",
                    "subject":"Letter 2",
                    "letter":"Letter 2 body"
                    }],
		"require_customized_letter": "0",
		"send_thanks_email": "0",
		"include_cc_in_thanks_email": "0",
		"thank_you_text": "",
		"thank_you_email_subject": "",
		"thank_you_email_body": "",
		"thank_you_redirect": null,
		"thank_you_id": null,
		"thank_you_type": "1",
		"spk_recipient_type_id": null,
		"goal_display_percent": "0",
		"goal_display_boolean": "0",
		"letter_goal": "0",
		"recipient_letter_limit": "0",
		"at_letter_limit_behavior": "1",
		"recipient_goal": "0",
		"default_country": "US",
		"chapter_id": "1",
		"base_campaign_id": null,
		"activated_dt": null,
		"create_dt": "2015-03-24 19:39:14",
		"create_app": null,
		"create_user": null,
		"modified_dt": "2015-03-24 19:41:34",
		"modified_app": null,
		"modified_user": null,
		"status": "1",
		"note": null,
		"enable_addr_autofill": "0"
	}
]
				
				
send_letter_to_target

Send advocacy letters to given target(s)

Method: GET or POST

URL: /page/api/spk/send_letter_to_target

Parameters:

spk_campaign_id (required)
The id of the advocacy campaign
spk_recipient_ids (required)
A comma seperated list of compound recipient ids in the form of 'RecipientTypeId_RecipientId'. Sending 2 letters to recipients 1 and 2 for recipient type 44 would look like this: '&spk_recipient_ids=44_1,44_2&...'
message_subject (required)
The subject email being sent to the recipients.
message_body (required)
The body of the email being sent to the recipients.
sender_firstname (required)
The firstname of the user the messages are coming from.
sender_lastname (required)
The lastname of the user the messages are coming from.
sender_phone (required or optional as defined by the Speakout campaign)
The phone number of the user the messages are coming from.
sender_addr1 (required or optional as defined by the Speakout campaign)
The address1 field of the user the messages are coming from.
sender_city (required or optional as defined by the Speakout campaign)
The city of the user the messages are coming from.
sender_state_cd (required or optional as defined by the Speakout campaign)
The state abbrev. of the user the messages are coming from.
sender_zip (required or optional as defined by the Speakout campaign)
The zip code of the user the messages are coming from.
sender_country (required or optional as defined by the Speakout campaign)
The country of the user the messages are coming from.
sender_email (required)
The email of the user the messages are coming from.
sender_addr2 (required or optional as defined by the Speakout campaign)
The address2 of the user the messages are coming from.
sender_zip_4 (required or optional as defined by the Speakout campaign)
The extra 4 digits of the zip code of the user the messages are coming from.

Returns:

Returns a JSON array of success/failure messages for each recipient being sent to.

Deferred Results: Never

Example:


https://XYZ/page/api/spk/send_letter_to_target?api_id=my_custom_app&api_ts=1179943123&api_mac=61722c6a82a16779c956992e351ae1582f4a3cc1&spk_campaign_id=14&spk_recipient_ids=711_3,711_4&message_subject='Test Subject'&message_body='Test Body'&sender_firstname=Hank&sender_lastname=Blue&=sender_addr1='711 Atlantic Ave'&sender_city=Boston&sender_state_cd=MA&sender_zip=02111&sender_country=US&sender_email=hank@bluestatedigital.com

Response:

			
{"711_3":"Message sent via email to recipient 711_3","711_4":"Message sent via email to recipient 711_4"}
			
			

Branches API Calls

list_branches

Retrieve a list of all branches

Method: GET

URL: /page/api/branches/list_branches

Parameters:

No parameters

Returns:

An XML-formatted description of zero or more branches:

        
<?xml version="1.0"?>
<api>
    <branch id="1" modified_dt="2013-01-03 15:51:53">
        <name>Test Chapter #1</name>
        <create_dt>2013-01-03 15:51:53</create_dt>
    </branch>
    <branch id="2" modified_dt="2013-01-03 15:51:53">
        <name>Test Chapter #2</name>
        <create_dt>2013-01-03 15:51:53</create_dt>
    </branch>
</api>
        

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

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/branches/list_branches?api_ver=2&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6

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.
deferred (optional)
When set to 1, the results will be deferred. This should be used with greater than 10 constituent ids to avoid timeouts

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: Only if deferred parameter set to 1

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_by_email

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

Method: GET or POST

URL: /page/api/cons/get_constituents_by_email

Parameters:

emails (required)
One or more (comma separated) constituent emails.
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.
deferred (optional)
When set to 1, the results will be deferred. This should be used with greater than 10 constituent emails to avoid timeouts

Returns:

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

Deferred Results: Only if deferred parameter set to 1

Example:


http://XYZ/page/api/cons/get_constituents_by_email?api_id=my_custom_app&api_ts=1179943123&api_mac=3c3452091bf7ff0e2be8b638694a187ca7c0a013&emails=email@example.com&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=2&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: Only if deferred parameter set to 1 .

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

get_updated_constituent_ids

Returns all constituent ids that have been updated since a particular date and time as a JSON array.

Method: GET

URL: /page/api/cons/get_updated_constituent_ids

Parameters:

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

Returns:

Returns a JSON array with the cons_id of all matching constituents.

Deferred Results: Only if deferred parameter set to 1 .

Example:


http://XYZ/page/api/cons/get_updated_constituent_ids?api_id=my_custom_app&api_ts=1179943123&api_mac=c1fd787ec5431781f1d601f6e3299fe083ca56c4&changed_since=1179856723&filter=cons_group%3D1

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/upload_bulk_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">
        <guid>NeTcdcmDVR1XdXufoJ2W4tA</guid>
    </cons>
    <cons is_new="1" id="1090">
        <guid>JZU4C8mDVR1XdYbXEiim4tA</guid>
    </cons>
</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_ext>
            <ext_type>My_Ext_Type</ext_type>
            <ext_id>123456</ext_id>
        </cons_ext>

        <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>

This method will try to match the xml input with an existing constituent. If an id is provided, the corresponding constituent will be updated. If no existing cons has the provided id an error will be thrown. If no id is provided, the input will be matched by ext_id and ext_type. If ext_id and ext_type were not provided or did not match any existing constituents, the input will be matched by email. If the input is still not matched to any existing constituents, a new constituent will be created, populated with the specified data, and assigned a unique id.

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.

set_custom_constituent_fields

This method allows creating or updating a constituent record's custom fields.

Method: POST

URL: /page/api/cons/set_custom_constituent_fields

cons_id (required)
The constituent ID we are modifying.
delete_missing (optional)
1 or 0. If 1, delete any custom constituent fields associated with the cons and not referenced in this call. Defaults to 1 if not specified

Parameters: POST data

Returns:

Returns an HTTP status code indicating success or failure. On success, the created or updated cons_field_value_ids are returned. For example:

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

The "is_new" attribute tells if this constituent field was created via this API call or 0 if it was simply modified and the "id" attribute is the the constituent field value id.

Deferred Results: Never

Example:

URL:


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

POST:


<?xml version="1.0" encoding="utf-8"?>
<api>
    <cons_field id="23">
        <value>0</value>
    </cons_field>
</api>

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_unsubscribe

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.

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&state=MA&city=boston

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.

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

list_datasets

This method returns a JSON list of all personalization datasets.

Method: GET or POST

URL: /page/api/cons/list_datasets

Parameters:

Returns:

Returns a JSON hash with a "data" object containing all of the datasets in the system.

Deferred Results: Never

Example:

URL:


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

Returned JSON:


{
    "data":[
        {
            "dataset_id":42,
            "slug":"my_dataset",
            "rows":100,
            "map_type":"state"
        },
        {
            "dataset_id":43,
            "slug":"downballot_dataset",
            "rows":50,
            "map_type":"downballot"
        }
    ],
}

list_dataset_maps

This method returns a JSON list of all personalization dataset maps.

Method: GET or POST

URL: /page/api/cons/list_dataset_maps

Parameters:

Returns:

Returns a JSON hash with a "data" object containing all of the dataset maps in the system.

Deferred Results: Never

Example:

URL:


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

Returned JSON:


{
    "data":[
        {
            "map_id":1,
            "type":"state"
        },
        {
            "map_id":2,
            "type":"downballot"
        },
        {
            "map_id":3,
            "type":"houseparty"
        }
    ],
}
            
upload_dataset

This method creates a new personalization dataset from a slug, map_type, and CSV data, or if the supplied slug already exists, replaces the existing dataset.

Method: POST or PUT

URL: /page/api/cons/upload_dataset

Parameters:

slug (required)
The name of the dataset. This is the name the dataset will be referenced by in personalization tags. It should be alphanumeric, with underscores/dashes allowed.
map_type (required)
The map to associate the dataset with. This must already exist; you can check for existing maps with the list_dataset_maps method.
csv_data (required)
The CSV-formatted content of the dataset. This must be passed in either the csv_data parameter or the request body. If passed in the body the entire request body is interpreted as the uploaded file, and the other parameters must be passed in the URL. The format is the same as used for datasets via the control panel (CSV: rows of comma-separated values terminated with a newline).

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:


http://XYZ/page/api/cons/upload_dataset?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&slug=downballot_dataset&map_type=downballot

Request body:


index,house,house_link,senate,senate_link
NJ01,Elect Camille Andrew,http://camilleandrew.com,Elect Bob Smith,http://bobsmith.com
NJ02,Elect David Kurkowski,http://davidforcongress.com,Elect Joe Jim,http://joejim.com

upload_dataset_map

This method takes a CSV of dataset map data and creates or updates all of the mappings found in the CSV.

Method: POST or PUT

URL: /page/api/cons/upload_dataset_map

Parameters:

csv_data (required)
The CSV to process, containing cons_ids and one or more map columns. The CSV-formatted content of the dataset. This must be passed in either the csv_data parameter or as the request body. If passed in the body the entire request body is interpreted as the uploaded file. The format is the same as used for maps via the control panel (CSV: rows of comma-separated values terminated with a newline).

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:


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

Request body:


cons_id,downballot,houseparty
123456,NJ01,HP01
123457,NJ02,HP01
123458,NJ03,HP04
123459,NJ04,HP02

delete_dataset

This method deletes a personalization dataset.

Method: POST

URL: /page/api/cons/delete_dataset

Parameters:

dataset_id (required)
The numeric id of the dataset to delete.

Returns:

Returns an HTTP status code and JSON array indicating success or failure.

Deferred Results: Never

Example:

URL:


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

POST data:


dataset_id=42
delete_dataset_map

This method deletes a personalization dataset map.

Method: POST

URL: /page/api/cons/delete_dataset_map

Parameters:

map_id (required)
The numeric id of the map to delete.

Returns:

Returns an HTTP status code and JSON array indicating success or failure.

Deferred Results: Never

Example:

URL:


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

POST data:


map_id=42

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

get_constituent_group_by_name

Returns a list (see list_constituent_groups) of one constituent group, or an empty list if a group with the given name does not exist.

Method: GET or POST

URL: /page/api/cons_group/get_constituent_group_by_name

Parameters:

name (required)
The constituent group name to look up.

Returns:

Returns one <cons_group> element (see Common Record Formats) for the constituent group matching name, or none if there is no match.

Deferred Results: Never

Example:


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

get_constituent_group_by_slug

Returns a list (see list_constituent_groups) of one constituent group, or an empty list if a group with the given slug does not exist.

Method: GET or POST

URL: /page/api/cons_group/get_constituent_group_by_slug

Parameters:

slug (required)
The constituent group slug to look up.

Returns:

Returns one <cons_group> element (see Common Record Formats) for the constituent group matching slug, or none if there is no match.

Deferred Results: Never

Example:


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

rename_group

Renames a constituent group

Method: GET or POST

URL: /page/api/cons_group/rename_group

Parameters:

cons_group_id (required)
The constituent group id to get.
new_name (required)
The new name for the group

Returns:

Nothing

Deferred Results: Never

Example:


http://XYZ/page/api/cons_group/rename_group?cons_group_id=1&new_name=mynewnameapi_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=van

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. Setting cons_ids= or cons_id=0 will empty the group.

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

Entity API Calls (entity)

fetch

This method gets the entity with the given primary key.

Method: GET

URL: /page/api/entity/fetch


    http://XYZ/page/api/entity/fetch/{class}/{pk1_name}/{pk1_value}/{pk2_name}/{pk2_value}/... (etc. for all primary key parts)
    

Returns:

If we are able to retrieve the entity successfully, we will return a 200 OK response code and a one-dimensional JSON map of key - value pairs If the entity is not found for the given ID, we will return a 404 Not Found response code In any other case, e.g. the database is unavailable or other internal error, we will return a 500 Internal Service Error response code

Example:


    GET /page/api/entity/fetch/cons/cons_id/3908692 HTTP/1.1
    Accept: application/json
    

    HTTP/1.0 200 OK
    Date: Fri, 31 Dec 1999 23:59:59 GMT
    Content-Type: application/json
    Content-Length: ####

    {"cons_id":"3908692", "cons_source_id":"4", "prefix":"", "firstname":"Joel", "middlename":"", "lastname":"Barciauskas", "suffix":"", "salutation":"", "gender":"", "birth_dt: 0000-00-00 00:00":"00", "title":"", "employer":"Blue State Digital", "occupation":"se", "income":"0.00", "source":"feb5post", "subsource":"OLWEB", "userid":"foobar@gmail.com", "password":"aaaaaaaaaaaaaaaaaaaaa", "is_validated":"0", "is_banned":"0", "change_password_next_login":"0", "create_dt: 2008-02-06 21:27":"30", "create_app":"signup_db_script", "create_user":"system", "modified_dt: 2011-05-11 00:32":"33", "modified_app":"signup_db_script", "modified_user":"system", "status":"1", "note":"102472629", "is_deleted":"0" }
    
fetch_batch

This method gets an array of entities from a list of primary keys.

Method: GET

URL: /page/api/entity/fetch_batch


    http://XYZ/page/api/entity/fetch_batch/{class}/{pk_name}/{pk_value}/{pk_value}/{pk_value}/... (etc. to a reasonable limit of 1000)
    

Returns:

If we are able to retrieve any requested entity successfully, we will return a 200 OK response code and an array of one-dimensional JSON map of key - value pairs of the found entities. If no entity is found for any of the given IDs, we will return a 404 Not Found response code. In any other case, e.g. the database is unavailable or other internal error, we will return a 500 Internal Service Error response code.

Example:


    GET /page/api/entity/fetch_batch/cons/cons_id/1/2/3 HTTP/1.1
    Accept: application/json
    

    HTTP/1.0 200 OK
    Date: Fri, 31 Dec 1999 23:59:59 GMT
    Content-Type: application/json
    Content-Length: ####

    [{"cons_id":"1", "cons_source_id":"4", "prefix":"", "firstname":"Joel", "middlename":"", "lastname":"Barciauskas", "suffix":"", "salutation":"", "gender":"", "birth_dt: 0000-00-00 00:00":"00", "title":"", "employer":"Blue State Digital", "occupation":"se", "income":"0.00", "source":"feb5post", "subsource":"OLWEB", "userid":"foobar@gmail.com", "password":"aaaaaaaaaaaaaaaaaaaaa", "is_validated":"0", "is_banned":"0", "change_password_next_login":"0", "create_dt: 2008-02-06 21:27":"30", "create_app":"signup_db_script", "create_user":"system", "modified_dt: 2011-05-11 00:32":"33", "modified_app":"signup_db_script", "modified_user":"system", "status":"1", "note":"102472629", "is_deleted":"0" },
    {"cons_id":"2", "cons_source_id":"4", "prefix":"", "firstname":"Joel2", "middlename":"", "lastname":"Barciauskas", "suffix":"", "salutation":"", "gender":"", "birth_dt: 0000-00-00 00:00":"00", "title":"", "employer":"Blue State Digital", "occupation":"se", "income":"0.00", "source":"feb5post", "subsource":"OLWEB", "userid":"foobar@gmail.com", "password":"aaaaaaaaaaaaaaaaaaaaa", "is_validated":"0", "is_banned":"0", "change_password_next_login":"0", "create_dt: 2008-02-06 21:27":"30", "create_app":"signup_db_script", "create_user":"system", "modified_dt: 2011-05-11 00:32":"33", "modified_app":"signup_db_script", "modified_user":"system", "status":"1", "note":"102472629", "is_deleted":"0" },
    {"cons_id":"3", "cons_source_id":"4", "prefix":"", "firstname":"Joel3", "middlename":"", "lastname":"Barciauskas", "suffix":"", "salutation":"", "gender":"", "birth_dt: 0000-00-00 00:00":"00", "title":"", "employer":"Blue State Digital", "occupation":"se", "income":"0.00", "source":"feb5post", "subsource":"OLWEB", "userid":"foobar@gmail.com", "password":"aaaaaaaaaaaaaaaaaaaaa", "is_validated":"0", "is_banned":"0", "change_password_next_login":"0", "create_dt: 2008-02-06 21:27":"30", "create_app":"signup_db_script", "create_user":"system", "modified_dt: 2011-05-11 00:32":"33", "modified_app":"signup_db_script", "modified_user":"system", "status":"1", "note":"102472629", "is_deleted":"0" }]
    

ExpressionEngine API Calls (expressionengine)

get_chapter_id

Gets the chapter ID associated with an ExpressionEngine site

Method: GET

URL: /page/api/expressionengine/get_chapter_id


    http://XYZ/page/api/expressionengine/get_chapter_id?site_id=1
    

Returns:

If we are able to retrieve the entity successfully, we will return a 200 OK response code and the ID as text

Example:


    HTTP/1.0 200 OK
    Date: Fri, 31 Dec 1999 23:59:59 GMT
    Content-Type: content-type: text/html
    Content-Length: ####

    1

Core API Calls (core)

get_config_collection

This api call will return the config collection associated with a chapter id.

Method: GET

URL: /page/api/core/get_config_collection

Parameters:


1

Returns:

Upon success, it will return the collection name. If the collection is not found the method will return a HTTP 409.

set_list

Given a JSON blob of key/value pairs, this api call will save the list in the database (which can be used elsewhere). The value associated with each key must be an array of values for that given key. Multiple lists may be set at once with this api call.

Method: GET

URL: /page/api/core/set_list

Parameters:


    {
        "funds":
        [
            "fund10",
            "fund20",
            "fund30",
            "fund40",
            "fund50"
        ],
        "appeal":
        [
            "appeal10",
            "appeal20",
            "appeal30",
            "appeal40",
            "appeal50"
        ],
        "campaign":
        [
            "campaign1",
            "campaign2",
            "campaign3",
            "campaign4",
            "campaign5"
        ]
    }
    

Returns:

Upon success, it will return the message ["SUCCESS"]

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=2&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=2&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=2&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=2&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=2&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=2&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=2&api_id=my_custom_app&api_ts=1274298526&api_mac=ecf927ac5dbcb825068838e5019f24204dabb0e6
get_form

This method gets all properties of the specified signup form.

Method: GET

URL: /page/api/signup/get_form

Parameters:

signup_form_id
The id of the signup form to get information for

Returns:

Returns an extended signup form record.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/signup/get_form?signup_form_id=1&api_ver=2&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=2&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=2&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=2&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>
    <email_opt_in>1</email_opt_in>
    <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>
    <source>Some event</source>
    <subsource>Some other source code</subsource>
  </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.

The email_opt_in parameter is only available on signup forms that have their email subscription set to 'User opt-in'

Version 1 of the API does not support source/subsource on signups. If you wish to use this functionality use version 2 (or newer).

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=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

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

get_signups_by_email

Returns the signup data associated with a given email

Method: GET

URL: /page/api/signup/get_signups_by_email

Parameters:

email (required)
Email address to look up signups for.

Returns:

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

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/signup/get_signups_by_email?email=email%40email.com&api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_signups_by_form_id

Returns the signup data associated with a given signup form. Up to 10,000 records will be returned at once. Pass in the optional 'page' parameter to page through the results.

Method: GET

URL: /page/api/signup/get_signups_by_form_id

Parameters:

signup_form_id (required)
Id of the signup form to look up signups for.
page (optional)
Dataset page to request (each page returns a maximum of 10,000 records)

Returns:

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

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/signup/get_signups_by_form_id?signup_form_id=1&api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
clone_form

Makes a copy of a signup form

Method: POST

URL: /page/api/signup/clone_form

Parameters:

signup_form_id (required)
The ID of the signup form to clone.
title (required)
The title of the new signup form.
signup_form_name (required)
The name of the new signup form.
slug (required)
The slug of the new signup form, used for url-based access.

The response is the ID of the newly created form:


            <signup_form>
                <id>1</id>
            </signup_form>
        

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/signup/clone_form?signup_form_id=1&api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
set_cons_group

Causes signups to get associated with a constituent group

Method: POST

URL: /page/api/signup/set_cons_group

Parameters:

signup_form_id
The ID of the signup form to associate with a constituent group. Either this or signup_form_field_id is required
signup_form_field_id
The ID of the signup form field to associate with a constituent group. Either this or signup_form_id is required

POST Parameters:

cons_group_id (required)
The ID of the constituent group to associated with the signup form or field.
Returns nothing.

Deferred Results: Never

Example:

URL:

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

Tag API Calls

update_tags_for_realm
This method adds a list of tags for a tag realm. Any tags within the realm that exist in the database but are not present in the request will be deleted.

Method: POST

URL: /page/api/tag/update_tags_for_realm

Parameters:

realm (required)

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

name (required)
description
external_id
integer
status (required)
boolean

Returns: A JSON object containing a property 'summary', which contains an object with properties 'added', 'updated', and 'deleted', with counts of affected tags.

Deferred Results: Always

Example:

URL:

http://XYZ/page/api/tag/update_tag_for_realm?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b&realm=tag_realm

POST:

[{"name":"tag1", "description":"tag1 description", "status":1},{"name":"tag2", "description":"tag2 description", "status":0}]

Event API Calls

search_events
Searches all the events and returns the future events unless specified by date_start.

Method: GET or POST

URL: /page/api/event/search_events

Parameters: (Optional)

event_id
event_type
host_name
day
date_start
date_end
create_day
create_date_start
create_date_end
country
zip
city
state
zip_radius
radius_unit
creator_cons_id
attendee_cons_id
order_field

Returns: A JSON object containing an array of event objects with following properties:

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/search_events?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
delete_event

Deletes given event_id event and notifies all attendees.

Method: GET or POST

URL: /page/api/event/delete_event

Parameters:

event_id (required)
The numeric id of the event.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Never

Example:

URL:

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

Returns list of all attendees 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.

Returns:

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

Deferred Results: Never

Example:

URL:

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

Method: GET or POST

URL: /page/api/event/create_event

Parameters:

event_api_version
The event API input JSON version number, the docs below assume version 2
values
The event API input JSON with the fields as detailed below

Version 2 JSON Parameters:

event_type_id (required)
creator_cons_id (required)
name (required / static if specified by given event type)
description (required, 50,000 character limit)
creator_name
local_timezone
venue_name (required)
venue_addr1
venue_addr2
venue_zip (required)
venue_city (required)
venue_state_cd (required)
venue_country
venue_directions
host_addr_addressee
host_addr_addr1
host_addr_addr2
host_addr_zip
host_addr_city
host_addr_state_cd
host_addr_country
host_receive_rsvp_emails
contact_phone
public_phone
attendee_visibility ('NONE'/'COUNT'/'FIRST')
attendee_require_phone
attendee_volunteer_show ('1'/'0'/'-1')
attendee_volunteer_message
is_official
pledge_override_type
pledge_show
pledge_source
pledge_subsource
pledge_require
pledge_min
pledge_max
pledge_suggest
rsvp_use_default_email_message ('1'/'0'/'-1')
rsvrp_email_message
rsvp_email_message_html
rsvp_use_reminder_email
rsvp_reminder_email_sent
rsvp_reminder_hours
rsvp_allow
rsvp_require_signup ('1'/'0'/'-1')
rsvp_disallow_account ('1'/'0'/'-1')
is_searchable
chapter_id
flag_approval
outreach_page_id
days
An array of days, each with the start_datetime_system, of the day and either a duration parameter or a shifts array as specified below. Example as follows:
[
    {
        'start_datetime_system': '2033-12-01 00:00:00',
        'duration': '120'
    },
    {
        'start_datetime_system': '2033-12-02 00:00:00',
        'shifts': [
            {
                'start_time':   '13:00:00',
                'end_time':     '14:00:00',
                'capacity'      '50'
            },
            {
                'start_time':   '13:00:00',
                'end_time':     '14:00:00',
                'capacity'      '50'
            }
        ]
    }
]
                    
shifts (a parameter for 'days')
An array of shifts, each with three params start_time, end_time, and capacity as follows:
[
    {
        'start_time':   '13:00:00',
        'end_time':     '14:00:00',
        'capacity'      '50'
    },
    {
        'start_time':   '13:00:00',
        'end_time':     '14:00:00',
        'capacity'      '50'
    }
]
                    

Returns: the same as get_event_details but for the created event.

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/create_event?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
update_event

Method: GET or POST

URL: /page/api/event/update_event

Parameters:

event_api_version
The event API input JSON version number, the docs below assume version 2
values
The event API input JSON with the fields as detailed below

Version 2 JSON Parameters:

event_id_obfuscated (required)
event_type_id (required)
creator_cons_id (required)
name (required / static if specified by given event type)
description (required)
creator_name
local_timezone
venue_name (required)
venue_addr1
venue_addr2
venue_zip (required)
venue_city (required)
venue_state_cd (required)
venue_country
venue_directions
host_addr_addressee
host_addr_addr1
host_addr_addr2
host_addr_zip
host_addr_city
host_addr_state_cd
host_addr_country
host_receive_rsvp_emails
contact_phone
public_phone
attendee_visibility ('NONE'/'COUNT'/'FIRST')
attendee_require_phone
attendee_volunteer_show ('1'/'0'/'-1')
attendee_volunteer_message
is_official
pledge_override_type
pledge_show
pledge_source
pledge_subsource
pledge_require
pledge_min
pledge_max
pledge_suggest
rsvp_use_default_email_message ('1'/'0'/'-1')
rsvrp_email_message
rsvp_email_message_html
rsvp_use_reminder_email
rsvp_reminder_email_sent
rsvp_reminder_hours
rsvp_allow
rsvp_require_signup ('1'/'0'/'-1')
rsvp_disallow_account ('1'/'0'/'-1')
is_searchable
chapter_id
flag_approval
outreach_page_id
days
An array of days, each with the start_datetime_system, of the day and either a duration parameter or a shifts array as specified below. Example as follows:
[
    {
        'start_datetime_system': '2033-12-01 00:00:00',
        'duration': '120'
    },
    {
        'start_datetime_system': '2033-12-02 00:00:00',
        'shifts': [
            {
                'start_time':   '13:00:00',
                'end_time':     '14:00:00',
                'capacity'      '50'
            },
            {
                'start_time':   '13:00:00',
                'end_time':     '14:00:00',
                'capacity'      '50'
            }
        ]
    }
]
                    
shifts (a parameter for 'days')
An array of shifts, each with three params start_time, end_time, and capacity as follows:
[
    {
        'start_time':   '13:00:00',
        'end_time':     '14:00:00',
        'capacity'      '50'
    },
    {
        'start_time':   '13:00:00',
        'end_time':     '14:00:00',
        'capacity'      '50'
    }
]
                    

Returns: the same as get_event_details but for the updated event

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/update_event?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_event_details

Returns information about a given event

Method: GET or POST

URL: /page/api/event/get_event_details

Parameters:

event_api_version
The event API input JSON version number, the docs below assume version 2
values
The event API input JSON with the fields as detailed below

Version 2 JSON Parameters:

event_id_obfuscated (required)
The event_id_obfuscated of the event.

Returns: A JSON object representing the event

Includes saved information about the event.

Special fields:

guest_count
The number of confirmed guests for each day of the event. If the event has shifts, then the guest_count parameter will appear on each shift object (and represent the confirmed guests for that shift) and not on their respective days.

Deferred Results: Never

Example:

{
        "event_id_obfuscated": "rtt",
        "event_type_id": "1",
        "creator_cons_id": "12",
        "outreach_page_id": null,
        "name": "Our Awesome Event!",
        "description": "It's an awesome event. Come visit.",
        "creator_name": "",
        "venue_name": "The Awesome House",
        "venue_addr1": "123 Fake Street",
        "venue_addr2": "",
        "venue_zip": "02210",
        "venue_city": "Boston",
        "venue_country": "US",
        "venue_directions": "",
        "latitude": "20.000000",
        "longitude": "-20.000000",
        "host_addr_addressee": "",
        "host_addr_addr1": "",
        "host_addr_addr2": "",
        "host_addr_zip": "",
        "host_addr_city": "",
        "host_addr_state_cd": "MA",
        "host_addr_country": "US",
        "host_receive_rsvp_emails": "0",
        "contact_phone": "",
        "public_phone": "0",
        "attendee_visibility": null,
        "attendee_require_phone": "0",
        "attendee_volunteer_show": "0",
        "attendee_volunteer_message": "",
        "is_official": "0",
        "pledge_override_type": "0",
        "pledge_show": "1",
        "pledge_source": null,
        "pledge_subsource": null,
        "pledge_require": "0",
        "pledge_min": "0",
        "pledge_max": "0",
        "pledge_suggest": "0",
        "rsvp_use_default_email_message": "1",
        "rsvp_email_message_html": null,
        "rsvp_use_reminder_email": "1",
        "rsvp_reminder_email_sent": "1",
        "rsvp_allow": "-1",
        "rsvp_require_signup": "-1",
        "rsvp_disallow_account": "-1",
        "is_searchable": "-2",
        "flag_approval": "0",
        "chapter_id": "1",
        "days": [
        {
            "start_dt": "2033-12-31 12:00:00",
            "duration": "120",
            "capacity": "0",
            "guest_count": 1
        }
    ],
        "local_timezone": "US/Pacific",
        "venue_state_code": "Leicestershire"
}

URL:

http://XYZ/page/api/event/get_event_details?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_event_parameter_details

Method: GET or POST

URL: /page/api/event/get_event_parameter_details

Parameters:

Returns:

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/get_event_parameter_details?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_create_event_requirements

Method: GET or POST

URL: /page/api/event/get_create_event_requirements

Parameters:

Returns:

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/get_create_event_requirements?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_update_event_requirements

Method: GET or POST

URL: /page/api/event/get_update_event_requirements

Parameters:

Returns:

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/get_update_event_requirements?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_events_for_cons

Method: GET or POST

URL: /page/api/event/get_events_for_cons

Parameters:

Returns:

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/get_events_for_cons?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b
get_available_types

Method: GET or POST

URL: /page/api/event/get_available_types

Parameters:

Returns:

Deferred Results: Never

Example:

URL:

http://XYZ/page/api/event/get_available_types?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

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.
stg_contribution_recurring_id
An existing stg_contribution_recurring record to associate this contribution with for reporting purposes.
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. Please optionally pass either contribution_page_slug or contribution_page_id but not both.
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']
opt_compliance
Determines whether the contributor's email address will be subscribed to the mailing list. Set to 0 to not subscribe donor. The default behavior when the opt_compliance flag is not sent will be to subscribe the donor.
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.
middlename
The contributor's middle name.
prefix
The contributor's name prefix.
suffix
The contributor's name suffix.
customFields
Custom fields must be associated with a contribution page; therefore either a valid contribution_page_id or contribution_page_slug must be provided for the custom fields to be meaningful.
An array of key/values that represent the custom field (the key), and the value for the field. For custom field with multi-checkbox type, the value is an array of the selected options.
For example, "custom4": {"Program A":1, "Program B":1, "Program C": 1}.

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: Sometimes (Depends on the number of contributions passed; at or below a configurable threshold, results will not be deferred. The default threshold is 1.)

URL:


http://XYZ/page/api/contribution/add_external_contribution?api_ver=2&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", "contribution_page_slug": "contribution_page_slug_name", "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":"US", "phone":"5555551234", "email":"jsmith@testperson.com", "source":["page1","page2"], "employer":"Acme Inc.", "occupation":"Engineer", "customFields":{"re_funds":"fund val","re_appeal":"appeal val","re_campaign":"campaign val","custom1":"RB3","custom3":"RB5","custom2":{"MC1":1, "MC3":1, "MC4":1,"MC5":1}} } ]

Response:

{ "summary": { "sucesses":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."] } }
get_contributions

Given a set of filters, this call will return a list of contribution records that fall in the range of the specified filters.

Method: GET

URL: /page/api/contribution/get_contributions

Parameters: GET data

filter (required)
An array of filters to apply to contribution records.

List of filters

date
Determines the date range of filters to display. Valid values are:
today
Show contributions for the current date
yesterday
Show contributions for yesterday
thisweek
Show contributions for this week
lastweek
Show contributions for last week
thismonth
Show contributions for this month
lastmonth
Show contributions for last month
thisquarter
Show contributions for this quarter
lastquarter
Show contributions for last quarter
ytd
Show contributions for the year to date
lastyear
Show contributions for last year
past24hours
Show contributions for the past 24 hours
past7days
Show contributions for the past 7 days
past30days
Show contributions for the past 30 days
past90days
Show contributions for the past 90 days
past12months
Show contributions for the past 12 months
custom
Use the date ranges specified in the query string params "start" and "stop." Date format is "YYYY-MM-DD HH:MM:SS." The timezone used for dates varies by client configuration, however, most clients will be UTC.
type
external
All external contributions
online
All online contributions (one-time and recurring)
one
Online one-time contributions
recur
Online recurring contributions
all
All contributions (online and external)
source[]
An array of eligible source codes
contribution_pages
A comma-delimited list of eligible contribution_page_ids

Returns:

A JSON object containg the an array of contribution objects with the following properties:

If the contribution was made in memory of somebody else, it will have the following extra fields: If membership is enabled, it will have the following extra fields:

Deferred Results: Always

URL:


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

Example filters:

?filter[date]=today
Show contributions from today
?filter[date]=?filter[date]=custom&filter[start]=2012-07-26%2000%3A00%3A00&filter[stop]=2012-07-26%2023%3A59%3A59
Show contributions from a specified time period (note: dates are url-encoded)
?filter[date]=thisweek&filter[type]=recur
Show all contributions from this week that were recurring
?filter[date]=thisweek&filter[source][]=banana
Show all contributions from this week that have a source of "banana"
?filter[date]=thisweek&filter[source][]=banana&filter[source][]=apple
Show all contributions from this week that have a source of "banana" or "apple"
?filter[source][]=apple&filter[contribution_pages]=1,2,3
Show all contributions with a source of "apple" from contribution pages 1, 2 or 3

Sample Response:

{ "contributions": [ { "stg_contribution_id": 1, "cons_id": 1, "date": "2012-07-19 00:05:55, "contribution_key": "GdAzDC9hHwYaQlszcY", "ip_address": "127.0.0.1", "prefix": null, "first_name": "John", "middle_name": null, "last_name": "Doe", "suffix": null, "email": "john@doe.com", "amount": "25.00", "tickets": null, "occupation": null, "employer": null, "phone": 1238675309, "addr1": "123 First Ave", "addr2": null, "city": "landville", "state_cd": "AA", "postal_code": "00000", "country": "AA", "card_type": "vs", "card_last_4": "0000", "custom1": null, "custom2": null, "custom3": null, "source": ["somepage"], "custom_country_field1": null, "custom_country_field2": null, "bill_ref_num": "74B49741TE455931Y", "page_name": "General donation page", "note": null, "outreach": null, "ext_id": null, "facebook": null } ] }
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=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

get_custom_form_fields

Gets a list of custom form fields for contribution pages

Method: POST

URL: /page/api/contribution/get_custom_form_fields

None

Returns:

XML with the following fields
  • app_form_id ID of the form that this is attached to
  • typeThe type of field, checkbox, text, etc.
  • settingsExtended settings. Notable here is "label" which is treated as the name of the field for display purposes
  • display_orderA numeric index for the order of display on this form.

Deferred Results: Never

URL:


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

Response

<app_form_field id="1" modified_dt="1223651690"> <app_form_id>1</app_form_id> <type>text</test> <settings> <label><![CDATA[Program]]></label> <valueIfBlank><![CDATA[General]]></valueIfBlank> </settings> <display_order>1</display_order> </app_form_field>
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. If the transaction is monthly, the day needs to be between 1-28.
external_recurring
Default 0. If this is set to 1, BSD will not attempt to charge the contribution automatically. This option will also be automatically set if the gateway associated with the page slug has the corresponding external_recurring set. If this is set, the token_raw will automatically prepended with the text "ext_" before storing in the database.
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. Example:
"token_info":{ "account_last_four":"1111", "cc_type_cd":"vs", "cc_expir_month":"03", "cc_expir_year":"2020", "firstname":"David", "lastname":"Blackman-Mathis", "addr1":"711 Atlantic Ave", "addr2":"Suite 102", "city":"Boston", "state_cd":"MA", "zip":"02111", "country":"US", "email":"help@bluestatedigital.com", "phone":"2342342345", "employer":"na", "occupation":"na" }

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=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

            
cancel_recurring

Cancels a recurring contribution record by stg_contribution_recurring_id.

Method: POST

URL: /page/api/contribution/cancel_recurring

Parameters: POST data

stg_contribution_recurring_id (required)
The id of the record you want to cancel.

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 canceled stg_contribution_recurring record.

Deferred Results: Never

URL:


http://XYZ/page/api/contribution/cancel_recurring?api_ver=2&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=2&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=2&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=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf767

get_stg_contribution

Retrieve a stg_contribution by proc_request_id , it returns the transaction amount , charge_dt , created_dt and modified_dt

Method: GET

URL: /page/api/contribution/get_stg_contribution?proc_request_id=ch_h732lkfds9sf9ckjs

Parameters: GET

proc_request_id (required)
the request process id

Returns:

A JSON object containg four properties:
  • amount - The transaction amount.
  • charge_dt - Charge Date.
  • create_dt - Record Create Date.
  • modified_dt - Record Modification Date.
            
            http://XYZ/page/api/contribution/get_stg_contribution?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf767&proc_request_id=ch_19Im4bJ2y7ivS7q8lgfajyPv
            
            
record_refund

Refund a stg_contribution using the stg_contribution_id

Method: GET

URL: /page/api/contribution/record_refund?id=11

Parameters: GET

id (required)
the stg_contributin.stg_contribution_id
            
            http://XYZ/page/api/contribution/record_refund?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf767&id=11
            
            

Recurring Contribution API Calls

get by token

Given a charge token, this method will return metadata for recurring contributions.

Method: GET

URL: /page/api/contribution_recurring/get_by_token

Parameters: GET data

charge_token (required*)
string

Returns:

An array of JSON objects for each recurring contribution. The objects contain metadata about the recurring contribution.

Deferred Results: Never

URL:


http://XYZ/page/api/contribution_recurring/get_by_token?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b&charge_token=123456a1234

Response:

[{"stg_contribution_recurring_id": "4","last_bill_dt": "2016-11-21 21:07:30","next_bill_dt": "2016-12-21 21:07:30","bill_interval": "+1 month","email": "user@example.com","obfuscated_cc_number": "XXXXXXXXXXXX4242","cc_expir_month": "04","cc_expir_year": "2021","modified_dt": "2016-11-21 21:07:30","modified_user": null,"modified_app": null}, {"stg_contribution_recurring_id": "5","last_bill_dt": "2016-11-21 21:16:50","next_bill_dt": "2016-12-21 21:16:50","bill_interval": "+1 month","email": "user@example.com","obfuscated_cc_number": "4242XXXXXXXX4242","cc_expir_month": "05","cc_expir_year": "2019","modified_dt": "2016-11-21 21:16:50","modified_user": null,"modified_app": null}]

update_contributions

Update stored charge data for recurring contributions by stg_contribution_recurring_id.

Method: POST

URL: /page/api/contribution_recurring/update_contributions

POST Data should be formatted as a JSON object containing the following:

ids (required*)
array of stg_contribution_recurring_ids to update
charge_data (required*)
JSON object containing the following optional parameters:
  • cc_expir_month
  • cc_expir_year
  • cc_type_cd
  • addr1
  • addr2
  • city
  • state_cd
  • zip
  • country
  • cc_last_4

Returns:

An array of JSON objects for each updated recurring contribution. The objects contain metadata about the recurring contribution.

Deferred Results: Never

URL:


http://XYZ/page/api/contribution_recurring/update_contributions?api_ver=2&api_id=my_custom_app&api_ts=1274298735&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

POST:

{"ids": [4,5],"charge_data": {"cc_expir_month":"06","cc_expir_year":"2020","cc_type_cd":"vs","addr1":"123 Fake St.","addr2":"","city":"New York","state_cd":"NY","zip":"10013","country":"usa","cc_last_4":1234}}

Response:

[{"stg_contribution_recurring_id":"4","last_bill_dt":"2016-11-21 21:07:30","next_bill_dt":"2016-12-21 21:07:30","bill_interval":"+1 month","email":"user@example.com","obfuscated_cc_number":"XXXXXXXXXXXX1234","cc_expir_month":"06","cc_expir_year":"2020","modified_dt":"2016-11-28 18:14:24","modified_user":null,"modified_app":null},{"stg_contribution_recurring_id":"5","last_bill_dt":"2016-11-21 21:16:50","next_bill_dt":"2016-12-21 21:16:50","bill_interval":"+1 month","email":"user@example.com","obfuscated_cc_number":"4242XXXXXXXX1234","cc_expir_month":"06","cc_expir_year":"2020","modified_dt":"2016-11-28 18:14:24","modified_user":null,"modified_app":null}]

Mailer API Calls

get_stats

Given a list of mailing IDs or a list of mailing send IDs, this method will return the mailing stats for each mailing.

Method: GET

URL: /page/api/mailer/get_stats

Parameters: GET data

mailing_ids (required*)
A comma separated list of mailing IDs that stats are requested for
mailing_send_ids (required*)
A comma separated list of mailing send IDs that stats are requested for
stats_mode (optional)
Either 'unique' or 'total'. If not provided, both stats will be returned

* Only one of mailing_ids or mailing_send_ids is required

Returns:

An array of JSON objects for each matched mailing that has at least been prepped. The objects contain mailing stats data along with basic details about each mailing.

URL:


http://XYZ/page/api/mailer/get_stats?api_ver=2&api_id=my_custom_app&api_ts=1274298735&mailing_ids=2,3&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

Response:

[ { "mailing_id":2, "mailing_send_id":7, "mailing_name":"Testing Stats API", "subject":"Hi Friend!", "sent_dt":"2012-10-26 14:41:41", "from_name":"Test Mailer", "from_email":"user@example.com", "recipient_count":1, "number_unique_opens":1, "number_unique_clicks":0, "number_total_opens":1, "number_total_clicks":6, "number_unsubs":0 }, { "mailing_id":3, "mailing_send_id":2, "mailing_name":"Links2", "subject":"Hi Friend!", "sent_dt":"2012-10-18 16:52:53", "from_name":"Test Mailer", "from_email":"user@example.com", "recipient_count":234324, "number_unique_opens":12344, "number_unique_clicks":3452, "number_total_opens":14555, "number_total_clicks":4232, "number_unsubs":14 } ]

URL:


http://XYZ/page/api/mailer/get_stats?api_ver=2&api_id=my_custom_app&api_ts=1274298735&mailing_ids=4&stats_mode=unique&api_mac=95ed2067d75a49943b851c88c84fccbf7673281b

Response:

[ { "mailing_id":4, "mailing_send_id":7, "mailing_name":"Testing Stats API", "subject":"Hi Friend!", "sent_dt":"2012-10-26 14:41:41", "from_name":"Test Mailer", "from_email":"user@example.com", "recipient_count":1, "number_opens":1, "number_clicks":0, "number_unsubs":0 } ]
get_recipients

This method takes a pair mailing id/mailing send id and returns a list of the constituent ids that are recipients for the corresponding mailing. The result is a text file with one constituent id per line.

Important: because of the potential time involved in retrieving a large volume of recipients, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/mailer/get_recipients

Parameters:

mailing_id (required)
The numeric id of the mailing id of the mailing.
mailing_send_id (required)
The numeric id of the mailing send id of the mailing.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

			
			http://XYZ/page/api/mailer/get_recipients?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&mailing_id=7&mailing_send_id=18
			
			

POST:

				
				mailing_id=7&mailing_send_id=18
				
			
get_raw

This method takes a type ('opens' or 'clicks') and a mailing_send_id as required input parameters. It can also take optional start & end date times for bounded time window. It returns an public URL to a csv file that contains a list of the constituent ids and epoch time of either opens or clicks corresponds to the mailing. The result is a text file in csv format with one constituent id and epoch time per line.

Important: because of the potential time involved in retrieving a large volume of opens or clicks, the final result code of this call is always deferred.

Method: GET or POST

URL: /page/api/mailer/get_raw

Parameters:

type (required)
There are only two types that are currently recognized, opens and clicks.
mailing_send_id (required)
The numeric id of the mailing send id of the mailing.
start (optional)
The start date & time of the time window that you are interested in. For example, 12-1-2014 10:00:00.
end (optional)
The end date & time of the time window that you are interested in.

Returns:

Returns an HTTP status code indicating success or failure.

Deferred Results: Always

Example:

URL:

			
			http://XYZ/page/api/mailer/get_raw?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&type=opens&mailing_send_id=18
			
			

POST:

				
				type=opens&mailing_send_id=18
				
			
send_triggered_email

This method immediately sends an email to the provided email address. Be sure to specify the api_ver in your request as this method is only available in version 2. See Common API Parameters

Method: GET or POST
URL: /page/api/mailer/send_triggered_email

Parameters:

mailing_id (required)
The obfuscated id of the triggered mailing.
email (required)
Recipient’s valid email address.
email_opt_in (optional)
Create new constituents as unsubscribed if set to 0. Defaults to 1.

Returns:

Returns an HTTP status code indicating success or failure. If successful, an obfuscated triggered_mailing_id will also be returned.

Response code outline:

Scenario HTTP
Code
HTTP
Status
Headers Body
Cons exists and is unsub'd 403 Forbidden Errors structure w/ e-mail field and message
Mailing is disabled 403 Forbidden Errors structure w/ mailing_id field and message
Mailing doesn't exist 403 Forbidden Errors structure w/ mailing_id field and message
Mailing is not triggered 403 Forbidden Errors structure w/ mailing_id field and message
Cons creation failed 500 Server Error Errors message
Invalid e-mail 400 Bad Request Errors structure w/ e-mail field and message
Missing mailing ID 400 Bad Request Errors structure w/ mailing_id field and message
Missing e-mail 400 Bad Request Errors structure w/ e-mail field and message
Failed allocating recipient ID 500 Server Error Error Message
Failed creating unique recipient 500 Server Error Error Message
Failed adding to queue 500 Server Error Error message
Success 202 Accepted Location header w/ status check endpoint URL Obfuscated mailing_triggered_id

Deferred Results: Never

Example:

URL:

            
                http://XYZ/page/api/mailer/send_triggered_email?api_id=my_custom_app&api_ts=1179943123&api_mac=7c2b2e1f825c8946ce9e3bb8607c58ac27cb5171&mailing_id=VFw&email=bsmith@somecompany.com
            
            

POST:

                 
                    mailing_id=VFw&email=bsmith@somecompany.com
                
            

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=2&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=2&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:

$api_mac = hash_hmac('sha1', $signing_string, $api_secret);

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)

C#:

using System;
using System.Security.Cryptography;
using System.Text;
using System.IO;

System.Text.UTF8Encoding encoding = new System.Text.UTF8Encoding();
byte[] api_bytes = encoding.GetBytes(api_secret);
HMACSHA1 hmac = new HMACSHA1(api_bytes);
Stream s = new MemoryStream(ASCIIEncoding.Default.GetBytes(signing_string));
byte[] hash = hmac.ComputeHash(s);
string api_mac = System.Convert.ToBase64String(hash);

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=2&api_id=my_custom_app&api_ts=1179962001&api_mac=955e6266d18921a25feb2bebeaa8d5e2bfb518c4&ext_type=van_id&ext_ids=12772,1129,1983321

Code Samples and Libraries

API Libraries

We maintain API libraries in several languages on GitHub. For example:

There are additional resources available - just check out our GitHub profile

Required Functions

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.

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.
429 Too many requests
You have exceeded the BSD Tools API rate limit. A retry-after header will be sent with this response, indicating in how many seconds you may resume making API calls.
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.