Introduction

Welcome to the ControlShift Labs Developer documentation. Our APIs are designed to allow software engineers to create rich integrations between ControlShift content and third-party services and websites.

We offer several APIs to customers to cover different integration use cases.

• JSONP API Unauthenticated API designed to be consumed by javascript clients written by front-end engineers. Quickly display public information about petitions, efforts, and users on external sites.

• Webhooks Get notified when changes happen so external systems can react.

• Bulk Data Integrate your ControlShift instance with a data warehouse like Redshift for SQL access and reporting.

• Authenticated REST Server Side API integration option for more advanced scenarios. Uses OAuth2 to allow third-party developers to create applications and customers to grant access.

JSON API Endpoints

The JSONP API is a simple way to embed ControlShift petition content in external sites. It's intended for use by a front-end developer embed content on web pages outside of the platform. For example, a developer could:

• Show petitions
• Allow a user to search for near by petitions
• List petition categories
• Show petitions within an effort
• If a site visitor is logged in, show a users past actions and created petitions

All of the endpoints can be consumed as JSONP instead of JSON by adding callback or variable parameters to the URLs.

The URL slugs through the API are the same as those that are used through the web to represent specific petitions or categories. Many front-end libraries including jQuery make it easy to consume JSONP endpoints. Our examples below use jQuery to consume these resources.

Get a single petition

$(document).ready(function(){
  var petitionSlug = 'repair-the-yellow-brick-road-1';
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/petitions/'+petitionSlug+'.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would display your returned petition data in the console. The JSON response data would be structured like this:

{
  "id": 92283,
  "title": "Repair the Yellow Brick Road",
  "slug": "repair-the-yellow-brick-road-1",
  "who": "Oz, the Great and Terrible, Wizard",
  "what": "The Yellow Brick Road has been neglected; commit to repairing the damaged sections of the road in the next year!",
  "why": "The Yellow Brick Road is the main road connecting Munchkin Country to the Emerald City and in its current state it's impassable.",
  "created_at": "2014-10-02T01:43:17Z",
  "updated_at": "2018-05-07T15:38:39Z",
  "delivery_details": "We're off to see the wizard!",
  "administered_at": "2018-03-21T19:05:54Z",
  "source": "homepage",
  "alias": null,
  "categories": [
    {
      "name": "Oz",
      "slug": "oz"
    }
  ],
  "goal": 500,
  "effort": null,
  "partnership": null,
  "group": null,
  "resized_image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/hero/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741",
  "image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/original/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741",
  "creator_name": "Kristyn Arrighi",
  "signature_count": 223,
  "location": {
    "latitude":"36.1946827",
    "longitude":"-78.8087571",
    "query":"Land of Oz",
    "venue":"Land of OZ",
    "street_number":"1007",
    "street":"Beech Mountain Pkwy",
    "street_address":"1007 Beech Mountain Pkwy",
    "locality":"Beech Mountain",
    "region":"NC",
    "postal_code":"28604",
    "country":"US",
    "country_code":"US",
    "country_name":"United States",
    "static_map_url":"https://d8s293fyljwh4.cloudfront.net/locations/static_maps/27575/27575-static-map.png?1532035340"
  }
}

Note: The "group" key is deprecated and will be removed soon. Code should be updated to use the "partnership" key instead.

This retrieves a single petition object.

HTTP Request

GET https://demo.controlshiftlabs.com/petitions/<slug>.json

Query Parameters

Working Example

View and edit a working example on codepen.io:

    $(document).ready(function(){
      var petitionSlug = 'repair-the-yellow-brick-road-1';
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/petitions/'+petitionSlug+'.json',
        dataType: 'jsonp',
      })
      .done(function(data) {
        $('#title').html(data.title);
        $('#signature_count').html(data.signature_count);
        $('#creator_name').html(data.creator_name);
        $('#what').html(data.what);
        $('#who').html(data.who);
        $('#why').html(data.why);
        $('#js-content-wrapper').removeClass('hidden');
      });
    });
  

Get featured petitions

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/petitions/featured.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would display your returned featured petitions data in the console. The JSON would be structured like this:

{
  "meta": {
    "total_pages": 3,
    "total_entries": 25,
    "per_page": 10
  },
  "data": [
    {
      "slug": "repair-the-yellow-brick-road-1",
      "url": "http://demo.controlshiftlabs.com/petitions/repair-the-yellow-brick-road-1",
      "title": "Repair the Yellow Brick Road",
      "who": " Oz, the Great and Terrible, Wizard",
      "what": "The Yellow Brick Road has been neglected; commit to repairing the damaged sections of the road in the next year!",
      "why": "The Yellow Brick Road is the main road connecting Munchkin Country to the Emerald City and in its current state it's impassable.",
      "admin_status": "good",
      "signature_count": 223,
      "goal": 500,
      "creator_name": "Kristyn Arrighi",
      "locale": "en",
      "successful": false,
      "ended": false,
      "created_at": "2014-10-02T01:43:17Z",
      "updated_at": "2018-05-07T15:38:39Z",
      "image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/hero/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741",
      "additional_image_sizes_url": [
        {
          "style": "original",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/original/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "form",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/form/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "horizontal",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/horizontal/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "open_graph",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/open_graph/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        }
      ],
      "target": {
        "name": " Oz, the Great and Terrible",
        "slug": "oz-the-great-and-terrible",
        "context": "Wizard",
        "location": {
          "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
          "latitude": "42.9399637",
          "longitude": "-78.8087571",
          "street": "Kensington Ave",
          "postal_code": "",
          "country": "US",
          "region": "NY",
          "street_number": "",
          "venue": "",
          "created_at": "2016-06-10T19:13:19Z"
        }
      },
      "location": {
        "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
        "latitude": "42.9399637",
        "longitude": "-78.8087571",
        "street": "Kensington Ave",
        "postal_code": "",
        "country": "US",
        "region": "NY",
        "street_number": "",
        "venue": "",
        "created_at": "2016-06-10T19:13:19Z"
      }
    },
    {
      "slug": "we-need-more-bike-lanes",
      "title": "We Need More Bike Lanes",
      "who": "My Mayor",
      "what": "Build the bike lanes",
      "why": "Cyclists aren't safe.",
      "admin_status": "good",
      "signature_count": 5,
      "goal": 100,
      "creator_name": "Greg Dutcher",
      "locale": "en",
      "successful": false,
      "ended": false,
      "created_at": "2016-08-12T18:08:32Z",
      "updated_at": "2016-09-14T12:43:45Z",
      "image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/167492/original/IMG_1854.JPG?1472046912",
      "additional_image_sizes_url": [
      ]
        {
          "style": "original",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/167492/original/IMG_1854.JPG?1473884741"
        },
        {
          "style": "form",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/167492/form/IMG_1854.JPG?1473884741"
        },
        {
          "style": "horizontal",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/167492/horizontal/IMG_1854.JPG?1473884741"
        },
        {
          "style": "open_graph",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/167492/open_graph/IMG_1854.JPG?1473884741"
        }
      ],
      "location": {
        "query": "New York",
        "latitude": "40.6974034",
        "longitude": "-74.1197633",
        "street": "",
        "postal_code": "",
        "country": "US",
        "region": "NY",
        "street_number": "",
        "venue": "New York",
        "created_at": "2017-04-11T13:32:08Z"
      }
    }
  ],
  "links": {
    "self": "https://demo.controlshiftlabs.com/petitions/featured.json?page=1",
    "first": "https://demo.controlshiftlabs.com/petitions/featured.json",
    "prev": null,
    "next": "https://demo.controlshiftlabs.com/petitions/featured.json?page=2",
    "last": "https://demo.controlshiftlabs.com/petitions/featured.json?page=3"
  }
}

