Common models

The following is an example of a Phone Bank Event called Neighbors Calling Neighbors on June 1, 2015 from 3PM to 8PM EDT. It has two locations, two codes, two notes, two roles, three shifts, and one linked voter registration batch.

{
  "eventId": 1370,
  "name": "Neighbors Calling Neighbors",
  "shortName": "NeighborCall",
  "description": "Come help get the word out about our great campaign.",
  "startDate": "2015-06-01T15:00:00-04:00",
  "endDate": "2015-06-01T20:00:00-04:00",
  "eventType": {
    "eventTypeId": 143856,
    "name": "Phone Bank"
  },
  "isOnlyEditableByCreatingUser": false,
  "isPubliclyViewable": null,
  "locations": [
    {
      "locationId": 272,
      "name": "Campaign HQ",
      "displayName": "Campaign HQ, 48 Grove St Somerville, MA 02144-2500 ",
      "address": {
        "addressId": null,
        "addressLine1": "48 Grove St",
        "addressLine2": null,
        "addressLine3": null,
        "city": "Somerville",
        "stateOrProvince": "MA",
        "zipOrPostalCode": "02144",
        "geoLocation": {
          "lon": -71.120121,
          "lat": 42.396363
        },
        "countryCode": "US",
        "preview": "48 Grove St \r\nSomerville, MA 02144-2500 ",
        "type": null,
        "isPreferred": null
      },
      "id": 272,
      "notes": null,
      "codes": null
    },
    {
      "locationId": 273,
      "name": "Northwest Regional Field Office",
      "displayName": "Northwest Regional Field Office, 800 Oak St Salem, MA 02111 ",
      "address": {
        "addressId": null,
        "addressLine1": "800 Oak St",
        "addressLine2": null,
        "addressLine3": null,
        "city": "Salem",
        "stateOrProvince": "MA",
        "zipOrPostalCode": "02111",
        "geoLocation": null,
        "countryCode": "US",
        "preview": "800 Oak St \r\nSalem, MA 02111 ",
        "type": null,
        "isPreferred": null
      },
      "id": 273,
      "notes": null,
      "codes": null
    }
  ],
  "codes": [
    {
      "codeId": 20516,
      "parentCodeId": 20513,
      "name": "Seniors",
      "codeType": "Tag",
      "dateCreated": "2015-04-05T13:00:00Z",
      "supportedEntities": null
    },
    {
      "codeId": 20518,
      "parentCodeId": 20513,
      "name": "Youth",
      "codeType": "Tag",
      "dateCreated": "2015-04-05T13:02:00Z",
      "supportedEntities": null
    },
    {
      "codeId": 20615,
      "parentCodeId": null,
      "name": "Digital Ads",
      "codeType": "Sourcecode",
      "dateCreated": "2017-10-01T13:02:00Z",
      "supportedEntities": null
    }
  ],
  "notes": [
    {
      "noteId": 6,
      "text": "Sed ut perspiciatis unde omnis iste natus error sit ... qui dolorem eum fugiat quo voluptas nulla pariatur?",
      "isViewRestricted": true,
      "category": null,
      "createdDate": "2015-04-05T13:21:00Z"
    },
    {
      "noteId": 5,
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut ... deserunt mollit anim id est laborum.",
      "isViewRestricted": false,
      "category": null,
      "createdDate": "2015-04-05T13:20:00Z"
    }
  ],
  "shifts": [
    {
      "eventShiftId": 2162,
      "name": "Setup",
      "startTime": "2015-06-01T15:00:00-04:00",
      "endTime": "2015-06-01T16:00:00-04:00"
    },
    {
      "eventShiftId": 2163,
      "name": "Early Shift",
      "startTime": "2015-06-01T16:00:00-04:00",
      "endTime": "2015-06-01T18:00:00-04:00"
    },
    {
      "eventShiftId": 2164,
      "name": "Late Shift",
      "startTime": "2015-06-01T18:00:00-04:00",
      "endTime": "2015-06-01T20:00:00-04:00"
    }
  ],
  "roles": [
    {
      "roleId": 111687,
      "name": "Host",
      "isEventLead": true,
      "min": null,
      "max": null,
      "goal": null
    },
    {
      "roleId": 111689,
      "name": "Phone Banker",
      "isEventLead": false,
      "min": 5,
      "max": null,
      "goal": 20
    }
  ],
  "districtFieldValue": "003",
  "voterRegistrationBatches": [
    {
      "voterRegistrationBatchId": 123456
    }
  ],
  "createdDate": "2015-04-05T13:18:00Z"
}

