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",
  "delayInMilliseconds": null
}

You can simulate a slow request with POST /echoes, by using the delayInMilliseconds parameter. This can be helpful in testing responses to slow requests. delayInMilliseconds defaults to 0, and can be at most 30,000 milliseconds (30 seconds).

POST /echoes
{
  "message": "Hello, world, you seem sleepy this morning",
  "delayInMilliseconds": 1000
}

200 OK
{
  "message": "Hello, world, you seem sleepy this morning",
  "dateSent": "2017-01-01T00:00:00Z",
  "delayInMilliseconds": 1000
}

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",
      "isCellStatus": {
        "statusId": 2,
        "statusName": "Likely Cell"
      }
    },
    {
      "phoneId": 5309,
      "phoneNumber": "1-555-555-1234",
      "phoneType": "W",
      "ext": 999,
      "isPreferred": false,
      "isCellStatus": null
    }
  ],
  "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.

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

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.

A Changed Entity Export Job is a process that provides data in bulk about entities that have changed in the last 24 hours to API consumers. Each successful job results in the creation of one or several .csv files that may be downloaded before their expiration dates.

Developers might first catalog the available Resource Types as well as the available Fields for each type.

Once a framework is established, API users first create a job with a POST /changedEntityExportJobs request containing the job parameters, and then make additional requests to GET /changedEntityExportJobs/{exportJobId} for the status and content of the job.

Multiple permissions are required to access this endpoint. Please reach out to developer support to request access.

The following is an example of a completed Changed Entity Export Job:

{
  "exportJobId": 12345,
  "jobStatus": "Complete",
  "dateChangedFrom": "2019-01-01T01:02:03+04:00",
  "dateChangedTo": "2019-01-01T07:03:09+04:00",
  "files": [
    {
      "downloadUrl": "https://www.example.com/some-unique-file-name.csv",
      "dateExpired": "2019-01-31T15:05:54.2106809-04:00"
    }
  ],
  "message": "Finished processing export job",
  "code": null,
  "exportedRecordCount": 10500
}

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 metadata about each. You can perform these operations on a single code or on a batch of codes.

Codes are applied using the appropriate endpoint for the supported entity to which the Code is being applied. For example, to apply Codes to a Person, use POST /people/{vanId}/codes.

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",
  "dateModified": "2015-05-05T16:00: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",
  "dateModified": "2017-10-08T12:00:00Z",
  "supportedEntities": null
}

The following list of Codes is formatted for batch operations:

{
  "codes": [
    {
      "parentCodeID": "1019966",
      "name": "Labor",
      "description": "The tag for describing Labor",
      "supportedEntities": [
        {
          "name": "Contacts",
          "isSearchable": true,
          "isApplicable": true
        },
        {
          "name": "ActivistCodes",
          "isSearchable": true,
          "isApplicable": true
        }
      ],
      "codeType": "Tag"
    },
    {
      "name": "Volunteers",
      "description": "The tab for describing all of our Volunteers",
      "supportedEntities": null,
      "codeType": "Tag"
    }
  ]
}

Code

Each Code has the following properties:

Supported Entity

Codes

Each list of Codes has the following properties:

A Contribution is a record of a person’s monetary gift. They must be linked to both the contact that contributed, and the designation corresponding to the contribution.

Contributions can be associated with a pledge, attributed to other contacts, and have codes applied to them.

The following is an example of a contribution.

{
    "contributionId": 23453,
    "contact": {
        "vanId": 10005165
    },
    "designation": {
        "designationId": 18754,
    },
    "dateReceived": "2013-12-25T12:23:00Z",
    "amount": "12.34",
    "coverCostsAmount": "2.34",
    "status": "Settled",
    "paymentType": "Check",
    "bankAccount": "PNC Bank Account 1",
    "contributionBankAccount": {
        "bankAccountId": 9876,
        "name": "PNC Bank Account 1"
    },
    "depositDate": "2013-12-28",
    "depositNumber": 3,
    "checkDate": "2013-12-25",
    "checkNumber": "1222 123",
    "contactAttributions": [
        {
          "vanId": 303,
          "amountAttributed": "100.50",
          "attributionType": "DefaultAttribution",
          "notes": "some notes go here",
          "dateThanked": "2013-12-30"
        },
        {
          "vanId": 701,
          "amountAttributed": "202.10",
          "attributionType": "CorporateMatch",
          "notes": "some notes go here",
          "dateThanked": "2013-12-30"
        },
    ],
    "onlineReferenceNumber": "1230230423",
    "pledge": {
        "pledgeId": 1035
    },
    "codes": [
        { "codeId": 12345, "codeName": "Signup Form Source Code" }
    ],
    "directMarketingCode": "Excelsior Consulting",
    "dateThanked": "2013-12-30",
    "notes": "Processed as part of the Christmas Fundraiser",
    "disclosureFieldValues": [
        {
          "disclosureFieldId": 190,
          "disclosureFieldValue": "41",
          "designationId": 1121
        },
        {
          "disclosureFieldId": 40,
          "disclosureFieldValue": "5",
          "designationId": 1121
        },
        {
          "disclosureFieldId": 1001,
          "disclosureFieldValue": "John",
          "designationId": 1121
        }
    ],
    "identifiers": [
        {
          "type": "ActBlue ID",
          "externalId": "123456"
        }
    ],
    "financialBatchId": 825,
    "processedAmount": 3,
    "processedCurrency": "USD",
    "acceptedOneTimeAmount": "12.34",
    "acceptedRecurringAmount": "5.67",
    "selectedOneTimeAmount": "20.00",
    "upsellType": "Split",
    "isUpsellShown": true,
    "isUpsellAccepted": true
}

