Tutorial: Add People Version 2

This tutorial demonstrates how to add new people to your email list and database by posting them using the person signup helper.

The Action Network does not support adding people without the helper, as the helper performs deduplication based on email address, a key part of our system.

In this tutorial, we'll explore adding a person using the helper.

Steps:

Find the person signup helper

The link to the person signup helper is available on the API entry point (AEP), labeled osdi:person_signup_helper. Call the AEP like so:

						
GET https://actionnetwork.org/api/v2/

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

Will return a response like this:

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "motd": "Welcome to the Action Network OSDI API v2 Entry Point!",
  "_links": {
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "http://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ],
    "canvasser:brand_logo": {
      "href": "https://actionnetwork.org/images/logo.png",
      "title": "The branding logo for use in UI"
    },
    "docs": {
      "href": "https://actionnetwork.org/docs/",
      "title": "Documentation",
      "name": "Docs",
      "index": "index"
    },
    "self": {
      "title": "This API entry point",
      "href": "https://actionnetwork.org/api/v2/"
    },
    "osdi:people": {
      "title": "The collection of people in the system",
      "href": "https://actionnetwork.org/api/v2/people"
    },
    "osdi:events": {
      "title": "The collection of events in the system",
      "href": "https://actionnetwork.org/api/v2/events"
    },
    "osdi:petitions": {
      "title": "The collection of petitions in the system",
      "href": "https://actionnetwork.org/api/v2/petitions"
    },
    "osdi:fundraising_pages": {
      "title": "The collection of fundraising_pages in the system",
      "href": "https://actionnetwork.org/api/v2/fundraising_pages"
    },
    "osdi:donations": {
      "title": "The collection of donations in the system",
      "href": "https://actionnetwork.org/api/v2/donations"
    },
    "osdi:advocacy_campaigns": {
      "title": "The collection of advocacy campaigns in the system",
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns"
    },
    "osdi:lists": {
      "title": "The collection of lists in the system",
      "href": "https://actionnetwork.org/api/v2/lists"
    },
    "osdi:forms": {
      "title": "The collection of forms in the system",
      "href": "https://actionnetwork.org/api/v2/forms"
    },
    "osdi:tags": {
      "title": "The collection of tags in the system",
      "href": "https://actionnetwork.org/api/v2/tags"
    },
    "action_network:event_campaigns": {
      "title": "The collection of event campaigns in the system",
      "href": "https://actionnetwork.org/api/v2/event_campaigns"
    },
    "action_network:campaigns": {
      "title": "The collection of campaigns in the system",
      "href": "https://actionnetwork.org/api/v2/campaigns"
    },
    "osdi:person_signup_helper": {
      "title": "Person Signup Helper",
      "href": "https://actionnetwork.org/api/v2/people"
    }
  },
  "max_page_size": 25,
  "vendor_name": "Action Network",
  "product_name": "Action Network",
  "osdi_version": "1.1.1",
  "namespace": "action_network"
}
					

In the response you are able to see the person signup helper's link in the links section. In this case, it's https://actionnetwork.org/api/v2/people.

Back To Top ↑

Post a new person using the person signup helper

To POST the new person using the helper, you'll include an object hash with the person's data. Email address is required, but you can include other fields if you'd like, such as address or custom fields. You can also include an array of tags to tag this person if you'd like. Finally, it's a best practice to include an identifier. Identifiers are deduplicated globally, across groups and API keys, so ensure any you set are globally unique. Here is an example:

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

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

{
  "person" : {
    "identifiers": [
      "my_system:1"
    ],
    "family_name" : "Smith",
    "given_name" : "John",
    "postal_addresses" : [ { "postal_code" : "20009" }],
    "email_addresses" : [ { "address" : "jsmith@mail.com" }]
  },
  "add_tags": [
    "volunteer",
    "member"
  ]
} 
					

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:d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b",
    "my_system:1"
  ],
  "created_date": "2014-03-25T17:09:57Z",
  "modified_date": "2014-03-25T17:09:57Z",
  "family_name": "Smith",
  "given_name": "John",
  "email_addresses": [
    {
      "primary": true,
      "address": "jsmith@mail.com",
      "status": "subscribed"
    }
  ],
   "postal_addresses": [
     {
       "primary": true,
       "address_lines": [
         "1900 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/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b"
    },
    "osdi:attendances": {
      "href": "https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/attendances"
    },
    "osdi:signatures": {
      "href": "https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/signatures"
    },
    "osdi:submissions": {
      "href": "https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/submissions"
    },
    "osdi:donations": {
      "href": "https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/donations"
    },
    "osdi:outreaches": {
      "href": "https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/outreaches"
    },
    "osdi:taggings": {
      "href": "https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/taggings"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
					

The response is your person object.

People are matched and deduplicated by email address. If a new person is created as part of a POST operation, that person will be added to the email list associated with your API key and have the status you passed in the API call. (No status will subscribe the person. Adding a new person with the unsubscribed status will add them to the list unsubscribed.) If the email address is found, that person's subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed or unsubscribed in the status field, as described in the people documentation. In that case, the person will be subscribed or unsubscribed to the list, even if they previously had a different status. (In networks, a subscribed status will travel up the network where an unsubscribed will not.) No other status fields are valid on this endpoint.

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. 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 or unsubscribed in the status field, as described in the people documentation. In that case, they 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 on this endpoint.

Either way, if the tags for "volunteer" and "member" already exist, they were added to this person's record. If not, they were ignored.

People posted this way will act as if they'd been uploaded, so they won't be matched by the activity filter when targeting.

Click here for full documentation of people resources.

Back To Top ↑

Next Tutorial: Post a new fundraising page from another system and add donors to that page and your list