The following is an overview of the Event object and its related objects. In some cases, the related object has a dedicated endpoint. In these cases, a link to those endpoints is provided.

Event

Property	Type	Description
`eventId`	int	Read-only; Unique identifier for an Event in this context
`name`	string	A name for this Event, no longer than 500 characters
`shortName`	string	A shorter name for this Event, no longer than 12 characters
`description`	string	An optional internal-facing description for this Event, no longer than 500 characters. This corresponds to a field used by staff to track event information; it is not a public-facing description for attendees.
`startDate`	datetime	A start date and time for this Event
`endDate`	datetime	An end date and time for this Event that is after `startDate`
`eventType`	object	Required; read-only after Event creation; a simple Event Type for the current context
`isOnlyEditableByCreatingUser`	bool	Optional; If `true`, prevents modification of this Event by any users other than the user associated with the API context. Setting this to `true` effectively makes the Event read-only in the VAN interface. Defaults to `false`.
`isPubliclyViewable`	bool	Optional; Used by NGP VAN’s website platform to indicate whether this Event can be viewed publicly
`locations`	array	An array of zero or more simple Locations where the Event is to take place
`codes`	array	An array of zero or more Codes that are applied to this Event for organizational purposes. Note that at most one Source Code, and any number of Tags, may be applied to an Event.
`notes`	array	An array of zero or more Notes that are applied to this Event
`shifts`	array	An array of one or more Shifts participants may sign up for at this Event
`roles`	array	An array of one or more Roles participants may have at this Event. The roles indicated must be a subset of the roles available for the event’s Event Type
`districtFieldValue`	string	If events are organized by a District Field in this context, this optional property should be a valid value for the District Field, and indicates, e.g. “this event is related to Congressional District 003.”
`voterRegistrationBatches`	array	An array of zero or more Voter Registration Batches that are linked to this Event
`createdDate`	datetime	Read-only; the date and time this Event was created

Note

Property	Type	Description
`noteId`	int	Read-only; Unique identifier for this Note
`text`	string	The text of a the note, no longer than 500 characters
`category`	object	Optional; A simple Note Category for this Note. Note Categories must be enabled in the target VAN context and the category must be applicable to Events.
`isViewRestricted`	bool	Optional; indicates whether the note is only visible to users with the ability to see restricted notes. Defaults to `false`.
`createdDate`	datetime	Read-only; the date and time this Note was created

Shift

Events can divided in to multiples Shifts, each with a custom time range and name (e.g., Setup, Morning, Afternoon, Evening, Clean Up, etc.). Even Events with an Event Type that prohibits Events from having multiple Shifts must have one element in the shifts array (even if the startTime and endTime are the same as the Event’s).

Property	Type	Description
`eventShiftId`	int	Read-only; Unique-identifier for this Shift
`name`	string	A name for this Shift, no longer than 15 characters and does not need to be unique
`startTime`	datetime	A start time for this Shift which is assumed to be on the same date as the event. If the shift’s start date differs from that of the event, VAN will use the event’s date and the shift’s start time.
`endTime`	datetime	An end time for this Shift that is after `startTime` but no more than 24 hours later.

Role

A Role is flexible means of recording volunteer commitments, tasks, and assignments within an Event.

Property	Type	Description
`roleId`	int	Read-only; Unique identifier for a Role that is available to the Event’s Event Type
`name`	string	Read-only; the name of this Role, no longer than 50 characters
`isEventLead`	bool	Indicates that participants with this Role are leaders of an Event (e.g., hosts). Defaults to `false`.
`min`	int	Optional; The minimum number of participants for this Role the Event should allow
`max`	int	Optional; The maximum number of participants, or capacity, for this Role the Event should allow (NB: this is a suggested maximum and is not enforced when creating a Signup)
`goal`	int	Optional; The target number of participants for this Role the Event should allow

Voter Registration Batch

If voters were registered at an event, the resulting Voter Registration Batches for those voters can be linked back to the corresponding event using this property. Multiple batches can be linked to a single event. This property should not be used when an event was not related to voter registration.

In order to successfully POST or PUT Voter Registration Batch data, the following validation checks must be satisfied:

Batch linking must be supported in the current context
The eventType of the passed event must support batch linking
The batch referenced in a passed voterRegistrationBatchId must already exist, must be available to the current user, and must not already be linked to another event
The final state of the event, with respect to linked batches, must not exceed certain limits: at most one Applicant batch, and at most one Pledge batch, may be linked to an event. (Although in some contexts, Applicant or Pledge batches may not be available at all.)

Property	Type	Description
`voterRegistrationBatchId`	int	Unique identifier for the Voter Registration Batch in question