People Version 1

Note: This documentation describes Version 1 of our API, which is now depreciated. It will continue to work, but it will not reveive any updates or bug fixes. We recommend you use Version 2 instead. Documentation for this resource for Version 2 of our API is available here.

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 subscribed to the email list associated with your API key.

People have names, email addresses, 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.

Sections:

Endpoints and URL structures

Endpoints:

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

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

URL Structures:

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

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

Back To Top ↑

Field names and descriptions

Field Name Type Required on POST Description
identifiers array[] An array of identifiers in the format [system name]:[id]. See the general concepts document for more information about identifiers.
originating_system string Yes A human readable string identifying where this person originated. May be used in the user interface for this purpose.
created_at datetime The date and time the resource was created. System generated, not update-able or editable.
modified_at datetime The date and time the resource was last modified. System generated, not update-able or editable.
family_name string The person's last name.
given_name string The person's first name.
email_addresses email_addresses[] Yes An array of email address hashes for the person. At least one is required.
email_addresses.primary boolean If there is more than one email address, we will keep the one marked primary and ignore the others.
email_addresses.address string Yes The email address of the person. At least one is required.
postal_addresses postal_addresses[] Yes An array of postal address hashes for the person. At least one with at least a ZIP code is required.
postal_addresses.primary boolean If there is more than one postal address, we will keep the one marked primary and ignore the others.
postal_addresses.address_lines array[] An array of strings representing the person's street address. We will ignore any beyond the first.
postal_addresses.locality string A city or other local administrative area. This will be overwritten based on our geocoding.
postal_addresses.region string State / subdivision codes according to ISO 3166-2 (Final 2 alpha digits). This will be overwritten based on our geocoding.
postal_addresses.postal_code string Yes Region specific postal code such as ZIP code.
postal_addresses.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.
postal_addresses.language string Language in which the address is recorder -- language code according to ISO 639. This will be overwritten and set to English.
postal_addresses.location hash A hash of location information for the address. This will be overwritten based on our geocoding.
postal_addresses.location.latitude float Geolocation latitude. This will be overwritten based on our geocoding.
postal_addresses.location.longitude float Geolocation longitude. This will be overwritten based on our geocoding.
postal_addresses.location.accuracy enum One of ["Rooftop" "Approximate"]. This will be overwritten based on our geocoding.
Back To Top ↑

Links

Link Name Description
self A link to this individual person resource.
osdi:question_answers A link to a collection of all question answer resources associated with this person. Click here for question_answers documentation.
osdi:attendance 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.
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 subscribed to the email list associated with your api key.

Request

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

Header:
api-key:[your api key here]

Response

						
200 OK

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


{
  "total_pages": 88,
  "per_page": 25,
  "page": 1,
  "total_records": 2188,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v1/people?page=2"
    },
    "osdi:people": [
      {
        "href": "https://actionnetwork.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
      },
      {
        "href": "https://actionnetwork.org/api/v1/people/1efc3644-af25-4253-90b8-a0baf12dbd1e"
      },
      //(truncated for brevity)
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://actionnetwork.org/api/v1/people"
    }
  },
  "_embedded": {
    "osdi:people": [
      {
        "given_name": "John",
        "family_name": "Smith",
        "identifiers": [
          "action_network:d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3",
          "foreign_system:1"
        ],
        "originating_system": "Action Network",
        "created_at": "2014-03-20T21:04:31Z",
        "modified_at": "2014-03-20T21:04:31Z",
        "email_addresses": [
          {
            "primary": true,
            "address": "johnsmith@mail.com"
          }
        ],
        "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"
            }
          }
        ],
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
          },
          "osdi:question_answers": {
            "href": "https://actionnetwork.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/question_answers"
          },
          "osdi:attendance": {
            "href": "https://actionnetwork.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/attendance"
          },
          "osdi:signatures": {
            "href": "https://actionnetwork.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/signatures"
          },
          "osdi:submissions": {
            "href": "https://actionnetwork.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/submissions"
          },
          "osdi:donations": {
            "href": "https://actionnetwork.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/donations"
          }
        }
      },
      {
        "given_name": "Jane",
        "family_name": "Doe",
        "identifiers": [
          "action_network:1efc3644-af25-4253-90b8-a0baf12dbd1e"
        ],
        "originating_system": "Action Network",
        "created_at": "2014-03-20T20:44:13Z",
        "modified_at": "2014-03-20T20:44:13Z",
        "email_addresses": [
          {
            "primary": true,
            "address": "janedoe@mail.com"
          }
        ],
        "postal_addresses": [
          {
            "primary": true,
            "locality": "Washington",
            "region": "DC",
            "postal_code": "20009",
            "country": "US",
            "language": "en",
            "location": {
              "latitude": 38.919,
              "longitude": -77.0379,
              "accuracy": "Approximate"
            }
          }
        ],
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/people/1efc3644-af25-4253-90b8-a0baf12dbd1e"
          },
          "osdi:question_answers": {
            "href": "https://actionnetwork.org/api/v1/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/question_answers"
          },
          "osdi:attendance": {
            "href": "https://actionnetwork.org/api/v1/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/attendance"
          },
          "osdi:signatures": {
            "href": "https://actionnetwork.org/api/v1/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/signatures"
          },
          "osdi:submissions": {
            "href": "https://actionnetwork.org/api/v1/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/submissions"
          },
          "osdi:donations": {
            "href": "https://actionnetwork.org/api/v1/people/1efc3644-af25-4253-90b8-a0baf12dbd1e/donations"
          }
        }
      },
      //(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/v1/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b

Header:
api-key:[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"
  ],
  "originating_system": "Action Network",
  "created_at": "2014-03-25T17:09:57Z",
  "modified_at": "2014-03-25T17:09:57Z",
  "email_addresses": [
    {
      "primary": true,
      "address": "johndoe@mail.com"
    }
  ],
   "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"
       }
     }
  ],
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b"
    },
    "osdi:question_answers": {
      "href": "https://actionnetwork.org/api/v1/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/question_answers"
    },
    "osdi:attendance": {
      "href": "https://actionnetwork.org/api/v1/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/attendance"
    },
    "osdi:signatures": {
      "href": "https://actionnetwork.org/api/v1/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/signatures"
    },
    "osdi:submissions": {
      "href": "https://actionnetwork.org/api/v1/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/submissions"
    },
    "osdi:donations": {
      "href": "https://actionnetwork.org/api/v1/people/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b/donations"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{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.

New people can be created an subscribed to your email list by posting an action they've taken either on an existing page or a new one you create with the API. See the documentation describing each action type (petitions, events, forms, fundraising pages) and each individual action record (signatures, attendance, submissions, donations) for details.

Back To Top ↑

Scenario: Modifying a person (PUT)

The people collection does not allow PUT -- modifying a person directly is not allowed.

To modify a person's information, post an action they've taken either on an existing page or a new one you create with the API. See the documentation describing each action type (petitions, events, forms, fundraising pages) and each individual action record (signatures, attendance, submissions, donations) for details.

Back To Top ↑

Scenario: Unsubscribing a person (DELETE)

To unsubscribe a person from the email list associated with your API key, use the DELETE verb on their person resource.

Request

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

Header:
api-key:[your api key here]

Response

						
200 OK

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


{
  "notice": "This user was successfully unsubscribed."
}
Back To Top ↑