Welcome to the DNC VoteBuilder API Docs!

A platform for applications servicing Democratic State Parties and Campaigns

Welcome. If you're a developer who is working with Democratic campaigns or State Parties, you've come to the right place! The DNC offers a series of API’s and services for developer to build applications to work with all kinds of data in VoteBuilder. With this set of APIs, you'll be able to search for people in My Voters or My Campaign, surface canvass responses and activist codes, and retrieve survey questions. With the ActionID service you will be able to allow your users to access your app with their existing ActionID account they already use to log in to VoteBuilder and other apps in the ecosystem.

Ready to get started? Request an API key today, and tell us what you think!

Are you a member of the press with questions? Reach out to the DNC Press Team here.



Getting Started

Back to Top

Overview

The VAN’s RESTfulAPI 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 /resourceslists all resources in the authenticated context, GET /resources/:idgets the details of a specific object, POST /resourcescreates a new object, PUT /resources/:idupdates a specific object, and DELETE /resources/:iddeletes or suppresses a specific object. Some endpoints also support the PATCHHTTP verb for partial resource updates.

Back to Top

Authentication

Before using the API, you will need to know your Application Nameand API Key. The Application Nameis a short string that identifies your application (e.g., acmeCrmProduct) and the API Keyis a string that identifies the specific contextto 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 0or 1(e.g., 7c9e6679-7425-40de-944b-e07fc1f90ae7|1). Because the API key is connected to a specific context, the API will only return data available to that context.

Note:

API keys are connected to specific developers and applications. Do not share or re-use an API key for different applications nor expose it via client-side scripts or public code repositories.

To authenticate your API requests, use Basic HTTP authenticationand set the usernameto the Application Nameand passwordto the API Key. Most every programming framework supports Basicauthentication out of the box.

The following is a very basic NodeJSexample of an authenticated request:

var request = require('request');
var username = 'acmeCrmProduct';
var password = '7c9e6679-7425-40de-944b-e07fc1f90ae7|1';
var options = {
  url: 'https://api.securevan.com/v4/resourcePath',
  auth: {
    user: username,
    password: password
  },
  ...
};
request(options, function (err, res, body) {
  if (err) {
    console.dir(err);
    return;
  }
  console.dir('headers', res.headers);
  console.dir('status code', res.statusCode);
  console.dir(body);
});

The following is a basic C#example of an authenticated request:

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

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

  var response = client.GetAsync(url).Result;
}
Back to Top

Errors

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 Errorobjects. These objects have the following properties:

Property Description
code Required; a descriptive, all caps, underscore-separated string (e.g., CHECK_OUTS_TOO_FREQUENT)
text Required; a description of the error that is suitable for display to end users
properties Optional; an array containing the path(s) to one or more of the request object’s offending properties using dot notation (e.g., primaryAddress.streetAddress). If the offending property is on an object in an array, the property will use square brackets and a zero based index of the item in the original array.
referenceCode Optional; a string containing a reference to the request’s error
hint Optional; typically a regular expression used to evaluate the property
resourceUrl Optional; a link to technical resources to assist developer with resolving the error

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"
    }
  ]
}
Note:

Failed requests count against your overall API use quota. It’s recommended you employ an Exponential Backoffstrategy for error handling.

Back to Top

Input Validation

Requests are validated to ensure data integrity and to guard against malicious code. Validation errors will be returned as standard Errorobjects with the codeproperty set to INVALID_PARAMETERand 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 firstNameand lastNameproperties 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 context’s country.

Back to Top

Expansion

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 $expandquery parameter. This technique is used in both “list” endpoints and “get” endpoints.

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

Parameter Location Type Description
$expand query string A comma delimited list of expansion properties. Valid expansion properties are documented for each endpoint.

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 emailsand phonesin the query string:

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

Returns the first-order properties (names), populated emailsand 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 $expandparameter to an endpoint that does not expand parameters will yield a 400 Bad Requesterror response:

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

Sending an invalid $expandparameter to an endpoint also yields a 400 Bad Requesterror response. The supported properties are included in the hintof 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'"
    }
  ]
}
Back to Top

Pagination

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:

