Tutorial: Add Actions and Action Takers Version 2
This tutorial demonstrates how to add a new action and a new person to your database via the Action Network API, in this case adding a new fundraising page created in another system and posting a new donation from a person in that other system so they're registered as a donor in the Action Network as well.
This is useful to categorize and organize the actions and people you want to register in the Action Network database. For example, you can use the API to create a form action that represents a physical email list signup sheet at a meeting you held, and then add people who signed that piece of paper as submitters on that form. Those people will then show up in our targeting interface as having taken that action, allowing you to send a followup welcome message to just these people easily.
Note: Actions you create via the API like this are different from pages you create using the Action Network user interface. If you create a form using the API, we will not give it a URL where you can collect additional submissions online. Rather, the action will only exist in our targeting interface and in API calls. In this way, actions created via the API could be thought of as a way to categorize or tag people based on their action history taken using another toolset or platform.
Steps:
Post a new action
The first step is to create a new action. In this case, we'll be posting a new fundraising page representing a fundraising page that you created in another system and that has data you want to send to Action Network. Navigate to the fundraising pages endpoint and post the new action, making sure to include the origin system and a title as required fields. Here's an example:
POST https://actionnetwork.org/api/v2/fundraising_pages/ Header: Content-Type: application/json OSDI-API-Token: your_api_key_here{ "title": "Help us run our ad on TV", "origin_system": "Your System" }
Which will return a response like this:
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{ "origin_system": "Your System", "identifiers": [ "action_network:853b797a-8779-4b06-99c6-3c8f6bdc0a90" ], "created_date": "2014-03-24T19:39:40Z", "modified_date": "2014-03-24T19:39:40Z", "title": "Help us run our ad on TV", "total_donations": 0, "total_amount": "0.00", "currency": "USD", "action_network:hidden": false, "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Doe", "created_date": "2014-02-18T19:44:49Z", "modified_date": "2014-02-25T16:08:26Z", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "email_addresses": [ { "primary": true, "address": "johndoe@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": 38.919, "longitude": -77.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/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v2/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/donations" }, "record_donation_helper": { "href": "https://actionnetwork.org/api/v2/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/donations" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v2/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/embed" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v2/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v2/{rel}", "templated": true } ] } }
Note that we've added a creator to this fundraising page. If you don't specify a creator, one will be added for you. If you're using an individual API key, your individual person record will be added as the creator. If you're using a group API key, the original founder of your group will be added.
This fundraiser will now show up when you call the fundraising_pages endpoint using the API as well as in our targeting interface when sending an email or creating a report or query, allowing you to target all people who took action on this fundraising page.
Add a new donation and person to your new fundraising page
Next, navigate to this new fundraising page using the links provided, and then to the donations collection of that fundraising page.
Post a new donation on the record donation helper link, making sure to include at least one recipient and inline person data with at least an email address to register your new donation and person.
Note: Posting a donation like this does not charge this person any money or send an autoresponse. Posting donations only registers them in the system as having donated using some other system, where their money was actually taken.
Make your post call to add a donation and a person like so:
POST https://actionnetwork.org/api/v2/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/donations Header: Content-Type: application/json OSDI-API-Token: your_api_key_here{ "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "recipients" : [ { "display_name": "Barack Obama", "amount": "20.00" }, { "display_name": "Elizabeth Warren", "amount": "30.00" } ], "person" : { "family_name" : "Doe", "given_name" : "Jane", "postal_addresses" : [ { "address_lines" : [ "1900 Pennsylvania Ave" ], "locality" : "Washington", "region" : "DC", "postal_code" : "20009", "country" : "US" } ], "email_addresses" : [ { "address" : "jdoe@mail.com" }], "phone_numbers" : [ { "number" : "12021234444" }] } }
Which will return a response like this:
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{ "identifiers": [ "action_network:3a1b74fa-27b6-49a3-bb0c-67f1a35460ef" ], "created_date": "2014-03-24T19:48:23Z", "modified_date": "2014-03-24T19:48:23Z", "currency": "USD", "amount": "50.00", "recipients": [ { "display_name": "Barack Obama", "amount": "20.00" }, { "display_name": "Elizabeth Warren", "amount": "30.00" } ], "payment": { "method": "Credit Card", "reference_number": "3a1b74fa-27b6-49a3-bb0c-67f1a35460ef", "authorization_stored": false }, "action_network:recurrence": { "recurring": false }, "action_network:person_id": "fbce520b-12fa-437e-bd8c-f89310fdc005", "action_network:fundraiser_id": "853b797a-8779-4b06-99c6-3c8f6bdc0a90", "_links": { "self": { "href": "https://actionnetwork.org/api/v2/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/donations/3a1b74fa-27b6-49a3-bb0c-67f1a35460ef" }, "osdi:fundraising_page": { "href": "https://actionnetwork.org/api/v2/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90" }, "osdi:person": { "href": "https://actionnetwork.org/api/v2/people/fbce520b-12fa-437e-bd8c-f89310fdc005" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v2/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v2/{rel}", "templated": true } ] } }
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. If they are an existing person already in your group, their email subscription status will not change unless you pass subscribed or unsubscribed in the status field, as described in the people documentation. In that case, their status will be changed to the passed subscription status. (In networks, subscribed statuses will travel up the network. Unsubscribed statuses will not). 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 or unsubscribed. If they are an existing person already in your group, the person's mobile subscription status will not be changed, unless you pass subscribed or unsubscribed 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 action in your action history targeting section, or they can be targeted as a donor and based on their donation level, using the donation data you posted.
Background processing is available on this operation via thebackground_request=true URL argument. You can learn more about background processing here.
Note: You must post at least one recipient for a donation. If the system you used to collect this donation does not recognize recipients, make one a default to use, such as 'My Donation System' or something similar.
Click here for full documentation of donation resources.
Back To Top ↑