You May Want Javascript For This

Your browser currently has Javascript turned off. While some things, like signing petitions, will work without Javascript you may encounter errors. If you do, enabling JavaScript should get around the problems.

Actions

People

Record Signature Helper Version 2

This document describes the OSDI record signature helper endpoint as implemented by the Action Network.

The record signature helper allows you to create or update a person record and mark that person as having signed a petition at the same time (as well as tag that person).

This saves API calls. POSTing a new signature without the helper would mean you need a link to the person you want to associate the signature with, which would entail either an oData search to look up the existing person or a POST using the person_signup_helper to add the person first. The record signature helper allows you to post a person's data along with a signature, and the helper will automatically create or deduplicate the person and then create a signature for them on the specified petition, all in one API call.

The record signature helper takes the normal signature format (described here) with an additional JSON hash with person data, and an optional array of tags to add to the person's record.

People are matched and deduplicated by email address. If a new person is created as part of a POST operation, that person will be subscribed to the email list associated with your API key. If the email address is found, that person's subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed in the status field, as described in the people documentation. In that case, the person will be subscribed to the list, even if they were previously unsubscribed. No other status fields are valid on this endpoint.

Items in the optional tags array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added to the person's record. If not, the tag will be ignored.

An optional triggers object can be added as well, indicating an autoresponse email should be sent back to the activist, which typically thanks them for taking action. Autoresponse emails are only sent from actions created with our user interface, and will respect the autoresponse settings in that action's Response Options tab on its manage page. For example, if you're POSTing to a petition that has the autoresponse email turned on and you include the autoresponse trigger, the activist will get an autoresponse email as normal, thanking them for taking action. If you're POSTing to a petition with the autoresponse turned off, they won't get that email.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. If you use unauthenticated or "blind" 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. See the blind post tutorial for an example.

Note: Signatures are deduplicated based on person, so a specific person can only sign a petition once.

A hash representing person data to associate with this signature. You can use any valid fields for person resources. An email address is required. See the people document for more information about people. (The person's language preference will be set to the language of the action as specified in the action's user interface.)

Referrer Data fields:

The source code of this signature. Equivalent to someone taking action with the url argument ?source=[your source]. Corresponds to the sources chart in this action's manage page. Action Network-only.

referrer

string

The referrer code of this signature. Equivalent to someone taking action with the url argument ?referrer=[your referrer code]. Must be a valid Action Network referrer code. Read-only. Corresponds to the referrers chart in this action's manage page. Action Network-only.

website

string

The website referrer for this signature. Equivalent to someone taking action after clicking a link on the listed website. Corresponds to the websites chart in this action's manage page. Action Network-only.

Related resources

Scenario: Creating a new signature (POST)

If you post with an inline person hash instead of with a link to a person object as described here, we will create or update the matching person and associate them with a new signature on the specified petition, all in one API call.

An email address is the only required field, though others can be POSTed.

People are matched and deduplicated by email address. If a new person is created as part of a POST operation, that person will be subscribed to the email list associated with your API key. If the email address is found, that person's subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed in the status field, as described in the people documentation. In that case, the person will be subscribed to the list, even if they were previously unsubscribed. No other status fields are valid on this endpoint.

Either way, signatures are deduplicated by person, so a person can only sign a petition once. Posting a new signature by a person who previously signed the petition will replace the old signature resource with the new one.

Tags can also be added to a person's record when POSTing using the helper by including the optional tags array. Items in the array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added to the person's record. If not, the tag will be ignored.

And an optional triggers object can be added, indicating an autoresponse email should be sent back to the activist, which typically thanks them for taking action. Autoresponse emails are only sent from actions created with our user interface, and will respect the action's response options settings.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. See the blind post tutorial for an example.

Here is an example of posting a signature with person data inlined to the special record_signature_helper link on the signature collection, along with tags and an autoresponse:

In the above example, a new person was created and their signature added to the petition at the same time. The tags "volunteer" and "member" were added to that person's record as well. They received an autoresponse email from the action, according to its response option settings in the user interface. We deduplicate people added this way by email address, so if the email posted corresponded with a person already in the system, we would update their record instead of creating a new person. The required fields for person remain the same -- email address -- and any posts missing that information will fail.

If the person is new, they will be subscribed to the list associated with your API key. If not, their subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed in the status field, as described in the people documentation. In that case, they will be subscribed to the list, even if they were previously unsubscribed. No other status fields are valid on this endpoint.

Of course you can POST a signature with more fields such as address lines for your inline person data or custom fields if you'd like, but they are not required. And you can omit your API key, in which case the response will a success status code and an empty JSON object if successful, or an error code and message if not.

Action Network is an open platform that empowers individuals and groups to organize for progressive causes. We encourage responsible activism, and do not support using the platform to take unlawful or other improper action. We do not control or endorse the conduct of users and make no representations of any kind about them.

Get Help

Get In Touch

Want to partner with us?

Action Network partners get access to our full range of tools, including the ability to upload activists and subscribe them to your list, create custom-branded email and page wrappers, and more. Join organizations large and small who've made the switch!