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

A Bulk Import Job allows the user to create bulk imports of various resource types such as Contacts or Contributions, and Activist Codes. For a complete list, see the resources endpoint.

API users first create a job with a POST /bulkImportJobs request containing the job parameters, and then make additional requests to GET /bulkImportJobs/{jobId} for the status and content of the job.

Notes:

• An individual user with access to a data set will have their own permissions and data upload requirements. You may have specific prerequisites for certain mapping fields, preventing you from creating or modifying some fields unless you’ve also included mapping for their prerequisite fields. These will be displayed in your informational endpoints, and if you attempt to upload without prerequisites, the error messages from the import job will give you information about the missing requirements.
• You can only upload to Disclosure Fields for either Organizations or Individuals at a time when applying Contributions. If you have both, they will need to be imported as two separate bulk import files.

Currently supported mapping types include the following. Please contact developer support to discuss your use case and request appropriate permissions.

• Apply Activist Code
• Apply Contribution Adjustments
• Apply Contributions
• Apply Custom Address
• Apply Email Address
• Apply External ID
• Apply Mailing Address
• Apply Origin Source Code
• Apply Custom Contact Fields
• Apply Phone Numbers
• Apply Suppressions
• Apply Work Address
• Edit Contribution Data
• Create Or Update Contact
• Create or Update Activist Codes

A Bulk Import Job consists of an Upload File and a Mapping Definition. Each Bulk Import Job is of a single Resource Type and may be either creation of new entities, updating existing entities, or a combination of the two.

Upload File

The Upload File is simple flat tabular data.

Each row of the Upload File contains information about one entity of the given Resource Type. For example, if your Resource Type is Contacts, and you are creating new records, your Upload File might look like this:

Limitations

• It is a zip file which contains data formatted as plain text, either as comma separated values (.csv) or tab delimited (.txt).
• Characters should be in the ISO-8859-1 (Latin-1) character set.
• If any instances of the delimiter character appear in your file itself, you will need to make sure to quote those strings. This is very likely if you use commas as your delimiter, as commas appear in many fields you are likely to upload. If you create your data with a spreadsheet program, it will probably quote the strings with delimiter in them automatically when saving.
• An upload file can have at most 50 columns.

Mapping Definition

Our sample Upload File corresponds to several different Mapping Definitions in a Bulk Import Job.

• Most of the columns are straightforward columns that can be part of your Create Or Update Contact mapping definition: fundamental columns for creating a new Contact.
• There’s a different Mapping Definition for external identifiers: Apply External ID.
• This sample upload file includes both work and personal phones for each of our contacts. We can add Mapping Definitions for both kinds of phone separately: Apply Phone Numbers.

Some fields can be created initially with the Create Or Update Contact mapping definition if you only want to make a simple Upload File. For example, if you have only one email address or phone number per contact, you can add the email address and phone number as part of the Create Or Update Contact mapping. Other fields always need to be created as part of a separate mapping definition, such as External ID or Origin Source Code. To see what mappings are available to your API key, make a call to GET /bulkImportMappingTypes.

Our sample spreadsheet will correspond to five mapping definitions: one for the base contact definition, one for each of the three different types of phones, and one for the external ID.

{
    "name": "CreateOrUpdateContact",
    "fieldValueMappings": [
        {
            "fieldName": "FirstName",
            "columnName": "GivenName"
        },
        {
            "fieldName": "LastName",
            "columnName": "Surname"
        },
        {
            "fieldName": "AddressLine1",
            "columnName": "StreetAddress"
        },
        {
            "fieldName": "City"
        },
        {
            "fieldName": "StateOrProvince",
            "columnName": "State"
        },
        {
            "fieldName": "ZipOrPostal",
            "columnName": "Zip"
        },
        {
            "fieldName": "Email"
        }
    ]
}

{
    "name": "Phones",
    "fieldValueMappings": [
        {
            "fieldName": "Phone",
            "columnName": "HomePhone"
        },
        {
            "fieldName": "PhoneTypeID",
            "staticValue": "H"
        },
        {
            "fieldName": "PhoneOptInStatusID",
            "staticValue": "Opt-In"
        },
        {
            "fieldName": "CountryCode",
            "columnName": "HPCountry"
        }
    ]
}

{
    "name": "Phones",
    "fieldValueMappings": [
        {
            "fieldName": "Phone",
            "columnName": "MPhone"
        },
        {
            "fieldName": "PhoneTypeID",
            "staticValue": "C"
        },
        {
            "fieldName": "PhoneOptInStatusID",
            "staticValue": "Opt-In"
        },
        {
            "fieldName": "CountryCode",
            "staticValue": "US"
        }
    ]
}

{
    "name": "Phones",
    "fieldValueMappings": [
        {
            "fieldName": "Phone",
            "columnName": "WorkPhone"
        },
        {
            "fieldName": "PhoneTypeID",
            "staticValue": "W"
        },
        {
            "fieldName": "PhoneOptInStatusID",
            "staticValue": "Unknown"
        },
        {
            "fieldName": "CountryCode",
            "staticValue": "US"
        }
    ]
}

{
    "name": "ApplyExternalID",
    "fieldValueMappings": [
        {
            "fieldName": "ExternalId"
        },
        {
            "fieldName": "ExternalIdTypeID",
            "staticValue": "Friendster"
        }
    ]
}

Bulk Import Jobs are run asynchronously. The entire workflow of initiating a bulk import job and investigating the returned results consists of multiple calls.

1. API users first create a job with a POST /bulkImportJobs call.
2. A successful POST returns the jobId of the bulk import job.
3. API users make a GET /bulkImportJobs/{jobId} call.
4. When the results of the GET return a status of Complete, the asynchronous job is completed, and the API user can inspect the results.

If at least a subset of the rows in the Upload File are successfully imported into the database, the status of the GET call will be Complete, and the resultFiles array will contain links to files containing information about the Bulk Import Job.

Result Files

For every row in your upload file that validates, there will be a row in the results file. For the upload file in the Conceptual Overview, the results file should look something like this.

The columns in the result file can be parsed by the consuming software.

The following is an example of a completed Bulk Import Job:

{
    "id": 75,
    "status": "Completed",
    "resourceType": "Contacts",
    "resultFileSizeLimitKb": 5000,
    "errors": [],
    "resultFiles": [
        {
            "url": "https://somedomain.com/filename.csv",
            "dateExpired": "2019-05-15T08:45:50.2062048-04:00"
        }
    ]
}

An error object can have multiple properties to help debug a failed bulkImportantJob.

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.

Currently supported entities include the following. Please contact developer support to discuss your use case and request appropriate permissions.

• ActivistCodes
• ContactHistory
• Contacts
• ContactsActivistCodes
• ContactsSurveyResponses
• ContributionAdjustments
• Contributions
• RecurringContributions

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,
  "excludeChangesFromSelf": "true"
}

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

Each Supported Entity has the following properties:

Codes

Each list of Codes has the following properties: