The VAN’s RESTful API exposes resources as varied as those available through the VAN’s user interface. Unless specified otherwise, these endpoints only respond to and return JSON. Most REST conventions are followed: GET /resources lists all resources in the authenticated context, GET /resources/{id} gets the details of a specific object, POST /resources creates a new object, PUT /resources/{id} updates a specific object, and DELETE /resources/{id} deletes or suppresses a specific object. Some endpoints also support the PATCH HTTP verb for partial resource updates.

Unless specified otherwise, these endpoints only respond to and return JSON. Any request containing JSON data must also set the Content-Type header to application/json.

Before using the API, you will need to know your Application Name and API Key. The Application Name is a short string that identifies your application (e.g., acmeCrmProduct) and the API Key is a string that identifies the specific context to which API requests should resolve. Specifically, it identifies an API user in an instance, database tab, and committee–the same information that is determined during the typical VAN login process.

The API key will look like the concatenation of a GUID, a | and a 0 or 1 (e.g., 7c9e6679-7425-40de-944b-e07fc1f90ae7|1). Use 0 to work in VoterFile mode, and 1 to work in MyCampaign mode. Because the API key is connected to a specific context, the API will only return data available to that context.

To authenticate your API requests, use Basic HTTP authentication and set the username to the Application Name and password to the API Key. Most programming frameworks supports basic authentication out of the box.

The easiest way to get started is to send a sample request to the POST /echoes endpoint. This endpoint takes a message and repeats it back, with a datetime stamp:

POST /echoes
{
  "message": "Hello, world"
}

200 OK
{
  "message": "Hello, world",
  "dateSent": "2017-01-01T00:00:00Z"
}

The following are three basic code samples for interacting with this API using cURL, NodeJS, and C#. Note that in each case we are using a fictional API key (7c9e6679-7425-40de-944b-e07fc1f90ae7) and that the call is being placed in MyCampaign mode. You will need to replace that key with your own before running the code, and will need to use "0" instead of "1" to place the call in VoterFile mode.

cURL example

  curl -H "Content-type: application/json" \
       --user "acmeCrmProduct:7c9e6679-7425-40de-944b-e07fc1f90ae7|1" \
       -X POST \
       --data '{ "message": "Hello, world" }' \
       https://api.securevan.com/v4/echoes

NodeJS example

var request = require('request');
var username = 'acmeCrmProduct';
var apiKey = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
var dbMode = '1';
var password = apiKey + '|' + dbMode;
var options = {
  headers: { 'Content-type' : 'application/json' },
  auth: {
    user: username,
    password: password
  },
  json: {
    "message": "Hello, world"
  },
  uri: 'https://api.securevan.com/v4/echoes'
};
request.post(options, function (err, res, body) {
  if (err) {
    console.dir(err);
    return;
  }
  console.dir(res.statusCode);
  console.dir(body);
});

C# example

string username = "acmeCrmProduct";
string apiKey = "7c9e6679-7425-40de-e07fc1f90ae7";
string dbMode = "1";
string password = apiKey + "|" + dbMode;
string url = "https://api.securevan.com/v4/echoes";

object data = new {
  message = "Hello, world"
};

var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
var content = new System.Net.Http.StringContent(json, Encoding.UTF8, "application/json");

using(var client = new HttpClient())
{
  client.DefaultRequestHeaders.Add("Authorization", 
    "Basic " + Convert.ToBase64String(ASCIIEncoding.ASCII.GetBytes(
      string.Format("{0}:{1}", username, password))));

  var response = client.PostAsync(url, content).Result;
}

All API calls use the NGP VAN standard error format for returning errors. The response will always have an HTTP status code of 400 or greater and a single property called errors which is an array of one or more standard Error objects. These objects have the following properties:

In the following example, an error is reported that is not tied to a specific property.

{
  "errors": [
    {
      "text": "Events are not supported in this database",
      "code": "EVENTS_NOT_SUPPORTED_IN_DB"
    }
  ]
}

