Tutorial: Blind POST & Autoresponses Version 2
This tutorial demonstrates how to add signatures and activists to a petition you created using Action Network's user interface without exposing your API key, and also send activists an autoresponse email to thank them for signing.
This is useful to enable use of a custom form that you create, instead of using the page we make or our embedded form. You could create your own form on your own website and POST in data using javascript, allowing for more control over the look, feel, and behavior of your form.
OSDI has also released a jQuery plugin, which works with our unauthenticated POST and autoresponse trigger features and may help you implement what's been discussed in this tutorial. Check it out here.
Steps:
Find the target petition to POST to
The first step is to find an action you've already made. While you can POST activist data to any action in our system (though some rules apply), in this case we'll be looking for an action you made in the user interface, rather than an action you created over the API, as actions you create with the user interface are the only onces that can trigger autoresponse emails. Use our API browser or some other tool to navigate to the petitions endpoint to view a list of all of your petitions, API-created and user interface created, like so:
GET https://actionnetwork.org/api/v2/petitions/
Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here
Which will return a response like this:
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{ "total_pages": 7, "per_page": 25, "page": 1, "total_records": 162, "_links": { "next": { "href": "https://actionnetwork.org/api/v2/petitions?page=2" }, "self": { "href": "https://actionnetwork.org/api/v2/petitions" }, "osdi:petitions": [ { "href": "https://actionnetwork.org/api/v2/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d" }, { "href": "https://actionnetwork.org/api/v2/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3" }, //truncated for brevity ], "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v2/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v2/{rel}", "templated": true } ] }, "_embedded": { "osdi:petitions": [ { "identifiers": [ "action_network:a4dde5b6-0512-48ea-b4ad-63a71117b43d" ], "origin_system": "Action Network", "created_date": "2014-03-24T18:03:45Z", "modified_date": "2014-03-25T15:00:22Z", "title": "Stop doing the bad thing", "description": "<p>The mayor should stop doing the bad.</p>", "petition_text": "Mayor, stop doing the bad thing", "browser_url": "https://actionnetwork.org/petitions/stop-doing-the-bad-thing", "total_signatures": 2354, "target": [ { "name": "The Mayor" } ], "action_network:hidden": false, "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "created_date": "2014-03-24T18:03:45Z", "modified_date": "2014-03-25T15:00:22Z", "email_addresses": [ { "primary": true, "address": "jdoe@mail.com", "status": "subscribed" } ], "phone_numbers": [ { "primary": true, "number": "12021234444", "number_type": "Mobile", "status": "subscribed" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave." ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 35.919, "longitude": -72.0379, "accuracy": "Approximate" } } ], "languages_spoken": [ "en" ], "_links": { "self": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:attendances": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendances" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" }, "osdi:outreaches": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches" }, "osdi:taggings": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/taggings" } } } }, "_links": { "self": { "href": "https://actionnetwork.org/api/v2/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v2/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/signatures" }, "osdi:record_signature_helper": { "href": "https://actionnetwork.org/api/v2/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/signatures" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v2/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/embed" } } }, { "identifiers": [ "action_network:a27178b9-45c3-4844-8ebf-ebd5da74a1e3", "foreign_system:1" ], "origin_system": "Another System", "created_date": "2014-03-14T15:21:05Z", "modified_date": "2014-03-17T19:56:11Z", "title": "We need to do this now!", "total_signatures": 123, "action_network:hidden": false, "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "created_date": "2014-03-24T18:03:45Z", "modified_date": "2014-03-25T15:00:22Z", "email_addresses": [ { "primary": true, "address": "jdoe@mail.com", "status": "subscribed" } ], "phone_numbers": [ { "primary": true, "number": "12021234444", "number_type": "Mobile", "status": "subscribed" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave." ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 35.919, "longitude": -72.0379, "accuracy": "Approximate" } } ], "languages_spoken": [ "en" ], "_links": { "self": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:attendances": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendances" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" }, "osdi:outreaches": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches" }, "osdi:taggings": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29/taggings" } } } }, "action_network:sponsor": { "title": "Progressive Action Now", "url": "https://actionnetwork.org/groups/progressive-action-now" }, "_links": { "self": { "href": "https://actionnetwork.org/api/v2/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v2/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3/signatures" }, "osdi:record_signature_helper": { "href": "https://actionnetwork.org/api/v2/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3/signatures" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v2/petitions/a27178b9-45c3-4844-8ebf-ebd5da74a1e3/embed" } } }, //truncated for brevity ] } }
Now, look through the response to find the petition you want to POST signatures to, and note the URL of the osdi:record_signature_helper, which is the endpoint where you can POST signatures to add to this petition.
POST signatures and trigger an autoresponse
Next, if you were using this technique to create a custom form for your petition, you'd go ahead and create that form now, and write some javascript to use AJAX to POST to the record signature helper endpoint of the petition you're targeting.
Note: You should omit your API key in your javascript AJAX call, keeping your key secure. We'll use unauthenticated/blind POSTing to enable this type of javascript implementation.
When you POST a new signature to the record signature helper link, making sure to include at least some inline person data with at least an email address or phone number to register your new petition signature and person. Only a subscription status of subscribed is valid at this endpoint. Leave subscription status blank if you want the status to remain the same. And add the autoresponse trigger field to send them an autoresponse email.
Background processing is automatically implemented on unauthenticated posts. You can learn more about background processing here.
In the example below, we'll subscribe the user to the email list. Make your post call to add a signature and a person like so:
POST https://actionnetwork.org/api/v2/petitions/a4dde5b6-0512-48ea-b4ad-63a71117b43d/signatures Header: Content-Type: application/json{ "person" : { "family_name" : "Doe", "given_name" : "Jane", "postal_addresses" : [ { "postal_code" : "20009", "address_lines" : [ "1900 Pennsylvania Ave" ], "locality" : "Washington", "region" : "DC", "postal_code" : "20009", "country" : "US" } ], "email_addresses" : [ { "address" : "jdoe@mail.com", "status" : "subscribed" } ], "phone_numbers" : [ { "number" : "12021234444", "status" : "subscribed" } ] }, "triggers": { "autoresponse": { "enabled": true } } }
Because you're using unauthenticated POST without an API key, the response will be essentially no information, to avoid leaking any personal data over the API without an API key present. You will receive a success status code and an empty JSON response if successful, or an error status code and an error message if not. In this case, we'll see a success, like so:
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{}
If the person's email address wasn't on your list already when you made the POST, they were added to your list and subscribed to receive emails. If the person's email address did already exist on your list, their subscription status was changed to subscribed, since we passed the status field on POST. And, this person received an autoresponse email thanking them for taking action, in accordance with the autoresponse settings you saved on the Responses tab of this petition's manage page when you set up the petition in our user interface. Posting will also subscribe the person to the lists associated with the action. For example, if a petition lists an individual account as a creator and a group as a sponsor, the person will be subscribed to both lists when the signature is created. Currently multiple sponsors are not supported.
People are matched and deduplicated by phone number and email address, both of which can be attached to an activist record. People are required to have either an email address or a phone number. If a person is posted without an email address, a record with only phone number will be created and vice versa. If adding or changing a phone number results in more than one activist having the same number for your group, one of two things will happen. If both activists have email addresses, the phone number will be removed from the old activist and added to the new activist. If one of the activists is a mobile-only record, then the records will be merged. More on deduplicating here.
If the email or phone number posted corresponds with a person already in the system, we update their record instead of creating a new person. If the person is new to your email list, they will be subscribed to the email list associated with your API key. (In networks, subscribed statuses will travel up the network. Unsubscribed statuses will not). The only valid status is subscribed, no other status fields are valid at this endpoint.
People's mobile subscription status works differently than email subscription status. If they are new to your mobile list, by default they will be added as unsubscribed, unless you pass subscribed If they are an existing person already in your group, the person's mobile subscription status will not be changed, unless you pass subscribed in the mobile status field. (In networks, if this group does has the 'mobile status goes up the network' setting checked, a mobile subscribed status will travel up the network where an unsubscribed will not.) No other status fields are valid on this endpoint.
From now on, this person can be targeted by choosing this petition in your action history targeting section.
Click here for full documentation of the record signature helper.
Back To Top ↑