Scroll

JSONP API

Want to skip ahead? Choose the endpoint you want to use: 


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 to show petitions on other pages outside of the platform.

For a live example of the JSON endpoint available, please see our developer site: developers.controlshiftlabs.com.

The following endpoints are available. 

List featured campaigns:

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

List categories:

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

List petitions in a category:

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

List petitions in an effort:

https://demo.controlshiftlabs.com/efforts/forecast-the-facts.json

A single petition:

https://demo.controlshiftlabs.com/petitions/stop-making-excuses-for-sexual-violence-repeal-harmful-laws.json

 

Search for closest petition in an effort:

https://demo.controlshiftlabs.com/efforts/forecast-the-facts/near.json

This JSON endpoint allows you to reproduce the 'search for the nearest petition in an effort' interface. Use this endpoint to build a place for users to enter their location. Once they've searched for a location, we'll return the nearest petition. Note that the returned data will be in a JSON format. 

The following gist shows example code for a lookup page using the endpoint.

 

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.

 

Current User / Signed in status

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. 
The endpoint for the current user jsonp api is the following url, where demo.controlshiftlabs.com should be replaced with the hostname of your instance
 
http://demo.controlshiftlabs.com/api/graph/me.json
 
We authenticate requests to the current user endpoint by validating the hostname set in the http referer 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 referer header on those requests. We use this referer 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

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.

Want more information about the endpoints?

Check our our developer site: developers.controlshiftlabs.com

Have more questions? Submit a request

Comments

Powered by Zendesk