Tutorial: Add People
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 tutorial for Version 2 of our API is available here.
This tutorial demonstrates how to add new people to your email list and database by posting them taking action on an existing action page, in this case a form.
The Action Network does not support adding people directly. For example, you could not POST to the people endpoint to add a new name to your database. All people you add must be added by completing some kind of action -- say, signing a petition or attending an event. You can register these actions via the API.
In this tutorial, we'll explore adding a person by having them taking action on an existing action page you've published using our user interface. In the next tutorial, you'll learn how to create a new action via the API and add a person that way. This is useful for syncing "actions" that have taken place in another system (say, a sign in sheet at an event that was uploaded to a CRM).
Steps:
- Call the action where you will post a new submission
- Get the collection of existing submissions on this form
- Post a new action and person at the same time
Call the action where you will post a new submission
From the API entry point, navigate to the action type you're interested in, and then the specific action you'd like to post a new submission and person on. In this tutorial, we'll use an existing form. Call the form resource like so:
GET https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb
Header:
api-key:[your api key here]
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:8a0ab1b8-f965-4a96-bbd7-f500690d4beb" ], "created_at": "2014-03-06T18:09:08Z", "modified_at": "2014-03-06T19:24:17Z", "summary": "Take our end of year survey", "description": "<p>Please fill out our survey to let us know what's important to you this year.</p>", "call_to_action": "Share your tip", "url": "https://actionnetwork.org/forms/take-our-end-of-year-survey", "total_submissions": 251, "_embedded": { "osdi:creator": { "given_name": "Jane", "family_name": "Miller", "identifiers": [ "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29" ], "email_addresses": [ { "primary": true, "address": "j.miller@mail.com" } ], "postal_addresses": [ { "primary": true, "address_lines": [ "1600 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/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/question_answers" }, "osdi:attendance": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/attendance" }, "osdi:signatures": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/signatures" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/submissions" }, "osdi:donations": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29/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 } ] } } }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb" }, "osdi:submissions": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions" }, "osdi:creator": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "action_network:embed": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/embed" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } }
In the response you are able to see and parse data about this form -- the form's name, the URL to the signup page on the Action Network, who created the form, the total number of submissions, etc...
Back To Top ↑Get the collection of existing submissions on this form
Using the links provided, you can navigate to a collection of existing submissions on this form.
Call the submissions collection like this:
GET https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions
Header:
api-key:[your api key here]
Which will return a response like this:
200 OK Content-Type: application/hal+json Cache-Control: max-age=0, private, must-revalidate{ "total_pages": 1, "per_page": 25, "page": 1, "total_records": 2123, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions" }, "record_submissions_helper": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions" }, "osdi:submissions": [ { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b43ac894-3737-4b71-8005-97b67e7c8fd5" }, { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b11bddf5-baad-435a-b580-5b7edf5d4194" }, //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 } ] }, "_embedded": { "osdi:submissions": [ { "identifiers": [ "action_network:b43ac894-3737-4b71-8005-97b67e7c8fd5" ], "created_at": "2014-03-06T19:24:17Z", "modified_at": "2014-03-06T19:24:18Z", "action:person_id": "0c6edde5-ee8d-4592-96fd-9a1d1b50641d", "action_network:form_id": "8a0ab1b8-f965-4a96-bbd7-f500690d4beb", "_embedded": { "osdi:question_answers": [ { "identifiers": [ "action_network:dd92be6e-b90a-41e2-b1b6-3f019d6d896a" ], "value": "The Environment", "person_id": "0c6edde5-ee8d-4592-96fd-9a1d1b50641d", "question_id": "2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a", "_embedded": { "osdi:question": { "identifiers": [ "action_network:2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a" ], "name": "What is your most important issue?", "question_type": "Paragraph", "created_at": "2014-03-07T14:19:25Z", "modified_at": "2014-03-07T14:19:25Z", "_links": { "self": { "href": "https://actionnetwork.org/api/v1/questions/2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/questions/2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a/question_answers" } } } }, "created_at": "2014-03-06T19:24:17Z", "modified_at": "2014-03-06T19:24:18Z", "_links": { "self": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b43ac894-3737-4b71-8005-97b67e7c8fd5/question_answers/dd92be6e-b90a-41e2-b1b6-3f019d6d896a" }, "osdi:question": { "href": "https://actionnetwork.org/api/v1/questions/2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a" }, "osdi:person": { "href": "https://actionnetwork.org/api/v1/people/0c6edde5-ee8d-4592-96fd-9a1d1b50641d" } } } ] }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b43ac894-3737-4b71-8005-97b67e7c8fd5" }, "osdi:form": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb" }, "osdi:person": { "href": "https://actionnetwork.org/api/v1/people/0c6edde5-ee8d-4592-96fd-9a1d1b50641d" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b43ac894-3737-4b71-8005-97b67e7c8fd5/question_answers" } } }, { "identifiers": [ "action_network:b11bddf5-baad-435a-b580-5b7edf5d4194" ], "created_at": "2014-03-06T18:09:58Z", "modified_at": "2014-03-06T18:09:58Z", "action:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29", "action_network:form_id": "8a0ab1b8-f965-4a96-bbd7-f500690d4beb", "_embedded": { "osdi:question_answers": [ { "identifiers": [ "action_network:9cad814c-1468-4619-98a2-1b61fdb179f8" ], "value": "Social Security", "person_id": "0c6edde5-ee8d-4592-96fd-9a1d1b50641d", "question_id": "2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a", "_embedded": { "osdi:question": { "identifiers": [ "action_network:2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a" ], "name": "What is your most important issue?", "question_type": "Paragraph", "created_at": "2014-03-07T14:19:25Z", "modified_at": "2014-03-07T14:19:25Z", "_links": { "self": { "href": "https://actionnetwork.org/api/v1/questions/2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/questions/2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a/question_answers" } } } }, "created_at": "2014-03-06T19:24:17Z", "modified_at": "2014-03-06T19:24:18Z", "_links": { "self": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b11bddf5-baad-435a-b580-5b7edf5d4194/question_answers/9cad814c-1468-4619-98a2-1b61fdb179f8" }, "osdi:question": { "href": "https://actionnetwork.org/api/v1/questions/2936d4e9-7ea2-45e5-9b2b-1dc5fb38cd8a" }, "osdi:person": { "href": "https://actionnetwork.org/api/v1/people/0c6edde5-ee8d-4592-96fd-9a1d1b50641d" } } } ] }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b11bddf5-baad-435a-b580-5b7edf5d4194" }, "osdi:form": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb" }, "osdi:person": { "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions/b11bddf5-baad-435a-b580-5b7edf5d4194/question_answers" } } }, //(truncated for brevity) ] } }
Here you can see each current submissions on this form. You will use a link in the the links section as your endpoints for your new submission.
Back To Top ↑Post a new action and person at the same time
If all you want to do is add an existing person to this action, you'd post to the submissions endpoint on your form with a link to the person already in the database. However, as you want to post a new person that's not in the database currently (and thus doesn't have a link yet), you want to use the the helper link provided to post a submission and a person at the same time, in this case labeled "record_submissions_helper".
POST to the helper link with an originating system specified (so our API can identify where this submissions came from originally) and a person with at least email address and ZIP code. It's also a best practice to include an identifier, like so:
POST https://actionnetwork.org/api/v1/forms/8a0ab1b8-f965-4a96-bbd7-f500690d4beb/submissions Header: Content-Type: application/json api-key:[your api key here]{ "identifiers": [ "your_system:1" ], "originating_system" : "Your System", "person" : { "family_name" : "Smith", "given_name" : "John", "postal_addresses" : [ { "postal_code" : "20009" }], "email_addresses" : [ { "address" : "johnsmith@mail.com" }] } }
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:32dc6359-76fd-4e97-aef7-f053a4fcc550", "your_system:1" ], "originating_system": "Your System", "created_at": "2014-03-24T18:55:54Z", "modified_at": "2014-03-24T18:55:54Z", "action:person_id": "51529e30-2f2c-46d5-863b-93b39ab2da4c", "action_network:form_id": "adb951cb-51f9-420e-b7e6-de953195ec86", "_embedded": { "osdi:question_answers": [] }, "_links": { "self": { "href": "https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/32dc6359-76fd-4e97-aef7-f053a4fcc550" }, "osdi:form": { "href": "https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86" }, "osdi:person": { "href": "https://actionnetwork.org/api/v1/people/51529e30-2f2c-46d5-863b-93b39ab2da4c" }, "osdi:question_answers": { "href": "https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/32dc6359-76fd-4e97-aef7-f053a4fcc550/question_answers" }, "curies": [ { "name": "osdi", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true }, { "name": "action_network", "href": "https://actionnetwork.org/docs/v1/{rel}", "templated": true } ] } }
The response is your new submissions object, with a link to the new person you created as part of the post.
Click here for full documentation of people resources.