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.

See the Getting Started section.

Data in our system is divided into four dimensions.

• Instances are a group of databases which share a common national data set. Well-known instances include VoteBuilder, America Votes VAN, Labor Activation Network, and SmartVAN. While it is possible for certain kinds of data to be shared between one Database and another, across Database Modes, or between one Committee and another, data may not be shared across Instances.

• Databases are the sharding mechanism for data about people. For many Instances, people data is sharded by states, meaning that campaigns and organizations in one state do not share data with campaigns and organizations in another state.

• Database Modes offer two different sets of rules for sourcing and managing person data within a Database. My Voters mode contains contains data about voters gathered from official voting rolls; it is not possible to create new person records in My Voters mode. My Campaign mode contains data about an organization’s supporters, and new person records may be created in My Campaign mode. While many Databases have both My Voters and My Campaign modes available, some Databases have only My Campaign mode, or only My Voters mode. It is possible to annotate a Person record in both My Voters and My Campaign mode.

• Committees are the tenanting mechanism for separating data owned by different organizations. As a general rule, the data owned by one Committee may not be viewed by another Committee. However, it is possible for Committees to share certain kinds of data with one another if desired. Committees may exist in a single Database, as would be the case for a local or statewide electoral campaign, or they may exist in multiple Databases, as would be the case for a national organization.

• Users are the primary component of the security model, and indicate a person or entity who has permission to interact with the system.

• Permissions allow Users to carry out certain functions within the system, for example, Create and Edit Events. Some Permissions are available in My Voters mode only, or in My Campaign mode only. For example, because the Events feature is available in My Campaign mode only, the Create and Edit Events Permission is also available in My Campaign mode only.

• User Profiles indicate a series of Permissions. For each Database and Database Mode that a User may access, that User has a single User Profile which governs the functions the User is allowed to perform within that Database and Database Mode combination.

Every API key gives a single User the ability to access data within a single Instance, Database, and Committee only. In many cases, an API key will provide access to both My Voters and My Campaign mode. However, no API key will provide access to multiple Databases or Committees simultaneously.

Every API service is connected to a Permission, and an API key’s ability to access that service is determined by whether or not the API key’s User has the relevant Permission in the User Profile. In some cases, additional Permissions control the way in which a given API service operates - for example, there are some Expand Sections in the GET /people/{vanId} service which require special Permissions for access.

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.

If it’s necessary to record data about the activity of users in other systems, the API may be used to create records known as Public Users in My Campaign mode. Public Users are created using the identifiers property in the POST /people/findOrCreate request, provided the type property is configured as a Public User identifier. Please contact us to configure an identifer type for use in the Public User system.

For example, a Public User may be created as follows:

POST /people/findOrCreate

{
    "firstName": "Becky",
    "lastName": "Smith",
    "identifiers": [
      {
        "type": "AcmeCRMId",
        "externalId": "becky.smith"
      }
    ]
}

Once a Public User has been created, the user should be indicated by providing the type and externalId values as Base64-encoded values in the X-NGPVAN-User-Type and X-NGPVAN-User-Token headers, respectively.

Now the Public User created above may be specified as the actor on an API call as follows:

X-NGPVAN-User-Type: QWNtZUNSTUlk
X-NGPVAN-User-Token: YmVja3kuc21pdGg=

In this case, the type “AcmeCRMId” has been Base64-encoded, yielding the Public User Type “QWNtZUNSTUlk”, and the identifier “becky.smith” has been Base64-encoded, yielding the Public User Token “YmVja3kuc21pdGg=”.

As a result, when the API request is received, additional information is recorded about the Public User, indicating the person who triggered the request. For some API requests, providing the Public User headers in this manner will provide better visibility as to which person took an action. For example, use of the Public User system makes it easy to see which external user contacted a voter, when viewing contact history.

An introspection endpoint is available, if you need information about the API key you are using. The route returns a Paginated List of API keys available, with only one element in the list.