In the following example, a single property of a request has failed.

{
  "errors": [
    {
      "properties": [
        "creditCardNumber"
      ],
      "text": "Credit card number must be digits only",
      "code": "INVALID_PARAMETER"
    }
  ]
}

In the following example, two properties of the request contributed to a single failure.

{
  "errors": [
    {
      "properties": [
        "dateBegin",
        "dateEnd"
      ],
      "text": "dateEnd must come after dateBegin",
      "code": "INVALID_PARAMETER"
    }
  ]
}

The following example illustrates how to report a failure in the second phone (zero-based index) in a person object’s array of phones.

{
  "errors": [
    {
      "properties": [
        "phones[1].extension"
      ],
      "text": "Extensions must be numeric",
      "code": "INVALID_PARAMETER"
    }
  ]
}

In the following example, the request’s phone number is invalid. The regular expression used to validate is provided as a hint.

{
  "errors": [
    {
      "properties": [
        "phones[0].number"
      ],
      "text": "A valid phone number is required",
      "hint": "^1?[2-9][0-8]\d[2-9]\d{6,6}$",
      "code": "INVALID_PARAMETER"
    }
  ]
}

The following contains a link to a resource that describes the protocols supported by the service.

{
  "errors": [
    {
      "properties": [
        "sourceFile.fileUrl"
      ],
      "text": "The URL provided does not represent a supported protocol",
      "resourceUrl": "https://api.ngpvan.com/support/supportedProtocols",
      "code": "UNSUPPORTED_PROTOCOL"
    }
  ]
}

The following contains a reference code to allow developers to communicate with NGP VAN staff about the error encountered.

{
  "errors": [
    {
      "properties": [
        "canvassResponses[1].VANID"
      ],
      "text": "You do not have access to the VANID", 
      "code": "INACCESSIBLE_VANID",
      "referenceCode": "ABC-123-DEF-456"
    }
  ]
}

Requests are validated to ensure data integrity and to guard against malicious code. Validation errors will be returned as standard Error objects with the code property set to INVALID_PARAMETER and HTTP status code to 400 Bad Request. Whenever possible, we will attempt to validate all properties of a request before returning validation results. In other words, we’ll tell you if both the firstName and lastName properties of a request are invalid rather than just firstName.

Some validation rules apply to all properties across all endpoints (unless specified otherwise). In particular, text properties are expected to not include HTML or HTML special character syntax. More precisely, input must not match this regular expression: [\<\>]+|&#. An example response for this type of error follows below.

{
  "errors": [
    {
      "properties": [
        "eventDescription"
      ],
      "text": "'eventDescription' must not contain invalid characters",
      "hint": "Value must not match the regular expression: [\<\>]+|&#",
      "code": "INVALID_PARAMETER"
    }
  ]
}

We use standard validation for email addresses. It’s not quite a regular expression.

We use standard phone number validation. It’s based on your contact’s country.

By default, many API endpoints will only return first-order non-collection properties of a resource. These properties can be “expanded” by specifying valid expansion properties or sections in the $expand query parameter. This technique is used in both “list” endpoints and “get” endpoints.

If a collection property is not specified in an $expand parameter, the value of that property will be null. If a collection property is specified in an $expand parameter but that property has no values, that property will be an empty array.

For example, consider a Person object that has name properties and collections of addresses, of emails, and of phone numbers.

GET /v4/people/432135

Returns the first-order properties (names) and null values for addresses, emails, and phones.

{
  "firstName": "Jim",
  "lastName": "Gordon",
  "addresses": null,
  "emails": null,
  "phones": null
}

Emails and phones can be requested by specifying emails and phones in the query string:

GET /v4/people/432135?$expand=emails,phones

Returns the first-order properties (names), populated emails and phones (even though the record has no phone numbers), and null value for addresses:

{
  "firstName": "Jim",
  "lastName": "Gordon",
  "addresses": null,
  "emails": [
    {
      "email": "jim@gotham.ci.us",
      "type": "Work",
      "isPreferred": false
    },
    {
      "email": "jim.gordon@batmail.com",
      "type": "Home",
      "isPreferred": true
    }
  ],
  "phones": []
}

Sending an $expand parameter to an endpoint that does not expand parameters will yield a 400 Bad Request error response:

{
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "text": "There are no valid expand sections for this endpoint, therefore '$expand' must be null",
      "properties": [
        "$expand"
      ]
    }
  ]
}

Sending an invalid $expand parameter to an endpoint also yields a 400 Bad Request error response. The supported properties are included in the hint of the error:

{
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "text": "'addresses' is not a valid argument for the '$expand' parameter",
      "properties": [
        "$expand"
      ],
      "hint": "The only valid expand section is: 'phones'"
    }
  ]
}

Most API endpoints have “list” API methods that allow you to retrieve a large set of data (e.g., list Activist Codes, list Survey Questions, etc.). These endpoints share a common pattern for requests and responses.

Paginated endpoints accept the following optional parameters:

Paginated endpoints share a common response format as well. The endpoints will return an object with the following properties:

If no results are returned, an HTTP Status Code 200 OK is returned with the items array empty, count property equal to 0, and the nextPageLink null:

{
  "items": [],
  "nextPageLink": null,
  "count": 0
}

There are two primary endpoints for VAN API requests. Which endpoint you should use is determined by which VAN client with which you’re working.

https://api.securevan.com/v4

Used by all US-based clients and developer sandbox accounts

https://intlapi.securevan.com/v4

Used by most non-US clients

If you’re unsure which endpoint to use, contact NGP VAN API support.

People records are at the heart of VAN. Use this endpoint to interact with People in My Voters or My Campaign, and to create records in My Campaign.

Match Candidates

In order to ensure we are accurately matching to the one true person you are looking for in My Voters or My Campaign (or My Members or My Workers, where applicable), there are a few minimum combinations in order to trigger a match attempt. These include:

• first name, last name, and email address
• first name, last name, and phone
• first name, last name, zip5, and date of birth
• first name, last name, street number, street name, and zip5

Note that these are minimums - the more information you can provide about a contact, the better. If you fail to provide the minimum amount of required information, you will not get a match when attempting to find contacts, and will always create a new record when adding contacts.

Also note that clients can enable stricter match rules within specific contexts. These stricter rules do not change how a developer interacts with these endpoints but may reduce the match rate relative to other contexts (e.g., in sandbox accounts). Your VAN Administrator should be able to determine which rules are enabled in their production context. An example of a matching rule is “Disable Partial Matching” which requires a match on full first name and last name in order to match to an existing record (as opposed to using possible nicknames and other permutations of the name).

Additionally, matching is accent sensitive in all databases (except the few that support French localization). This means that if matching relies on a last name, Pérez will not match Perez and vice versa. Matching is, however, case insensitive. PEREZ will match Perez.

All requests to “find” endpoints expect data to be structured like the following.

