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 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 email subscription status you passed in the API call. (No email subscription 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.

People also have a mobile subscription status, indicating whether they are subscribed or not to the mobile list. New people who are added to the mobile list associated with your API key will have the status you passed in the API call. (No status will add the person as unsubscribed. Note that this is the opposite of email subscriptions, where default for new people is subscribed.) If the person is found (via email address matching, as explained above), that person's mobile subscription status will not be changed unless you pass subscribed or unsubscribed in the mobile status field. In this case, the person will be subscribed or unsubscribed to the mobile list, even if they previously had a different status. (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.

We also deduplicate by phone number. If the phone number you add to a person (or change on a person) already exists in our system, the number will be added or changed on this person, but the phone number will be removed from the old person record. More details on phone deduplication here.

Items in the optional 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 to the person's record. If not, the tag will be 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.

Sections:

Endpoint

Endpoint:

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

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

Back To Top ↑

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.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Creating a new person (POST)

If you post with an inline person hash, we will create or update the matching person.

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

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.

With regard to mobile subscription status, if the person is new, they will be subscribed to the mobile 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, their status will be changed to the passed subscription status. (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.

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"
  ]
} 
					

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, so if the email 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 -- and any posts missing that information will fail.

If the person is new, they will be subscribed to the email 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.

With regard to mobile subscription status, if the person is new, they will be subscribed to the mobile 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, 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.

We also deduplicate by phone number. If the phone number you add to a person (or change on a person) already exists in our system, the number will be added or changed on this person, but the phone number will be removed from the old person record. More details on phone deduplication here.

Back To Top ↑