GET /apiKeyProfiles

200 OK
{
    "items": [
        {
            "databaseName": "SmartVAN Massachusetts",
            "hasMyVoters": true,
            "hasMyCampaign": true,
            "committeeName": "People for Good",
            "apiKeyTypeName": "Custom Integration",
            "keyReference": "1234",
            "userFirstName": "peopleforgood",
            "userLastName": "api",
            "username": "peopleforgood.api"
        }
    ],
    "nextPageLink": null,
    "count": 1
}

The easiest way to get started is to send a sample request to the POST /echoes route. 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;
}

A common scenario in using the API is to add a supporter’s name and contact information to a My Campaign database. Often it’s also necessary to annotate the supporter record, e.g. to indicate that the supporter wants to volunteer, is interested in a particular issue, etc.

To create a supporter record in My Campaign, use the POST /people/findOrCreate route. This example illustrates creating the supporter record with an email address and zip code:

  curl -H "Content-type: application/json" \
    --user "awesomeSauceApp:7c9e6679-7425-40de-944b-e07fc1f90ae7|1" \
    -X POST \
    --data '{ "firstName": "Leslie", "lastName": "Knope", "emails": [ { "email": "knope@citycouncil.pawnee.in.example.org" } ], "addresses": [ { "zipOrPostalCode": "46064" } ] }' \
    https://api.securevan.com/v4/people/findOrCreate

The API response will look something like this:

  {
    "vanId": 101202303,
    "status": "Matched"
  }

The vanId property may now be used to provide additional data about this supporter, in conjunction with POST /people/{vanId}/canvassResponses. For example, if Activist Code 1234 indicates that the supporter wishes to volunteer, then the supporter record may be annotated as follows:

  curl -H "Content-type: application/json" \
    --user "awesomeSauceApp:7c9e6679-7425-40de-944b-e07fc1f90ae7|1" \
    -X POST \
    --data '{ "responses": [ { "activistCodeId": 1234, "action": "Apply", "type": "ActivistCode" } ] }' \
    https://api.securevan.com/v4/people/101202303/canvassResponses

Note that in the above example, the vanId property from the response to the first API call (that is, 101202303) was used to form the route for the second API call (that is, https://api.securevan.com/v4/people/101202303/canvassResponses).

The full list of Activist Codes which may be applied to a Person are available at GET /activistCodes. This list will be different for each API key, and may provide different responses in My Voters and My Campaign mode. Similarly, it is also possible to apply Survey Question Responses to a Person; the full list of Survey Questions are available at GET /surveyQuestions.

Event signup is crucial to the organizing strategy of many organizations. Providing supporters with tools to sign up for an event online is a common feature in many web sites and applications.

To sign up a supporter for an Event, it is first necessary to Add a supporter. The vanId of the supporter is used to create the Event RSVP.

The other data needed for an Event Signup includes:

• Event ID
• Event Location ID
• The supporter’s Role at the event
• The Shift which the supporter plans to attend
• The Status of the Event Signup

Most of these values are available in the GET /events/{eventId} route. For example, to get the details for Event 777:

curl -H "Content-type: application/json" \
  --user "awesomeSauceApp:7c9e6679-7425-40de-944b-e07fc1f90ae7|1" \
  -X GET \
  "https://api.securevan.com/v4/events/777?\$expand=locations,shifts,roles"

Note that the request URL (https://api.securevan.com/v4/events/777?$expand=locations,shifts,roles) is enclosed in quotes, and the $expand parameter is preceded with a backslash (\) to avoid unintentional shell expansion.

The response will look something like this:

{
  "eventId": 777,
  "name": "Future of Lot 48",
  "shortName": "Lot48",
  "description": "We will discuss what to do with Lot 48.",
  "startDate": "2018-02-14T19:00:00-05:00",
  "endDate": "2018-02-14T21:00:00-05:00",
  "eventType": {
    "eventTypeId": 555,
    "name": "Public hearing"
  },
  "locations": [
    {
      "locationId": 333,
      "name": "Sweetums Factory",
      "displayName": "Sweetums Factory, 123 Sugar StPendleton, IN 46064 ",
      "address": {
        "addressLine1": "123 Sugar St",
        "city": "Pendleton",
        "stateOrProvince": "IN",
        "zipOrPostalCode": "46064",
        "countryCode": "US",
      },
    }
  ],
  "shifts": [
    {
      "eventShiftId": 111,
      "name": "Single Shift",
      "startTime": "2018-02-14T19:00:00-05:00",
      "endTime": "2018-02-14T21:00:00-05:00"
    }
  ],
  "roles": [
    {
      "roleId": 444,
      "name": "Disgruntled citizen",
    }
  ],
}

To determine which Statuses are available for the Event Signup, us GET /events/types/{eventTypeId} to retrieve details on the Event Type - in this case, 555:

curl -H "Content-type: application/json" \
  --user "awesomesauceApp:7c9e6679-7425-40de-944b-e07fc1f90ae|1" \
  -X GET \
  "https://api.securevan.com/v4/events/types/555"

The response will look something like this:

{
  "eventTypeId": 555,
  "name": "Public hearing",
  "roles": [
    {
      "roleId": 444,
      "name": "Disgruntled citizen"
    }
  ],
  "statuses": [
    {
      "statusId": 1,
      "name": "Scheduled"
    },
    {
      "statusId": 15,
      "name": "Walk In"
    }
  ]
}

From these API responses, we can see that the following Event Signup options are valid:

• Event ID: 777
• Event Location ID: 333 (“Sweetums Factory”)
• The supporter’s Role at the event: 444 (“Disgruntled citizen”)
• The Shift which the supporter plans to attend: 111 (7pm - 9pm)
• The Status of the Event Signup: 1 (“Scheduled”) or 15 (“Walk in”)

Using this information, we can now signup a supporter for this event. The following example uses the POST /signups route to create an Event Signup in the Event indicated above, for the Person created in the Add a supporter section:

  curl -H "Content-type: application/json" \
    --user "awesomeSauceApp:7c9e6679-7425-40de-944b-e07fc1f90ae|1" \
    -X POST \
    --data '{ "person": { "vanId": 101202303 }, "event": { "eventId": 777 }, "shift": { "eventShiftId": 111 }, "role": { "roleId": 444 }, "status": { "statusId": 1 }, "location": { "locationId": 333 } }' \
    https://api.securevan.com/v4/signups

The response will be a simple integer:

  4848

This is the Event Signup ID, which may be used to alter the signup in the future, using PUT /signups/{eventSignupId}. The Event Signup may also be deleted using DELETE /signups/{eventSignupId}.

This example illustrates a simple Event Signup, because there is only one Location, one Role, and one Shift. If multiple options were available, then it might be necessary to present the user with options in the user interface - e.g., by providing a radio button that would allow the user to choose which Shift to use in the Event Signup. Similar considerations would apply for multiple Locations, Roles, and Statuses.

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
• email address

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,
      "subscriptionStatus": "N"
    },
    {
      "email": "jim@fake.ngpvan.com",
      "type": "W",
      "isPreferred": false,
      "isSubscribed": true,
      "subscriptionStatus": "S"
    },
  ],
  "phones": [
    {
      "phoneId": 867,
      "phoneNumber": "1-555-888-9999",
      "phoneType": "H",
      "isPreferred": true,
      "phoneOptInStatus": "I"
    },
    {
      "phoneId": 5309,
      "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"
    }
  ],
  "selfReportedRaces": [
    {
      "reportedRaceId": 4
    }
  ],
  "selfReportedEthnicities": [
    {
      "reportedEthnicityId": 5
    }
  ],
  "selfReportedLanguagePreference": {
    "reportedLanguagePreferenceId": 6
  },
  "selfReportedSexualOrientations": [
    {
      "reportedSexualOrientationId": 1
    }
  ],
  "selfReportedGenders": [
    {
      "reportedGenderId": 1
    }
  ],
  "suppressions": [
    {
      "suppressionCode": "NW",
      "suppressionName": "Do not walk"
    },
    {
      "suppressionCode": "NE",
      "suppressionName": "Do not email"
    }
  ],
  "disclosureFieldValues": [
    {   
      "disclosureFieldId": 1000,
      "disclosureFieldValue": "702",
      "designationId": 1121
    },
    {   
      "disclosureFieldId": 1001,
      "disclosureFieldValue": "John",
      "designationId": 1121
    }
  ]
}

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