Parameter Location Type Description
$top query integer A limit on the number of records to return in a single request, similar to a page size. This can be a value between 1 and the maximum $topvalue for a particular endpoint, typically 200. If no $topvalue is specified, an endpoint’s default $topsize is used, typically 50. If an end point has a default $topbut no maximum $top, you can retrieve all values by sending the $topparameter with no values (e.g., resources?$top=). The maximum and default values are documented for each endpoint.
$skip query integer The number of records in a collection that should be skipped and not included in the result. If specified, must be greater than or equal to 0. For example, if you have a collection of 100 items and specify a $skipvalue of 10, the endpoint will return resources starting at 11.
$expand query string A comma delimited list of expansion properties (see Expansion)

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

Property Type Description
items array An array of zero or more endpoint specific objects (e.g., an Activist Code)
count integer Total number of items available at this endpoint using the filters specified. This can be greater than the number of items in the itemsarray.
nextPageLink string An absolute URL at which additional records can be retrieved, if additional records are available. This will be the same as the request’s URL but with adjusted or appended $skipand $topvalues.

If no results are returned, an HTTP Status Code 200 OKis returned with the itemsarray empty, countproperty equal to 0, and the nextPageLinknull.

Back to Top

Endpoints

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

https://api.securevan.com/v4
Used by all US-based clients and developer sandbox accounts
https://intlapi.securevan.com/v4
Used by most non-US clients

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

People

Back to Top

Overview

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

Back to Top

Common Models

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

{
  "firstName": "James",
  "middleName": "Worthington",
  "lastName": "Gordon",
  "email": {
    "email": "jim@gotham.city.us",
    "isPreferred": true
  },
  "phone": {
    "phoneNumber": "1-555-555-1234",
    "phoneType": "W",
    "ext": 999,
    "isPreferred": true
  },
  "address": {
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 3",
    "addressLine3": "Blah",
    "city": "Gotham City",
    "stateOrProvince": "IL",
    "zipOrPostalCode": "01234",
    "countryCode": "US",
    "type": "H",
    "isPreferred": false
  },
  "identifiers": [
    {
      "type": "bsdid",
      "externalId": "746313"
    }
  ]
}
Person
Property Type Description
firstName string Optional; a person’s first name, no longer than 20 characters
middleName string Optional; a person’s first name, no longer than 20 characters
lastName string Optional; a person’s last name, no longer than 25 characters
email object Optional; a person’s email
phone object Optional; a person’s phone
address object Optional; a person’s address
identifiers array Optional; an array of identifierobjects
Email
Property Type Description
email string Required; a valid email address
isPreferred bool Optional; an indicator of whether the email address is the person’s preferred address; defaults to false
Phone
Property Type Description
phoneNumber string Required; after removing all non-numeric characters, the number is evaluated using the target context’s country specific validation.
phoneType string Optional; one of: H→ home, W→ work, C→ cell (alias for mobile), M→ mobile, F→ fax
ext string Optional; no more than six numeric characters
isPreferred bool Optional; an indicator of whether the phone number is the person’s preferred phone number; defaults to false
Address
Property Type Description
addressLine1 string Optional; first line of a street address
addressLine2 string Optional; second line of a street address
addressLine3 string Optional; third line of a street address
city string Optional; city or town
stateOrProvince string Optional; two or three character State or Province code (e.g., MN, ON, NSW, etc.)
zipOrPostalCode string Optional; ZIP, ZIP+4, Postal Code, Post code, etc.
countryCode string Optional; a two character ISO country code that is supported by your VAN context
type string Optional; one of: M→ mailing, H→ home, V→ voting, W→ work, C→ custom; some types may not be available in certain contexts.
isPreferred bool Optional; an indicator of whether the address is the person’s preferred address; defaults to false
Identifier

Used for known external identifiers (e.g., DWID, Voter File ID, etc.)

Property Type Description
type string Required; a known external identifier that is available in the current context
externalId string Required

The various findend points return a common response object.

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

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

The HTTP status code is set per statusvalue.

Status HTTP Code Description
Matched 302 Found A match was found (and updated, if relevant) and the Locationheader is set
Stored 201 Created Not implemented
Unmatched 404 Not Found No match was found
UnmatchedStored 201 Created No match was found, but a new record was created (and the Locationheader is set)
Processed 204 No Content Not implemented
UnmatchedProcessed 204 No Content Not implemented
Back to Top

