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"
              }
            ],
            "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"
              }
            ],
            "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.

Back To Top ↑

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 to register your new petition signature and person. Feel free to include any status fields to change their subscription status (either subscribe or unsubscribe) or leave them blank to keep their status as is. And add the autoresponse trigger field to send them an autoresponse email.

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"
      }
    ]
  },
  "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 Response Options tab of this petition's manage page when you set up the petition in our user interface.

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 ↑

Next Tutorial: Unsubscribe people from your list