{
  "vanId": 1234,
  "firstName": "James",
  "middleName": "Worthington",
  "lastName": "Gordon",
  "dateOfBirth": "1976-07-04",
  "party": "D",
  "sex": "M",
  "salutation": "Dr. Gordon",
  "envelopeName": "Dr. Jim Gordon",
  "title": "Dr.",
  "suffix": "M.D.",
  "nickname": "Jim",
  "website": "www.jimgordon.com",
  "contactMethodPreferenceCode": "P",
  "employer": "Acme Medical Group",
  "occupation": "Physician",
  "emails": [
    {
      "email": "jim@gotham.city.us",
      "type": "P",
      "isPreferred": true,
      "isSubscribed": null
    },
    {
      "email": "jim@fake.ngpvan.com",
      "type": "W",
      "isPreferred": false,
      "isSubscribed": true
    },
  ],
  "phones": [
    {
      "phoneNumber": "1-555-888-9999",
      "phoneType": "H",
      "isPreferred": true,
      "phoneOptInStatus": "I"
    },
    {
      "phoneNumber": "1-555-555-1234",
      "phoneType": "W",
      "ext": 999,
      "isPreferred": false
    }
  ],
  "addresses": [
    {
      "addressId": 1234,
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 3",
      "addressLine3": "c/o Jane Smith",
      "city": "Gotham City",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Voting",
      "isPreferred": true
    },
    {
      "addressId": 6789,
      "addressLine1": "555 Elm St",
      "addressLine2": "Suite 101",
      "addressLine3": "Marketing Department",
      "city": "Springfield",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Mailing",
      "isPreferred": false
    }
  ],
  "recordedAddresses": [
    {
      "addressId": 1234,
      "addressLine1": "123 Main St Apt 3",
      "city": "Gotham City",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Voting",
      "isPreferred": true
    },
    {
      "addressId": 6789,
      "addressLine1": "555 Elm St Suite 101",
      "city": "Springfield",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Mailing",
      "isPreferred": true
    },
    {
      "addressId": 888,
      "addressLine1": "987 Oak St",
      "city": "Gotham City",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Work",
      "isPreferred": true
    },
    {
      "addressId": 887,
      "addressLine1": "987 Maple St",
      "city": "Gotham City",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Work",
      "isPreferred": false
    },
    {
      "addressId": 999,
      "addressLine1": "2233 Ash St",
      "city": "Springfield",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Custom",
      "isPreferred": true
    }
  ],
  "identifiers": [
    {
      "type": "bsdid",
      "externalId": "746313"
    }
  ],
  "customFieldValues": [
    {
      "customFieldId": 500,
      "customFieldGroupId": 100,
      "assignedValue": "someValue"
    }
  ],
  "selfReportedRace": {
    "reportedRaceId": 4
  },
  "selfReportedEthnicity": {
    "reportedEthnicityId": 5
  },
  "selfReportedLanguagePreference": {
    "reportedLanguagePreferenceId": 6
  },
  "suppressions": [
    {
      "suppressionCode": "NW",
      "suppressionName": "Do not walk"
    },
    {
      "suppressionCode": "NE",
      "suppressionName": "Do not email"
    }
  ]
}

Person

Email

Phone

Address

Identifier

Used for known external identifiers (e.g., DWID, Voter File ID, etc.). External IDs in VAN are case-insensitive. Abcd1234 will always match ABCD1234.

CustomFieldValue

Suppression

Match Responses

The various find endpoints return a common response object.

{
  "vanId": 1264324,
  "status": "UnmatchedStored"
}

vanId may be null if no match is found and a store is not requested.

The HTTP status code is set per status value.

VAN is a great tool for tracking interaction with People. Often this interaction is represented as “canvass responses,” or the result of a canvassing interaction. Use this endpoint to retrieve metadata around the canvassing infrastructure.

An Activist Code is a tag used to identify someone’s affiliations, activities, or interests that can also tell you the direction and strength of their political views. Examples are members of PETA, union members, campaign volunteers, party officials, or signers of a petition. An Activist Code is essentially a “yes” answer to a question. In other words, you really don’t care who is not a union member or does not want a yard sign, but you frequently may want to search on records that meet those criteria. Use this endpoint to retrieve information about all available Activist Codes.

Activist Codes can be applied to people by applying canvass responses.

{
  "activistCodeId": 3202,
  "type": "Visibility",
  "name": "Yard Sign",
  "mediumName": "Yard sign",
  "shortName": "YS",
  "description": "Voter requested yard sign",
  "scriptQuestion": "Would you be interested in having a yard sign in support of Democratic candidates?",
  "status": "Active"
}