POST /people/find

Look for a matched record.
Description

Attempts to find a person using the given match candidate.

Request

Match Candidate

Response

Match Response

Back to Top

POST /people/findOrCreate

Look for a matched record, create one if none exists
Description

Attempts to find the given match candidate. If a person is found, it is updated with the information provided. If a person is not found, a new person record is created.

Request

Match Candidate

Response

Match Response

Back to Top

GET /people/{vanId}

Retrieve a person by vanId.
Description

Retrieve a person record and associated contact information

Request
Parameter Location Type Description
vanId route integer Unique person identifier available in the current context
$expand query string Optional; comma delimited list of expansionproperties: phones, emails, addresses
/people/215501?$expand=phones,emails,addresses
Response

If a result is found, it will look like:

{
  "vanId": 215501,
  "firstName": "James",
  "lastName": "Gordon",
  "middleName": null,
  "emails": [
    {
      "type": null,
      "email": "jim@gotham.city.us",
      "dateCreated": "2004-10-31T14:35:00Z",
      "isPreferred": true
    }
  ],
  "phones": [
    {
      "phoneNumber": "6175555920",
      "ext": "5125",
      "dateCreated": "2013-10-25T12:23:00Z",
      "phoneType": "Work",
      "isPreferred": false
    },
    {
      "phoneNumber": "7815550256",
      "ext": null,
      "dateCreated": "2013-10-25T12:23:00Z",
      "phoneType": "Cell",
      "isPreferred": true
    }
  ],
  "addresses": [
    {
      "addressId": null,
      "addressLine1": "3001 Tradewinds Trl",
      "addressLine2": null,
      "addressLine3": null,
      "city": "Orlando",
      "stateOrProvince": "FL",
      "zipOrPostalCode": "32805",
      "geoLocation": null,
      "countryCode": null,
      "preview": "3001 Tradewinds Trl",
      "type": "Voting",
      "isPreferred": null
    },
    {
      "addressId": null,
      "addressLine1": "320 College Ave",
      "addressLine2": null,
      "addressLine3": null,
      "city": "Somerville",
      "stateOrProvince": "MA",
      "zipOrPostalCode": "02145",
      "geoLocation": null,
      "countryCode": null,
      "preview": "320 College Ave ",
      "type": "Mailing",
      "isPreferred": null
    }
  ],
  "identifiers": null
}

If the specified vanIdcan’t be found, an error will be returned with a 404.

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "text": "The specified resource cannot be found."
    }
  ]
}

If the specified vanIdis not accessible in the current context (e.g., the associated user does not have access to the person), an error will be returned with a 403.

{
  "errors": [
    {
      "code": "FORBIDDEN",
      "text": "Access to this resource is restricted."
    }
  ]
}
Back to Top

GET /people/{personIdType}:{personId}

Back to Top
Retrieve a person by an external ID.
Description

Retrieve a person record and associated contact information. For example /people/DWID:12345would retrieve a person whose DWID is 12345.

Request
Parameter Location Type Description
personIdType route string Required; a known person identifier type available in the current context
personId route string Required; an external identifier, URL encoded
$expand query string Optional; comma delimited list of expansionproperties: phones, emails, addresses
/people/dwid:98877325?$expand=phones,emails,addresses
Response

If a result is found, it will look like:

{
  "vanId": 215501,
  "firstName": "James",
  "lastName": "Gordon",
  "middleName": null,
  "emails": [
    {
      "type": null,
      "email": "jim@gotham.city.us",
      "dateCreated": "2004-10-31T14:35:00Z",
      "isPreferred": true
    }
  ],
  "phones": [
    {
      "phoneNumber": "6175555920",
      "ext": "5125",
      "dateCreated": "2013-10-25T12:23:00Z",
      "phoneType": "Work",
      "isPreferred": false
    },
    {
      "phoneNumber": "7815550256",
      "ext": null,
      "dateCreated": "2013-10-25T12:23:00Z",
      "phoneType": "Cell",
      "isPreferred": true
    }
  ],
  "addresses": [
    {
      "addressId": null,
      "addressLine1": "3001 Tradewinds Trl",
      "addressLine2": null,
      "addressLine3": null,
      "city": "Orlando",
      "stateOrProvince": "FL",
      "zipOrPostalCode": "32805",
      "geoLocation": null,
      "countryCode": null,
      "preview": "3001 Tradewinds Trl",
      "type": "Voting",
      "isPreferred": null
    },
    {
      "addressId": null,
      "addressLine1": "320 College Ave",
      "addressLine2": null,
      "addressLine3": null,
      "city": "Somerville",
      "stateOrProvince": "MA",
      "zipOrPostalCode": "02145",
      "geoLocation": null,
      "countryCode": null,
      "preview": "320 College Ave ",
      "type": "Mailing",
      "isPreferred": null
    }
  ],
  "identifiers": null
}

If the specified vanIdcan’t be found, an error will be returned with a 404.

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "text": "The specified resource cannot be found."
    }
  ]
}

If the specified vanIdis not accessible in the current context (e.g., the associated user does not have access to the person), an error will be returned with a 403.

{
  "errors": [
    {
      "code": "FORBIDDEN",
      "text": "Access to this resource is restricted."
    }
  ]
}
Back to Top

POST /people/{vanId}/canvassResponse

Add Canvass Responses to a person
Description

A Canvass Response encapsulates a complete interaction with a person: it may have a Result Code (if the person was unavailable) or it may have an array of responses such as Activist Codes, Survey Questions, and other Script elements. Optionally, additional information about the canvass interaction can be specified using the canvassContextproperty such as the date of the contact attempt ( dateCanvassed) or the Contact Type ( contactTypeId). Use this end point to record these interactions.

Request

A Canvass Response is expected to be structured like the following:

{
  "canvassContext": {
    "contactTypeId": 2,
    "inputTypeId": 14,
    "dateCanvassed": "2012-04-09T00:00:00-04:00"
    },
  "resultCodeId": null,
  "responses": [
    {
      "activistCodeId": 18917,
      "action": "Apply",
      "type": "ActivistCode"
    },
    {
      "volunteerActivityId": 3425,
      "action": "Apply",
      "type": "VolunteerActivity"
    },
    {
      "surveyQuestionId": 109149,
      "surveyResponseId": 465468,
      "type": "SurveyResponse"
    }
  ]}
Canvass Response
Property Type Description
canvassContext object Optional; describes the context in which this Canvass Response was created
resultCodeId int Optional; specifies the Result Codeof this Response. If no resultCodeIdis specified, responsesmust be specified. Conversely, if responsesare specified, resultCodeIdmust be null (a result of Canvassedis implied). The resultCodeIdmust be a valid Result Codein the current context.
responses array Optional; an array of Script Responses. If specified, resultCodeIdmust be null.
Canvass Context
Property Type Description
contactTypeId int Optional; a valid Contact Type ID
inputTypeId int Optional; a valid Input Type ID(defaults to 11API)
dateCanvassed int Optional; the ISO 8601formatted date that the canvass attempt was made (defaults to today’s date)
Script Responses

Each Script Responsehas a property that determine’s the response’s type—currently one of ActivistCode, SurveyResponse, and VolunteerActivity.

Activist Codes
Property Type Description
type string ActivistCode
activistCodeId int Required; a valid
action string Optional; Apply(default) or Removeto indicate whether to apply or remove an Activist Code from a person
Survey Responses
Property Type Description
type string SurveyResponse
surveyQuestionId int Required; a valid Survey Question ID
surveyResponseId int Required; a valid Response to the specified surveyQuestionId
Volunteer Activities
Property Type Description
type string VolunteerActivity
volunteerActivityId int Optional; a valid Volunteer Activity ID
action string Optional; Apply(default) or Removeto indicate whether to apply or remove a Volunteer Activity from a person
Response

HTTP Status Code 204 No Contentis returned.

Back to Top

POST /people/{personIdType}:{personId}/canvassResponse

Add Canvass Responses to a person by an external ID.
Description

This endpoint is the same as people/{vanId}/canvassResponsebut uses external IDs rather than VANIDs.