This retrieves a JSON object compliant with the JSON API specification, containing an array of featured petitions objects on its data property.

Important Note: The previous featured petitions API endpoint at https://demo.controlshiftlabs.com/featured.json (note the missing /petitions path) is being deprecated and will be removed in the near future. Please use this new endpoint for retrieving featured petitions from now on.

HTTP Request

GET https://demo.controlshiftlabs.com/petitions/featured.json

Query Parameters

Working Example

View and edit a working example on codepen.io:

    $(document).ready(function(){
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/petitions/featured.json',
        dataType: 'jsonp',
      })
      .done(function(resp) {
        var $placeholder = $('#featured-petitions');
        $.each(resp.data, function(index, petition){
          output = '
'
          output += ''+petition.title+'';
          output += '
'+petition.signature_count+' signatures out of '+petition.goal+' needed 
';
          output += '
'+petition.why+'
';
          output += '
Learn More
';
          output += '
';
          $placeholder.append(output);
        });
      });
    });
  

Get list of categories

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/categories.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would display a list of categories in the console. The JSON would be structured like this:

[
  {
    "category_name": "Education",
    "category_count": 18,
    "slug": "education-9",
    "url": "https://demo.controlshiftlabs.com/categories/education-9.json",
    "signature_count": 421,
    "locales": {
      "es": "Educación"
    }
  },
  {
    "category_name": "Environment",
    "category_count": 352,
    "slug": "environment-6",
    "url": "https://demo.controlshiftlabs.com/categories/environment-6.json",
    "signature_count": 2606,
    "locales": {
      "es": "Medio Ambiente"
    }
  }
]

This retrieves a JSON array of category objects.

HTTP Request

GET https://demo.controlshiftlabs.com/categories.json

Working Example

View and edit a working example on codepen.io:

    $(document).ready(function(){
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/categories.json',
        dataType: 'jsonp',
      })
      .done(function(data) {
        var $placeholder = $('#categories');
        $.each(data, function(index, category){
          output = ''+category.category_name+'';
          output += '
'
          output += '
Slug: '+category.slug+'
';
          output += '
Signatures:'+category.signature_count+'
';
          output += '
API URL:'+category.url+'
';
          output += '
';
          $placeholder.append(output);
        });
      });
    });
  

List petitions in a category

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/categories/oz.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would return petitions data from the category with the slug oz. The JSON would be structured like this:

{
  "current_page": 1,
  "total_pages": 25,
  "previous_page": null,
  "next_page": 2,
  "name": "Oz",
  "results": [
    {
      "slug": "let-dorothy-go-home",
      "url": "http://demo.controlshiftlabs.com/petitions/let-dorothy-go-home",
      "title": "Let Dorothy Go Home!",
      "who": " Oz, the Great and Terrible, Wizard",
      "what": "Let poor Dorothy Gale go home to Kansas",
      "why": "There's no place like home.",
      "admin_status": "good",
      "signature_count": 123,
      "goal": 200,
      "creator_name": "Tin Man",
      "locale": "en",
      "successful": false,
      "ended": false,
      "created_at": "2015-12-02T01:43:17Z",
      "updated_at": "2017-05-07T15:38:39Z",
      "image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/hero/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741",
      "additional_image_sizes_url": [
        {
          "style": "original",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/original/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "form",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/form/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "horizontal",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/horizontal/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "open_graph",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/open_graph/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        }
      ],
      "target": {
        "name": " Oz, the Great and Terrible",
        "slug": "oz-the-great-and-terrible",
        "context": "Wizard",
        "location": {
          "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
          "latitude": "42.9399637",
          "longitude": "-78.8087571",
          "street": "Kensington Ave",
          "postal_code": "",
          "country": "US",
          "region": "NY",
          "street_number": "",
          "venue": "",
          "created_at": "2016-06-10T19:13:19Z"
        }
      }
    },
    {
      "slug": "repair-the-yellow-brick-road-1",
      "url": "http://demo.controlshiftlabs.com/petitions/repair-the-yellow-brick-road-1",
      "title": "Repair the Yellow Brick Road",
      "who": " Oz, the Great and Terrible, Wizard",
      "what": "The Yellow Brick Road has been neglected; commit to repairing the damaged sections of the road in the next year!",
      "why": "The Yellow Brick Road is the main road connecting Munchkin Country to the Emerald City and in its current state it's impassable.",
      "admin_status": "good",
      "signature_count": 223,
      "goal": 500,
      "creator_name": "Kristyn Arrighi",
      "locale": "en",
      "created_at": "2014-10-02T01:43:17Z",
      "updated_at": "2018-05-07T15:38:39Z",
      "image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/hero/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741",
      "additional_image_sizes_url": [
        {
          "style": "original",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/original/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "form",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/form/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "horizontal",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/horizontal/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "open_graph",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/open_graph/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        }
      ],
      "target": {
        "name": " Oz, the Great and Terrible",
        "slug": "oz-the-great-and-terrible",
        "context": "Wizard",
        "location": {
          "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
          "latitude": "42.9399637",
          "longitude": "-78.8087571",
          "street": "Kensington Ave",
          "postal_code": "",
          "country": "US",
          "region": "NY",
          "street_number": "",
          "venue": "",
          "created_at": "2016-06-10T19:13:19Z"
        }
      },
      "location": {
        "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
        "latitude": "42.9399637",
        "longitude": "-78.8087571",
        "street": "Kensington Ave",
        "postal_code": "",
        "country": "US",
        "region": "NY",
        "street_number": "",
        "venue": "",
        "created_at": "2016-06-10T19:13:19Z"
      }
    }
  ]
}

This retrieves a paginated list of petitions in a category.

HTTP Request

GET https://demo.controlshiftlabs.com/categories/<category slug>.json

Query Parameters

Working Example

View and edit a working example on codepen.io:

    $(document).ready(function(){
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/categories/mice.json',
        dataType: 'jsonp',
      })
      .done(function(data) {
        // Populate global category data
        $('#name').text(data.name);

        // Populate petitions data
        var $placeholder = $('#petitions');
        $.each(data.results, function(index, petition){
          output = ''+petition.title+'';
          output += '
';
          output += '
Image: '+petition.image_url+'
';
          output += '
Who: '+petition.who+'
';
          output += '
What: '+petition.what+'
';
          output += '
Why: '+petition.why+'
';
          output += '
Signatures: '+petition.signature_count+'
';
          output += '
URL: '+petition.url+'
';
          output += '
';
          $placeholder.append(output);
        });
      });
    });
  

List petitions in a partnership

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/partnerships/our-awesome-partner/petitions.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would return petitions data from the partnership with the slug our-awesome-partner. The JSON would be structured like this:

{
  "current_page": 1,
  "total_pages": 25,
  "previous_page": null,
  "next_page": 2,
  "name": "Oz",
  "results": [
    {
      "slug": "let-dorothy-go-home",
      "url": "http://demo.controlshiftlabs.com/petitions/let-dorothy-go-home",
      "title": "Let Dorothy Go Home!",
      "who": " Oz, the Great and Terrible, Wizard",
      "what": "Let poor Dorothy Gale go home to Kansas",
      "why": "There's no place like home.",
      "admin_status": "good",
      "signature_count": 123,
      "goal": 200,
      "creator_name": "Tin Man",
      "locale": "en",
      "successful": false,
      "ended": false,
      "created_at": "2015-12-02T01:43:17Z",
      "updated_at": "2017-05-07T15:38:39Z",
      "image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/hero/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741",
      "additional_image_sizes_url": [
        {
          "style": "original",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/original/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "form",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/form/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "horizontal",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/horizontal/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "open_graph",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/open_graph/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        }
      ],
      "target": {
        "name": " Oz, the Great and Terrible",
        "slug": "oz-the-great-and-terrible",
        "context": "Wizard",
        "location": {
          "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
          "latitude": "42.9399637",
          "longitude": "-78.8087571",
          "street": "Kensington Ave",
          "postal_code": "",
          "country": "US",
          "region": "NY",
          "street_number": "",
          "venue": "",
          "created_at": "2016-06-10T19:13:19Z"
        }
      }
    },
    {
      "slug": "repair-the-yellow-brick-road-1",
      "url": "http://demo.controlshiftlabs.com/petitions/repair-the-yellow-brick-road-1",
      "title": "Repair the Yellow Brick Road",
      "who": " Oz, the Great and Terrible, Wizard",
      "what": "The Yellow Brick Road has been neglected; commit to repairing the damaged sections of the road in the next year!",
      "why": "The Yellow Brick Road is the main road connecting Munchkin Country to the Emerald City and in its current state it's impassable.",
      "admin_status": "good",
      "signature_count": 223,
      "goal": 500,
      "creator_name": "Kristyn Arrighi",
      "locale": "en",
      "successful": false,
      "ended": false,
      "created_at": "2014-10-02T01:43:17Z",
      "updated_at": "2018-05-07T15:38:39Z",
      "image_url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/hero/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741",
      "additional_image_sizes_url": [
        {
          "style": "original",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/original/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "form",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/form/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "horizontal",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/horizontal/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        },
        {
          "style": "open_graph",
          "url": "https://d8s293fyljwh4.cloudfront.net/petitions/images/92283/open_graph/2016-06-20-1466458252-1098096-ywllowbrickroad.jpg?1473884741"
        }
      ],
      "target": {
        "name": " Oz, the Great and Terrible",
        "slug": "oz-the-great-and-terrible",
        "context": "Wizard",
        "location": {
          "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
          "latitude": "42.9399637",
          "longitude": "-78.8087571",
          "street": "Kensington Ave",
          "postal_code": "",
          "country": "US",
          "region": "NY",
          "street_number": "",
          "venue": "",
          "created_at": "2016-06-10T19:13:19Z"
        }
      },
      "location": {
        "query": "Land of Oz, Kensington Avenue, Buffalo, NY, United States",
        "latitude": "42.9399637",
        "longitude": "-78.8087571",
        "street": "Kensington Ave",
        "postal_code": "",
        "country": "US",
        "region": "NY",
        "street_number": "",
        "venue": "",
        "created_at": "2016-06-10T19:13:19Z"
      }
    }
  ]
}

This retrieves a paginated list of petitions in a partnership.

HTTP Request

GET https://demo.controlshiftlabs.com/partnerships/<partnership slug>/petitions.json

Query Parameters

Working Example

View and edit a working example on codepen.io:

    $(document).ready(function(){
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/partnerships/rtm-roundtable-of-mice/petitions.json',
        dataType: 'jsonp',
      })
      .done(function(data) {
        // Populate global partnership data
        $('#name').text(data.name);

        // Populate petitions data
        var $placeholder = $('#petitions');
        $.each(data.results, function(index, petition){
          output = ''+petition.title+'';
          output += '
';
          output += '
Image: '+petition.image_url+'
';
          output += '
Who: '+petition.who+'
';
          output += '
What: '+petition.what+'
';
          output += '
Why: '+petition.why+'
';
          output += '
Signatures: '+petition.signature_count+'
';
          output += '
URL: '+petition.url+'
';
          output += '
';
          $placeholder.append(output);
        });
      });
    });
  

List petitions in an effort

$(document).ready(function(){
  var effortSlug = 'drivers-licenses-for-all';
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/efforts/'+effortSlug+'.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would return petitions data from the effort with the slug drivers-licenses-for-all. The JSON would be structured like this:

{
  "title": "Drivers' Licenses for All",
  "slug": "drivers-licenses-for-all",
  "description": "We're asking towns and villages across New York to pass resolutions in support of the Drivers' License bill. Anyone who can pass a driving test should be able to get a license.",
  "goal": 1000,
  "signature_count": 511,
  "petitions": [
    {
      "slug": "ossining-support-drivers-licenses-for-all",
      "url": "http://demo.controlshiftlabs.com/petitions/ossining-support-drivers-licenses-for-all",
      "title": "Ossining: Support Drivers' Licenses For All",
      "who": "Ossining Village Board of Trustees",
      "what": "Pass a resolution in support of the Drivers' Licenses bill",
      "why": "Undocumented immigrants need access to drivers' licenses so they can drive to work, school, and everywhere else. This will improve road safety for everyone.",
      "admin_status": "good",
      "signature_count": 223,
      "goal": 500,
      "creator_name": "Jacinda Moore",
      "locale": "en",
      "successful": false,
      "ended": false,
      "created_at": "2016-10-02T01:43:17Z",
      "updated_at": "2016-10-07T15:38:39Z",
      "target": {
        "name": "Ossining Village Board of Trustees",
        "slug": "ossining-village-board-of-trustees",
        "context": "",
        "location": {
          "query": "Ossining",
          "latitude": "41.1617921",
          "longitude": "-73.8874165",
          "street": "",
          "postal_code": "10562",
          "country": "US",
          "region": "NY",
          "street_number": "",
          "venue": "",
          "created_at": "2016-06-10T19:13:19Z"
        }
      },
      "location": {
        "query": "Ossining",
        "latitude": "41.1617921",
        "longitude": "-73.8874165",
        "street": "",
        "postal_code": "10562",
        "country": "US",
        "region": "NY",
        "street_number": "",
        "venue": "",
        "created_at": "2016-06-10T19:13:19Z"
      }
    },
    {
      "slug": "yonkers-support-drivers-licenses-for-all",
      "url": "http://demo.controlshiftlabs.com/petitions/yonkers-support-drivers-licenses-for-all",
      "title": "Yonkers: Support Drivers' Licenses For All",
      "who": "Yonkers City Council",
      "what": "Pass a resolution in support of the Drivers' Licenses bill",
      "why": "Undocumented immigrants need access to drivers' licenses so they can drive to work, school, and everywhere else. This will improve road safety for everyone.",
      "admin_status": "good",
      "signature_count": 300,
      "goal": 500,
      "creator_name": "Jacinda Moore",
      "locale": "en",
      "successful": true,
      "ended_story": "We did it, we won!",
      "ended": true,
      "ended_type": "won",
      "ended_reason": "Campaigner said they won the campaign",
      "created_at": "2016-10-02T01:43:17Z",
      "updated_at": "2016-10-07T15:38:39Z",
      "target": {
        "name": "Yonkers City Council",
        "slug": "yonkers-city-council",
        "context": "",
        "location": {
          "query": "Yonkers",
          "latitude": "40.9443748",
          "longitude": "-73.8993138",
          "street": "",
          "postal_code": "10701",
          "country": "US",
          "region": "NY",
          "street_number": "",
          "venue": "",
          "created_at": "2016-06-10T19:13:19Z"
        }
      },
      "location": {
        "query": "Yonkers",
        "latitude": "40.9443748",
        "longitude": "-73.8993138",
        "street": "",
        "postal_code": "10701",
        "country": "US",
        "region": "NY",
        "street_number": "",
        "venue": "",
        "created_at": "2016-06-10T19:13:19Z"
      }
    }
  ]
}

This retrieves a list of petitions in an effort.

Ended petitions will have the ended attribute set to true and will also include the following additional attributes:

• ended_type: with values "won", "lost" and "other" as set from petition Admin page.
• ended_reason: with private reason for ending set from petition Admin page.

Additionally, successful petitions will have the successful attribute set to true and will include the following additional attribute:

• ended_story: with ended story from petition Settings / Admin pages.

HTTP Request

GET https://demo.controlshiftlabs.com/efforts/<effort slug>.json

Working Example

View and edit a working example on codepen.io:

    $(document).ready(function(){
      var effortSlug = 'forecast-the-facts';
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/efforts/'+effortSlug+'.json',
        dataType: 'jsonp',
      })
      .done(function(data) {
        // Populate global effort data
        $('#title').text(data.title);
        $('#description').text(data.description);

        // Populate petitions data
        var $placeholder = $('#petitions');
        $.each(data.petitions, function(index, petition){
          output = ''+petition.title+'';
          output += '
';
          output += '
Image: '+petition.image_url+'
';
          output += '
Who: '+petition.who+'
';
          output += '
What: '+petition.what+'
';
          output += '
Why: '+petition.why+'
';
          output += '
Signatures: '+petition.signature_count+'
';
          output += '
Goal: '+petition.goal+'
';
          output += '
URL: '+petition.url+'
';
          output += '
Location: 
'
          output += '
Query: '+petition.location.query+'
';
          output += '
Latitude: '+petition.location.latitude+'
';
          output += '
Longitude: '+petition.location.longitude+'
';
          output += '
';
          output += '
';
          $placeholder.append(output);
        });
      });
    });
  

