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

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.

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

And of course you can POST a person with more fields such as address lines or custom fields if you'd like, but they are not required.

Back To Top ↑