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

PropertyTypeDescription
eventIdintRead-only; Unique identifier for an Event in this context
namestringA name for this Event, no longer than 500 characters
shortNamestringA shorter name for this Event, no longer than 12 characters
descriptionstringAn 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.
startDatedatetimeA start date and time for this Event
endDatedatetimeAn end date and time for this Event that is after startDate
eventTypeobjectRequired; read-only after Event creation; a simple Event Type for the current context
isOnlyEditableByCreatingUserboolOptional; 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.
isPubliclyViewableboolOptional; Used by NGP VAN’s website platform to indicate whether this Event can be viewed publicly
locationsarrayAn array of zero or more simple Locations where the Event is to take place
codesarrayAn 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.
notesarrayAn array of zero or more Notes that are applied to this Event
shiftsarrayAn array of one or more Shifts participants may sign up for at this Event
rolesarrayAn 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
districtFieldValuestringIf 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.”
voterRegistrationBatchesarrayAn array of zero or more Voter Registration Batches that are linked to this Event
createdDatedatetimeRead-only; the date and time this Event was created

Note

PropertyTypeDescription
noteIdintRead-only; Unique identifier for this Note
textstringThe text of a the note, no longer than 500 characters
categoryobjectOptional; 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.
isViewRestrictedboolOptional; indicates whether the note is only visible to users with the ability to see restricted notes. Defaults to false.
createdDatedatetimeRead-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).

PropertyTypeDescription
eventShiftIdintRead-only; Unique-identifier for this Shift
namestringA name for this Shift, no longer than 15 characters and does not need to be unique
startTimedatetimeA 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.
endTimedatetimeAn 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.

PropertyTypeDescription
roleIdintRead-only; Unique identifier for a Role that is available to the Event’s Event Type
namestringRead-only; the name of this Role, no longer than 50 characters
isEventLeadboolIndicates that participants with this Role are leaders of an Event (e.g., hosts). Defaults to false.
minintOptional; The minimum number of participants for this Role the Event should allow
maxintOptional; 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)
goalintOptional; 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.)
PropertyTypeDescription
voterRegistrationBatchIdintUnique identifier for the Voter Registration Batch in question