Survey Questions are at the heart of interactions with people. Survey Questions have a set of possible Survey Responses. For example, the question “If the election were held today, for whom would you vote?” may have a set of responses including “Supports my candidate,” “Undecided,” and “Supports my opponent.” Use this endpoint to retrieve information about all available Survey Questions and Responses.

Survey Question Responses can be applied to people by applying canvass responses.

{
  "surveyQuestionId": 54949,
  "type": "Candidate",
  "cycle": 2010,
  "name": "Maddow for Senate",
  "mediumName": "Maddow",
  "shortName": "MS",
  "scriptQuestion": "In the upcoming race for US Senate, do you plan to vote for Republican Scott Brown or Democrat Rachel Maddow?",
  "status": "Active",
  "responses": [
    {
      "surveyResponseId": 246016,
      "name": "1 - Strong Maddow",
      "mediumName": "1",
      "shortName": "1"
    },
    {
      "surveyResponseId": 246017,
      "name": "2 - Leaning Maddow",
      "mediumName": "2",
      "shortName": "2"
    },
    {
      "surveyResponseId": 246018,
      "name": "3 - Undecided",
      "mediumName": "3",
      "shortName": "3"
    },
    {
      "surveyResponseId": 246020,
      "name": "4 - Leaning Brown",
      "mediumName": "4",
      "shortName": "4"
    },
    {
      "surveyResponseId": 246019,
      "name": "5 - Strong Brown",
      "mediumName": "5",
      "shortName": "5"
    }
  ]
}

Each Survey Question has the following properties:

Each Survey Response has the following properties:

Codes are used as hierarchical categorization system in VAN (and are not to be confused with Activist Codes). Like Activist Codes, they are a “yes” answer to a question, but because they provide hierarchy, they’re able to answer more than a single “yes” question. For example, you could categorize constituent groups in a hierarchical manner:

• Constituencies
  • Elected Officials
    • Federal
      • Representative
      • Senator
    • Municipal
      • City Councilor
      • County Commissioner
      • Mayor
    • State
      • Governor
      • State Representative
      • State Senator
  • Faith Community
    • Catholic Americans
    • Jewish Americans
  • Labor
    • AFL-CIO
    • SEIU
    • Teamsters
  • Seniors and Retirees
  • Youth
    • College Democrats
    • Young Democrats

If the “SEIU” Code is applied, it answers “yes” to three questions: first, Is this a Constituency?, second, Is this a Labor Constituency?, and third, Is this an SEIU Labor Constituency?. This allows a single Code to carry a significant amount of information because each Code can have a parent. (e.g., the parent of College Democrats is Youth) As is demonstrated in the above example, Codes need not have the same number of parents, grand-parents, etc. “Mayor” is three levels deep whereas “Seniors and Retirees” is only one level deep.

Codes can have another helpful attribute called applicability. In some cases, a Code’s parent may be able to stand on its own. For example, if “Catholic Americans” is too specific of an attribute, Faith Community may suffice. In this case, it’d make sense to allow “Faith Community” to be Applicable. In the case of “Elected Officials,” you may decide that your classifications are complete enough that you do not want to simply classify something as “State.” In that case, you’d make “State” be Searchable Only. This means that you can find things tagged with any State Elected Official but no thing can be just a State Elected Official in and of itself.

Last but not least, the same Code, unlike Activist Codes, can be applied to a number of different entities in VAN: Events, Locations, Organizations, People, etc. (NB: not all APIs have Code support yet.) This notion is a Code’s Supported Entities. Each entity can have different applicability rules. For example, if you’re using the above Constituency Codes to classify Organizations, you may only be interested in organizations of Elected Officials at the Federal, Municipal, and State levels and nothing more specific.

Use the Codes endpoint to create, update, and delete Codes, as well as to discover existing Codes and retrieve meta data about each.

Codes are applied using each supported entity’s endpoint.