Search petitions in a effort

$(document).ready(function(){
  var effortSlug = 'drivers-licenses-for-all';
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/efforts/'+effortSlug+'/'+'lookup/query.json',
    dataType: 'jsonp',
    data: {
      'location_query': 'briarcliff manor, ny'
    }
  })
  .done(function( data ) {
    console.log(data);
  });
});

The above code would return petitions, decision makers, or objectives data from the effort with the slug drivers-licenses-for-all. If returning decision makers, the JSON would be structured like this:

{
  "closest_target": {
    "slug": "ossining-village-board-of-trustees",
    "name": "Ossining Village Board of Trustees",
    "context": "",
    "location": "Ossining, NY",
    "status": "target_petition_created",
    "petition": {
      "slug": "ossining-support-drivers-licenses-for-all",
      "title": "Ossining: Support Drivers' Licenses For All",
      "url": "http://demo.controlshiftlabs.com/petitions/ossining-support-drivers-licenses-for-all",
      "who": "Ossining Village Board of Trustees",
      "signature_count": 223,
      "goal": 500,
      "created_at": "2016-10-02T01:43:17Z",
      "updated_at": "2016-10-07T15:38:39Z",
    }
  },
  "other_targets": [
    {
      "slug": "yorktown-town-council",
      "name": "Yorktown Town Council",
      "context": "",
      "location": "Yorktown, NY",
      "status": "target_awaiting_petition",
      "create_petition_url": "https://demo.controlshiftlabs.com/efforts/drivers-licenses-for-all/petitions/creating?target_id=1234"
    }
  ]
}

This JSON endpoint allows you to build an interface where users can search the petitions in an effort. Depending on how the effort is configured, you can search either by location, or by keyword.

HTTP Request

GET https://demo.controlshiftlabs.com/efforts/<effort slug>/lookup/query.json

Query Parameters

Working Example

View and edit a working example on codepen.io:

    function buildPetition(target, description){
      output = ''+description+' Petition: '+target.name+'';
      output += '
'+target.location+'
 
';
      output += '
Title: '+target.petition.title+'
';
      output += '
Who: '+target.petition.who+'
';
      output += '
Goal: '+target.petition.goal+'
';
      output += '
Signatures so far: '+target.petition.signature_count+'
';
      output += '
';
      return output;
    }

    function performSearch(query) {
      // get the targets and petitions (if they exist) for the effort near the place specified.
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/efforts/forecast-the-facts/lookup/query.json',
        dataType: 'jsonp',
        data: {
          'location_query': query
        }
      })
      .done(function(data) {
        $placeholder = $('#petitions');
        if (data.code != undefined) {
          if ((data.code == 'no_nearby_targets') || (data.code == 'no_nearby_petitions')){
            $placeholder.html('No Petitions Found');
            return;
          } else if (data.code == 'location_required') {
            $placeholder.html('Location required');
            return;
          }
        }
        //populate closest target
        $placeholder.html( buildPetition(data.closest_target, 'Closest') );
        $.each(data.other_targets, function(index, other_petition){
          $placeholder.append( buildPetition(other_petition, 'Near By') );
        });
      });
    };

    $(document).ready(function(){
      var input = document.getElementById('effort-lookup-input');
      $('form').on('submit', function(e){
        e.preventDefault()

        var searchQuery = $(input).val()
        performSearch(searchQuery);
      });
    });
  

Get calendar data

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/calendars/national-day-of-action-against-fracking.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would display a calendar's properties the js console. The JSON would be structured like this:

{
   "calendar":{
      "name":"National Day of Action Against Fracking",
      "description":"This is the description. It will be great.",
      "slug":"national-day-of-action-against-fracking",
      "image_url":"https://d8s293fyljwh4.cloudfront.net/calendars/images/26/hero/Oak-tree-in-field-007.jpg?1450370489",
      "event_count":85,
      "attendee_count":19,
      "events_upcoming":10
   }
}

This retrieves a JSON object representing a calendar.

HTTP Request

GET https://demo.controlshiftlabs.com/calendars/slug.json

Where slug is the slug of the calendar you're retrieving.

Get organizing locations: points

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/api/local/points.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would retrieve point locations and log them to the js console. The JSON would be structured like this:

[
    {
        "lat": 40.7032775,
        "lon": -74.0170279,
        "type": "Event",
        "id": "picnic-in-the-park"
    },
    {
        "lat": 8.2710078,
        "lon": 148.0209055,
        "type": "Group",
        "id": "default-org-mariana-trench"
    },
    {
        "lat": 41.467116,
        "lon": -73.9992597,
        "type": "ExternalEvent",
        "id": "https://example.com/sail-on-the-hudson"
    }
]

This JSON endpoint returns a complete list of latitude/longitude coordinates for publicly listed events, groups, and external events in your organisation. It's intended to be used for plotting organizing activities on a map.

HTTP Request

GET https://demo.controlshiftlabs.com/api/local/points.json

Get organizing locations: details

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/api/local.json?page=1&per_page=3',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would retrieve one page of location data and log it to the js console. The JSON would be structured like this:

{
    "meta": {
        "count": 23,
        "page": 1,
        "per_page": 3,
        "total_pages": 8
    },
    "data": [
        {
            "type": "Event",
            "id": "picnic-in-the-park",
            "title": "Picnic in the Park",
            "description": "We are having a picnic in the park and you are invited!",
            "start_at": "2020-03-01T12:00:00Z"
        },
        {
            "type": "Group",
            "id": "default-org-mariana-trench",
            "title": "Default Org: Mariana Trench",
            "description": "This group has the deepest conversations you will ever hear."
        },
        {
            "type": "ExternalEvent",
            "id": "https://example.com/sail-on-the-hudson"
            "title": "Sail on the Hudson",
            "description": "Go for a sail on the Hudson river to promote environmentalism.",
            "start_at": "2019-05-03T13:00:00Z"
        }
    ]
}

This JSON endpoint returns a paginated list of publicly listed events, groups, and external events in your organisation. It can be used alongside the /api/local/points endpoint; the criteria for inclusion are the same.

HTTP Request

GET https://demo.controlshiftlabs.com/api/local.json

