Tutorial: Add People Version 2
This tutorial demonstrates how to add new people to your email list and database by posting them using the person signup helper.
The Action Network does not support adding people without the helper, as the helper performs deduplication based on email address and phone number, a key part of our system.
In this tutorial, we'll explore adding a person using the helper.
Steps:
Find the person signup helper
The link to the person signup helper is available on the API entry point (AEP), labeled osdi:person_signup_helper. Call the AEP like so:
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" }
In the response you are able to see the person signup helper's link in the links section. In this case, it's https://actionnetwork.org/api/v2/people.
Post a new person using the person signup helper
To POST the new person using the helper, you'll include an object hash with the person's data. Email address or phone number is required, but you can include other fields if you'd like, such as address or custom fields. You can also include an array of tags to tag this person if you'd like.
POST https://actionnetwork.org/api/v2/people/ Header: Content-Type: application/json OSDI-API-Token: your_api_key_here{ "person" : { "family_name" : "Smith", "given_name" : "John", "postal_addresses" : [ { "postal_code" : "20009" }], "email_addresses" : [ { "address" : "jsmith@mail.com" }], "phone_number" : [ { "number" : "12021234444" }] }, "add_tags": [ "volunteer", "member" ] }
Which will return a response like this:
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{ "identifiers": [ "action_network:d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b" ], "created_date": "2014-03-25T17:09:57Z", "modified_date": "2014-03-25T17:09:57Z", "family_name": "Smith", "given_name": "John", "email_addresses": [ { "primary": true, "address": "jsmith@mail.com", "status": "subscribed" } ], "phone_numbers": [ { "primary": true, "number": "12021234444", "number_type": "Mobile", "status": "unsubscribed" } ], "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" ], "_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" }, "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 response is your person object.
People are matched and deduplicated by phone number and email address, both of which can be attached to an activist record. People are required to have either an email address or a phone number. If a person is posted without an email address, a record with only phone number will be created and vice versa. 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.
If the email or phone number posted corresponds with a person already in the system, we update their record instead of creating a new person. If the person is new to your email list, they will be subscribed to the email list associated with your API key. If they are an existing person already in your group, their email subscription status will not change unless you pass subscribed or unsubscribed in the status field, as described in the people documentation. In that case, their status will be changed to the passed subscription status. (In networks, subscribed statuses will travel up the network. Unsubscribed statuses will not). No other status fields are valid at this endpoint.
People's mobile subscription status works differently than email subscription status. If they are new to your mobile list, by default they will be added as unsubscribed, unless you pass subscribed or unsubscribed. If they are an existing person already in your group, the person's mobile subscription status will not be changed, unless you pass subscribed or unsubscribed in the mobile status field. (In networks, if this group does has the 'mobile status goes up the network' setting checked, a mobile subscribed status will travel up the network where an unsubscribed will not.) No other status fields are valid on this endpoint.
If the tags for 'volunteer' and 'member' already exist, they were added to this person's record. If not, they were ignored.
People posted this way will act as if they'd been uploaded, so they won't be matched by the activity filter when targeting.
Background processing is available on this operation via thebackground_request=true URL argument. You can learn more about background processing here.
Click here for full documentation of people resources.
Back To Top ↑