Response

HTTP Status Code 204 No Contentis returned.

Canvass Responses

Back to Top

Overview

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

Back to Top

GET /canvassResponses/contactTypes

Retrieve available Contact Types
Description

Contact Types are different ways a canvass response was collected. For example, responses collected while walking around your neighborhood would have a Contact Type of Walk. While most Contact Types are common across VAN instances, some instances may have custom Contact Types. Use this end point to retrieve all available Contact Types. Additionally, Contact Types can be assigned to specific Input Types. For example, a Contact Type of Walkwouldn’t make sense for an Input Type of Virtual Phone Bank. To return Input Type appropriate Contact Types, use the optional inputTypeIdparameter.

Request
Parameter Location Type Description
inputTypeId query int Optional; filter Contact Types to those available to the given Input Type
/canvassResponses/contactTypes?inputTypeId=11
Response
[
  {
    "contactTypeId": 1,
    "name": "Phone"
  },
  {
    "contactTypeId": 2,
    "name": "Walk"
  }
]
Back to Top

GET /canvassResponses/inputTypes

Retrieve available Input Types
Description

Input Types are different ways canvass responses are entered into VAN. For example, responses entered via Bulk Upload will use the Input Type of Bulk. By default, responses entered via the API will use an Input Type of API. While most Input Types are common across VAN instances, some instances may have custom Input Types. Use this end point to retrieve all available Input Types.

Request
/canvassResponses/inputTypes
Response
[
  {
    "inputTypeId": 11,
    "name": "API"
  },
  {
    "inputTypeId": 4,
    "name": "Bulk"
  },
  {
    "inputTypeId": 2,
    "name": "Manual"
  },
  {
    "inputTypeId": 14,
    "name": "Mobile"
  },
  {
    "inputTypeId": 10,
    "name": "VPB"
  },
  {
    "inputTypeId": 23,
    "name": "Website"
  }
]
Back to Top

GET /canvassResponses/resultCodes

Retrieve available Result Codes
Description

Result Codes, or contact dispositions, are the result of a contact attempt. For example, Not Home, Wrong Number, Moved, etc. A successful contact interaction yields a Result Code called Canvassedwhich is automatically applied when canvass responses are submitted (e.g., when a Survey Response is recorded). Unsuccessful contact attempts are what Result Codes are all about. This end point returns a list of those response codes available in the current context. Similar to Contact Types, Result Codes’ availability can vary by Input Type and/or Contact Type. For example, Wrong Numberonly makes sense in the context of a CallContact Type. Movedonly makes sense in the context of a WalkContact Type.

Note:

The application of some Result Codes triggers additional actions. For example, if you record a Wrong Numberresult, the person’s phone number is marked “bad.”

Request
Parameter Location Type Description
inputTypeId query int Optional; filter Result Codes to those available to the given Input Type
contactTypeId query int Optional; filter Result Codes to those available to the given Contact Type
/canvassResponses/resultCodes?contactTypeId=1
Response
[
  {
    "resultCodeId": 18,
    "name": "Busy",
    "mediumName": "Busy",
    "shortName": "BZ"
  },
  {
    "resultCodeId": 25,
    "name": "Disconnected",
    "mediumName": "Disc",
    "shortName": "WX"
  },
  {
    "resultCodeId": 19,
    "name": "Left Message",
    "mediumName": "LM",
    "shortName": "LM"
  },
  {
    "resultCodeId": 20,
    "name": "Wrong Number",
    "mediumName": "Wr#",
    "shortName": "WN"
  }
]

Activist Codes

Back to Top

Overview

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

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

Back to Top

Common Models

{
  "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"
}
Property Type Description
activistCodeId int Unique identifier for an Activist Code in this context (this is an ID that is often unique across many VAN database tabs)
type string A general category for an Activist Code
name string A name for the Activist Code, no longer than 20 characters
mediumName string A shorter name for the Activist Code, no longer than 9 characters
shortName string An even shorter name for the Activist Code, no longer than 3 characters
description string A description of this Activist Code
scriptQuestion string If the Activist Code is to appear on a Script, this is the question that would appear on the script
status string For organizational purposes, users often use various statuses to hide older Activist Codes. This property will be one of: Active, Archived, or Inactive.
Back to Top