The following is an overview of the Contribution 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.

Contribution

The required properties are contact, designation, dateReceived, amount, status, and paymentType.

Designation

Contribution Bank Account

Attributions

Attribution Type

One of

• BoardMemberGiving
• CorporateMatch
• DefaultAttribution
• DonorAdvisedFund
• DonorMatch
• FamilyPrivateFoundation
• FinanceCommittee
• GiftMembership
• RaisedContribution
• TributeGift
• TallyMember
• WorkplaceGiving

Pledge

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.

Identifier

Used for known external identifiers (e.g., ActBlue ID). External IDs are case-insensitive. Abcd1234 will always match ABCD1234.

Payment Type

One of

• Check
• MoneyOrder
• Cash
• CreditCard
• InKind
• Unknown
• ElectronicFundsTransfer
• ElectronicPaySystem
• PayPal
• Stock
• ApplePay

A Custom Field represents structured data about a person or other object in VAN, configured by a VAN user. A Custom Contact Field is a Custom Field applied to People.
A Custom Contribution Field is a Custom Field applied to Contributions. These are the only types of Custom Fields available via the API. Note: Custom Contact Fields may only be assigned to Contacts in MyCampaign mode; assignment is not available in VoterFile mode.

Custom Fields are collected into Groups for better organization and administration. For example, a committee which works heavily with college students might have a Custom Fields Group called "Student Custom Field Group", with fields such as "Selected field of study", "Name of high school", etc.

Every Custom Field has a data type, which indicates what kind of data will be accepted for that custom field. The data types, and restrictions on the data available, are as follows:

• Boolean: accepts only "true" or "false"
• Selection: accepts only one of the available values belonging to the custom field
• Text: accepts any text, limited by the maximum number of characters stipulated in the custom field
• Date: accepts only dates in the format YYYY-MM-DD
• Number: accepts numeric values, limited by the maximum number of characters stipulated in the custom field
• Money: accepts currency amounts

Custom Fields of type Selection may have parents to indicate hierarchies within the available values. The parent of a Custom Field must also be a Selection field, and is usually used to indicate a higher level of groupings for the available values. If a Custom Field has a parent, then each of its available values also has a parent, and each parent is an available value in the parent custom field. For example, if one custom field indicates "Field of study" for college students, then its parent custom field might indicate "Department", and their available values might be organized as follows: Note: Only Custom Contact Fields may have parented custom fields.

• Physical sciences (available value for Department)
  • Biology (available value for Field of study; parent available value is Physical sciences)
  • Chemistry (available value for Field of study; parent available value is Physical sciences)
• Liberal arts (available value for Department)
  • History (available value for Field of study; parent available value is Liberal arts)
  • English (available value for Field of study; parent available value is Liberal arts)

• CustomFieldTypes:
  • B = Boolean (Checkbox)
  • S = Selection (Dropdown)
  • T = Text
  • D = Date
  • N = Number
  • M = Money (Currency)

{
    "customFieldId": 157,
    "customFieldParentId": null,
    "customFieldName": "Education level",
    "customFieldGroupId": 52,
    "customFieldGroupName": "Education",
    "customFieldGroupType": "Contacts",
    "customFieldTypeId": "S",
    "isEditable": true,
    "isExportable": false,
    "maxTextboxCharacters": null,
    "availableValues": [
      {
        "id": 1,
        "name": "High School diploma",
        "parentValueId": null
      },
      {
        "id": 2,
        "name": "College degree",
        "parentValueId": null
      },
      {
        "id": 3,
        "name": "Postgraduate degree",
        "parentValueId": null
      },
      {
        "id": 4,
        "name": "Doctorate",
        "parentValueId": null
      }
    ]
}

Custom Field

AvailableValue

A designation is the representation of a compliance report inside one VAN committee. Calls to the designation endpoint retrieve a list of designations including the logical name and id for those designations. Contributions can be assigned designations by id.

The following is an example of designation

    {
        "designationId": 123456789,
        "name": "Jane for Congress Committee"
    }

The following is an overview of the Designation object.

Designation

Available properties

A Disbursement is a record of an expenditure made by your organization. They must be linked to both the Person that received the expenditure, and the Designation corresponding to the disbursement. Disbursements can have Codes applied to them.

The following is an example of a disbursement.

{
    "disbursementId": 23453,
    "contact": {
        "vanId": 10005444
    },
    "designation": {
        "designationId": 18754,
    },
    "dateIssued": "2013-12-25T12:23:00Z",
    "amount": "12.34",
    "batchCode": "123",
    "checkDate": "2013-12-25",
    "checkNumber": "1222 123",
    "codes": [
        { "codeId": 12345 }
    ],
    "notes": "Expense for the Christmas Fundraiser",
    "disclosureFieldValues": [
        {
          "disclosureFieldId": 30000,
          "disclosureFieldValue": "30060",
          "designationId": 1121
        },
        {
          "disclosureFieldId": 30008,
          "disclosureFieldValue": "2018",
          "designationId": 1121
        }
    ]
}

The following is an overview of the Disbursement 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.

If any of the specified ids (vanId or codeId) are not accessible in the current context (e.g., the associated api user does not have access to the person), the response will be considered invalid.

Disbursement

The required properties are contact, designation, dateIssued, and amount.

Designation

Disclosure Field Values

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: