Action Network

Person Signup Helper Version 2

This document describes the OSDI person signup helper endpoint as implemented by the Action Network.

The person signup helper allows you to create or update a person record as well as optionally tag that person. This is the only way to directly POST to the person endpoint.

The person signup helper takes the normal person format (described here) and an optional array of tags to add to the person's record.

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 phone-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

Items in the optional add_tags and remove_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 or removed from the person's record. If not, the tag will be ignored. The operation to add tags will always run before the operation to remove tags.

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

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Endpoint

Endpoint:

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

The person signup helper lives at the endpoint relating to the collection of people.

Field names and descriptions

Person Signup Helper fields:

Field Name	Type	Required on POST	Description
person	Person*	Yes	A hash representing person data. You can use any valid fields for person resources. An email address is required. See the people document for more information about people.
add_tags	strings[]		An array of strings representing tags to add to the person's record.
remove_tags	strings[]		An array of strings representing tags to remove from the person's record.

Related resources

People

Scenario: Creating a new person (POST)

If you post with an inline person hash, we will create or update the matching person. A person must be added with an email address or a phone number, or both.

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

People are matched and deduplicated by email address and phone number. If a new person with an email address 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 email 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 email 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.

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.

Here is an example of posting a person to the special person_signup_helper link on the person collection, along with tags:

Request

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

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

{
  "person" : {
    "family_name" : "Smith",
    "given_name" : "John",
    "postal_addresses" : [ { "postal_code" : "20009" }],
    "email_addresses" : [ { "address" : "jsmith@mail.com" }],
    "phone_numbers": [ {"number": "2021234444" }]
   },
  "add_tags": [
    "volunteer",
    "member"
  ],
  "remove_tags": [
    "inactive"
  ]
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b"
  ],
  "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"
    }
  ],
  "phone_numbers": [
   {
    "primary": true,
    "number": "12021234444",
    "number_type": "Mobile",
    "status": "unsubscribed"
   }
],
   "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
      }
    ]
  }
}

In the above example, a new person was created and the tags 'volunteer' and 'member' were added to that person's record as well. We deduplicate new people added this way by email address and phone number, so if the email or phone number 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 or phone number -- and any posts missing that information will fail.