Record Attendance Helper Version 2

This document describes the OSDI record attendance helper endpoint as implemented by the Action Network.

The record attendance helper allows you to create or update a person record and mark that person as having RSVPed for an event at the same time (as well as tag that person).

This saves API calls. POSTing a new attendance without the helper would mean you need a link to the person you want to associate the attendance with, which would entail either an oData search to look up the existing person or a POST using the person_signup_helper to add the person first. The record attendance helper allows you to post a person's data along with an attendance, and the helper will automatically create or deduplicate the person and then create an attendance for them on the specified event, all in one API call.

The record attendance helper takes the normal attendance format (described here) with an additional JSON hash with person data, and an optional array of tags to add to the person's record.

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. (In networks, subscribed statuses will travel up the network. Unsubscribed statuses will not). The only valid status is subscribed, no other status fields are valid at this endpoint.

Posting will also subscribe the person to the email lists associated with the event. For example, if the event lists an individual account as a creator, a group as a sponsor, and is part of an event campaign sponsored by another group, the person will be subscribed to all three email lists when the attendance is created. Currently multiple sponsors are not supported.

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. If they are an existing person already in your group, the person's mobile subscription status will not be changed, unless you pass subscribed 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. Similar to email subscriptions, posting will also subscribe the person to the lists associated with this event if you pass subscribed in your API calls.

Items in the optional tags array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added to the person's record. If not, the tag will be ignored.

An optional triggers object can be added as well, indicating an autoresponse email should be sent back to the activist, which typically thanks them for taking action. Autoresponse emails are only sent from actions created with our user interface, and will respect the autoresponse settings in that action's Responses tab on its manage page. For example, if you're POSTing to an event that has the autoresponse email turned on and you include the autoresponse trigger, the activist will get an autoresponse email as normal, thanking them for taking action. If you're POSTing to an event with the autoresponse turned off, they won't get that email.

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. If you use unauthenticated or "blind" POST without an API key, the response will be essentially no information, to avoid leaking any personal data over the API without an API key present. You will receive a success status code and an empty JSON response if successful, or an error status code and an error message if not. See the blind post tutorial for an example.

Note: Attendances are deduplicated based on person, so a specific person can only RSVP to an event once.

Sections:

Endpoint

Endpoint:

https://actionnetwork.org/api/v2/events/[event_id]/attendances

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

The record attendance helper lives at the endpoint relating to the collection of attendances on a specific event.

Back To Top ↑

Field names and descriptions

Record Attendance Helper 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.
action_network:referrer_data Referrer Data A hash of referrer data such as source code and referrer code. Action Network-only.
person Person* Yes A hash representing person data to associate with this attendance. You can use any valid fields for person resources. An email address or phone number is required. See the people document for more information about people. (The person's language preference will be set to the language of the action as specified in the action's user interface.)
add_tags strings[] An array of strings representing tags to add to the person's record.
triggers Triggers* A hash of triggers to be acted upon when the attendance is created.
Referrer Data fields:
Field Name Type Required on POST Description
source string The source code of this attendance. Equivalent to someone taking action with the url argument ?source=[your source]. Corresponds to the sources chart in this action's manage page. Action Network-only.
referrer string The referrer code of this attendance. Equivalent to someone taking action with the url argument ?referrer=[your referrer code]. Must be a valid Action Network referrer code. Read-only. Corresponds to the referrers chart in this action's manage page. Action Network-only.
website string The website referrer for this attendance. Equivalent to someone taking action after clicking a link on the listed website. Corresponds to the websites chart in this action's manage page. Action Network-only.
email_referrer string The id of the email that brought someone to the link to take action. Action Networks adds the ?email_referrer=[your email referrer] URL parameter on the links sent through the emailer. Pass that value back in your API calls here to mark this action as having taken place because of a response to that email.
mobile_message_referrer string The id of the mobile message that brought someone to the link to take action. Action Networks adds the ?mobile_message_referrer=[your mobile referrer] URL parameter on the links sent through mobile messages. Pass that value back in your API calls here to mark this action as having taken place because of a response to that message.
Triggers fields:
Field Name Type Required on POST Description
autoresponse Autoresponse* A hash of autoresponse information to be triggered when this attendance is created.
Autoresponse fields:
Field Name Type Required on POST Description
enabled boolean Indicates whether an autoresponse email should be sent or not. If true, an autoresponse will be sent according to the settings of this event's response options.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Creating a new attendance (POST)

If you post with an inline person hash instead of with a link to a person object as described here, we will create or update the matching person and associate them with a new attendance on the specified event, all in one API call.

An email address or phone number is the only required field, though others can be POSTed.

Attendances are deduplicated by person, so a person can only RSVP to an event once. Posting a new attendance by a person who previously RSVPed to the event will replace the old attendance resource with the new one.

Tags can also be added to a person's record when POSTing using the helper by including the optional tags array. Items in the array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added to the person's record. If not, the tag will be ignored.

And an optional triggers object can be added, indicating an autoresponse email should be sent back to the activist, which typically thanks them for taking action. Autoresponse emails are only sent from actions created with our user interface, and will respect the action's response options settings.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. See the blind post tutorial for an example.

Here is an example of posting an attendance with person data inlined to the special record_attendance_helper link on the attendance collection, along with tags and an autoresponse:

Request

						
POST https://actionnetwork.org/api/v2/events/9f837109-710d-442f-8a99-857a21f36d25/attendances/

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_numbers": [ {"number": "2021234444" }]
  },
  "add_tags": [
    "volunteer",
    "member"
  ],
  "triggers": {
    "autoresponse": {
      "enabled": true
    }
  }
}
						
					

Response

						
200 OK

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



{
  "identifiers": [
    "action_network:dcd21938-0ccf-4d7c-98ef-e4fcd54ea7a3"
  ],
  "created_date": "2014-03-26T21:22:36Z",
  "modified_date": "2014-03-26T21:22:36Z",
  "status": "accepted",
  "action_network:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "action_network:event_id": "12c9a105-1ab6-472e-ac04-667c521a5968",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/events/12c9a105-1ab6-472e-ac04-667c521a5968/attendances/dcd21938-0ccf-4d7c-98ef-e4fcd54ea7a3"
    },
    "osdi:event": {
      "href": "https://actionnetwork.org/api/v2/events/12c9a105-1ab6-472e-ac04-667c521a5968"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
					

In the above example, a new person was created and their attendance added to the event at the same time. The tags "volunteer" and "member" were added to that person's record as well. They received an autoresponse email from the action, according to its response option settings in the user interface. We deduplicate people added this way by email address and phone number, so if the email or phone number posted corresponded with a person already in the system, we would update their record instead of creating a new person. The required fields for person remain the same -- email address or phone number -- and any posts missing that information will fail.

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. (In networks, subscribed statuses will travel up the network. Unsubscribed statuses will not). The only valid status is subscribed, 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 If they are an existing person already in your group, the person's mobile subscription status will not be changed, unless you pass subscribed 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.

Of course you can POST an attendance with more fields such as address lines for your inline person data or custom fields if you'd like, but they are not required. And you can omit your API key, in which case the response will a success status code and an empty JSON object if successful, or an error code and message if not.

Back To Top ↑