People Version 2

This document describes the OSDI people collection and person resource as implemented by the Action Network.

People are individual activists who have taken some action on the Action Network or been otherwise imported to the database via the API or other means, and are linked to the email list associated with your API key, whether their status is subscribed, unsubscribed, or the like.

People have names, email addresses, mobile numbers, and other information, and they have associated action histories recording the actions they've taken on the system, such as a list of their signatures on various petitions.

Note: The Action Network deduplicates people based on email address. The people collection does not return the total_records or total_pages fields. And people are not ordered by newest modified_date first. All of this has been done to improve API response speed.

Sections:

Endpoints and URL structures

Endpoints:

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

People resources live exclusively at the above endpoint. The endpoint returns a collection of all the people associated with the email list associated with your API key.

URL Structures:

https://actionnetwork.org/api/v2/people/[id]

To address a specific person, use their identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3

Back To Top ↑

Field names and descriptions

People fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. Must be globally unique. See the general concepts document for more information about identifiers.
created_date datetime The date and time the resource was created, corresponding to when the person was first added to the list associated with your API key. System generated, not update-able or editable.
modified_date datetime The date and time the resource was last modified. This includes the last time personal information was changed, subscription status was changed, custom fields were changed, or the person was updated in any other way (such as was part of an upload or took an action). System generated, not update-able or editable.
family_name string The person's last name.
given_name string The person's first name.
languages_spoken strings[] An array of languages spoken (using language codes) indicating the language preference of the person. Action Network supports one language per person, and only the following languages: English (en), Arabic (ar), Bulgarian (bg), Danish (da), Dutch (nl), Finnish (fi), French (fr), Georgian (ka), German (de), Hebrew (he), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Latvian (lv), Lithuanian (lt), Moldovan (mo), Norwegian (no), Polish (pl), Portuguese (pt-BR), Russian (ru), Serbian (sr), Simplified Chinese (zh), Slovenian (sl), Spanish (es), Swedish (sv), Turkish (tr), Vietnamese (vi), and Welsh (cy). Adding more than one language to the array will result in the first valid language being set as the preferred language for the person. Unknown languages will be ignored. People with no language or invalid languages will default to English.
email_addresses Email Addresses[] Yes, or a phone number An array of email address hashes for the person. An email address or phone number is required for POSTs.
phone_numbers Phone Numbers[] Yes, or an email address An array of phone number hashes for this person. An email address or phone number is required for POSTs.
postal_addresses Postal Addresses[] An array of postal address hashes for the person. At least one with at least a ZIP code is required.
custom_fields Custom Fields An object hash of key/value pairs associated with the person, corresponding to custom fields/questions in Action Network.
Email Addresses fields:
Field Name Type Required on POST Description
primary boolean If there is more than one email address, we will keep the one marked primary and ignore the others.
address string Yes, or a phone number The email address of the person. An email address or phone number is required. Changing an email address via PUT may not work -- see the note in the PUT scenario for more details.
status string Denotes the subscription status of this email address. One of ['subscribed', 'unsubscribed', 'bouncing', 'previous bounce', 'spam complaint', or 'previous spam complaint']. Changing the subscription status, either via PUT or via POST on one of the helpers, will subscribe or potentially unsubscribe the activist from the list associated with your API key. The statuses of 'subscribed' or 'unsubscribed' are the only ones that can be set via PUT or POST. See each helper documentation for which statuses are valid on which helper.
Phone Numbers fields:
Field Name Type Required on POST Description
primary boolean If there is more than one phone number, we will keep the one marked primary and ignore the others.
number string Yes, or an email address The mobile number for this person, displayed in international format without the plus sign. Will be accepted in international or national format, and be formatted to accept international numbers, more here. An email address or phone number is required.
number_type string The type of phone number for this person. Will always be mobile.
status string Denotes the subscription status of this phone number. One of ['subscribed', 'unsubscribed', 'bouncing', or 'previous bounce']. Changing the subscription status, either via PUT or via POST on one of the helpers, will subscribe or potentially unsubscribe the activist from the list associated with your API key. The statuses of 'subscribed' or 'unsubscribed' are the only ones that can be set via PUT or POST. See each helper documentation for which statuses are valid on which helper.
Postal Addresses fields:
Field Name Type Required on POST Description
primary boolean If there is more than one postal address, we will keep the one marked primary and ignore the others.
address_lines strings[] An array of strings representing the person's street address. We will ignore any beyond the first.
locality string A city or other local administrative area. This will be filled in if blank, based on our geocoding.
region string State / subdivision codes according to ISO 3166-2 (Final 2 alpha digits). This will be overwritten based on our geocoding.
postal_code string Region specific postal code such as ZIP code.
country string Country code according to ISO 3166-1 Alpha-2. Unless you pass us a country code, US will be assumed and added automatically. If you pass another address part (such as address lines or postal code) and you don't also pass country, US will be assumed, so always set country on your people calls if you want a country outside of the US.
language string Language in which the address is recorder -- language code according to ISO 639. This will be overwritten and set to English ('EN').
location hash A hash of geolocation information for the address. This will be overwritten based on our geocoding.
location.latitude float Geolocation latitude. This will be overwritten based on our geocoding.
location.longitude float Geolocation longitude. This will be overwritten based on our geocoding.
location.accuracy enum One of ['Rooftop' 'Approximate']. This will be overwritten based on our geocoding.
Custom fields:
Field Name Type Required on POST Description
[key] string The key associated with this custom field, with a corresponding value as a string.
Back To Top ↑

Links

Link Name Description
self A link to this individual person resource.
osdi:attendances A link to a collection of all attendance resources associated with events this person has signed up to attend. Click here for attendance documentation.
osdi:signatures A link to a collection of all signature resources associated with petitions this person has signed. Click here for signatures documentation.
osdi:submissions A link to a collection of all signup resources associated with forms this person has submitted. Click here for submissions documentation.
osdi:donations A link to a collection of all donation resources associated with fundraisers this person has donated on. Click here for donations documentation.
osdi:outreaches A link to a collection of all outreach resources associated with advocacy campaigns this person has taken action on. Click here for outreach documentation.
osdi:taggings A link to a collection of all tagging resources associated with tags this person has on their record. Click here for tagging documentation.
action_network:responses A link to a collection of all response resources associated with surveys this person has taken action on. Click here for response documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of person resources (GET)

Person resources are sometimes presented as collections of people. For example, calling the people endpoint will return a collection of all the people associated with the email list associated with your api key, including in all subscription statuses (subscribed, unsubscribed, etc...).

Request

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

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

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


{
  "per_page": 25,
  "page": 1,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/people?page=2"
    },
    "osdi:people": [
      {
        "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
      },
      {
        "href": "https://actionnetwork.org/api/v2/people/1efc3644-af25-4253-90b8-a0baf12dbd1e"
      },
      //(truncated for brevity)
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://actionnetwork.org/api/v2/people"
    }
  },
  "_embedded": {
    "osdi:people": [
      {
        "given_name": "John",
        "family_name": "Smith",
        "identifiers": [
          "action_network:d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3",
          "foreign_system:1"
        ],
        "created_date": "2014-03-20T21:04:31Z",
        "modified_date": "2014-03-20T21:04:31Z",
        "email_addresses": [
          {
            "primary": true,
            "address": "johnsmith@mail.com",
            "status": "subscribed"
          }
        ],
        "phone_numbers": [
          {
            "primary": true,
            "number": "12024444444",
            "number_type": "Mobile",
            "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"
        ],
        "custom_fields": { 
          "phone": "310.753.8209",
          "I am a parent": "1"
        },
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
          },
          "osdi:attendances": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/attendances"
          },
          "osdi:signatures": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/signatures"
          },
          "osdi:submissions": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/submissions"
          },
          "osdi:donations": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/donations"
          },
          "osdi:outreaches": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/outreaches"
          },
          "osdi:taggings": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/taggings"
          },
		  "action_network:responses": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/responses"
          }
        }
      },
      {
        "given_name": "Jane",
        "family_name": "Doe",
        "identifiers": [
          "action_network:1efc3644-af25-4253-90b8-a0baf12dbd1e"
        ],
        "origin_system": "Action Network",
        "created_date": "2014-03-20T20:44:13Z",
        "modified_date": "2014-03-20T20:44:13Z",
        "email_addresses": [
          {
            "primary": true,
            "address": "janedoe@mail.com",
            "status": "unsubscribed"
          }
        ],
        "phone_numbers": [
          {
            "primary": true,
            "number_type": "Mobile",
            "status": "unsubscribed"
          }
        ],
        "postal_addresses": [
          {
            "primary": true,
            "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/1efc3644-af25-4253-90b8-a0baf12dbd1e"
          },
          "osdi:attendances": {
            "href": "https://actionnetwork.org/api/v2/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/attendances"
          },
          "osdi:signatures": {
            "href": "https://actionnetwork.org/api/v2/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/signatures"
          },
          "osdi:submissions": {
            "href": "https://actionnetwork.org/api/v2/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/submissions"
          },
          "osdi:donations": {
            "href": "https://actionnetwork.org/api/v2/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/donations"
          },
          "osdi:outreaches": {
            "href": "https://actionnetwork.org/api/v2/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/outreaches"
          },
          "osdi:taggings": {
            "href": "https://actionnetwork.org/api/v2/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/taggings"
          },
		  "action_network:responses": {
            "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/responses"
          }
        }
      },
      //(truncated for brevity)
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual person resource (GET)