The following is an example of a Labor Code which is applicable to Events but not to Locations. (To search for a Location searchable with a Labor Code, you’d create a child of this Code that is applicable.) This Code’s parent has parentCodeId which, in this example, is a Code called Constituencies.

{
  "codeId": 20515,
  "parentCodeId": 20513,
  "name": "Labor",
  "description": "This is a description of Labor.",
  "dateCreated": "2015-04-05T12:59:00Z",
  "supportedEntities": [
    {
      "name": "Events",
      "isSearchable": true,
      "isApplicable": true
    },
    {
      "name": "Locations",
      "isSearchable": true,
      "isApplicable": false
    }
  ]
}

Code

Each Code has the following properties:

Supported Entity

VAN’s Event Calendar system is used to track the participation of your volunteers, members, and activists at calendar events. Organizers use this system to track events like House Parties, Campaign Rallies, Phone Banks, and more. The Event system is designed to allow some campaigns and organizations a high degree of complexity, but is easily scalable down to the local level where such sophistication may be less desired. This varying degree of sophistication is facilitated by Event Types which allow users to set defaults for which Roles are available for volunteers, how many Locations the event has, whether volunteers may sign up for multiple Shifts, and more. Use this endpoint to create, update, and delete specific Events, and to find existing Events.

See Event Types for additional information about Event configuration rules.

Use the Signups endpoint to record a person’s participation at Events.

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",
      "codePath": "",
      "createdByName": "",
      "dateCreated": "2015-04-05T13:00:00Z",
      "supportedEntities": null
    },
    {
      "codeId": 20518,
      "parentCodeId": 20513,
      "name": "Youth",
      "codePath": "",
      "createdByName": "",
      "dateCreated": "2015-04-05T13: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

Note

Notes are user entered text associated with an Event.

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).

Role

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

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.)

VAN’s Events system can be used to track all kinds of events: House Parties, Campaign Rallies, Phone Banks, and any other type of event your organization hosts. While each of these types share common traits, they can also have requirements that significantly change how an event is represented. For example, a Campaign Rally is likely to occur on a specific day at a specific location, while a Phone Bank may occur every night until Election Day at many of your organization’s offices. Similarly, an organization may ask supporters to host House Parties on a specific date across the state. These “rules” are, in effect, “templates” for events, or Event Types. Use this endpoint to retrieve information about all available Event Types. These Event Types will serve as the basis for validation rules when creating or updating Events.

Event Types can only be created or edited using the VAN UI.

The following is an example of a Phone Bank Event Type. Events of this type have the following rules:

