Tutorial: Get People
This tutorial demonstrates how to navigate to the people collection using the Action Network API and browse through a list of people subscribed to the list associated with your API key.
Steps:
Calling the API Entry Point (AEP)
The API entry point (AEP) is the top URL where the Action Network API is located. From the AEP you can use HAL links to navigate to every resource contained within the API.
Call the AEP using your preferred method of making API calls (curl, etc...) like this:
GET https://actionnetwork.org/api/v1/
Header:
Content-Type: application/json
api-key:[your api key here]
Will return a response like this:
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{ "motd": "Welcome to the Action Network OSDI API Entry Point!", "_links": { "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/", "title": "This API entry point" }, "osdi:people": { "href": "https://actionnetwork.org/api/v1/people", "title": "The collection of people in the system" }, "osdi:questions": { "href": "https://actionnetwork.org/api/v1/questions", "title": "The collection of questions in the system" }, "osdi:events": { "href": "https://actionnetwork.org/api/v1/events", "title": "The collection of events in the system" }, "osdi:petitions": { "href": "https://actionnetwork.org/api/v1/petitions", "title": "The collection of petitions in the system" }, "osdi:fundraising_pages": { "href": "https://actionnetwork.org/api/v1/fundraising_pages", "title": "The collection of fundraising_pages in the system" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/donations", "title": "The collection of donations in the system" }, "osdi:queries": { "href": "https://actionnetwork.org/api/v1/queries", "title": "The collection of queries in the system" }, "osdi:forms": { "href": "https://actionnetwork.org/api/v1/forms", "title": "The collection of forms in the system" }, "docs": { "href": "https://actionnetwork.org/docs/v1/", "title": "Documentation", "name": "Docs", "index": "index" } } }
The response shows links to all of the collections available in the API, as well as links to documentation.
You can use the links provided to navigate to the various resource collections the API provides, such as the collection of people subscribed to your list.
Back To Top ↑Calling the people collection
Next, navigate to the link for the people collection and call it to get the collection of all of the people subscribed to your list:
GET https://actionnetwork.org/api/v1/people/
Header:
Content-Type: application/json
api-key:[your api key here]
Will return a response like this:
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" ], "modified_at": "2014-03-20T21:04:31Z", "email_addresses": [ { "primary": true, "address": "johnsmith@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/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" ], "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 ] } }
In the response you are able to see and parse data about each person -- their email address, their physical address, their name, etc... Each person has at least an Action Network identifier as well, which is used to form URLs in the API.
You can use the links provided to navigate to each specific person, pull a list of all of their signatures on petitions, or view the next page of people.
You can also use URL arguments to change how the paging works. Use ?page=[page number] to jump to a specific page, and ?per_page=[number of items per page] to control how many people are shown for each call. Note: You can retrieve a maximum of 25 resources per page.
Click here for full documentation of people resources.