Calling an individual person resource will return the resource directly, along with all associated fields and appropriate links to additional information about the person.

Request

						
GET https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b",
    "foreign_system:1"
  ],
  "created_date": "2014-03-25T17:09:57Z",
  "modified_date": "2014-03-25T17:09:57Z",
  "email_addresses": [
    {
      "primary": true,
      "address": "johndoe@mail.com",
      "status": "subscribed"
    }
  ],
  "phone_numbers": [
    {
      "primary": true,
      "number": "12021234444",
      "number_type": "Mobile",
      "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"
  ],
  "custom_fields": { 
    "phone": "310.753.8209",
    "I am a parent": "1"
  },
  "_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"
    },
	"action_network:responses": {
      "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/responses"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new person (POST)

The people collection does not allow POST -- posting a new person directly to the people endpoint is not allowed.

People can be created by using the person signup helper, documented here.

Back To Top ↑

Scenario: Modifying a person (PUT)

You can modify an existing person by using PUT on its individual endpoint.

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

Request

						
PUT https://actionnetwork.org/api/v2/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/

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

{	
  "languages_spoken": [
    "fr"
  ]
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b",
    "foreign_system:1",
    "another_foreign_system:5"
  ],
  "created_date": "2014-03-25T17:09:57Z",
  "modified_date": "2014-03-25T17:09:57Z",
  "email_addresses": [
    {
      "primary": true,
      "address": "johndoe@mail.com",
      "status": "subscribed"
    }
  ],
  "phone_numbers": [
    {
      "primary": true,
      "number": "19166752557",
      "number_type": "Mobile",
      "status": "subscribed"
    }
  ],
   "postal_addresses": [
     {
       "primary": true,
       "address_lines": [
         "1900 Pennsylvania Ave"
       ],
       "locality": "Washington",
       "region": "DC",
       "postal_code": "20009",
       "country": "US",
       "location": {
         "latitude": 38.919,
         "longitude": -77.0379,
         "accuracy": "Approximate"
       }
     }
  ],
  "languages_spoken": [
    "fr"
  ],
  "custom_fields": { 
    "phone": "310.753.8209",
    "I am a parent": "1"
  },
  "_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"
    },
	"action_network:responses": {
      "href": "https://actionnetwork.org/api/v2/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/responses"
    },
    "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 above example changed the person's language to French.

Editing of certain fields via PUT is not allowed, and is noted in the field names table above. For example, you can't change the created_date or modified_date timestamps.

The phone number can take international format or national format and will be sanitized to international format when storing. It will use the user's country (or the group default if no country is passed and the user doesn't match anyone existing) for the country number prefix.

A note on changing email address: While you can change a person's email address with PUT, because email address is our primary key, if the email address you're trying to change to already exists in our system, the change will not be allowed and the person resource will be returned in the response without the change having been made. To change the email address of a person to another email address that already exists in our system, you must use our user interface to resolve potential data conflicts between the two people.

A note on changing phone number: 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 mobile-only record, then the records will be merged. More on deduplicating here.

Back To Top ↑

Scenario: Deleting a person (DELETE)

Deleting a person is not allowed via the API. DELETE requests will return an error.

Back To Top ↑