• Events can have more than one Shift
• A Location isn’t required, but an Event can have more than one Location
• Can have the Host and/or Phone Banker Roles
• Each Role can have fulfillment Goals and minimum requirements but cannot have maximum capacity requirements
• Signups to Events of this type can only have one of the following Statuses: Invited, Scheduled, Declined, Confirmed, Completed, or Walk In
• Events are displayed in purple (#C6AFDA) in the VAN UI
• When creating Events in the VAN UI, Campaign HQ is offered as the default Location
• When creating Events in the VAN UI, users can create Repeatable Events

{
  "eventTypeId": 143856,
  "name": "Phone Bank",
  "canHaveMultipleShifts": true,
  "canHaveMultipleLocations": true,
  "canHaveGoals": true,
  "canHaveRoleMaximums": false,
  "canHaveRoleMinimums": true,
  "canBeRepeatable": true,
  "roles": [
    {
      "roleId": 111687,
      "name": "Host",
      "isEventLead": true
    },
    {
      "roleId": 111689,
      "name": "Phone Banker",
      "isEventLead": false
    }
  ],
  "statuses": [
    {
      "statusId": 4,
      "name": "Invited"
    },
    {
      "statusId": 1,
      "name": "Scheduled"
    },
    {
      "statusId": 3,
      "name": "Declined"
    },
    {
      "statusId": 11,
      "name": "Confirmed"
    },
    {
      "statusId": 2,
      "name": "Completed"
    },
    {
      "statusId": 15,
      "name": "Walk In"
    }
  ],
  "color": "#C6AFDA",
  "isAtLeastOneLocationRequired": false,
  "defaultLocation": {
    "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
  }
}

Each Event Type has the following properties:

An Event Signup (Signup for short) is a record of a person’s participation at an Event. A Signup corresponds to a unique combination of:

• Person (person)
• Event (event)
• Shift (shift)
• Role (role)

Additionally, a Signup has a Status (status) that indicates the person’s current participation disposition. Examples include Invited, Declined, or Scheduled. In the case of a multi-location Event, a Signup may also have a Location (location).

A person’s participation status may change. For example, a Signup may be created with a Status of Invited. If the person responds to the invitation, the status may change to Scheduled or Declined. Just before the event, an event organizer may call the person to confirm whether the person still plans to attend the event changing the status to Confirmed. After the event, an organizer may review the event’s sign-in sheet. Using that information, a person’s status may be updated to Completed or No Show. Use the Signup modification endpoint to change a Signup’s status.

Quite often, the purpose of an event is to organize volunteers for canvassing activities. In these cases, volunteers are usually assigned lists of people to canvass during the course of the event. It is possible to indicate which list(s) a volunteer canvassed by populating the printedLists or minivanExports properties of a signup.

The following is an example of a Person’s (James W. Gordon) Signup for the Neighbors Calling Neighbors Event. James has been Invited to be the Host during Shift 2452 (specifically from 3PM to 4PM) at Campaign HQ. During this event, James will be responsible for contacting the people on printed list 15981815-49117 and 15982500-51399, as well as MiniVAN exports 2186 and 2187.

{
  "eventSignupId": 2452,
  "person": {
    "vanId": 100476252,
    "firstName": "James",
    "middleName": "Worthington",
    "lastName": "Gordon"
  },
  "event": {
    "eventId": 1370,
    "name": "Neighbors Calling Neighbors",
    "shortName": "NeighborCall"
  },
  "shift": {
    "eventShiftId": 2162,
    "name": null
  },
  "role": {
    "roleId": 111687,
    "name": "Host"
  },
  "status": {
    "statusId": 4,
    "name": "Invited"
  },
  "location": {
    "locationId": 272,
    "name": "Campaign HQ",
    "displayName": "Campaign HQ, 48 Grove St Somerville, MA 02144-2500"
  },
  "startTimeOverride": "2015-06-01T15:00:00-04:00",
  "endTimeOverride": "2015-06-01T16:00:00-04:00",
  "printedLists": [
    {
      "number": "15981815-49117",
      "name": "Test Turf 01",
    },
    {
      "number": "15982500-51399",
      "name": "Test Turf 02",
    }
  ],
  "minivanExports": [
    {
      "minivanExportId": 2186,
      "name": "My List 10/9/15 4:23 PM",
      "databaseMode": 0
    },
    {
      "minivanExportId": 2187,
      "name": "My List 10/9/15 4:34 PM",
      "databaseMode": 1
    }
  ]
}

Signup

The overall Signup object has a number of properties with simple object values. Only simple objects’ unique identifiers are required.

Person

Event

Shift

Role

Status

Location

VAN Locations are first class objects that support other entities such as Events and Organizations. The idea behind Locations is that these entities can have common locations (e.g., a union hall is both the site of a Labor Union Local (Organization), and is the site that Local hosts a phone bank Event), and that these kinds of Locations have traits beyond just a name and address. These traits, some only accessible via the VAN UI, include Notes, Codes, and availability (i.e., what days of the week a Location is available).

Use this endpoint to create and delete specific Locations, and to find existing Locations. Locations can be associated with other entities using each supported entity’s endpoint.

The following is an example of a Location called Campaign HQ.

{
  "locationId": 272,
  "name": "Campaign HQ",
  "displayName": "Campaign HQ, 48 Grove St Somerville, MA 02144-2500",
  "address": {
    "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"
  }
}

Location

Address

Geographic Coordinate

Notes are incredibly useful for providing full text annotations to entities in VAN. Notes can be applied to People, Events, Locations, and Organizations. (NB: not all APIs have Note support yet).

Some VAN clients have an additional feature of Notes enabled called “Note Categories.” This feature allows users to categorize individual Notes. Further, each Note Category can be applicable to Notes of different entity types, or Note Category Types.

For example, you may have a Note Category called Venue Details. Notes in this Note Category may provide textual directions to a Location (e.g., “First house on the right”) or reminders for Event hosts (e.g., “Remember to turn off the lights”).

Which Note Category Types are available in your VAN context may vary. If you’d like the feature enabled, reach out to your VAN Administrator.

Use this endpoint to retrieve meta data about Note Categories and Note Category Types. Notes are applied using each supported entity’s endpoint. Use the VAN UI to create or edit Note Categories.

The following is an example of a Note Category:

{
  "assignableTypes": [
    "Event",
    "Organization"
  ],
  "noteCategoryId": 23,
  "name": "Venue Directions"
}

Note Category

Each Note Category has the following properties:

Users are people who can log in to the VAN. Some VAN clients may organize their users by district field values, as a way to indicate which user(s) have been assigned to which turf(s). A given user may be assigned multiple district field values, and a single district field value may be assigned to multiple users. Or a user may be assigned no district field values. The district field which is used to organize users is fixed, within each state, at the committee level.

For example, if the “Jane Casey for Senate” committee in Massachusetts is organized by Congressional District, it’s possible to organize users in that committee, as follows:

• User 1234 is assigned to Congressional Districts “001” and “002”
• User 1235 is assigned to Congressional Districts “002” and “003”
• User 1236 has no Congressional District assignments

The following is an example of a District Field Value assignment for a user:

{
    "districtFieldValues": [
      "W1P2",
      "W1P3",
      "W2P1"
    ]
}

In this case, the District Field which is used to organize users for the state and committee specified by the API key has district field values whose identifiers are “W1P2”, “W1P3”, and “W2P1”.

A District Field is a geographic segmentation of a state into politically meaningful entities. Common district fields include “Congressional district”, “State senate district”, and “Precinct”. Each district field has multiple District Field Values, indicating the ways the state is segmented. For example, in Washington state, the Congressional district field may have District Field Values “01”, “02”, … “10”.

Some VAN clients have custom districts, which are used to segment a state according to divisions that are meaningful for that client. For example, a Minnesota custom district might have values like “Minneapolis/St. Paul”, “Rochester area”, etc.

Some districts are arranged into hierarchies; a single district in one field is composed of multiple districts from another field. In this case the first District Field is said to be the “parent” of the second District Field, and the values within the first District Field are said to be the “parents” of the values in the second District Field.

For example, in some states a State Senate district is composed of one or more State House districts: State Senate District “1234” is composed of State House Districts “10”, “11”, and “12”. In this case:

• The “State Senate” District Field is said to be the parent of the “State House” District Field.
• State Senate District Field Value “1234” is said to be the parent of State House District Field Values “10”, “11”, and “12”.

The following is an example of a District Field:

{
    "districtFieldId": 999,
    "name": "State House",
    "parentFieldId": 888,
    "isCustomDistrict": false,
    "districtFieldValues": [
        {
            "id": "10",
            "name": "Jackson County District 10",
            "parentId": "1234"
        },
        {
            "id": "11",
            "name": "Jackson County District 11",
            "parentId": "1234"
        },
        {
            "id": "12",
            "name": "Jackson County District 12",
            "parentId": "1234"
        },
        {
            "id": "20",
            "name": "Jefferson County District 20",
            "parentId": "2345"
        }
    ]
}

District Field

Each District Field has the following properties: