Forms 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 forms collection and form resource as implemented by the Action Network.

Forms are a type of action created by the organizer or group associated with your API key that involves activists filling out the form and submitting their information.

Forms have summaries (titles) and can have descriptions and other fields, and when activists submit them submission resources are created representing the submission an activist made on that form.

Forms are not deduplicated except on identifiers, to keep identifiers unique.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v1/forms

Form resources live exclusively at the above endpoint. The endpoint returns a collection of all the forms associated with your API key.

URL Structures:

https://actionnetwork.org/api/v1/forms/[id]

To address a specific form, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v1/forms/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3

Back To Top ↑

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 form 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 editable.
modified_at datetime The date and time the resource was last modified. System generated, not editable.
summary string Yes The form's title.
description string The form's description. May contain HTML.
call_to_action string A call to action signifying what an activist does by submitting the form. (ex: Tell your story)
url string The URL to this form on the Action Network. Only present for forms created with our user interface. Not editable.
total_submissions integer A system generated count of the number of submissions on this petition. Not editable.
osdi:creator osdi:person* An embedded person representing the user who created this form. If you do not assign a creator, we will assign one based on your API key. Cannot be edited once created.
action_network:sponsor hash A hash of the sponsoring group of this form. Action Network-only feature. Automatically added if you post using a group API key. System generated, not editable.
action_network:sponsor.summary string The name of the sponsoring group.
action_network:sponsor.url string The URL to the group's public page.
Back To Top ↑

Links

Link Name Description
self A link to this individual form resource.
osdi:submissions A link to a collection of all submission resources associated with this form. Click here for submissions documentation.
osdi:creator A link to the person who created this form. Click here for people documentation.
action_network:embed A link to embed code for this form. Action Network-only feature. Click here for embed documentation.
Back To Top ↑

Scenario: Retrieving a collection of form resources (GET)

Form resources are sometimes presented as collections of forms. For example, calling the forms endpoint will return a collection of all the forms associated with your API key.

Request

						
GET https://actionnetwork.org/api/v1/forms/

