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. It's also a best practice to pass along an identifier from the other system. Identifiers are deduplicated globally, across groups and API keys, so ensure any you set are globally unique. Here's an example:

						
POST https://actionnetwork.org/api/v2/fundraising_pages/

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "identifiers": [
    "your_system:1"
  ],
  "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",
    "your_system:1"
  ],
  "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"
        }
      ],
      "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.

Back To Top ↑

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. It's helpful to include an identifier as well for both your person and donation. Identifiers are deduplicated globally, across groups and API keys, so ensure any you set are globally unique.

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": [
    "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" : [ 
      { 
        "postal_code" : "20009",
        "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"
  ],
  "created_date": "2014-03-24T19:48:23Z",
  "modified_date": "2014-03-24T19:48:23Z",
  "currency": "USD",
  "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/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/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 person who made the donation.

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 (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.

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.

Back To Top ↑

Next Tutorial: Blind POST & autoresponses