GET /activistCodes

Retrieve available Activist Codes
Description

Use this end point to retrieve all Activist Codes that are available in the current context.

Request

This end point accepts standard pagination parametersand returns a standard paginated response.

By default, this endpoint returns 50 records per request. A maximum of 200 records per request is allowed via the $topparameter.

Parameter Location Type Description
statuses query string Comma delimited list of statusesof Activist Codes. One or more of Active(default), Archived, and Inactive.
name query string Filters to Activist Codes with names that start with the given input
type query string Filters to Activist Codes of the given type
/activistCodes?statuses=Active,Archived&type=Volunteer
Response

This end point responds with a standard paged response of Activist Codes.

{
  "items": [
    {
      "activistCodeId": 3214,
      "type": "Volunteer",
      "name": "Precinct Captain",
      "mediumName": "P Capt",
      "shortName": "PC",
      "description": "Precinct Captain",
      "scriptQuestion": "Would you be willing to be a Precinct Captain?",
      "status": "Active"
    },
    {
      "activistCodeId": 8009,
      "type": "Volunteer",
      "name": "Stand Out",
      "mediumName": "Stand Out",
      "shortName": "SO",
      "description": null,
      "scriptQuestion": null,
      "status": "Archived"
    },
    {
      "activistCodeId": 36222,
      "type": "Volunteer",
      "name": "Supporter",
      "mediumName": "Supporter",
      "shortName": "Sup",
      "description": null,
      "scriptQuestion": null,
      "status": "Active"
    }
  ],
  "nextPageLink": null,
  "count": 3
}
Back to Top

GET /activistCodes/{activistCodeId}

Retrieve a specific Activist Code
Description

Use this end point to retrieve information about a specific Activist Code available in the current context.

Request

This end point accepts standard list parameters, returns a standard paged response, and takes the following optional filter parameters:

Parameter Location Type Description
activistCodeId route intor string Unique identifier for a specific Activist Code. This is either an integer or a VAN encoded identifier (e.g., EID28CG).
/activistCodes/3202
Response

A standard Activist Codeobject, if found.

Survey Questions

Back to Top

Overview

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

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

Back to Top

Common Models

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

Each Survey Questionhas the following properties:

Property Type Description
surveyQuestionId int Unique identifier for a Survey Question in this context (this is an ID that is often unique across many VAN database tabs)
type string A general category for a Survey Question (e.g., Candidate, Issue, etc.)
cycle int The election cycle or year this question is assigned
name string A name for the Survey Question, no longer than 20 characters
mediumName string A shorter name for the Survey Question, no longer than 9 characters
shortName string An even shorter name for the Survey Question, no longer than 4 characters
scriptQuestion string The text of the actual question that would appear on a script
status string For organizational purposes, VAN users often use various statuses to hide older Survey Questions. This property will be one of: Active, Archived, or Inactive.
responses array An array of zero or more Survey Responseobjects, sorted as they should appear on a script

Each Survey Responsehas the following properties:

Property Type Description
surveyResponseId int An identifier (unique to this Survey Question) for a Survey Response
name string A name for the Survey Question, no longer than 20 characters
mediumName string A shorter name for the Survey Question, no longer than 3 characters
shortName string An even shorter name for the Survey Question, no longer than 1 character
Back to Top

GET /surveyQuestions

Retrieve available Survey Questions
Description

Use this end point to retrieve all Survey Questions that are available in the current context.

Request

This end point accepts standard pagination parametersand returns a standard paginated response.

By default, this endpoint returns 50 records per request. A maximum of 200 records per request is allowed via the $topparameter.

A Survey Question’s Response collection is automatically populated without specifying an $expandparameter.

The endpoint takes the following optional filter parameters:

Parameter Location Type Description
statuses query string Comma delimited list of statusesof Survey Questions. One or more of Active(default), Archived, and Inactive.
name query string Filters to Survey Questions with names that start with the given input
type query string Filters to Survey Questions of the given type
question query string Filters to Survey Questions with script questions that contain the given input
cycle query int A year in the format YYYY; filters to Survey Questions with the given cycle
/surveyQuestions?statuses=Active,Archived&cycle=2010&type=Candidate
Response

This end point responds with a standard paged response of Survey Questions.

{
  "items": [
    {
      "surveyQuestionId": 54945,
      "type": "Candidate",
      "cycle": 2010,
      "name": "John Kerry senate",
      "mediumName": "Kerry",
      "shortName": "Kerr",
      "scriptQuestion": "Will you vote for John Kerry in the upcoming Senate race?",
      "status": "Archived",
      "responses": [
        {
          "surveyResponseId": 245998,
          "name": "1 Strong Kerry",
          "mediumName": "1",
          "shortName": "K"
        },
        {
          "surveyResponseId": 245999,
          "name": "2 Leaning Kerry",
          "mediumName": "2",
          "shortName": "k"
        },
        {
          "surveyResponseId": 246000,
          "name": "3 Undecided",
          "mediumName": "3",
          "shortName": "U"
        },
        {
          "surveyResponseId": 246002,
          "name": "4 Leaning Republican",
          "mediumName": "5 L",
          "shortName": "r"
        },
        {
          "surveyResponseId": 246001,
          "name": "5 Strong Republican",
          "mediumName": "4",
          "shortName": "R"
        },
        {
          "surveyResponseId": 403566,
          "name": "6 Green Party",
          "mediumName": "6 G",
          "shortName": "G"
        },
        {
          "surveyResponseId": 408826,
          "name": "7 Libertarian",
          "mediumName": "7 L",
          "shortName": "L"
        }
      ]
    },
    {
      "surveyQuestionId": 54949,
      "type": "Candidate",
      "cycle": 2010,
      "name": "Maddow for Senate",
      "mediumName": "Maddow",
      "shortName": "MS",
      "scriptQuestion": "In the upcoming race for US Senate, do you plan to vote for Republican Scott Brown or Democrat Rachel Maddow?",
      "status": "Active",
      "responses": [
        {
          "surveyResponseId": 246016,
          "name": "1 - Strong Maddow",
          "mediumName": "1",
          "shortName": "1"
        },
        {
          "surveyResponseId": 246017,
          "name": "2 - Leaning Maddow",
          "mediumName": "2",
          "shortName": "2"
        },
        {
          "surveyResponseId": 246018,
          "name": "3 - Undecided",
          "mediumName": "3",
          "shortName": "3"
        },
        {
          "surveyResponseId": 246020,
          "name": "4 - Leaning Brown",
          "mediumName": "4",
          "shortName": "4"
        },
        {
          "surveyResponseId": 246019,
          "name": "5 - Strong Brown",
          "mediumName": "5",
          "shortName": "5"
        }
      ]
    }
  ],
  "nextPageLink": null,
  "count": 2
}
Back to Top

GET /surveyQuestions/{surveyQuestionId}

Retrieve a specific Survey Question
Description

Use this end point to retrieve information about a specific Survey Question (and its set of Survey Responses) available in the current context.

Request

This end point takes the following parameter:

Parameter Location Type Description
surveyQuestionId route intor string Unique identifier for a specific Survey Question. This is either an integer or a VAN encoded identifier (e.g., EID28CG).
/surveyQuestions/54949
Response

A standard Survey Questionobject, if found.

Request an API Key

Go Back to API

ActionID

Overview

ActionID is a single sign on provider, used to login to many applications in the progressive ecosystem. Accounts are freely available to anyone who wants to create them, and many tools (such as openVPB) allow users to begin volunteering immediately upon account creation. For more restricted access (such as to VoteBuilder or NGP), system administrators are still in control of whether users with ActionIDs can log in and have fine grained controls over feature availability and data access. Third party applications have the same options - either trust all accounts or apply additional security.

Usage

The implementation of ActionID is currently OpenID 1.1, with plans to also support OpenID Connect in the near future. Most programming languages have available libraries for OpenID interaction - see passport-openid for node.js and DotNetOpenAuth for ASP.NET, as a few examples.

ActionID is available now at http://accounts.ngpvan.com, and the OpenID endpoint for ActionID is https://accounts.ngpvan.com/Home/Xrds.

For more information on the technical details of ActionID, check out the OpenID 1.1 spec.