Tutorial: Get People Version 2
This tutorial demonstrates how to navigate to the people collection using the Action Network API and browse through a list of people on the list associated with your API key, both subscribed and unsubscribed.
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/v2/
Header:
Content-Type: application/json
OSDI-API-Token: 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 v2 Entry Point!", "_links": { "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v2/{rel}", "templated": true }, { "name": "action_network", "href": "http://actionnetwork.org/docs/v2/{rel}", "templated": true } ], "canvasser:brand_logo": { "href": "https://actionnetwork.org/images/logo.png", "title": "The branding logo for use in UI" }, "docs": { "href": "https://actionnetwork.org/docs/", "title": "Documentation", "name": "Docs", "index": "index" }, "self": { "title": "This API entry point", "href": "https://actionnetwork.org/api/v2/" }, "osdi:people": { "title": "The collection of people in the system", "href": "https://actionnetwork.org/api/v2/people" }, "osdi:events": { "title": "The collection of events in the system", "href": "https://actionnetwork.org/api/v2/events" }, "osdi:petitions": { "title": "The collection of petitions in the system", "href": "https://actionnetwork.org/api/v2/petitions" }, "osdi:fundraising_pages": { "title": "The collection of fundraising_pages in the system", "href": "https://actionnetwork.org/api/v2/fundraising_pages" }, "osdi:donations": { "title": "The collection of donations in the system", "href": "https://actionnetwork.org/api/v2/donations" }, "osdi:advocacy_campaigns": { "title": "The collection of advocacy campaigns in the system", "href": "https://actionnetwork.org/api/v2/advocacy_campaigns" }, "osdi:lists": { "title": "The collection of lists in the system", "href": "https://actionnetwork.org/api/v2/lists" }, "osdi:forms": { "title": "The collection of forms in the system", "href": "https://actionnetwork.org/api/v2/forms" }, "osdi:tags": { "title": "The collection of tags in the system", "href": "https://actionnetwork.org/api/v2/tags" }, "action_network:event_campaigns": { "title": "The collection of event campaigns in the system", "href": "https://actionnetwork.org/api/v2/event_campaigns" }, "action_network:campaigns": { "title": "The collection of campaigns in the system", "href": "https://actionnetwork.org/api/v2/campaigns" }, "osdi:person_signup_helper": { "title": "Person Signup Helper", "href": "https://actionnetwork.org/api/v2/people" } }, "max_page_size": 25, "vendor_name": "Action Network", "product_name": "Action Network", "osdi_version": "1.1.1", "namespace": "action_network" }
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 on 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 on your list, both subscribed and unsubscribed:
GET https://actionnetwork.org/api/v2/people/
Header:
Content-Type: application/json
OSDI-API-Token: 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{ "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": [ { "created_date": "2014-02-06T16:04:05Z", "modified_date": "2014-02-20T21:16:57Z", "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", "status": "subscribed" } ], "phone_numbers": [ { "primary": true, "number": "19166752557", "number_type": "Mobile", "status": "subscribed" } ], "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/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" } } }, { "created_date": "2014-02-06T16:04:05Z", "modified_date": "2014-02-20T21:16:57Z", "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", "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" } } }, //truncated for brevity ] } }
In the response you are able to see and parse data about each person -- their email address, their phone number, their subscription statuses, 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.
Back To Top ↑