Header:
api-key:[your api key here]

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "total_pages": 10,
  "per_page": 25,
  "page": 1,
  "total_records": 250,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v1/forms?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v1/forms"
    },
    "osdi:forms": [
      {
        "href": "https://actionnetwork.org/api/v1/forms/65345d7d-cd24-466a-a698-4a7686ef684f"
      },
      {
        "href": "https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86"
      },
      //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:forms": [
      {
        "originating_system": "FreeForms.com",
        "identifiers": [
          "action_network:65345d7d-cd24-466a-a698-4a7686ef684f",
          "free_forms:1"
        ],
        "created_at": "2014-03-25T14:40:07Z",
        "modified_at": "2014-03-25T14:47:44Z",
        "summary": "Tell your story",
        "total_submissions": 25,
        "_embedded": {
          "osdi:creator": {
            "given_name": "John",
            "family_name": "Doe",
            "identifiers": [
              "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29"
            ],
            "originating_system": "Action Network",
            "created_at": "2014-03-24T18:03:45Z",
            "modified_at": "2014-03-25T15:00:22Z",
            "email_addresses": [
              {
                "primary": true,
                "address": "jdoe@mail.com"
              }
            ],
            "postal_addresses": [
              {
                "primary": true,
                "address_lines": [
                  "1600 Pennsylvania Ave"
                ],
                "locality": "Washington",
                "region": "DC",
                "postal_code": "20009",
                "country": "US",
                "language": "en",
                "location": {
                  "latitude": 32.935,
                  "longitude": -73.1338,
                  "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"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/forms/65345d7d-cd24-466a-a698-4a7686ef684f"
          },
          "osdi:submissions": {
            "href": "https://actionnetwork.org/api/v1/forms/65345d7d-cd24-466a-a698-4a7686ef684f/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/65345d7d-cd24-466a-a698-4a7686ef684f/embed"
          }
        }
      },
      {
        "identifiers": [
          "action_network:adb951cb-51f9-420e-b7e6-de953195ec86"
        ],
        "created_at": "2014-03-21T23:39:53Z",
        "modified_at": "2014-03-25T15:26:45Z",
        "summary": "Take our end of year survey",
        "description": "<p>Let us know what you think!</p>",
        "call_to_action": "Let us know",
        "url": "https://actionnetwork.org/forms/end-of-year-survey",
        "total_submissions": 6,
        "_embedded": {
          "osdi:creator": {
            "given_name": "John",
            "family_name": "Doe",
            "identifiers": [
              "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29"
            ],
            "originating_system": "Action Network",
            "created_at": "2014-03-24T18:03:45Z",
            "modified_at": "2014-03-25T15:00:22Z",
            "email_addresses": [
              {
                "primary": true,
                "address": "jdoe@mail.com"
              }
            ],
            "postal_addresses": [
              {
                "primary": true,
                "address_lines": [
                  "1600 Pennsylvania Ave."
                ],
                "locality": "Washington",
                "region": "DC",
                "postal_code": "20009",
                "country": "US",
                "language": "en",
                "location": {
                  "latitude": 32.934,
                  "longitude": -74.5319,
                  "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"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86"
          },
          "osdi:submissions": {
            "href": "https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86/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/adb951cb-51f9-420e-b7e6-de953195ec86/embed"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual form resource (GET)

Calling an individual form resource will return the resource directly, along with all associated fields and appropriate links to additional information about the form.

Request

						
GET https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86

Header:
api-key:[your api key here]

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "action_network:adb951cb-51f9-420e-b7e6-de953195ec86"
  ],
  "created_at": "2014-03-21T23:39:53Z",
  "modified_at": "2014-03-25T15:26:45Z",
  "summary": "form combo posting testing",
  "summary": "Take our end of year survey",
  "description": "<p>Let us know what you think!</p>",
  "call_to_action": "Let us know",
  "url": "https://actionnetwork.org/forms/end-of-year-survey",
  "total_submissions": 6,
  "_embedded": {
    "osdi:creator": {
      "given_name": "John",
      "family_name": "Doe",
      "identifiers": [
        "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29"
      ],
      "originating_system": "Action Network",
      "created_at": "2014-03-24T18:03:45Z",
      "modified_at": "2014-03-25T15:00:22Z",
      "email_addresses": [
        {
          "primary": true,
          "address": "jdoe@mail.com"
        }
      ],
      "postal_addresses": [
        {
          "primary": true,
          "address_lines": [
            "1600 Pennsylvania Ave"
          ],
          "locality": "Washington",
          "region": "DC",
          "postal_code": "20009",
          "country": "US",
          "language": "en",
          "location": {
            "latitude": 32.934,
            "longitude": -72.0377,
            "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/adb951cb-51f9-420e-b7e6-de953195ec86"
    },
    "osdi:submissions": {
      "href": "https://actionnetwork.org/api/v1/forms/adb951cb-51f9-420e-b7e6-de953195ec86/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/adb951cb-51f9-420e-b7e6-de953195ec86/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
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new form (POST)

You can post a new form to the forms endpoint and a form resource will be created in our system.

Note: Forms created via the API in this way are not equivalent to forms created with our user interface. API-created forms will not show up in lists of all of your actions on your dashboard of group page, they will not be given a URL on actionnetwork.org where people can sign, and they will not have individual manage pages for statistics and submission downloads. Rather, once they have at least one submission, they will show up as actions available for selection in our targeting interface, allowing you to select all people who have taken action on that form for reports or email targeting.

In the targeting interface, they will show up in the format [1, (originating system) Form], (summary). For example, a form with the originating system "FreeForms.com" and the summary "My Free Form" will show up in the targeting interface as [1, FreeForms.com Form], My Free Form so you can easily identify what it is and where it came from when doing your targeting.

Request

						
POST https://actionnetwork.org/api/v1/forms

Header:
Content-Type: application/json
api-key:[your api key here]
						

{	
  "identifiers": [
    "free_forms:1"
  ],
  "summary": "My Free Form",
  "originating_system": "FreeForms.com"
}

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "originating_system": "FreeForms.com",
  "identifiers": [
    "free_forms:1",
    "action_network:d8fff9ec-78a4-4c3d-a724-d4bb751abfbb"
  ],
  "created_at": "2014-03-26T21:52:07Z",
  "modified_at": "2014-03-26T21:52:07Z",
  "summary": "My Free Form",
  "total_submissions": 0,
  "_embedded": {
    "osdi:creator": {
      "given_name": "John",
      "family_name": "Doe",
      "identifiers": [
        "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29"
      ],
      "originating_system": "Action Network",
      "created_at": "2014-03-24T18:03:45Z",
      "modified_at": "2014-03-25T15:00:22Z",
      "email_addresses": [
        {
          "primary": true,
          "address": "jdoe@mail.com"
        }
      ],
      "postal_addresses": [
        {
          "primary": true,
          "address_lines": [
            "1600 Pennsylvania Ave"
          ],
          "locality": "Washington",
          "region": "DC",
          "postal_code": "20009",
          "country": "US",
          "language": "en",
          "location": {
            "latitude": 32.935,
            "longitude": -56.0377,
            "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/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb"
    },
    "osdi:submissions": {
      "href": "https://actionnetwork.org/api/v1/forms/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb/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/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb/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 above example, you can see how the foreign identifier being posted is merged into the identifiers array. We will intelligently search and deduplicate based on foreign and native identifiers. So if you post a form with an identifier that matches one already assigned to a form resource, your POST request will update that resource with new information instead of creating a duplicate.

You can post a form with a creator link as well, if you want to assign the form to a specific Action Network user, like so:

						
POST https://actionnetwork.org/api/v1/petitions

Header:
Content-Type: application/json
api-key:[your api key here]
						

{	
  "identifiers": [
    "free_forms:1"
  ],
  "summary": "My Free Form",
  "originating_system": "FreeForms.com",
  "_links" : {
    "osdi:creator" : { 
      "href" : "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" 
    }
  }
}

The link must be a valid person resource and must be associated with your API key for it to be accepted. If your API key is for an individual account, then the link must be to your account's person resource. If your API key is for a group, then the link must be to a member of administrator of your group. If no link or an invalid link is provided, the form will be assigned to your API key's account person record or to the original creator of the group, whichever is appropriate. If a creator is explicitly set, people who take action will be added to that creator's personal email list. Otherwise, the creator is has no effect on what email list people who submit to the form are subscribed to.

And of course you can post a form with more fields (such as description) if you'd like, but they are not required.

Back To Top ↑

Scenario: Modifying a form (PUT)

You can modify an existing form by using PUT on its individual endpoint.

Request

						
PUT https://actionnetwork.org/api/v1/forms/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb

Header:
Content-Type: application/json
api-key:[your api key here]
						

{	
  "identifiers": [
    "free_forms:2"
  ],
  "summary": "My Free Form With A New Name",
  "description": "This is my free form description"
}

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "originating_system": "FreeForms.com",
  "identifiers": [
    "free_forms:1",
    "action_network:d8fff9ec-78a4-4c3d-a724-d4bb751abfbb",
    "free_forms:2"
  ],
  "created_at": "2014-03-26T21:52:07Z",
  "modified_at": "2014-03-26T21:54:28Z",
  "summary": "My Free Form With A New Name",
  "description": "This is my free form description",
  "total_submissions": 0,
  "_embedded": {
    "osdi:creator": {
      "given_name": "John",
      "family_name": "Doe",
      "identifiers": [
        "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29"
      ],
      "originating_system": "Action Network",
      "created_at": "2014-03-24T18:03:45Z",
      "modified_at": "2014-03-25T15:00:22Z",
      "email_addresses": [
        {
          "primary": true,
          "address": "jdoe@mail.com"
        }
      ],
      "postal_addresses": [
        {
          "primary": true,
          "address_lines": [
            "1600 Pennsylvania Ave"
          ],
          "locality": "Washington",
          "region": "DC",
          "postal_code": "20009",
          "country": "US",
          "language": "en",
          "location": {
            "latitude": 32.416,
            "longitude": -75.0672,
            "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/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb"
    },
    "osdi:submissions": {
      "href": "https://actionnetwork.org/api/v1/forms/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb/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/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb/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
      }
    ]
  }
}

The above example added a new identifier to the form, changed the summary, and added a description.

Editing of certain fields via PUT is not allowed, and is noted in the field names table above. For example, you can't change the total_submissions count -- that is a system generated number reflecting a count of the underlying submissions. And you can't change the creator of a form. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting a form (DELETE)

Deleting forms is not allowed via the API. DELETE requests will return an error.

Back To Top ↑