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
- Field names and descriptions
- Links
- Scenario: Retrieving a collection of person resources (GET)
- Scenario: Retrieving an individual person resource (GET)
- Scenario: Creating a new person (POST)
- Scenario: Modifying a person (PUT)
- Scenario: Deleting a person (DELETE)
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
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. |
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. |
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
Back To Top ↑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) ] } }
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
Back To Top ↑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 } ] } }
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
Back To Top ↑200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{ "notice": "This user was successfully unsubscribed." }