Query Parameters

Logged in user

$(document).ready(function(){
  $.ajax({
    url: 'https://demo.controlshiftlabs.com/api/graph/me.json',
    dataType: 'jsonp',
  })
  .done(function(data) {
    console.log(data);
  });
});

The above code would user details for a signed in user. The returned JSON would be structured like this:

{
  "status":"authenticated",
  "me":{
    "first_name":"John",
    "last_name":"Smith",
    "email":"john@smith.com"
  },
  "petitions":[
    {
       "slug":"sample-campaign",
       "title":"Sample Campaign",
       "created_at":"2016-03-25T15:37:28Z",
       "updated_at":"2016-03-25T15:37:35Z"
    }
  ],
  "events":[
    {
       "slug":"sample-campaign",
       "title":"Sample Campaign",
       "created_at":"2016-03-25T15:37:28Z",
       "updated_at":"2016-03-25T15:37:35Z"
    }
  ],
  "chapters":[
    {
       "name":"Brooklyn bruisers",
       "slug":"brooklyn-bruisers",
       "created_at":"2015-05-14T15:53:03Z",
       "updated_at":"2016-03-25T15:40:44Z"
    }
  ]
}

Response for a visitor who is not logged in:

{
  "status":"not_authenticated",
  "message":"user is not signed in"
}

Response for a hostname that is not whitelisted:

{
  "status":"error",
  "errors":[
    {
      "field":"referer",
      "messages":[
        "host name not whitelisted"
      ]
    }
  ]
}

We provide a specialized jsonp endpoint to return information about the currently signed in user. Customers can use this endpoint to power features where information about the current user's petitions, sign in status, and other information about their account is displayed on external sites. Some examples of the sorts of functionality that this could be used to provide include:

• Conditionally show either a login link for unauthenticated users or a link to the user's my account page in the header of external pages.
• Show information about a user's campaigns when someone visits an external site, or a prompt to start a campaign if the currently signed in user has none.
• Show a direct link to a user's local group from an external site rather than linking to a generic search for your group page.

HTTP Request

GET http://demo.controlshiftlabs.com/api/graph/me.json

Working Example

