Tutorial: Add Actions and Action Takers Version 1
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 targeter 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 coud 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 want to send to the Action Network. Navigate to the fundraising pages endpoint and post the new action, making sure to include the originating system and a summary as required fields. It's also a best practice to pass along an identifier from the other system, like so:
POST https://actionnetwork.org/api/v1/fundraising_pages/ Header: Content-Type: application/json api-key:[your api key here]{ "identifiers": [ "your_system:1" ], "summary": "Help us run our ad on TV", "originating_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{ "originating_system": "Your System", "identifiers": [ "action_network:853b797a-8779-4b06-99c6-3c8f6bdc0a90", "your_system:1" ], "created_at": "2014-03-24T19:39:40Z", "modified_at": "2014-03-24T19:39:40Z", "summary": "Help us run our ad on TV", "total_donations": 0, "total_amount": "0.00", "currency": "USD", "_embedded": { "osdi:creator": { "given_name": "John", "family_name": "Smith", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "email_addresses": [ { "primary": true, "address": "jsmith@mail.com" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 Pennsylvania Ave." ], "locality": "Washington", "region": "DC", "postal_code": "20009", "country": "US", "language": "en", "location": { "latitude": 32.919, "longitude": -72.0379, "accuracy": "Approximate" } } ], "_links": { "self": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/question_answers" }, "osdi:attendance": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendance" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/donations" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } } }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/donations" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v1/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/embed" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{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 user interface when sending an email or creating a report, 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 donations collection helper link, making sure to include at least one recipient and inline person data with at least an email address and ZIP code to register your new donation and person. It's helpful to include an identifier as well for both your person and donation.
Note: Posting a donation like this does not charge this person any money. Posting 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/v1/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/donations Header: Content-Type: application/json api-key:[your api key here]{ "originating_system" : "Your System", "identifiers": [ "your_system:3" ], "recipients" : [ { "name": "Barack Obama", "amount": "20.00" }, { "name": "Elizabeth Warren", "amount": "30.00" } ], "person" : { "identifiers": [ "your_system:4" ], "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" }] } }
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", "your_system:3" ], "originating_system": "Your System", "created_at": "2014-03-24T19:48:23Z", "modified_at": "2014-03-24T19:48:23Z", "currency": "USD", "total_amount": "50.00", "recipients": [ { "name": "Barack Obama", "amount": "20.00" }, { "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/v1/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90/donations/3a1b74fa-27b6-49a3-bb0c-67f1a35460ef" }, "osdi:fundraising_page": { "href": "https://actionnetwork.org/api/v1/fundraising_pages/853b797a-8779-4b06-99c6-3c8f6bdc0a90" }, "osdi:person": { "href": "https://actionnetwork.org/api/v1/people/fbce520b-12fa-437e-bd8c-f89310fdc005" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } }
The response is your new donation object, with a link to the new person you created as part of the post.
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.
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.