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