View and edit a working example on codepen.io. Note: codepen.io is whitelisted for the demo account.

    $(document).ready(function(){
      $.ajax({
        url: 'https://demo.controlshiftlabs.com/api/graph/me.json',
        dataType: 'jsonp',
      })
      .done(function(data) {
        if(data.status == 'authenticated'){
          // Populate data for logged in user
          $('#first_name').html(data.me.first_name);
          $('#last_name').html(data.me.last_name);
          $('#email').html(data.me.email);

          var $petitionsPlaceholder = $('#petitions');
          $.each(data.petitions, function(index, petition){
            $petitionsPlaceholder.append('
'+petition.title+'
');
          });

          var $eventsPlaceholder = $('#events');
          $.each(data.events, function(index, event){
            $eventsPlaceholder.append('
'+event.title+'
');
          });

          var $chaptersPlaceholder = $('#chapters');
          $.each(data.chapters, function(index, chapter){
            $chaptersPlaceholder.append('
'+chapter.name+'
');
          });

          $('.js-logged-in').removeClass('hidden');
        }else if(data.status == 'not_authenticated'){
          // Show "not logged in" for users who aren't logged in
          $('.js-not-logged-in').removeClass('hidden');
        }else if(data.status == 'error'){
          // Show known error messages
          $('body').append('Errors
')
          $.each(data.errors, function(index, error){
            $('body').append('
'+error.field+' '+error.messages.join('; ')+'
')
          });
          $('body').append('
')
        }
      });
    })
    .error(function(data){
      $('body').append('Errors
Unknown Error
');
    });
  

Whitelisting a Hostname

We authenticate requests to the current user endpoint by validating the hostname set in the HTTP referrer header against a whitelist. The whitelist is set of hostnames that scripts can be served from. If you request the endpoint from a script served from a non-whitelisted hostname you'll get an error message. This is necessary to prevent cross site scripting attacks that would allow someone to display logged in user information on unauthorized sites.

You can add hostnames to the whitelist through a self-serve interface in the "Settings" area of your instance. Settings > Add Hostname > enter a Hostname, and click save.

The hostname must be a hostname string like "localhost" "www.google.com" or the like. Wildcards or full HTTP URLs are not supported.

When you access the graph API endpoint from a page served from a whitelisted hostname the browser will automatically set a referrer header on those requests. We use this referrer header to validate the server the script was served from against the whitelist. You can verify that a whitelisted hostname is working properly with the curl command line tool:

curl --referer http://localhost/ http://demo.controlshiftlabs.com/api/graph/me.json

The above should return a JSON blob indicating that the user is not signed in if localhost is whitelisted. Otherwise you'll get a not whitelisted error.

For authenticated users we currently return their first and last names, email addresses, and lists of petitions they've created, events they've created and local groups they are a member of.

Bulk data schema

This retrieves information on the underlying schemas of tables exported by the Bulk Data feature. It can be used in your ETL processes to automate the setup of tables in your data warehouse.

Response format:

{
  "tables": [
    {
      "table": {
        "name": "petitions",
        "columns": [
          "title": {
            "type": "string",
            "sql_type": "character varying",
            "limit": null,
            "nullable": true,
            "default_value": null
          },
          "custom_goal": {
            "type": "integer",
            "sql_type": "integer",
            "limit": 4,
            "nullable": true,
            "default_value": null
          },
          ...
        ]
      }
    },
    ...
  ]
}

HTTP Request

GET https://demo.controlshiftlabs.com/api/bulk_data/schema.json

Bulk data columns

This retrieves information on the tables exported by the Bulk Data API. For convenience when working with third-party data warehouse tools like Amazon Redshift it can be useful to know the current columns for each table that the bulk data API exposes in CSV format.

The response is equivalent to the header row of tables exposed through our Bulk Data API. The table parameter controls which table header row is returned.

Response format:

id,petition_id,email,first_name,last_name,phone_number,postcode,created_at,join_organisation,deleted_at,unsubscribe_at,external_constituent_id,member_id,additional_fields,cached_organisation_slug,source,external_id,new_member,external_action_id,locale,bucket,country,updated_at,user_ip,confirmation_token,confirmed_at,confirmation_sent_at,last_signed_at,join_list_suppressed,old_daisy_chain_used,from_embed,user_agent,confirmed_reason,synced_to_crm_at,daisy_chain_experiment_slug,eu_data_processing_consent,from_one_click,consent_content_version_id,daisy_chain_id_used,email_opt_in_type_id,facebook_id,utm_params,postcode_id,referring_share_click_id,join_partnership,opt_in_sms,sms_opt_in_type_id,recaptcha_score,new_mobile_subscriber

HTTP Request

GET https://demo.controlshiftlabs.com/api/bulk_data/schema/columns?table=signatures

Query Parameters

Webhook Endpoints

Webhooks can be used by software engineers to integrate ControlShift with third-party systems. They allow engineers to build software that is triggered by events that take place within ControlShift. ControlShift executes HTTPS callbacks when certain events happen (e.g. a petition is launched; a category is changed).

To begin using webhooks, visit the admin for your ControlShift Platform and choose Settings > Integrations > Webhooks. To begin sending data, you'll need to add a "New Webhook Endpoint." Each Webhook Endpoint URL you specify will receive a stream of all the hooks that occur within your ControlShift account.

If you need additional information about webhooks or how to use them, please send us a support email support@controlshiftlabs.com.

Retries

For webhook notifications successfully processed the response should have an HTTP 2XX status code. Responses returning a different status code will be marked as failed and automatically retried up to 9 times with an exponential backoff (e.g.: after 15s, 30s, 90s, etc.).

If after 9 retries the notification cannot be delivered, the webhook endpoint will be automatically disabled and will need to be re-enabled from the admin page to start receiving webhook notifications again.

Security

Securing access to your endpoints where webhooks are sent is important. We recommend taking a variety of steps.

• Using HTTPS with modern cypher suite.
• Restricting access by IP address
• Using basic HTTP authentication or an API token/secret in the URL.
• Verifying the signature hash of the message payload we send to authenticate ControlShift as the source of the webhook.

Webhook HMAC Authenticity Signing

We send a special HTTP header along with webhook deliveries that allows customers to verify that the body of the webhook being delivered originated from within your ControlShift account. We use HMAC and SHA 256 along with a secret generated for each endpoint

You can retrieve the secret or generate a new one via Settings > Integrations > Webhooks within your ControlShift platform admin.

The value is the prefix sha256: specifying the algorithm in use combined with the HMAC digest of the webhook HTTP request body signed with the signing secret specified for your endpoint in the ControlShift admin tools.

To verify the webhooks you receive are authentic, users should calculate the same digest value and compare it to the digest passed in the x-controlshift-webhook-signature header. These values should always be the same.

IP Addresses

Webhooks will be delivered from a stable set of the IP addresses that will not change. It is a good idea to safe-list these addresses and block webhooks originating from unknown IP addresses.

• 54.144.65.46
• 54.208.56.53

Direct AWS Access

The Bulk Data API notifies customers about new data files via webhook. In addition to allowing access via signed HTTPS request, the Bulk Data API allows direct access to these files from within the same region where your ControlShift account resides (usually us-east-1). Direct AWS Access allows for high-performance access to files on AWS S3 without leaving the AWS Cloud for customers with a point of presence in the same AWS Region. Contact support if you would like to make use of this advanced feature.

Webhook types summary

You can configure ControlShift Labs Webhooks to return the following event types:

blast_email.created

Example payload for blast_email.created:

  {
  "type": "blast_email.created",
  "data": {
    "id": 100,
    "from_name": "Jane Doe",
    "from_address": "jane@example.com",
    "subject": "Please help spread the word",
    "recipient_count": 990
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A new blast email is ready for moderation

category.created

Example payload for category.created:

  {
  "type": "category.created",
  "data": {
    "id": 22,
    "name": "Environment",
    "slug": "environment",
    "external_id": null,
    "created_at": "2015-08-03T12:38:46Z",
    "updated_at": "2015-08-03T12:38:46Z"
  },
  "jid": "df67126973794c2efde76cc4"
}

A new category is created

category.updated

Example payload for category.updated:

  {
  "type": "category.updated",
  "data": {
    "id": 22,
    "name": "Environment",
    "slug": "environment",
    "external_id": null,
    "created_at": "2015-08-03T12:38:46Z",
    "updated_at": "2015-08-03T12:38:46Z"
  },
  "jid": "df67126973794c2efde76cc4"
}

A category is changed

category.deleted

Example payload for category.deleted:

  {
  "type": "category.deleted",
  "data": {
    "id": 22,
    "name": "Environment",
    "slug": "environment",
    "external_id": null,
    "created_at": "2015-08-03T12:38:46Z",
    "updated_at": "2015-08-03T12:38:46Z"
  },
  "jid": "df67126973794c2efde76cc4"
}

A category has been deleted and removed from the organisation

data.full_table_exported

Example payload for data.full_table_exported:

  {
  "type": "data.full_table_exported",
  "data": {
    "url": "https://agra-data-exports.s3.amazonaws.com/default/petitions_20150803180434.csv?AWSAccessKeyId=XXX&Expires=1438711490&Signature=ABCDE%3D",
    "table": "petitions"
  },
  "jid": "cf0f50d7d225e20a188be328"
}

A full-table dump is ready for retrieval on S3

Note URL is encoded using (7-bit) ASCII and some characters will be escaped (i.e.: '&', '<', '>', etc.). See http://www.rubydoc.info/gems/activesupport/3.2.22/ActiveSupport/JSON/Encoding for more details

data.incremental_table_exported

Example payload for data.incremental_table_exported:

  {
  "type": "data.incremental_table_exported",
  "data": {
    "url": "https://agra-data-exports.s3.amazonaws.com/default/petitions_20150803180434.csv?AWSAccessKeyId=XXX&Expires=1438711490&Signature=ABCDE%3D",
    "table": "petitions"
  },
  "jid": "cf0f50d7d225e20a188be328"
}

An incremental CSV update is ready for retrieval on S3

Note URL is encoded using (7-bit) ASCII and some characters will be escaped (i.e.: '&', '<', '>', etc.). See http://www.rubydoc.info/gems/activesupport/3.2.22/ActiveSupport/JSON/Encoding for more details

email.open

Example payload for email.open:

  {
  "type": "email.open",
  "data": {
    "email": "example@test.com",
    "timestamp": 1513299569,
    "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
    "event": "open",
    "category": "cat facts",
    "sg_event_id": "sg_event_id",
    "sg_message_id": "sg_message_id",
    "useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
    "ip": "255.255.255.255"
  },
  "jid": "df67126973794c2efde76cc4"
}

Link in an email has been clicked

email.click

Example payload for email.click:

  {
  "type": "email.click",
  "data": {
    "email": "example@test.com",
    "timestamp": 1513299569,
    "smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
    "event": "click",
    "category": "cat facts",
    "sg_event_id": "sg_event_id",
    "sg_message_id": "sg_message_id",
    "useragent": "Mozilla/4.0 (compatible; MSIE 6.1; Windows XP; .NET CLR 1.1.4322; .NET CLR 2.0.50727)",
    "ip": "255.255.255.255",
    "url": "http://www.controlshift.app/"
  },
  "jid": "df67126973794c2efde76cc4"
}

Email has been opened

event.created

Example payload for event.created:

  {
  "type": "event.created",
  "data": {
    "slug": "petition-hand-in",
    "title": "Petition Hand In",
    "url": "https://demo.controlshiftlabs.com/events/petition-hand-in"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A new event is published

event.updated

Example payload for event.updated:

  {
  "type": "event.updated",
  "data": {
    "slug": "petition-hand-in",
    "title": "Petition Hand In",
    "url": "https://demo.controlshiftlabs.com/events/petition-hand-in"
  },
  "shifts": [
    {
      "id": "103",
      "name": "Lunch",
      "start_at": "2018-03-01T12:00:00Z",
      "end_at": "2018-03-01T13:00:00Z"
    },
    {
      "id": "105",
      "name": "Demonstration",
      "start_at": "2018-03-01T13:00:00Z",
      "end_at": "2018-03-01T13:30:00Z"
    }
  ],
  "jid": "030ee43a4fa9788e084d9cfc"
}

An event is updated

attendee.created

Example payload for attendee.created:

  {
  "type": "attendee.created",
  "data": {
    "id": 645,
    "first_name": "Jennifer",
    "last_name": "Goines",
    "email": "jenny@example.com",
    "phone_number": null,
    "postcode": "23456",
    "country": "",
    "attending_status": "attending",
    "join_organisation": null,
    "join_partnership": null,
    "user_ip": "127.0.0.1",
    "additional_fields": {
    },
    "email_opt_in_type": {
      "context": "web_form",
      "kind": "pre_checked_checkbox",
      "mailable": true,
      "external_id": "abcd12345"
    },
    "eu_data_processing_consent": true,
    "consent_content_version": {
      "id": 123,
      "external_id": "abc345",
      "consent_type": "explicit"
    },
    "member": {
      "id": 747,
      "created_at": "2015-08-03T13:30:01Z"
    },
    "event": {
      "url": "http://localhost/events/meetup-at-park",
      "slug": "meetup-at-park"
    },
    "created_at": "2015-08-03T13:30:01Z",
    "source": "facebook",
    "utm_source": "facebook",
    "utm_campaign": "share-campaign-v2",
    "utm_medium": "social",
    "utm_content": "share-variant-3",
    "utm_term": "parks"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

Member RSVP to event

attendee.confirmed

Example payload for attendee.confirmed:

  {
  "type": "attendee.confirmed",
  "data": {
    "id": 645,
    "first_name": "Jennifer",
    "last_name": "Goines",
    "email": "jenny@example.com",
    "phone_number": null,
    "postcode": "23456",
    "country": "",
    "attending_status": "attending",
    "join_organisation": null,
    "join_partnership": null,
    "user_ip": "127.0.0.1",
    "additional_fields": {
    },
    "email_opt_in_type": {
      "context": "web_form",
      "kind": "pre_checked_checkbox",
      "mailable": true,
      "external_id": "abcd12345"
    },
    "eu_data_processing_consent": true,
    "consent_content_version": {
      "id": 123,
      "external_id": "abc345",
      "consent_type": "explicit"
    },
    "member": {
      "id": 747,
      "created_at": "2015-08-03T13:30:01Z"
    },
    "event": {
      "url": "http://localhost/events/meetup-at-park",
      "slug": "meetup-at-park"
    },
    "created_at": "2015-08-03T13:30:01Z",
    "source": "facebook",
    "utm_source": "facebook",
    "utm_campaign": "share-campaign-v2",
    "utm_medium": "social",
    "utm_content": "share-variant-3",
    "utm_term": "parks"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

Member confirmed RSVP and email address. This event is only emitted for organisations who have email confirmation turned on. This event is only emitted for explicit attendee confirmations, not implicit confirmations eg: for logged in users.

attendee.updated

Example payload for attendee.updated:

  {
  "type": "attendee.updated",
  "data": {
    "id": 645,
    "first_name": "Jennifer",
    "last_name": "Goines",
    "email": "jenny@example.com",
    "phone_number": null,
    "postcode": "23456",
    "country": "",
    "attending_status": "attending",
    "join_organisation": null,
    "join_partnership": null,
    "user_ip": "127.0.0.1",
    "additional_fields": {
    },
    "email_opt_in_type": {
      "context": "web_form",
      "kind": "pre_checked_checkbox",
      "mailable": true,
      "external_id": "abcd12345"
    },
    "eu_data_processing_consent": true,
    "consent_content_version": {
      "id": 123,
      "external_id": "abc345",
      "consent_type": "explicit"
    },
    "member": {
      "id": 747,
      "created_at": "2015-08-03T13:30:01Z"
    },
    "event": {
      "url": "http://localhost/events/meetup-at-park",
      "slug": "meetup-at-park"
    },
    "created_at": "2015-08-03T13:30:01Z",
    "source": "facebook",
    "utm_source": "facebook",
    "utm_campaign": "share-campaign-v2",
    "utm_medium": "social",
    "utm_content": "share-variant-3",
    "utm_term": "parks"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

Member updates RSVP to event

attendee.deleted

Example payload for attendee.deleted:

  {
  "type": "attendee.deleted",
  "data": {
    "id": 645,
    "first_name": "Jennifer",
    "last_name": "Goines",
    "email": "jenny@example.com",
    "phone_number": null,
    "postcode": "23456",
    "country": "",
    "attending_status": "attending",
    "join_organisation": null,
    "join_partnership": null,
    "user_ip": "127.0.0.1",
    "additional_fields": {
    },
    "email_opt_in_type": {
      "context": "web_form",
      "kind": "pre_checked_checkbox",
      "mailable": true,
      "external_id": "abcd12345"
    },
    "eu_data_processing_consent": true,
    "consent_content_version": {
      "id": 123,
      "external_id": "abc345",
      "consent_type": "explicit"
    },
    "member": {
      "id": 747,
      "created_at": "2015-08-03T13:30:01Z"
    },
    "event": {
      "url": "http://localhost/events/meetup-at-park",
      "slug": "meetup-at-park"
    },
    "created_at": "2015-08-03T13:30:01Z",
    "source": "facebook",
    "utm_source": "facebook",
    "utm_campaign": "share-campaign-v2",
    "utm_medium": "social",
    "utm_content": "share-variant-3",
    "utm_term": "parks"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

Attendee permanently deleted. This is currently only triggered when a member deletes its account.

flag.created

Example payload for flag.created:

  {
  "type": "flag.created",
  "data": {
    "id": 7,
    "flagged": {
      "type": "ForumMessage",
      "id": 224
    },
    "flagged_by": {
      "email": "bobby@example.com",
      "name": "Bobby Singer"
    },
    "reason": "This violates our community commitments",
    "status": "unreviewed",
    "created_at": "2015-08-05T13:17:46Z",
    "updated_at": "2015-08-05T13:17:46Z"
  },
  "jid": "f848f4b38b9125f7089d59ad"
}

Someone flags a problem for admin attention

For example, a local chapter organiser flags a forum message.

label.applied

Example payload for label.applied:

A label is applied to a campaign, event, group, or member

label.removed

Example payload for label.removed:

A label is removed from a campaign, event, group, or member

local_chapter.created

Example payload for local_chapter.created:

  {
  "type": "local_chapter.created",
  "data": {
    "slug": "springfield-members",
    "name": "Springfield Members",
    "url": "https://demo.controlshiftlabs.com/local_chapters/springfield-members"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A local group has been created.

local_chapter.last_organiser.deleted

Example payload for local_chapter.last_organiser.deleted:

  {
  "type": "local_chapter.last_organiser.deleted",
  "data": {
    "slug": "springfield-members",
    "name": "Springfield Members",
    "url": "https://demo.controlshiftlabs.com/local_chapters/springfield-members"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A local chapter's last organiser leaves the group

local_chapter.organiser_request.created

Example payload for local_chapter.organiser_request.created:

  {
  "type": "local_chapter.organiser_request.created",
  "data": {
    "id": 1234,
    "local_chapter": {
      "slug": "springfield-members",
      "name": "Springfield Members",
      "url": "https://demo.controlshiftlabs.com/local_chapters/springfield-members"
    },
    "user": {
      "id": 505,
      "email": "jane@example.com",
      "full_name": "Jane Goodall",
      "first_name": "Jane",
      "last_name": "Goodall",
      "phone_number": "12345-1",
      "postcode": "34058-2356"
    },
    "reason": "I want to be part of this amazing group",
    "created_at": "2015-08-03T12:38:46Z"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A user applies to be a local chapter organiser

local_chapter.organiser_request.approved

Example payload for local_chapter.organiser_request.approved:

  {
  "type": "local_chapter.organiser_request.approved",
  "data": {
    "id": 1234,
    "local_chapter": {
      "slug": "springfield-members",
      "name": "Springfield Members",
      "url": "https://demo.controlshiftlabs.com/local_chapters/springfield-members"
    },
    "user": {
      "id": 505,
      "email": "jane@example.com",
      "full_name": "Jane Goodall",
      "first_name": "Jane",
      "last_name": "Goodall",
      "phone_number": "12345-1",
      "postcode": "34058-2356"
    },
    "reason": "I want to be part of this amazing group",
    "created_at": "2015-08-03T12:38:46Z"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

An admin approves a user's application to be a local chapter organiser

local_chapter.organiser.created

Example payload for local_chapter.organiser.created:

  {
  "type": "local_chapter.organiser.created",
  "data": {
    "id": 180,
    "email": "jenny@example.com",
    "full_name": "Jennifer Goines",
    "first_name": "Jennifer",
    "last_name": "Goines",
    "phone_number": null,
    "postcode": "23456",
    "country": "US",
    "introduction": "I want to save the world!",
    "notification_level": "all_messages",
    "local_chapter": {
      "slug": "springfield-members",
      "name": "Springfield Members",
      "url": "https://demo.controlshiftlabs.com/local_chapters/springfield-members"
    },
    "eu_data_processing_consent": true,
    "consent_content_version": {
      "id": 123,
      "external_id": "abc345",
      "consent_type": "explicit"
    },
    "utm_source": "facebook",
    "utm_campaign": "share-campaign-v2",
    "utm_medium": "social",
    "utm_content": "share-variant-3",
    "utm_term": "parks"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

An organiser is added to a local chapter

local_chapter.member.created

Example payload for local_chapter.member.created:

  {
  "type": "local_chapter.member.created",
  "data": {
    "id": 180,
    "email": "jenny@example.com",
    "full_name": "Jennifer Goines",
    "first_name": "Jennifer",
    "last_name": "Goines",
    "phone_number": null,
    "postcode": "23456",
    "country": "US",
    "introduction": "I want to save the world!",
    "notification_level": "all_messages",
    "local_chapter": {
      "slug": "springfield-members",
      "name": "Springfield Members",
      "url": "https://demo.controlshiftlabs.com/local_chapters/springfield-members"
    },
    "eu_data_processing_consent": true,
    "consent_content_version": {
      "id": 123,
      "external_id": "abc345",
      "consent_type": "explicit"
    },
    "utm_source": "facebook",
    "utm_campaign": "share-campaign-v2",
    "utm_medium": "social",
    "utm_content": "share-variant-3",
    "utm_term": "parks"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A member joins a local chapter

local_chapter.member.deleted

Example payload for local_chapter.member.deleted:

  {
  "type": "local_chapter.member.deleted",
  "data": {
    "id": 180,
    "email": "jenny@example.com",
    "full_name": "Jennifer Goines",
    "first_name": "Jennifer",
    "last_name": "Goines",
    "phone_number": null,
    "postcode": "23456",
    "country": "US",
    "introduction": "I want to save the world!",
    "notification_level": "all_messages",
    "local_chapter": {
      "slug": "springfield-members",
      "name": "Springfield Members",
      "url": "https://demo.controlshiftlabs.com/local_chapters/springfield-members"
    },
    "eu_data_processing_consent": true,
    "consent_content_version": {
      "id": 123,
      "external_id": "abc345",
      "consent_type": "explicit"
    },
    "utm_source": "facebook",
    "utm_campaign": "share-campaign-v2",
    "utm_medium": "social",
    "utm_content": "share-variant-3",
    "utm_term": "parks"
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A member leaves or is removed from a local chapter

member.deleted

Example payload for member.deleted:

  {
  "type": "member.deleted",
  "data": {
    "member": {
      "id": 100,
      "email": "jane@example.com"
    },
    "resources": {
      "new_owner": {
        "id": 888,
        "email": "richard@example.com",
        "full_name": "Richard Chamberlain",
        "first_name": "Richard",
        "last_name": "Chamberlain",
        "phone_number": "12345-1",
        "postcode": "34058-2356"
      }
    }
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

A member is deleted

member.deleted.resources_transferred

Example payload for member.deleted.resources_transferred:

  {
  "type": "member.deleted.resources_transferred",
  "data": {
    "member": {
      "id": 100,
      "email": "jane@example.com"
    },
    "resources": {
      "new_owner": {
        "id": 888,
        "email": "richard@example.com",
        "full_name": "Richard Chamberlain",
        "first_name": "Richard",
        "last_name": "Chamberlain",
        "phone_number": "12345-1",
        "postcode": "34058-2356"
      }
    }
  },
  "jid": "030ee43a4fa9788e084d9cfc"
}

Resources previously owned by a deleted member have been transferred to another

petition.ended

Example payload for petition.ended:

  {
  "type": "petition.ended",
  "data": {
    "slug": "don-t-destroy-our-park",
    "title": "Don't destroy our park!",
    "url": "https://demo.controlshiftlabs.com/petitions/don-t-destroy-our-park",
    "image_url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/hero/imag0945.jpg?1438621934",
    "additional_image_sizes_url": [
      {
        "style": "form",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/form/imag0945.jpg?1438621934"
      },
      {
        "style": "large",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/large/imag0945.jpg?1438621934"
      },
      {
        "style": "open_graph",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/open_graph/imag0945.jpg?1438621934"
      },
      {
        "style": "original",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/original/imag0945.jpg?1438621934"
      }
    ],
    "who": "Anytown City Council",
    "what": "The park on Main Street is an important community space.  Don't approve the proposal to sell it to office building developers.",
    "goal": 100,
    "signature_count": 0,
    "creator": {
      "id": 1,
      "email": "agra.user.adm@gmail.com",
      "full_name": "Tyshawn Morissette",
      "first_name": "Tyshawn",
      "last_name": "Morissette",
      "phone_number": "12345-1",
      "postcode": "34058-2356"
    },
    "locale": "en-US",
    "created_at": "2015-08-03T13:11:02Z",
    "updated_at": "2015-08-03T13:12:15Z",
    "why": "Studies have shown that green space is important to child development and community well-being.",
    "ended": true,
    "ended_type": "won",
    "ended_reason": "We won the campaign! The Main Street park will be protected for years to come.",
    "successful": true,
    "ended_story": "We won! Thanks to your support, the city council has agreed to protect the Main Street park from development."
  },
  "jid": "9fccc1957d7d7ebc93fb0f05"
}

A petition is marked as won, lost, or ended for another reason

petition.flagged

Example payload for petition.flagged:

  {
  "type": "petition.flagged",
  "data": {
    "slug": "don-t-destroy-our-park",
    "title": "Don't destroy our park!",
    "url": "https://demo.controlshiftlabs.com/petitions/don-t-destroy-our-park",
    "image_url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/hero/imag0945.jpg?1438621934",
    "additional_image_sizes_url": [
      {
        "style": "form",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/form/imag0945.jpg?1438621934"
      },
      {
        "style": "large",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/large/imag0945.jpg?1438621934"
      },
      {
        "style": "open_graph",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/open_graph/imag0945.jpg?1438621934"
      },
      {
        "style": "original",
        "url": "https://d34smfggpfnvat.cloudfront.net/petitions/images/788/original/imag0945.jpg?1438621934"
      }
    ],
    "who": "Anytown City Council",
    "what": "The park on Main Street is an important community space.  Don't approve the proposal to sell it to office building developers.",
    "goal": 100,
    "signature_count": 0,
    "creator": {
      "id": 1,
      "email": "agra.user.adm@gmail.com",
      "full_name": "Tyshawn Morissette",
      "first_name": "Tyshawn",
      "last_name": "Morissette",
      "phone_number": "12345-1",
      "postcode": "34058-2356"
    },
    "locale": "en-US",
    "created_at": "2015-08-03T13:11:02Z",
    "updated_at": "2015-08-03T13:12:15Z",
    "why": "Studies have shown that green space is important to child development and community well-being.",
    "ended": true,
    "ended_type": "won",
    "ended_reason": "We won the campaign! The Main Street park will be protected for years to come.",
    "successful": true,
    "ended_story": "We won! Thanks to your support, the city council has agreed to protect the Main Street park from development."
  },
  "jid": "9fccc1957d7d7ebc93fb0f05"
}