Disclosure Field Values

Disclosure Fields exist on a range of objects (e.g. People, Contributions) and are used for Disclosure Reports for FEC and state filing purposes.

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 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 a hierarchical categorization system which may be applied to a variety of Entities.

There ar two types of Codes: Source Codes, and Tags. Source Codes are used to indicate the effort or activity which caused an Entity to be added to the database; at most one Source Code may be applied to any given Entity. Tags may be used to indicate a variety of properties about an Entity; any number of Tags may be applied to a given Entity.

Source Codes may only be applied to the following Entities only: People, Events, and Contributions. Tags may be applied to People, Events, and other Entities. The list of Entities to which a Tag may be applied depends on the context of the API key in use; the GET /entities/supportedEntities route may be used to determine which Entities may have Tags applied for an given API key.

The hierarchical nature of Codes makes it possible for a single Code to convey several pieces of information at once. For example, you could categorize a variety of marketing campaigns in a hierarchical manner:

• Digital Ads
  • Facebook
    • Jan 2017
    • Feb 2017
    • Valentine’s Day Promotion
  • Twitter
    • Promoted tweets
• Bulk mail
  • Post cards
  • Newsletter

If the Promoted tweets Code is applied to a Contribution, that conveys three pieces of information: that the Contribution came from Digital Ads, and more specifically from Twitter, and finally that it came from Promoted tweets. This hierarchy allows a single Code to carry a significant amount of information because each Code can have a parent (e.g., the parent of Promoted tweets is Twitter.) As is demonstrated in the above example, Codes need not have the same number of parents, grand-parents, etc. Promoted tweets is three levels deep whereas Post cards is only two levels deep.

Codes have another helpful attribute called applicability. In some cases, a Code’s parent may be able to stand on its own. For example, if Post cards is too specific of an attribute for certain kinds of Contributions, Bulk mail may suffice. In this case, it’d make sense to allow Bulk mail to be Applicable.

In the case of Digital Ads, you may decide that your classifications are complete enough that you do not want to simply classify something as Twitter. In that case, you’d make Twitter be Searchable Only. This means that you can find Contributions marked with any Twitter promotion, but no Contribution can be just from Twitter only.

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

Codes are applied using each supported entity’s endpoint, e.g. POST /people/{vanId}/codes in the case of People.

The following is an example of a Labor Tag 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 Tag’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.",
  "codeType": "Tag",
  "dateCreated": "2015-04-05T12:59:00Z",
  "supportedEntities": [
    {
      "name": "Events",
      "isSearchable": true,
      "isApplicable": true
    },
    {
      "name": "Locations",
      "isSearchable": true,
      "isApplicable": false
    }
  ]
}

The following Source Code is used to keep track of people and contributions that came from digital ad campaigns:

{
  "codeId": 20615,
  "parentCodeId": null,
  "name": "Digital ads",
  "description": "Used to mark people and contributions retrieved because of digital ad campaigns",
  "codeType": "SourceCode",
  "dateCreated": "2017-10-05T12:59:00Z",
  "supportedEntities": null
}

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",
      "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

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
  },
  "isSharedWithMasterCommitteeByDefault": false,
  "isSharedWithChildCommitteesByDefault": true
}

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