General Principles Version 1

The Action Network API is based off of the Open Supporter Data Interface specification. It uses HAL+JSON.

This document introduces general principles and definitions used in most API calls.

Sections:

• API Entry Point (AEP)
  • Endpoints and URL structures
  • Field names and descriptions
  • Links
• Authentication
• Resources
• Embedded resources
• Collections
• Paging and Navigation
• Curies and namespacing
• Field types and notation
• Creating, editing, updating, and deleting (CRUD)
• Searching and filtering (OData)

API Entry Point (AEP)

The AEP is your entry point into the Action Network API. From there you will find links to all collections and resources in the system as well as documentation.

Endpoints and URL structures

Endpoints:

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

The AEP is located at the above link, and all collections and resources stem from that basic URL structure.

URL Structures:

https://actionnetwork.org/api/v1/[resource_type]

To address a specific type of resources, use the resource type name like https://actionnetwork.org/api/v1/petitions

Field names and descriptions

Links

Authentication

An API key is required to access the API. API keys are provided by request, and are considered a partner feature. Please contact us to request an API key. Each user account and group on the Action Network has a separate API key allowing you to access that user or group's data. You can manage your keys from the API & Sync page.

Once you've been given access to our API, you can generate and manage your key from the API & Sync page, located in the upper right dropdown menu under your name. Once on the page, first choose the list you want to generate a key for. Choosing your personal list will allow you to add actions and people to your personal account's email list. Choosing any groups you are an administrator of allows you to add actions or people to that group's list. After you select the list, you can generate an API key for that list.

Note: Keep your API key secret. Anyone with your API key will be able to access any data in your account. Therefore, the Action Network API is not suitable for front end-only implementations (such as a javascript client), as this could expose your API key to others. You can revoke your key and regenerate a new one from the API & Sync page.

API keys must be sent as a header in this format:

						
api-key:[your api key here]
					

Resources

Almost everything in the Action Network API is a resource. An individual person is a resource, as is a petition, as is an action a specific person takes on a petition.

Resources have an array of identifiers -- one and only one generated by the Action Network when that resource is created, as well as any foreign identifiers you have passed in when you create resources using POST or modify them using PUT. Identifiers must be unique at least by type. We deduplicate foreign identifiers.

Resources also have created_at and modified_at fields, created by our system, and a hash of _links pointing to various URL endpoints that are related to that resource, including at least one pointing to itself (the self link).

Here is an example of a person resource with a native and foreign identifier, created_at and modified_at fields, and links to various related resources:

						
{
  "identifiers": [
    "action_network:d3e27e15-e5b5-4707-be96-8bc359462133",
    "foreign_system:1"
  ],
  "modified_at": "2014-03-25T15:26:45Z",
  "email_addresses": [
    {
      "primary": true,
      "address": "jdoe@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/d3e27e15-e5b5-4707-be96-8bc359462133"
    },
    "osdi:question_answers": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/question_answers"
    },
    "osdi:attendance": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/attendance"
    },
    "osdi:signatures": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/signatures"
    },
    "osdi:submissions": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/submissions"
    },
    "osdi:donations": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/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
      }
    ]
  }
}
					

Embedded resources

The Action Network API will sometimes embed related resources within a parent resource for convenience. For example, when you request a petition resource, the API will embed the person resource of the creator of that petition along with the petition resource itself, saving you an API call to find out who created the petition in question.

Embedded resources are prefixed with the _embedded field name. Any resource that is embedded will always also be linked in the _links section.

For example, here is a petition with an embedded creator:

						
{
  "identifiers": [
    "action_network:7580a324-9a72-11e3-a2e9-12313d316c29"
  ],
  "created_at": "2014-02-06T16:04:05Z",
  "modified_at": "2014-02-20T21:16:57Z",
  "summary": "Stop doing the bad thing",
  "description": "<p>Please stop doing this really bad thing.</p>",
  "petition_text": "Mayor Doe, stop doing the bad thing.",
  "url": "https://actionnetwork.org/petitions/stop-doing-the-bad-thing",
  "total_signatures": 2637,
  "target": [
    {
      "name": "Mayor Doe"
    }
  ],
  "_embedded": {
    "osdi:creator": {
      "given_name": "John",
      "family_name": "Smith",
      "identifiers": [
          "action_network:c945d6fe-929e-11e3-a2e9-12313d316c29"
      ],
      "email_addresses": [
        {
          "primary": true,
          "address": "jsmith@mail.com"
        }
      ],
      "postal_addresses": [
        {
          "primary": true,
          "address_lines": [
            "1600 Pennsylvanie 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/petitions/7580a324-9a72-11e3-a2e9-12313d316c29"
    },
    "osdi:signatures": {
      "href": "https://actionnetwork.org/api/v1/petitions/7580a324-9a72-11e3-a2e9-12313d316c29/signatures"
    },
    "osdi:creator": {
      "href": "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "action_network:embed": {
      "href": "https://actionnetwork.org/api/v1/petitions/7580a324-9a72-11e3-a2e9-12313d316c29/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
      }
    ]
  }
}
					

Collections

An array of resources is called a collection. A URL endpoint may return a collection of resources. For example, visiting https://actionnetwork.org/api/v1/people will return a collection of people corresponding to the email list associated with your api key.

Individual resources in a collection are both embedded in the array and linked to in the links section, allowing for easy browsing and navigation.

Here is an example of the people collection:

						
{
  "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)
    ]
  }
}
					

