Events Version 2

This document describes the OSDI events collection and petition resource as implemented by the Action Network.

Events are a type of action created by the organizer or group associated with your API key that involves activists RSVPing for an event they would like to attend.

Events have names (corresponding to our administrative titles), titles, and can have descriptions, locations, dates, and times, and when activists sign them attendance resources are created representing the RSVP an activist made for that event.

Events are not deduplicated except on identifiers, to keep identifiers unique. Identifiers are deduplicated globally, across groups and API keys, so ensure any you set are globally unique.

Note: Events created via the API are not equivalent to events created with our user interface. API-created events will not show up in lists of all of your actions on your dashboard or group manage page, they will not be given a URL on actionnetwork.org where people can sign, they will not have individual manage pages for statistics, and they will not send out autoresponses or reminders. Rather, once they have at least one attendance, 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 event for reports or email targeting.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/events

https://actionnetwork.org/api/v2/event_campaigns/[event_campaign_id]/events

Event resources live at the above endpoints. The endpoints returns a collection of all events associated with your API key or all events associated with a specific event campaign.

URL Structures:

https://actionnetwork.org/api/v2/events/[id]

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

Back To Top ↑

Field names and descriptions

Event fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. Must be globally unique. See the general concepts document for more information about identifiers.
origin_system string Yes A human readable string identifying where this event originated. May be used in the user interface for this purpose.
created_date datetime The date and time the resource was created. System generated, not editable.
modified_date datetime The date and time the resource was last modified. System generated, not editable.
name string The event's administrative title, only shown internally and not publicly.
title string Yes The event's public title.
description string The event's description. May contain HTML.
instructions string The event's instructions for activists, visible after they RSVP. May contain HTML.
browser_url string The URL to this event's page on the Action Network or a third party.
featured_image_url string The URL to this action's featured image on the Action Network, if a banner image has been set. Only present for events created with our user interface. Not editable.
start_date datetime The start date and time of the event. The time is assumed to be in the timezone local to the event's location.
end_date datetime The end date and time of the event. The time is assumed to be in the timezone local to the event's location.
location Location A hash representing the location of the event.
total_accepted integer A system generated count of the number of attendance resources on this petition. Not editable.
action_network:event_campaign_id string The Action Network identifier to an event campaign this event is part of. Action Network-only feature. Not editable.
status enum The status of the event. One of ['confirmed' 'tentative' 'cancelled'] System generated, will always be confirmed, not editable.
transparence enum Whether this event should block on online calendars. One of ['opaque' 'transparent']. System generated, will always be opaque, not editable.
visibility enum Whether this event is visible in search results or not. One of ['public' 'private']. System generated, not editable.
guests_can_invite_others boolean Whether guests can invite others to the event. System generated, will always be true, not editable.
capacity integer The maximum allowed number of RSVPs for the event, if a maximum has been set. System generated, not editable.
action_network:hidden boolean A read-only field indicating whether this action is hidden in our user interface or not.
reminders Reminders[] An array of hashes indicating when automatic reminders are to be send. System generated, not editable.
action_network:sponsor Sponsor A hash of the sponsoring group of this event. Action Network-only feature. Automatically added if you post using a group API key. System generated, not editable.
Location fields:
Field Name Type Required on POST Description
venue string The venue of the event. (ex: Jane White Hall)
address_lines strings[] An array of strings representing the event's street address. We will ignore any beyond the first.
locality string A city or other local administrative area. This will be overwritten based on our geocoding.
region string State / subdivision codes according to ISO 3166-2 (Final 2 alpha digits). This will be overwritten based on our geocoding.
postal_code string Region specific postal code such as ZIP code.
country string Country code according to ISO 3166-1 Alpha-2. Defaults to 'US'.
language string Language in which the address is recorded -- language code according to ISO 639. This will be overwritten and set to English.
location hash A hash of location information for the address. This will be overwritten based on our geocoding.
location.latitude float Geolocation latitude. This will be overwritten based on our geocoding.
location.longitude float Geolocation longitude. This will be overwritten based on our geocoding.
location.accuracy enum One of ['Rooftop' 'Approximate']. This will be overwritten based on our geocoding.
Reminder fields:
Field Name Type Required on POST Description
method enum The method of this reminder. One of ["email" "sms"]. System generated, will always be email, not editable.
minutes integer The number of minutes before the event reminders are scheduled to be sent. System generated, will always be 1440 (24 hours), not editable.
Sponsor fields:
Field Name Type Required on POST Description
title string The name of the sponsoring group.
browser_url string The URL to the group's public page.
Back To Top ↑

Links

Link Name Description
self A link to this individual event resource.
osdi:attendances A link to a collection of all attendance resources associated with this event. Click here for attendances documentation.
osdi:creator A link to the person who created this event. Click here for people documentation.
osdi:organizer A link to the person who organized this event. Click here for people documentation.
action_network:event_campaign A link to the event campaign this event is part of. Action Network-only feature. Click here for event campaign documentation.
action_network:embed A link to embed code for this event. Action Network-only feature. Click here for embed documentation.
osdi:record_attendance_helper A link to the record attendance helper for this event. Click here for the record attendance helper documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of event resources (GET)

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

Request

                        
GET https://actionnetwork.org/api/v2/events/

Header:
OSDI-API-Token: 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/v2/events?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/events"
    },
    "osdi:events": [
      {
        "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2"
      },
      {
        "href": "https://actionnetwork.org/api/v2/events/3f976089-4477-461f-9d2f-1d741aa9b7a8"
      },
      //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
      }
    ]
  },
  "_embedded": {
    "osdi:events": [
      {
        "origin_system": "FreeEvents.com",
        "identifiers": [
          "action_network:8a625981-67a4-4457-8b55-2e30b267b2c2",
          "free_events:1"
        ],
        "status": "confirmed",
        "created_date": "2014-03-18T22:17:36Z",
        "modified_date": "2014-03-19T14:07:41Z",
        "title": "House Party for Justice",
        "transparence": "opaque",
        "visibility": "public",
        "guests_can_invite_others": true,
        "capacity": 10,
        "reminders": [
          {
            "method": "email",
            "minutes": 1440
          }
        ],
        "total_accepted": 5,
        "action_network:hidden": false,
        "location": {
          "venue": "My House",
          "address_lines": [
            "1600 Pennsylvania Ave"
          ],
          "locality": "Washington",
          "region": "DC",
          "postal_code": "20009",
          "country": "US",
          "language": "en",
          "location": {
            "latitude": 33.1037330420451,
            "longitude": -72.0439414557911,
            "accuracy": "Rooftop"
          }
        },
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2"
          },
          "osdi:attendances": {
            "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2/attendances"
          },
          "osdi:record_attendance_helper": {
            "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2/attendances"
          },
          "osdi:organizer": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          },
          "osdi:creator": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          },
          "action_network:embed": {
            "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2/embed"
          }
        }
      },
      {
        "identifiers": [
          "action_network:3f976089-4477-461f-9d2f-1d741aa9b7a8"
        ],
        "status": "confirmed",
        "created_date": "2014-03-18T21:08:18Z",
        "modified_date": "2014-03-18T22:15:11Z",
        "origin_system": "Action Network"
        "title": "Movie Screening",
        "description": "<p>Come watch this awesome movie!</p>",
        "instructions": "<p>Feel free to bring a friend</p>",
        "browser_url": "https://actionnetwork.org/events/movie-screening",
        "featured_image_url": "https://actionnetwork.org/images/screening.jpg",
        "start_date": "2014-03-22T17:45:00Z",
        "transparence": "opaque",
        "visibility": "public",
        "guests_can_invite_others": true,
        "reminders": [
          {
            "method": "email",
            "minutes": 1440
          }
        ],
        "total_accepted": 7,
        "action_network:hidden": false,
        "action_network:sponsor": {
          "title": "Progressive Action Now",
          "browser_url": "https://actionnetwork.org/groups/progressive-action-now"
        },
        "location": {
          "venue": "My house",
          "address_lines": [
            "1600 Pennsylvania Ave"
          ],
          "locality": "Washington",
          "region": "DC",
          "postal_code": "20009",
          "country": "US",
          "language": "en",
          "location": {
            "latitude": 32.9135624691629,
            "longitude": -76.0487183148486,
            "accuracy": "Rooftop"
          }
        },
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/events/3f976089-4477-461f-9d2f-1d741aa9b7a8"
          },
          "osdi:attendances": {
            "href": "https://actionnetwork.org/api/v2/events/3f976089-4477-461f-9d2f-1d741aa9b7a8/attendances"
          },
          "osdi:record_attendance_helper": {
            "href": "https://actionnetwork.org/api/v2/events/3f976089-4477-461f-9d2f-1d741aa9b7a8/attendances"
          },
          "osdi:organizer": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          },
          "osdi:creator": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          },
          "action_network:embed": {
            "href": "https://actionnetwork.org/api/v2/events/3f976089-4477-461f-9d2f-1d741aa9b7a8/embed"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual event resource (GET)

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

Request

                        
GET https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2

Header:
OSDI-API-Token: your_api_key_here

Response

                        
200 OK

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


{
  "origin_system": "FreeEvents.com",
  "identifiers": [
    "action_network:8a625981-67a4-4457-8b55-2e30b267b2c2",
    "free_events:1"
  ],
  "status": "confirmed",
  "created_date": "2014-03-18T22:17:36Z",
  "modified_date": "2014-03-19T14:07:41Z",
  "title": "House Party for Justice",
  "transparence": "opaque",
  "visibility": "public",
  "guests_can_invite_others": true,
  "capacity": 10,
  "reminders": [
    {
      "method": "email",
      "minutes": 1440
    }
  ],
  "total_accepted": 5,
  "action_network:hidden": false,
  "location": {
    "venue": "My House",
    "address_lines": [
      "1600 Pennsylvania Ave"
    ],
    "locality": "Washington",
    "region": "DC",
    "postal_code": "20009",
    "country": "US",
    "language": "en",
    "location": {
      "latitude": 33.1037330420451,
      "longitude": -72.0439414557911,
      "accuracy": "Rooftop"
    }
  },
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2"
    },
    "osdi:attendances": {
      "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2/attendances"
    },
    "osdi:record_attendance_helper": {
      "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2/attendances"
    },
    "osdi:organizer": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "osdi:creator": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "action_network:embed": {
      "href": "https://actionnetwork.org/api/v2/events/8a625981-67a4-4457-8b55-2e30b267b2c2/embed"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new event (POST)

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

Note: Events created via the API in this way are not equivalent to events created with our user interface. API-created events will not show up in lists of all of your actions on your dashboard or group manage page, they will not be given a URL on actionnetwork.org where people can sign, they will not have individual manage pages for statistics, and they will not send out autoresponses or reminders. Rather, once they have at least one attendance, 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 event for reports or email targeting.

In the targeting interface, they will show up in the format [1, (origin system) Event], (title). For example, an event with the origin system 'FreeEvents.com' and the title 'My Free Event' will show up in the targeting interface as [1, FreeEvents.com Event], My Free Event so you can easily identify what it is and where it came from when doing your targeting.

Request

                        
POST https://actionnetwork.org/api/v2/events

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "title": "My Free Event",
  "origin_system": "FreeEvents.com"
}

Response

                        
200 OK

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


{
  "origin_system": "FreeEvents.com",
  "identifiers": [
    "action_network:21789f03-0180-45d3-853c-91bd6fdc8c07"
  ],
  "status": "confirmed",
  "created_date": "2014-03-26T21:02:09Z",
  "modified_date": "2014-03-26T21:02:09Z",
  "title": "My Free Event",
  "transparence": "opaque",
  "visibility": "public",
  "guests_can_invite_others": true,
  "capacity": 10,
  "reminders": [
    {
      "method": "email",
      "minutes": 1440
    }
  ],
  "total_accepted": 0,
  "action_network:hidden": false,
  "location": {
    "region": "",
    "country": "US",
    "language": "en",
    "location": {
      "latitude": 39.7599977890005,
      "longitude": -98.4999989109997,
      "accuracy": "Approximate"
    }
  },
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07"
    },
    "osdi:attendances": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07/attendances"
    },
    "osdi:record_attendance_helper": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07/attendances"
    },
    "osdi:organizer": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "osdi:creator": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "action_network:embed": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07/embed"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}

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

                        
POST https://actionnetwork.org/api/v2/events

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "title": "My Free Event",
  "origin_system": "FreeEvents.com"
  "_links" : {
    "osdi:creator" : {
      "href" : "https://actionnetwork.org/api/v2/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 an organizer or administrator of your group. If no link or an invalid link is provided, the event 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 attend the event are subscribed to.

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

Back To Top ↑

Scenario: Modifying an event (PUT)

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

Request

                        
PUT https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "title": "My Free Event With A New Name",
  "description": "This is my free event description"
}

Response

                        
200 OK

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


{
  "origin_system": "FreeEvents.com",
  "identifiers": [
    "action_network:21789f03-0180-45d3-853c-91bd6fdc8c07"
  ],
  "status": "confirmed",
  "created_date": "2014-03-26T21:02:09Z",
  "modified_date": "2014-03-26T21:06:13Z",
  "title": "My Free Event With A New Name",
  "description": "This is my free event description",
  "transparence": "opaque",
  "visibility": "public",
  "guests_can_invite_others": true,
  "reminders": [
    {
      "method": "email",
      "minutes": 1440
    }
  ],
  "total_accepted": 0,
  "action_network:hidden": false,
  "location": {
    "region": "",
    "country": "US",
    "language": "en",
    "location": {
      "latitude": 39.7599977890005,
      "longitude": -98.4999989109997,
      "accuracy": "Approximate"
    }
  },
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07"
    },
    "osdi:attendances": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07/attendances"
    },
    "osdi:record_attendance_helper": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07/attendances"
    },
    "osdi:organizer": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "osdi:creator": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "action_network:embed": {
      "href": "https://actionnetwork.org/api/v2/events/21789f03-0180-45d3-853c-91bd6fdc8c07/embed"
    },
    "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 above example changed the title 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_accepted count -- that is a system generated number reflecting a count of the underlying attendance collection. And you can't change a creator of an event. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting an event (DELETE)

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

Back To Top ↑