Paging and Navigation

By default we will return 25 resources per page when querying a collection. You can adjust the number of items returned by using the ?per_page=[number of items per page] URL argument. Note: You can retrieve a maximum of 25 resources per page.

To move through pages, use the previous and next links in the link section, or use the ?page=[page number] URL argument to jump to a specific page

Curies and namespacing

A curie section is included with each API response. Curies are templated links that allow you to quickly find documentation on resources.

Curies are related to resources labeled in the [curie name]:[URI fragment] format. For example, if a resource is labeled with the code osdi:person you would find the curie labeled "osdi" and then add people to the templated URL.

For example, here is a person resource:

						
{
  "identifiers": [
    "action_network:d3e27e15-e5b5-4707-be96-8bc359462133",
    "foreign_system:1"
  ],
  "modified_at": "2014-03-25T15:26:45Z",
  "email_addresses": [
    {
      "primary": true,
      "address": "jdoe@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/d3e27e15-e5b5-4707-be96-8bc359462133"
    },
    "osdi:question_answers": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/question_answers"
    },
    "osdi:attendance": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/attendance"
    },
    "osdi:signatures": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/signatures"
    },
    "osdi:submissions": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/submissions"
    },
    "osdi:donations": {
      "href": "https://actionnetwork.org/api/v1/people/d3e27e15-e5b5-4707-be96-8bc359462133/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
      }
    ]
  }
}
					

To look up documentation on, say, the osdi:donations link, you would find the curie named "osdi" and add donations on to the end of the specified link to create https://actionnetwork.org/docs/v1/donations, which is the link to documentation about this resource.

Curies also serve as namespaces. For example, things labeled osdi:[resource] correspond to the OSDI specification. Things labeled action_network:[resource] are namespaced resources that appear in the Action Network API but are not part of the OSDI specification.

Field types and notation

Each page of documentation about a specific resource contains a chart showing all of the field names for that resource, their type, whether they are required, and a description about what they represent.

When describing elements of a JSON hash, dot notation will be used. For example, take this hash:

{
  "object" : {
    "name" : "this object has a name",
    "value" : "this object has a value"
  }
}
					

The name field will be notated as object.name under the object field name.

Type may include definitions such as string or datetime. Field types can also be arrays, which are noted with the [] notation. If the array is an array of json hashes, then the array is named (ex: email_addresses[]). Otherwise, it will be notated as array[].

Finally, field types can be an embedded resource, which will be noted with a *, such as osdi:person*.

Creating, editing, updating, and deleting (CRUD)

Generally, the Action Network API supports RESTful Create/Update/Edit/Delete (CRUD) operations. However, only certain resources will respond to certain verbs.

To create new resources, use POST. Generally, you post to endpoints of collections, such as https://actionnetwork.org/api/v1/petitions to create a new petition.

When you need to associate a resource you are creating via POST to another existing resource, you would post a link to that other resource in a _links section of your POST message. However, some collections have special "helper" links that are labeled as such. These helpers are used for creating two resources at the same time (such as a new person to be added to the list and a signature to a petition they signed). This is explained in more detail (with examples) in each resource's documentation.

To edit or update resources, use PUT. Generally, you update on endpoints identifying individual resources, not endpoints associated with collections of resources. Only some fields may be update-able. For examples, see the documentation on individual resources.

POST and PUT operations should include the Content-Type set to application/json along with your API key, like so:

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

To delete resources, use DELETE. Generally, you delete on endpoints identifying individual resources, not endpoints associated with collections of resources. Only some resources are delete-able. For examples, see the documentation on individual resources.

Searching and filtering (OData)

The Action Network API supports basic filtering using a small subset of the OData query language.

The use cases we generally support have to do with finding individual resources by identifying characteristics, or finding collections of newly created or updated resources. This facilitates updating specific resources and syncing data between systems.

OData queries are url arguments and take the format ?filter=[field_name] [operator] '[value]'.

The following operations are supported:

Operations

The following field names can be used for filtering on specific resources:

Resources and supported field names